@mohasinac/appkit 4.29.0 → 4.30.0

package/dist/_internal/client/features/layout/SidebarCollapseToggle.js

@@ -14,5 +14,5 @@ export function SidebarCollapseToggle({ expanded, onToggle, expandedLabel = "Col
     // Chevron rotation direction mirrors along with the dock side so it keeps
     // pointing "into" the collapsed panel regardless of which edge it's on.
     const chevronRotated = edge === "left" ? !expanded : expanded;
-    return (_jsx(IconButton, { type: "button", onClick: onToggle, "aria-label": expanded ? expandedLabel : collapsedLabel, "aria-expanded": expanded, variant: "ghost", style: HANDLE_STYLE, className: `w-9 shrink-0 ${roundedClass} shadow-lg transition-all duration-200 hover:shadow-xl hover:brightness-110 active:scale-[0.96]`, icon: _jsx("svg", { className: `w-4 h-4 drop-shadow-sm transition-transform duration-300 ${chevronRotated ? "rotate-180" : ""}`, style: CHEVRON_STYLE, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2.5, d: "M15 19l-7-7 7-7" }) }) }));
+    return (_jsx(IconButton, { type: "button", onClick: onToggle, "aria-label": expanded ? expandedLabel : collapsedLabel, "aria-expanded": expanded, variant: "ghost", style: HANDLE_STYLE, className: `w-9 shrink-0 ${roundedClass} shadow-lg transition-all duration-200 hover:shadow-xl hover:brightness-110 active:scale-[0.96]`, icon: _jsx("svg", { className: `w-4 h-4 drop-shadow-sm transition-transform duration-300 ${chevronRotated ? "rotate-180" : ""} shrink-0`, style: CHEVRON_STYLE, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2.5, d: "M15 19l-7-7 7-7" }) }) }));
 }

package/dist/_internal/server/jobs/handlers/_helpers.d.ts

@@ -10,5 +10,27 @@ export { getAdminRealtimeDb };
  * Query docs tagged isTestData:true in a collection. `cutoff: null` returns every
  * tester-sandbox doc regardless of expiry (manual force-purge); a real Date returns
  * only the ones past testDataExpiresAt (the scheduled 7-day sweep).
+ *
+ * ## 🛑 `isTestData` without `testDataExpiresAt` means PERMANENT, never purge
+ *
+ * The flag has two uses, and only one of them is a sandbox fixture:
+ *
+ *   · a fixture — `isTestData: true` PLUS `testDataExpiresAt`. Disposable,
+ *     swept on the 7-day cycle. Every doc in `features/tester/seed-data/` is
+ *     this shape; the invariant was checked across all six files.
+ *   · permanently hidden — `isTestData: true` and NO expiry. Real, permanent
+ *     content that simply must not reach the public or the sitemap.
+ *     `store-tester-qa-seller` is the case that forced this distinction.
+ *
+ * The scheduled path already separates them: `testDataExpiresAt <= cutoff`
+ * excludes docs lacking the field. The FORCE path did not — `cutoff: null`
+ * drops that clause and returned everything, so `tester:purge-sandbox --force`
+ * would have deleted a permanent seed store. Hence the filter below.
+ *
+ * Filtered in memory rather than as a query clause: a Firestore inequality on
+ * `testDataExpiresAt` would exclude every doc missing it, which is the trap
+ * documented in CLAUDE.md's anti-pattern table — correct here by luck, wrong
+ * the moment someone reuses the shape. In-memory keeps the intent legible, and
+ * the read is already bounded at 200.
  */
 export declare function getTestDataRefs(db: FirebaseFirestore.Firestore, collection: string, cutoff: Date | null): Promise<FirebaseFirestore.DocumentReference[]>;

package/dist/_internal/server/jobs/handlers/_helpers.js

@@ -22,6 +22,28 @@ export { getAdminRealtimeDb };
  * Query docs tagged isTestData:true in a collection. `cutoff: null` returns every
  * tester-sandbox doc regardless of expiry (manual force-purge); a real Date returns
  * only the ones past testDataExpiresAt (the scheduled 7-day sweep).
