@mohasinac/appkit 2.8.9 → 3.0.0

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

@@ -44,8 +44,8 @@ export declare const createCouponSchema: z.ZodObject<{
         perUserLimit: number;
         totalLimit?: number | undefined;
     }, {
-        perUserLimit?: number | undefined;
         totalLimit?: number | undefined;
+        perUserLimit?: number | undefined;
     }>;
     validity: z.ZodObject<{
         startDate: z.ZodString;
@@ -77,8 +77,8 @@ export declare const createCouponSchema: z.ZodObject<{
         applicableCategories?: string[] | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     code: string;
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     name: string;
     scope: "seller" | "admin";
     discount: {
@@ -103,8 +103,8 @@ export declare const createCouponSchema: z.ZodObject<{
         applicableCategories?: string[] | undefined;
     } | undefined;
 }, {
-    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     code: string;
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     name: string;
     scope: "seller" | "admin";
     discount: {
@@ -113,8 +113,8 @@ export declare const createCouponSchema: z.ZodObject<{
         minPurchase?: number | undefined;
     };
     usage: {
-        perUserLimit?: number | undefined;
         totalLimit?: number | undefined;
+        perUserLimit?: number | undefined;
     };
     validity: {
         endDate: string;
@@ -155,8 +155,8 @@ export declare const updateCouponSchema: z.ZodObject<Omit<{
         perUserLimit: number;
         totalLimit?: number | undefined;
     }, {
-        perUserLimit?: number | undefined;
         totalLimit?: number | undefined;
+        perUserLimit?: number | undefined;
     }>>;
     validity: z.ZodOptional<z.ZodObject<{
         startDate: z.ZodString;
@@ -223,8 +223,8 @@ export declare const updateCouponSchema: z.ZodObject<Omit<{
         minPurchase?: number | undefined;
     } | undefined;
     usage?: {
-        perUserLimit?: number | undefined;
         totalLimit?: number | undefined;
+        perUserLimit?: number | undefined;
     } | undefined;
     validity?: {
         endDate: string;

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

@@ -28,11 +28,11 @@ export declare const replyToReviewSchema: z.ZodObject<{
     reviewId: z.ZodString;
     reply: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    reviewId: string;
     reply: string;
-}, {
     reviewId: string;
+}, {
     reply: string;
+    reviewId: string;
 }>;
 export declare const deleteReviewSchema: z.ZodObject<{
     reviewId: z.ZodString;

package/dist/_internal/shared/listing-types/action-tracker.d.ts

@@ -1,3 +1,4 @@
+import type { FirestoreDocument } from "@mohasinac/appkit";
 /**
  * Action telemetry sink — SB-UNI-X5 2026-05-13.
  *
@@ -20,7 +21,7 @@ export interface ActionEvent {
     /** Stable id from the CTA registry (e.g. "product.add-to-cart"). */
     actionId: string;
     /** Contextual payload — resource id, listingType, store, etc. */
-    ctx?: Record<string, unknown>;
+    ctx?: FirestoreDocument;
     /** Result of the action — undefined when not yet known. */
     success?: boolean;
     /** ISO timestamp of the emission. */
@@ -33,7 +34,7 @@ export declare const actionTracker: {
      * never blocks the caller. Consumers wrap critical paths in try/catch
      * even though sinks must self-handle errors.
      */
-    emit(actionId: string, ctx?: Record<string, unknown>, success?: boolean): void;
+    emit(actionId: string, ctx?: FirestoreDocument, success?: boolean): void;
 };
 /** Replace the default sink — useful for Sentry/GA/custom telemetry. */
 export declare function setActionTrackerSink(sink: ActionTrackerSink): void;

package/dist/_internal/shared/listing-types/action-tracker.js

@@ -1,21 +1,3 @@
-/**
- * Action telemetry sink — SB-UNI-X5 2026-05-13.
- *
- * Pure-JS wrapper that Phase 7 (W-1 CTA registry) extends. Today the sink
- * is a no-op in development and a structured-event emitter in production
- * (writes to the `events` analytics stream OR an external sink configured
- * via env). The Phase 7 `<Button action={...}>` extension calls
- * `actionTracker.emit(action.id, ctx, success)` on click + outcome.
- *
- * Designed so a future telemetry consumer (Sentry, GA, custom) drops in by
- * replacing the `sink` impl via `setActionTrackerSink`. Default sink is
- * environment-aware:
- *   - SSR / Node + `NODE_ENV !== "production"` → console.debug
- *   - Browser + `NODE_ENV === "production"` → POST to /api/telemetry/actions
- *     (no-op when the endpoint isn't deployed yet — silently logs to console)
- *
- * Pattern 7 from the SB-UNI future-expansion plan.
- */
 function defaultSink(event) {
     if (typeof window === "undefined") {
         // SSR / Node — best-effort console log; production servers can swap

package/dist/_internal/shared/listing-types/cart-shipping.d.ts

@@ -16,7 +16,7 @@
  *
  *  - `cartIsChatOnly(items)` — does EVERY line have
  *    `canAddToCart === false`? Lets the cart UI surface "this product
- *    can only be reached via chat" when classified items somehow make it
+ * can only be reached via chat" when classified items somehow make it
  *    through (defence-in-depth — addToCart already rejects them).
  *
  * Used by both checkout server actions (skip address validation when

package/dist/_internal/shared/listing-types/cart-shipping.js

@@ -16,7 +16,7 @@
  *
  *  - `cartIsChatOnly(items)` — does EVERY line have
  *    `canAddToCart === false`? Lets the cart UI surface "this product
- *    can only be reached via chat" when classified items somehow make it
+ * can only be reached via chat" when classified items somehow make it
  *    through (defence-in-depth — addToCart already rejects them).
  *
  * Used by both checkout server actions (skip address validation when

package/dist/_internal/shared/serialization/index.js

@@ -16,12 +16,15 @@ export function toClient(value) {
     // Firestore Timestamp duck-type — `.toDate()` returns a JS Date.
     const maybeTs = value;
     if (typeof maybeTs.toDate === "function") {
+        // audit-unknown-ok: TS structural escape — generic param
         return maybeTs.toDate().toISOString();
     }
     if (value instanceof Date) {
+        // audit-unknown-ok: TS structural escape — generic param
         return value.toISOString();
     }
     if (Array.isArray(value)) {
+        // audit-unknown-ok: TS structural escape — generic param
         return value.map((v) => toClient(v));
     }
     const out = {};
@@ -30,6 +33,7 @@ export function toClient(value) {
             continue;
         out[k] = toClient(v);
     }
+    // audit-unknown-ok: TS structural escape — generic param
     return out;
 }
 /**

package/dist/_internal/shared/styles/grid.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Grid className tokens — extracted from `THEME_CONSTANTS.grid` and
+ * `THEME_CONSTANTS.card` during Phase 8 of the Theme/Tokens/Variants refactor.
+ * Used by homepage hero / advertisement / character-hotspot sections that
+ * still author raw grid className strings rather than the typed `<Grid cols=…>`
+ * primitive. A subsequent sweep can migrate each to the variant.
+ */
+export declare const GRID_COLS_2_MD = "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-2 xl:grid-cols-2 2xl:grid-cols-2";
+export declare const GRID_COLS_6_LG = "grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6";
+export declare const CARD_ASPECT_BANNER = "aspect-[4/3] md:aspect-auto";
+/** Vertical stack spacing — `space-y-4 sm:space-y-6`. */
+export declare const SPACING_STACK = "space-y-4 sm:space-y-6";

package/dist/_internal/shared/styles/grid.js

@@ -0,0 +1,12 @@
+/**
+ * Grid className tokens — extracted from `THEME_CONSTANTS.grid` and
+ * `THEME_CONSTANTS.card` during Phase 8 of the Theme/Tokens/Variants refactor.
+ * Used by homepage hero / advertisement / character-hotspot sections that
+ * still author raw grid className strings rather than the typed `<Grid cols=…>`
+ * primitive. A subsequent sweep can migrate each to the variant.
+ */
+export const GRID_COLS_2_MD = "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-2 xl:grid-cols-2 2xl:grid-cols-2";
+export const GRID_COLS_6_LG = "grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6";
+export const CARD_ASPECT_BANNER = "aspect-[4/3] md:aspect-auto";
+/** Vertical stack spacing — `space-y-4 sm:space-y-6`. */
+export const SPACING_STACK = "space-y-4 sm:space-y-6";

package/dist/_internal/shared/styles/page.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Page container className tokens — appkit-internal mirror of the consumer-
+ * side `src/constants/styles/page.ts` extracted during Phase 8 of the
+ * Theme/Tokens/Variants refactor. Replaces `THEME_CONSTANTS.page.container.*`
+ * for residual about / homepage / public view callsites that still wrap
+ * layout in raw className strings rather than a typed `<Container size=…>`
+ * primitive. A subsequent sweep can migrate each callsite to the variant.
+ */
+export declare const PAGE_CONTAINER: {
+    /** `max-w-3xl` — blog / policy */
+    readonly sm: "max-w-3xl mx-auto px-4 sm:px-6 lg:px-8";
+    /** `max-w-4xl` — contact / about */
+    readonly md: "max-w-4xl mx-auto px-4 sm:px-6 lg:px-8";
+    /** `max-w-5xl` — checkout / help */
+    readonly lg: "max-w-5xl mx-auto px-4 sm:px-6 lg:px-8";
+    /** `max-w-6xl` — product detail / cart */
+    readonly xl: "max-w-6xl mx-auto px-4 sm:px-6 lg:px-8";
+    /** `max-w-7xl` — main content grids */
+    readonly "2xl": "max-w-7xl mx-auto px-4 sm:px-6 lg:px-8";
+};

package/dist/_internal/shared/styles/page.js

@@ -0,0 +1,20 @@
+/**
+ * Page container className tokens — appkit-internal mirror of the consumer-
+ * side `src/constants/styles/page.ts` extracted during Phase 8 of the
+ * Theme/Tokens/Variants refactor. Replaces `THEME_CONSTANTS.page.container.*`
+ * for residual about / homepage / public view callsites that still wrap
+ * layout in raw className strings rather than a typed `<Container size=…>`
+ * primitive. A subsequent sweep can migrate each callsite to the variant.
+ */
+export const PAGE_CONTAINER = {
+    /** `max-w-3xl` — blog / policy */
+    sm: "max-w-3xl mx-auto px-4 sm:px-6 lg:px-8",
+    /** `max-w-4xl` — contact / about */
+    md: "max-w-4xl mx-auto px-4 sm:px-6 lg:px-8",
+    /** `max-w-5xl` — checkout / help */
+    lg: "max-w-5xl mx-auto px-4 sm:px-6 lg:px-8",
+    /** `max-w-6xl` — product detail / cart */
+    xl: "max-w-6xl mx-auto px-4 sm:px-6 lg:px-8",
+    /** `max-w-7xl` — main content grids */
+    "2xl": "max-w-7xl mx-auto px-4 sm:px-6 lg:px-8",
+};

package/dist/_internal/shared/styles/skeleton.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Skeleton className tokens — extracted from `THEME_CONSTANTS.skeleton`
+ * during Phase 8 of the Theme/Tokens/Variants refactor. Used by homepage /
+ * carousel skeleton-state components. Two variants: pulse (animate-pulse) +
+ * shimmer (animate-shimmer + gradient).
+ */
+export declare const SKELETON: {
+    readonly base: "animate-pulse rounded bg-zinc-200 dark:bg-slate-700/60";
+    readonly text: "animate-pulse rounded bg-zinc-200 dark:bg-slate-700/60 h-4";
+    readonly heading: "animate-pulse rounded bg-zinc-200 dark:bg-slate-700/60 h-7";
+    readonly image: "animate-pulse rounded-xl bg-zinc-200 dark:bg-slate-700/60";
+    readonly card: "animate-pulse rounded-2xl bg-zinc-200 dark:bg-slate-700/60";
+    readonly shimmer: "animate-shimmer bg-[length:400%_100%] rounded bg-gradient-to-r from-zinc-200 via-zinc-100 to-zinc-200 dark:from-slate-800 dark:via-slate-700/60 dark:to-slate-800";
+    readonly shimmerText: "animate-shimmer bg-[length:400%_100%] h-4 rounded bg-gradient-to-r from-zinc-200 via-zinc-100 to-zinc-200 dark:from-slate-800 dark:via-slate-700/60 dark:to-slate-800";
+    readonly shimmerCard: "animate-shimmer bg-[length:400%_100%] rounded-2xl bg-gradient-to-r from-zinc-200 via-zinc-100 to-zinc-200 dark:from-slate-800 dark:via-slate-700/60 dark:to-slate-800";
+};

package/dist/_internal/shared/styles/skeleton.js

@@ -0,0 +1,18 @@
+/**
+ * Skeleton className tokens — extracted from `THEME_CONSTANTS.skeleton`
+ * during Phase 8 of the Theme/Tokens/Variants refactor. Used by homepage /
+ * carousel skeleton-state components. Two variants: pulse (animate-pulse) +
+ * shimmer (animate-shimmer + gradient).
+ */
+export const SKELETON = {
+    // Pulse (fade) variant
+    base: "animate-pulse rounded bg-zinc-200 dark:bg-slate-700/60",
+    text: "animate-pulse rounded bg-zinc-200 dark:bg-slate-700/60 h-4",
+    heading: "animate-pulse rounded bg-zinc-200 dark:bg-slate-700/60 h-7",
+    image: "animate-pulse rounded-xl bg-zinc-200 dark:bg-slate-700/60",
+    card: "animate-pulse rounded-2xl bg-zinc-200 dark:bg-slate-700/60",
+    // Shimmer (sweep) variant
+    shimmer: "animate-shimmer bg-[length:400%_100%] rounded bg-gradient-to-r from-zinc-200 via-zinc-100 to-zinc-200 dark:from-slate-800 dark:via-slate-700/60 dark:to-slate-800",
+    shimmerText: "animate-shimmer bg-[length:400%_100%] h-4 rounded bg-gradient-to-r from-zinc-200 via-zinc-100 to-zinc-200 dark:from-slate-800 dark:via-slate-700/60 dark:to-slate-800",
+    shimmerCard: "animate-shimmer bg-[length:400%_100%] rounded-2xl bg-gradient-to-r from-zinc-200 via-zinc-100 to-zinc-200 dark:from-slate-800 dark:via-slate-700/60 dark:to-slate-800",
+};

package/dist/_internal/shared/styles/themed.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Themed className tokens — appkit-internal mirror of the consumer-side
+ * `src/constants/styles/themed.ts` extracted during Phase 8 of the
+ * Theme/Tokens/Variants refactor. These are dark-mode-aware Tailwind class
+ * pairs replacing the legacy `THEME_CONSTANTS.themed.*` lookups. A
+ * subsequent sweep migrates each callsite to a primitive `surface` /
+ * `color` / `border` variant.
+ */
+export declare const THEMED_BG_PRIMARY = "bg-zinc-50 dark:bg-slate-950";
+export declare const THEMED_BG_SECONDARY = "bg-zinc-100 dark:bg-slate-900";
+export declare const THEMED_BG_TERTIARY = "bg-zinc-200 dark:bg-slate-800";
+export declare const THEMED_BORDER = "border-zinc-200 dark:border-slate-700";
+export declare const THEMED_BORDER_STRONG = "border-zinc-300 dark:border-slate-600";
+export declare const THEMED_TEXT_PRIMARY = "text-zinc-900 dark:text-zinc-50";
+export declare const THEMED_TEXT_SECONDARY = "text-zinc-500 dark:text-zinc-400";
+export declare const THEMED_TEXT_TERTIARY = "text-zinc-400 dark:text-zinc-500";
+export declare const THEMED_TEXT_MUTED = "text-zinc-400 dark:text-zinc-400";
+export declare const THEMED_TEXT_SUCCESS = "text-emerald-600 dark:text-emerald-400";
+export declare const THEMED_TEXT_WARNING = "text-amber-600 dark:text-amber-400";
+export declare const THEMED_TEXT_ERROR = "text-red-600 dark:text-red-400";
+export declare const FLEX_CENTER = "flex items-center justify-center";
+export declare const FLEX_BETWEEN = "flex items-center justify-between";
+export declare const FLEX_START = "flex items-center justify-start";
+export declare const FLEX_ROW = "flex items-center";
+export declare const FLEX_COL = "flex flex-col";
+export declare const FLEX_COL_CENTER = "flex flex-col items-center justify-center";

package/dist/_internal/shared/styles/themed.js

@@ -0,0 +1,29 @@
+/**
+ * Themed className tokens — appkit-internal mirror of the consumer-side
+ * `src/constants/styles/themed.ts` extracted during Phase 8 of the
+ * Theme/Tokens/Variants refactor. These are dark-mode-aware Tailwind class
+ * pairs replacing the legacy `THEME_CONSTANTS.themed.*` lookups. A
+ * subsequent sweep migrates each callsite to a primitive `surface` /
+ * `color` / `border` variant.
+ */
+export const THEMED_BG_PRIMARY = "bg-zinc-50 dark:bg-slate-950";
+export const THEMED_BG_SECONDARY = "bg-zinc-100 dark:bg-slate-900";
+export const THEMED_BG_TERTIARY = "bg-zinc-200 dark:bg-slate-800";
+export const THEMED_BORDER = "border-zinc-200 dark:border-slate-700";
+export const THEMED_BORDER_STRONG = "border-zinc-300 dark:border-slate-600";
+export const THEMED_TEXT_PRIMARY = "text-zinc-900 dark:text-zinc-50";
+export const THEMED_TEXT_SECONDARY = "text-zinc-500 dark:text-zinc-400";
+export const THEMED_TEXT_TERTIARY = "text-zinc-400 dark:text-zinc-500";
+export const THEMED_TEXT_MUTED = "text-zinc-400 dark:text-zinc-400";
+// audit-semantic-color-ok: these constants ARE the semantic token definitions
+export const THEMED_TEXT_SUCCESS = "text-emerald-600 dark:text-emerald-400";
+// audit-semantic-color-ok: these constants ARE the semantic token definitions
+export const THEMED_TEXT_WARNING = "text-amber-600 dark:text-amber-400";
+// audit-semantic-color-ok: these constants ARE the semantic token definitions
+export const THEMED_TEXT_ERROR = "text-red-600 dark:text-red-400";
+export const FLEX_CENTER = "flex items-center justify-center";
+export const FLEX_BETWEEN = "flex items-center justify-between";
+export const FLEX_START = "flex items-center justify-start";
+export const FLEX_ROW = "flex items-center";
+export const FLEX_COL = "flex flex-col";
+export const FLEX_COL_CENTER = "flex flex-col items-center justify-center";

package/dist/_internal/shared/tokens/index.d.ts

@@ -7,7 +7,7 @@
  * CSS custom properties (--appkit-color-primary, etc.) are injected at runtime
  * by LayoutShellClient from siteSettings.theme, overriding these TS defaults.
  */
-export { COLORS, RADIUS, SHADOWS, Z_INDEX, THEME_CONSTANTS, LAYOUT, FLUID_GRID_MIN_WIDTHS, LOCALE_CONFIG, TOKENS, token, } from "../../../tokens/index";
+export { COLORS, RADIUS, SHADOWS, Z_INDEX, LAYOUT, FLUID_GRID_MIN_WIDTHS, LOCALE_CONFIG, TOKENS, token, } from "../../../tokens/index";
 export declare const SEMANTIC_COLORS: {
     readonly primary: "#84e122";
     readonly primaryMuted: "#e4ffc5";

package/dist/_internal/shared/tokens/index.js

@@ -8,7 +8,7 @@
  * by LayoutShellClient from siteSettings.theme, overriding these TS defaults.
  */
 // Re-export raw token sets for consumers that need JS values (charting, canvas)
-export { COLORS, RADIUS, SHADOWS, Z_INDEX, THEME_CONSTANTS, LAYOUT, FLUID_GRID_MIN_WIDTHS, LOCALE_CONFIG, TOKENS, token, } from "../../../tokens/index";
+export { COLORS, RADIUS, SHADOWS, Z_INDEX, LAYOUT, FLUID_GRID_MIN_WIDTHS, LOCALE_CONFIG, TOKENS, token, } from "../../../tokens/index";
 import { COLORS, RADIUS, SHADOWS, Z_INDEX } from "../../../tokens/index";
 // ---------------------------------------------------------------------------
 // Semantic color aliases — never reference COLORS.primary directly in components

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

@@ -0,0 +1 @@
+export {};

package/dist/_internal/shared/types/__tests__/action-result.test.js

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { wrapAction, isOk, unwrap } from "../action-result";
+import { ValidationError } from "../../../../errors/validation-error";
+import { NotFoundError } from "../../../../errors/not-found-error";
+describe("wrapAction", () => {
+    it("returns ok envelope on success", async () => {
+        const r = await wrapAction(async () => 42);
+        expect(r.ok).toBe(true);
+        if (r.ok)
+            expect(r.data).toBe(42);
+    });
+    it("returns error envelope on thrown ValidationError → VALIDATION_FAILED", async () => {
+        const r = await wrapAction(async () => {
+            throw new ValidationError("bad");
+        });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.code).toBe("VALIDATION_FAILED");
+            expect(r.error).toBe("bad");
+        }
+    });
+    it("returns error envelope on thrown NotFoundError → NOT_FOUND", async () => {
+        const r = await wrapAction(async () => {
+            throw new NotFoundError("user-1");
+        });
+        expect(r.ok).toBe(false);
+        if (!r.ok)
+            expect(r.code).toBe("NOT_FOUND");
+    });
+    it("returns error envelope on unknown Error → INTERNAL", async () => {
+        const r = await wrapAction(async () => {
+            throw new Error("oops");
+        });
+        expect(r.ok).toBe(false);
+        if (!r.ok)
+            expect(r.code).toBe("INTERNAL");
+    });
+    it("never throws — string throws also produce an envelope", async () => {
+        const r = await wrapAction(async () => {
+            throw "raw string";
+        });
+        expect(r.ok).toBe(false);
+    });
+});
+describe("isOk", () => {
+    it("narrows ok arm", async () => {
+        const r = await wrapAction(async () => "x");
+        if (isOk(r)) {
+            // type narrowed — `data` accessible
+            expect(r.data).toBe("x");
+        }
+    });
+});
+describe("unwrap", () => {
+    it("returns data on ok", async () => {
+        const r = await wrapAction(async () => 7);
+        expect(unwrap(r)).toBe(7);
+    });
+    it("throws on error", async () => {
+        const r = await wrapAction(async () => {
+            throw new ValidationError("bad");
+        });
+        expect(() => unwrap(r)).toThrow("bad");
+    });
+});

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

@@ -0,0 +1,49 @@
+/**
+ * Uniform envelope shape — emitted by every HTTP route, every server action,
+ * and consumed by the client ApiClient. Discriminated by `ok`.
+ *
+ * Mirrors the response shape of `createRouteHandler` so server actions and
+ * routes can be migrated through the same client surface (useApiMutation).
+ */
+export type ActionResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    /** Stable error code from ERROR_DISPLAY_MAP. Optional for compat with the legacy core/server-action envelope. */
+    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;
+    };
+    requestId?: string;
+};
+/**
+ * Wrap a server-action body so any thrown error is converted into the
+ * standard `{ ok: false, code, error, issues? }` envelope via `mapToHttpError`.
+ *
+ * Usage:
+ * ```ts
+ * "use server";
+ * export async function placeBidAction(input: BidInput): Promise<ActionResult<BidPlaced>> {
+ * return wrapAction(async () => {
+ * const parsed = bidSchema.parse(input);
+ * return await bidRepository.place(parsed);
+ * });
+ * }
+ * ```
+ *
+ * `wrapAction` itself never throws. Callers can rely on the returned envelope.
+ */
+export declare function wrapAction<T>(fn: () => Promise<T>): Promise<ActionResult<T>>;
+/** Type guard for ActionResult success arm. */
+export declare function isOk<T>(result: ActionResult<T>): result is {
+    ok: true;
+    data: T;
+};
+/** Throw if the envelope is a failure. Useful for code that wants the legacy throw semantics. */
+export declare function unwrap<T>(result: ActionResult<T>): T;

package/dist/_internal/shared/types/action-result.js

@@ -0,0 +1,47 @@
+import { normalizeError } from "../../../errors/normalize";
+import { mapToHttpError } from "../../../errors/error-mapping";
+/**
+ * Wrap a server-action body so any thrown error is converted into the
+ * standard `{ ok: false, code, error, issues? }` envelope via `mapToHttpError`.
+ *
+ * Usage:
+ * ```ts
+ * "use server";
+ * export async function placeBidAction(input: BidInput): Promise<ActionResult<BidPlaced>> {
+ * return wrapAction(async () => {
+ * const parsed = bidSchema.parse(input);
+ * return await bidRepository.place(parsed);
+ * });
+ * }
+ * ```
+ *
+ * `wrapAction` itself never throws. Callers can rely on the returned envelope.
+ */
+export async function wrapAction(fn) {
+    try {
+        const data = await fn();
+        return { ok: true, data };
+    }
+    catch (err) {
+        void normalizeError(err);
+        const mapped = mapToHttpError(err, {
+            isProduction: process.env.NODE_ENV === "production",
+        });
+        return {
+            ok: false,
+            code: mapped.code,
+            error: mapped.message,
+            ...(mapped.issues ? { issues: mapped.issues } : {}),
+        };
+    }
+}
+/** Type guard for ActionResult success arm. */
+export function isOk(result) {
+    return result.ok === true;
+}
+/** Throw if the envelope is a failure. Useful for code that wants the legacy throw semantics. */
+export function unwrap(result) {
+    if (result.ok)
+        return result.data;
+    throw Object.assign(new Error(result.error), { code: result.code });
+}

package/dist/cli/index.d.ts

@@ -15,12 +15,13 @@
  *   const messages = await mergeFeatureMessages(locale, features);
  */
 import type { FeaturesConfig } from "../contracts";
+import type { JsonValue } from "@mohasinac/appkit";
 export type { FeaturesConfig };
 export interface NextConfig {
     transpilePackages?: string[];
     [key: string]: unknown;
 }
-type Messages = Record<string, unknown>;
+type Messages = Record<string, JsonValue>;
 /** Maps feature config key → appkit sub-path (for documentation / future use) */
 export declare const FEATURE_SUBPATH_MAP: Record<string, string>;
 /**

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

@@ -0,0 +1,18 @@
+/**
+ * Client-side error class thrown by apiClient / surfaceError. Carries the
+ * server's stable `code`, the HTTP status, and any Zod issues so wrappers
+ * can route the failure (toast vs inline field error vs error boundary).
+ */
+export declare class ApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly issues?: unknown[];
+    readonly requestId?: string;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, status: number, options?: {
+        issues?: unknown[];
+        requestId?: string;
+        cause?: unknown;
+    });
+}
+export declare function isApiError(err: unknown): err is ApiError;

package/dist/client/api/ApiError.js

@@ -0,0 +1,23 @@
+/**
+ * Client-side error class thrown by apiClient / surfaceError. Carries the
+ * server's stable `code`, the HTTP status, and any Zod issues so wrappers
+ * can route the failure (toast vs inline field error vs error boundary).
+ */
+export class ApiError extends Error {
+    constructor(code, message, status, 
+    // audit-unknown-ok: ApiError cause/issues — error chaining canonical API
+    options) {
+        super(message);
+        this.name = "ApiError";
+        this.code = code;
+        this.status = status;
+        this.issues = options?.issues;
+        this.requestId = options?.requestId;
+        this.cause = options?.cause;
+        Object.setPrototypeOf(this, ApiError.prototype);
+    }
+}
+// audit-unknown-ok: type-narrowing entry point — accepts any value, narrows by typeof/Array.isArray
+export function isApiError(err) {
+    return err instanceof ApiError;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Public surface for the client-side error router.
+ *
+ * Given any thrown value, this helper:
+ *  - If `err` is an `ApiError` and the code maps to a form field AND a
+ *    setFieldError function is provided → routes to inline field error.
+ *  - Otherwise → calls `showToast(translatedMessage, "error")`.
+ *  - Fires `reportClientError(...)` for any non-ApiError that escapes a handler
+ *    (server-side ApiErrors are already in serverErrors; we don't double-count).
+ *
+ * Both `showToast` and the optional `setFieldError` / `translate` are injected
+ * by the caller — surfaceError does NOT depend on `useToast` directly, so it
+ * can be called from outside React hook boundaries (e.g. inside Button's
+ * non-hook handleClick wrapper).
+ */
+export interface SurfaceErrorOptions {
+    showToast: (message: string, variant?: "error" | "warning" | "info" | "success" | "loading") => void;
+    setFieldError?: (field: string, message: string) => void;
+    /** next-intl style translator. Falls back to the raw error message when undefined. */
+    translate?: (key: string) => string;
+    /** Optional reporter for the clientErrors / serverErrors collection. */
+    report?: (payload: {
+        code: string;
+        message: string;
+        stack?: string;
+        requestId?: string;
+    }) => void;
+}
+export declare function surfaceError(err: unknown, opts: SurfaceErrorOptions): void;
+export { ApiError, isApiError } from "./ApiError";

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

@@ -0,0 +1,39 @@
+"use client";
+import { isApiError } from "./ApiError";
+import { getErrorDisplay } from "../../errors/error-display-map";
+// audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
+export function surfaceError(err, opts) {
+    const { showToast, setFieldError, translate, report } = opts;
+    if (isApiError(err)) {
+        const display = getErrorDisplay(err.code);
+        const message = translate?.(display.messageKey) ?? err.message;
+        if (display.field && setFieldError) {
+            setFieldError(display.field, message);
+            return;
+        }
+        showToast(message, "error");
+        return;
+    }
+    // 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;
+    showToast(fallback, "error");
+    if (report) {
+        try {
+            report({
+                code: "CLIENT_UNHANDLED",
+                message,
+                stack: err instanceof Error ? err.stack : undefined,
+            });
+        }
+        catch {
+            // never let the reporter break the catch path
+        }
+    }
+    // Re-throw if it's a non-Error so framework error boundaries still see it.
+    if (!(err instanceof Error)) {
+        throw err;
+    }
+}
+export { ApiError, isApiError } from "./ApiError";