+ *
+ * ## 🛑 `isTestData` without `testDataExpiresAt` means PERMANENT, never purge
+ *
+ * The flag has two uses, and only one of them is a sandbox fixture:
+ *
+ *   · a fixture — `isTestData: true` PLUS `testDataExpiresAt`. Disposable,
+ *     swept on the 7-day cycle. Every doc in `features/tester/seed-data/` is
+ *     this shape; the invariant was checked across all six files.
+ *   · permanently hidden — `isTestData: true` and NO expiry. Real, permanent
+ *     content that simply must not reach the public or the sitemap.
+ *     `store-tester-qa-seller` is the case that forced this distinction.
+ *
+ * The scheduled path already separates them: `testDataExpiresAt <= cutoff`
+ * excludes docs lacking the field. The FORCE path did not — `cutoff: null`
+ * drops that clause and returned everything, so `tester:purge-sandbox --force`
+ * would have deleted a permanent seed store. Hence the filter below.
+ *
+ * Filtered in memory rather than as a query clause: a Firestore inequality on
+ * `testDataExpiresAt` would exclude every doc missing it, which is the trap
+ * documented in CLAUDE.md's anti-pattern table — correct here by luck, wrong
+ * the moment someone reuses the shape. In-memory keeps the intent legible, and
+ * the read is already bounded at 200.
  */
 export async function getTestDataRefs(db, collection, cutoff) {
     let q = db
@@ -30,5 +52,7 @@ export async function getTestDataRefs(db, collection, cutoff) {
     if (cutoff)
         q = q.where("testDataExpiresAt", "<=", cutoff);
     const snap = await q.limit(200).get();
-    return snap.docs.map((d) => d.ref);
+    return snap.docs
+        .filter((d) => cutoff !== null || d.get("testDataExpiresAt") != null)
+        .map((d) => d.ref);
 }

package/dist/_internal/shared/features/blog/schema.d.ts

@@ -4,7 +4,7 @@ export declare const blogPostInputSchema: z.ZodObject<{
     slug: z.ZodString;
     excerpt: z.ZodOptional<z.ZodString>;
     content: z.ZodString;
-    coverImage: z.ZodOptional<z.ZodString>;
+    coverImage: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     youtubeId: z.ZodOptional<z.ZodString>;
     category: z.ZodString;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
@@ -44,7 +44,7 @@ export declare const blogPostUpdateSchema: z.ZodObject<Omit<{
     slug: z.ZodOptional<z.ZodString>;
     excerpt: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     content: z.ZodOptional<z.ZodString>;
-    coverImage: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    coverImage: z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>>;
     youtubeId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     category: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;

package/dist/_internal/shared/features/blog/schema.js

@@ -1,11 +1,12 @@
 import { z } from "zod";
 import { BLOG_TITLE_MAX_LENGTH, BLOG_EXCERPT_MAX_LENGTH } from "./config";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 export const blogPostInputSchema = z.object({
     title: z.string().min(3).max(BLOG_TITLE_MAX_LENGTH),
     slug: z.string().min(1).regex(/^blog-[a-z0-9-]+$/, "Slug must start with 'blog-'"),
     excerpt: z.string().max(BLOG_EXCERPT_MAX_LENGTH).optional(),
     content: z.string().max(100000),
-    coverImage: z.string().url().optional(),
+    coverImage: mediaUrlSchema.optional(),
     youtubeId: z.string().optional(),
     category: z.string().min(1),
     tags: z.array(z.string()).max(10).default([]),

package/dist/_internal/shared/features/brands/schema.d.ts

@@ -3,7 +3,7 @@ export declare const brandInputSchema: z.ZodObject<{
     name: z.ZodString;
     slug: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
-    logoURL: z.ZodOptional<z.ZodString>;
+    logoURL: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     website: z.ZodOptional<z.ZodString>;
     country: z.ZodOptional<z.ZodString>;
     founded: z.ZodOptional<z.ZodNumber>;
@@ -34,7 +34,7 @@ export declare const brandUpdateSchema: z.ZodObject<Omit<{
     name: z.ZodOptional<z.ZodString>;
     slug: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
-    logoURL: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    logoURL: z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>>;
     website: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     country: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     founded: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;

package/dist/_internal/shared/features/brands/schema.js

@@ -1,10 +1,12 @@
 import { z } from "zod";
 import { BRAND_NAME_MAX_LENGTH, BRAND_DESCRIPTION_MAX_LENGTH } from "./config";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 export const brandInputSchema = z.object({
     name: z.string().min(1).max(BRAND_NAME_MAX_LENGTH),
     slug: z.string().min(1).regex(/^brand-[a-z0-9-]+$/, "Slug must start with 'brand-' and contain only lowercase letters, numbers, and hyphens"),
     description: z.string().max(BRAND_DESCRIPTION_MAX_LENGTH).optional(),
-    logoURL: z.string().url().optional(),
+    logoURL: mediaUrlSchema.optional(),
+    // `website` is a genuine EXTERNAL link, not stored media — stays `.url()`.
     website: z.string().url().optional(),
     country: z.string().optional(),
     founded: z.number().int().min(1800).max(new Date().getFullYear()).optional(),

package/dist/_internal/shared/features/categories/bundle-schemas.d.ts

@@ -60,7 +60,7 @@ export declare const bundleQueryRuleSchema: z.ZodDiscriminatedUnion<"type", [z.Z
     orderBy?: "price-asc" | "price-desc" | "createdAt-desc" | undefined;
 }>]>;
 export declare const bundleDisplaySchema: z.ZodObject<{
-    coverImage: z.ZodOptional<z.ZodString>;
+    coverImage: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     icon: z.ZodOptional<z.ZodString>;
     color: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
@@ -148,7 +148,7 @@ export declare const bundleCreateSchema: z.ZodObject<{
         drawCount?: number | undefined;
     }>, "many">>;
     display: z.ZodOptional<z.ZodObject<{
-        coverImage: z.ZodOptional<z.ZodString>;
+        coverImage: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
         icon: z.ZodOptional<z.ZodString>;
         color: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
@@ -295,7 +295,7 @@ export declare const bundleUpdateSchema: z.ZodObject<{
         drawCount?: number | undefined;
     }>, "many">>;
     display: z.ZodOptional<z.ZodObject<{
-        coverImage: z.ZodOptional<z.ZodString>;
+        coverImage: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
         icon: z.ZodOptional<z.ZodString>;
         color: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {

package/dist/_internal/shared/features/categories/bundle-schemas.js

@@ -9,6 +9,7 @@
  */
 import { z } from "zod";
 import { BUNDLE_MAX_ITEMS, BUNDLE_DRAW_COUNT_MAX, BUNDLE_KIND_SPECIAL, BUNDLE_KIND_BRAND, } from "./bundle-config";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 const productIdsSchema = z.array(z.string().min(1)).min(0).max(BUNDLE_MAX_ITEMS);
 /**
  * Per-member detail — mirrors BundleItemDetail in the Firestore schema.
@@ -39,7 +40,7 @@ export const bundleQueryRuleSchema = z.discriminatedUnion("type", [
     }),
 ]);
 export const bundleDisplaySchema = z.object({
-    coverImage: z.string().url().optional(),
+    coverImage: mediaUrlSchema.optional(),
     icon: z.string().optional(),
     color: z.string().optional(),
 });

package/dist/_internal/shared/features/events/schema.d.ts

@@ -8,7 +8,7 @@ export declare const eventInputSchema: z.ZodObject<{
     startsAt: z.ZodString;
     endsAt: z.ZodString;
     maxEntries: z.ZodOptional<z.ZodNumber>;
-    imageUrl: z.ZodOptional<z.ZodString>;
+    imageUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     location: z.ZodOptional<z.ZodString>;
     isOnline: z.ZodDefault<z.ZodBoolean>;
     entryFee: z.ZodDefault<z.ZodNumber>;
@@ -48,7 +48,7 @@ export declare const eventUpdateSchema: z.ZodObject<Omit<{
     startsAt: z.ZodOptional<z.ZodString>;
     endsAt: z.ZodOptional<z.ZodString>;
     maxEntries: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
-    imageUrl: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    imageUrl: z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>>;
     location: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     isOnline: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     entryFee: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;

package/dist/_internal/shared/features/events/schema.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { EVENT_TITLE_MAX_LENGTH, EVENT_DESCRIPTION_MAX_LENGTH } from "./config";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 export const eventInputSchema = z.object({
     title: z.string().min(3).max(EVENT_TITLE_MAX_LENGTH),
     slug: z.string().min(1).regex(/^event-[a-z0-9-]+$/, "Slug must start with 'event-'"),
@@ -9,7 +10,7 @@ export const eventInputSchema = z.object({
     startsAt: z.string().datetime({ offset: true }),
     endsAt: z.string().datetime({ offset: true }),
     maxEntries: z.number().int().min(1).optional(),
-    imageUrl: z.string().url().optional(),
+    imageUrl: mediaUrlSchema.optional(),
     location: z.string().max(300).optional(),
     isOnline: z.boolean().default(false),
     entryFee: z.number().min(0).default(0),

package/dist/_internal/shared/features/products/schema.d.ts

@@ -8,8 +8,8 @@ export declare const productInputSchema: z.ZodObject<{
     currency: z.ZodDefault<z.ZodString>;
     stockQuantity: z.ZodDefault<z.ZodNumber>;
     availableQuantity: z.ZodDefault<z.ZodNumber>;
-    mainImage: z.ZodString;
-    images: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    mainImage: z.ZodEffects<z.ZodString, string, string>;
+    images: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     seoTitle: z.ZodOptional<z.ZodString>;
@@ -81,8 +81,8 @@ export declare const productUpdateSchema: z.ZodObject<{
     currency: z.ZodOptional<z.ZodDefault<z.ZodString>>;
     stockQuantity: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     availableQuantity: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
-    mainImage: z.ZodOptional<z.ZodString>;
-    images: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
+    mainImage: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    images: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>>;
     condition: z.ZodOptional<z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]>>>;
     tags: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
     seoTitle: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -154,8 +154,8 @@ export declare const auctionInputSchema: z.ZodObject<{
     currency: z.ZodDefault<z.ZodString>;
     stockQuantity: z.ZodDefault<z.ZodNumber>;
     availableQuantity: z.ZodDefault<z.ZodNumber>;
-    mainImage: z.ZodString;
-    images: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    mainImage: z.ZodEffects<z.ZodString, string, string>;
+    images: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     seoTitle: z.ZodOptional<z.ZodString>;
@@ -255,8 +255,8 @@ export declare const preOrderInputSchema: z.ZodObject<{
     currency: z.ZodDefault<z.ZodString>;
     stockQuantity: z.ZodDefault<z.ZodNumber>;
     availableQuantity: z.ZodDefault<z.ZodNumber>;
-    mainImage: z.ZodString;
-    images: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    mainImage: z.ZodEffects<z.ZodString, string, string>;
+    images: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     seoTitle: z.ZodOptional<z.ZodString>;

package/dist/_internal/shared/features/products/schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 const priceSchema = z.number().min(0, "Price must be non-negative");
 const conditionSchema = z.enum(["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]);
 export const productInputSchema = z.object({
@@ -10,8 +11,8 @@ export const productInputSchema = z.object({
     currency: z.string().default("INR"),
     stockQuantity: z.number().int().min(0).default(0),
     availableQuantity: z.number().int().min(0).default(0),
-    mainImage: z.string().url("mainImage must be a valid URL"),
-    images: z.array(z.string().url()).max(20).default([]),
+    mainImage: mediaUrlSchema,
+    images: z.array(mediaUrlSchema).max(20).default([]),
     condition: conditionSchema.optional(),
     tags: z.array(z.string()).max(20).default([]),
     seoTitle: z.string().max(70).optional(),

package/dist/_internal/shared/features/reviews/schema.d.ts

@@ -5,7 +5,7 @@ export declare const createReviewSchema: z.ZodObject<{
     rating: z.ZodNumber;
     title: z.ZodString;
     comment: z.ZodString;
-    images: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    images: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     orderId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     title: string;

package/dist/_internal/shared/features/reviews/schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { mediaUrlSchema } from "../../../../validation/schemas";
 import { REVIEW_BODY_MAX_LENGTH, REVIEW_BODY_MIN_LENGTH, REVIEW_TITLE_MAX_LENGTH, REVIEW_MIN_RATING, REVIEW_MAX_RATING, REVIEW_IMAGES_MAX, REVIEW_REPLY_MAX_LENGTH, } from "./config";
 export const createReviewSchema = z.object({
     productId: z.string().min(1),
@@ -16,7 +17,7 @@ export const createReviewSchema = z.object({
      * never consulted it.
      */
     comment: z.string().min(REVIEW_BODY_MIN_LENGTH).max(REVIEW_BODY_MAX_LENGTH),
-    images: z.array(z.string().url()).max(REVIEW_IMAGES_MAX).default([]),
+    images: z.array(mediaUrlSchema).max(REVIEW_IMAGES_MAX).default([]),
     orderId: z.string().optional(),
 });
 export const replyToReviewSchema = z.object({

package/dist/_internal/shared/types/action-result.d.ts

@@ -14,8 +14,6 @@ export type ActionResult<T> = {
     code?: string;
     error: string;
     issues?: unknown[];
-    /** Legacy server-action shape — kept for compat. */
-    fieldErrors?: Record<string, string[]>;
     /** Legacy debug field — only populated in dev. */
     debug?: {
         stack?: string;

package/dist/client/api/surface-error.d.ts

@@ -18,6 +18,15 @@ export interface SurfaceErrorOptions {
     setFieldError?: (field: string, message: string) => void;
     /** next-intl style translator. Falls back to the raw error message when undefined. */
     translate?: (key: string) => string;
+    /**
+     * Curated copy preferred over `err.message` when the error carries no
+     * mapped display message. Lets a caller keep wording better than the raw
+     * server string WITHOUT adding a second toast of its own.
+     *
+     * Never overrides field-level `issues` — those are more specific than any
+     * caller-supplied sentence.
+     */
+    fallbackMessage?: string;
     /** Optional reporter for the clientErrors / serverErrors collection. */
     report?: (payload: {
         code: string;

package/dist/client/api/surface-error.js

@@ -1,5 +1,6 @@
 import { isApiError } from "./ApiError";
 import { ApiClientError } from "../../http/ApiClient";
+import { applyZodIssues, hasAttachableIssue } from "../../ui/forms/apply-zod-issues";
 import { normalizeError } from "../../errors/normalize";
 import { getErrorDisplay } from "../../errors/error-display-map";
 /** True for `ApiError` instances and for `ApiClientError` (the lower-level
@@ -9,11 +10,36 @@ import { getErrorDisplay } from "../../errors/error-display-map";
 function hasStableErrorCode(err) {
     return isApiError(err) || (err instanceof ApiClientError && typeof err.code === "string");
 }
+/** Field-level issues carried by either error shape, when present. */
+function issuesOf(err) {
+    if (isApiError(err))
+        return err.issues;
+    if (err instanceof ApiClientError)
+        return err.issues;
+    return undefined;
+}
 export function surfaceError(err, opts) {
-    const { showToast, setFieldError, translate, report } = opts;
+    const { showToast, setFieldError, translate, report, fallbackMessage } = opts;
+    // ISSUES FIRST. A validation failure names the fields it is about, and the
+    // right place for "photoURL must be …" is under the photoURL input — not a
+    // toast that says "Validation failed" and nothing else.
+    //
+    // This branch could not fire before: `errorResponse` serialised Zod issues
+    // under a `details` key that `ApiClientError` never read, so `err.issues`
+    // was always undefined and every schema rejection on every route fell
+    // through to the generic toast below.
+    //
+    // `ERROR_DISPLAY_MAP` deliberately has no `field` for VALIDATION_FAILED —
+    // a validation failure is not tied to one fixed field, which is exactly why
+    // the routing has to come from the issues themselves.
+    const issues = issuesOf(err);
+    if (setFieldError && hasAttachableIssue(issues)) {
+        applyZodIssues(issues, (name, message) => setFieldError(name, message ?? ""));
+        return; // inline errors only — no toast
+    }
     if (hasStableErrorCode(err)) {
         const display = getErrorDisplay(err.code);
-        const message = translate?.(display.messageKey) ?? err.message;
+        const message = translate?.(display.messageKey) ?? fallbackMessage ?? err.message;
         if (display.field && setFieldError) {
             setFieldError(display.field, message);
             return;
@@ -24,7 +50,7 @@ export function surfaceError(err, opts) {
     // Non-ApiError — this is a programming error or unhandled exception.
     // Report it (workstream 13) so clientErrors picks it up.
     const message = err instanceof Error ? err.message : "Something went wrong. Please try again.";
-    const fallback = translate?.("errors.codes.CLIENT_UNHANDLED") ?? message;
+    const fallback = fallbackMessage ?? translate?.("errors.codes.CLIENT_UNHANDLED") ?? message;
     showToast(fallback, "error");
     if (report) {
         try {

package/dist/client/api/useApiMutation.d.ts

@@ -16,6 +16,16 @@ export interface UseApiMutationOptions<TData, TError, TVariables, TContext> exte
     /** When set, a `loading` toast is shown on mutate and finalized on settle. */
     loadingMessage?: string;
     successMessage?: string;
+    /**
+     * Curated failure copy, preferred over `err.message` by the ONE surface.
+     *
+     * Exists so a caller with wording better than the raw server message
+     * ("Could not mark notification as read.") does not have to add a second
+     * toast in its own `onError` to say it — which is what produced two and
+     * three stacked banners for a single failure. A server error that carries
+     * field `issues` still wins: those route to inline field errors.
+     */
+    errorMessage?: string;
     /** Translation function (next-intl style); falls back to raw message. */
     translate?: (key: string) => string;
     /** Form field error setter (FormShell context). Optional. */

package/dist/client/api/useApiMutation.js

@@ -6,7 +6,7 @@ import { surfaceError } from "./surface-error";
 export function useApiMutation(options) {
     const { showToast, updateToast } = useToast();
     const loadingIdRef = React.useRef(null);
-    const { loadingMessage, successMessage, translate, setFieldError, reportClientError, onMutate, onError, onSuccess, onSettled, ...rest } = options;
+    const { loadingMessage, successMessage, errorMessage, translate, setFieldError, reportClientError, onMutate, onError, onSuccess, onSettled, ...rest } = options;
     return useMutation({
         ...rest,
         onMutate: (async (variables, ctx) => {
@@ -20,6 +20,7 @@ export function useApiMutation(options) {
                 showToast,
                 setFieldError,
                 translate,
+                fallbackMessage: errorMessage,
                 report: reportClientError,
             });
             onError?.(err, variables, context, ctx);

package/dist/core/server-action.d.ts

@@ -1,15 +1,5 @@
-export type ActionResult<TOutput> = {
-    ok: true;
-    data: TOutput;
-} | {
-    ok: false;
-    error: string;
-    code?: string;
-    fieldErrors?: Record<string, string[]>;
-    debug?: {
-        stack?: string;
-    };
-};
+export type { ActionResult } from "../_internal/shared/types/action-result";
+import type { ActionResult } from "../_internal/shared/types/action-result";
 export interface ActionMiddlewareContext<TInput = unknown, TOutput = unknown> {
     actionName: string;
     input: TInput;
@@ -50,7 +40,7 @@ export interface ServerActionOptions<TInput, TOutput> {
     name?: string;
     /**
      * Zod-compatible schema for input validation.
-     * If validation fails, returns `{ ok: false, fieldErrors }` before the handler runs.
+     * If validation fails, returns `{ ok: false, issues }` before the handler runs.
      */
     schema?: SafeParseSchema<TInput>;
     /**
@@ -79,4 +69,3 @@ export interface ServerActionOptions<TInput, TOutput> {
  * and can be exported directly from an `actions/` file.
  */
 export declare function createServerAction<TInput = unknown, TOutput = unknown>(options: ServerActionOptions<TInput, TOutput>): (rawInput: TInput) => Promise<ActionResult<TOutput>>;
-export {};

package/dist/core/server-action.js

@@ -1,4 +1,6 @@
 import { normalizeError } from "../errors/normalize";
+import { toApiIssues } from "../errors/error-envelope";
+import { HTTP_ERROR_CODES } from "../errors/error-mapping";
 /**
  * createServerAction — @mohasinac/appkit/core
  *
@@ -65,8 +67,15 @@ export function createServerAction(options) {
         if (options.schema) {
             const parsed = options.schema.safeParse(rawInput);
             if (!parsed.success) {
-                const fieldErrors = parsed.error.flatten?.().fieldErrors ?? {};
-                return { ok: false, error: "Validation failed", fieldErrors };
+                // `issues` (not the old `fieldErrors`, which had zero readers) so a
+                // server action's validation failure routes to inline field errors
+                // through the same path an HTTP route's does.
+                return {
+                    ok: false,
+                    error: "Validation failed",
+                    code: HTTP_ERROR_CODES.VALIDATION_FAILED,
+                    issues: toApiIssues(parsed.error.issues),
+                };
             }
             input = parsed.data;
         }

package/dist/errors/error-envelope.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The ONE shape of an HTTP error body.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * There were four independent producers of an error response, and the client
+ * read a shape none of them fully emitted:
+ *
+ *   - `next/api/api-response.ts`  → `{success, error, details}`  — no `code`
+ *   - `next/api/routeHandler.ts`  → `{ok, success, code, error, issues, requestId}`
+ *   - `errors/error-handler.ts`   → `{..., data: {issues}}`      — issues nested
+ *   - `core/server-action.ts`     → `{ok, error, fieldErrors}`
+ *
+ * while `http/ApiClient.ts`'s `ApiClientError` reads exactly three keys off the
+ * body: `code`, `issues`, `requestId`.
+ *
+ * The consequence was silent and app-wide. On every route built with
+ * `createApiHandler`, a Zod rejection serialised its issues under `details`,
+ * which nothing reads — so `err.code` was `undefined`, `surfaceError`'s
+ * `hasStableErrorCode()` check failed, the `ERROR_DISPLAY_MAP` branch was
+ * skipped, and the user got a bare toast reading "Validation failed" with no
+ * field name. `applyZodIssues(err.issues, …)` was dead code everywhere.
+ *
+ * Every producer now builds its body here, so the wire shape and the reader
+ * cannot drift again. `scripts/audit-api-error-envelope.mjs` enforces it in
+ * both directions.
+ */
+import type { ApiIssue } from "../client/api/ApiError";
+export interface ApiErrorEnvelope {
+    ok: false;
+    /**
+     * @deprecated Mirrors `ok` for consumers that still read `body.success`.
+     * `audit-server-action-envelope.mjs` is designed to start failing once the
+     * last reader is gone, at which point this key is removed.
+     */
+    success: false;
+    code: string;
+    error: string;
+    issues?: ApiIssue[];
+    requestId?: string;
+}
+/**
+ * Default stable code for an HTTP status, for producers that don't carry one.
+ *
+ * Mirrors the mapping already applied in `mapToHttpError`'s status branch —
+ * extracted so there is one table rather than two that can disagree about
+ * what a 409 is called.
+ */
+export declare function codeForStatus(status: number): string;
+/**
+ * Narrow raw Zod issues to the wire shape.
+ *
+ * Deliberately picks ONLY `path`, `message` and `code`. A `ZodIssue` can also
+ * carry `received` / `expected` / `unionErrors`, and `received` is the value
+ * the user actually submitted — i.e. potentially their email, phone or
+ * address. Spreading the issue wholesale would publish that in an error body
+ * and into any client-error log that captures it.
+ *
+ * The `unknown` parameter is the point: this is the sole entry point for issue
+ * arrays arriving from THREE mutually unassignable sources — zod v3
+ * `ZodIssue[]` (appkit), zod v4 `$ZodIssue[]` (the consumer app, a different
+ * major), and the `unknown[]` that `mapToHttpError` already returns. Narrowing
+ * it to any one of them makes the other two uncallable. This function exists
+ * precisely to be the place that narrows.
+ */
+export declare function toApiIssues(input: unknown): ApiIssue[] | undefined;
+export declare function buildErrorEnvelope(input: {
+    message: string;
+    status?: number;
+    code?: string;
+    issues?: ApiIssue[];
+    requestId?: string;
+}): ApiErrorEnvelope;