@mohasinac/appkit 4.29.0 → 4.30.0

package/dist/ui/forms/apply-zod-issues.js

@@ -0,0 +1,38 @@
+/**
+ * `applyZodIssues` — pipe every issue from a validation failure into a form's
+ * error map, so they render inline on `<FieldInput>` etc. rather than as a
+ * toast.
+ *
+ * WHY THIS IS ITS OWN FILE
+ * ------------------------
+ * It used to live in `FormShell.tsx`, which is a `"use client"` React module.
+ * `client/api/surface-error.ts` needs this function to route server-side
+ * validation failures to inline field errors, and that file is deliberately
+ * hook-free and React-free (see its header) so it can be called from outside a
+ * hook boundary — e.g. inside Button's non-hook click wrapper. Importing
+ * FormShell there would have dragged React and the whole form runtime into it.
+ *
+ * This is a MOVE, not a barrel re-export: `FormShell.tsx` imports it from here.
+ *
+ * Keys are the full dotted/indexed path (`"video.duration"`, `"images.2"`),
+ * not just the top-level segment — a plain `issue.path[0]` key would collapse
+ * every nested issue under one object onto the same map entry, silently
+ * dropping all but the last. Top-level-only fields (the common case) are
+ * unaffected: a single-segment path joins to the same string as before.
+ *
+ * Root-level `.refine()` issues (empty `path: []`, no owning field) are still
+ * skipped — there is no field to attach them to, so the caller must surface
+ * those some other way (they fall through to a toast in `surfaceError`).
+ */
+export function applyZodIssues(issues, setFieldError) {
+    for (const issue of issues) {
+        if (!issue.path || issue.path.length === 0)
+            continue;
+        const key = issue.path.map(String).join(".");
+        setFieldError(key, issue.message);
+    }
+}
+/** True when at least one issue carries a field path we can attach it to. */
+export function hasAttachableIssue(issues) {
+    return Boolean(issues?.some((i) => i.path && i.path.length > 0));
+}

package/dist/ui/forms/index.d.ts

@@ -1,5 +1,6 @@
 export type { FormShellProviderProps, FormShellStep, FormShellNav, FormShellContextValue, UseFormShellStateResult, } from "./FormShell";
-export { FormShellProvider, FormShellContext, useFormShell, useFormShellState, applyZodIssues } from "./FormShell";
+export { FormShellProvider, FormShellContext, useFormShell, useFormShellState } from "./FormShell";
+export { applyZodIssues, hasAttachableIssue } from "./apply-zod-issues";
 export type { FieldInputProps } from "./FieldInput";
 export { FieldInput } from "./FieldInput";
 export type { FieldSelectProps } from "./FieldSelect";

package/dist/ui/forms/index.js

@@ -1,4 +1,5 @@
-export { FormShellProvider, FormShellContext, useFormShell, useFormShellState, applyZodIssues } from "./FormShell";
+export { FormShellProvider, FormShellContext, useFormShell, useFormShellState } from "./FormShell";
+export { applyZodIssues, hasAttachableIssue } from "./apply-zod-issues";
 export { FieldInput } from "./FieldInput";
 export { FieldSelect } from "./FieldSelect";
 export { FieldCheckbox } from "./FieldCheckbox";

package/dist/ui/icons/icon-registry.d.ts

@@ -50,6 +50,14 @@ export declare const ICONS: {
     readonly settings: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly expand: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly user: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly notification: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly compare: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly help: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly menu: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly close: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly themeLight: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly themeDark: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly deals: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
 };
 /** Every valid `iconKey`. A typo is a compile error, not a silent blank. */
 export type IconKey = keyof typeof ICONS;

package/dist/ui/icons/icon-registry.js

@@ -39,7 +39,7 @@
  * @tag consumers:Button,RowActionMenu,BulkActionBar,action-registry
  * @tag sideEffects:none
  */
-import { Archive, ArrowLeft, Ban, Check, CheckCircle, ChevronDown, Copy, Download, Edit, Eye, EyeOff, FileDown, Filter, Flag, Gavel, Heart, Link as LinkIcon, Lock, Mail, MessageSquare, Package, Pause, Play, Plus, RefreshCw, Reply, RotateCcw, Save, Search, Send, Settings, Share2, ShieldCheck, ShoppingCart, Star, Trash2, TrendingUp, Truck, Upload, User, X, XCircle, } from "lucide-react";
+import { Archive, ArrowLeft, Ban, Bell, Check, CheckCircle, ChevronDown, Copy, Download, Edit, Eye, EyeOff, FileDown, Filter, Flag, Gavel, HelpCircle, Heart, Link as LinkIcon, Lock, Mail, Menu, MessageSquare, Moon, Package, Pause, Play, Plus, RefreshCw, Reply, RotateCcw, Save, Search, Send, Settings, Share2, ShieldCheck, ShoppingCart, Star, Sun, Scale, Tag, Trash2, TrendingUp, Truck, Upload, User, X, XCircle, } from "lucide-react";
 /**
  * Semantic name → component.
  *
@@ -98,6 +98,18 @@ export const ICONS = {
     settings: Settings,
     expand: ChevronDown,
     user: User,
+    // Header chrome. Added 2026-08-27 when TitleBarLayout stopped hand-inlining
+    // ten raw <svg> elements — a raw <svg> carries no `shrink-0`, so inside a
+    // padded flex control it silently shrank rather than rendering at its stated
+    // size, and no audit could see a size it never declared.
+    notification: Bell,
+    compare: Scale,
+    help: HelpCircle,
+    menu: Menu,
+    close: X,
+    themeLight: Sun,
+    themeDark: Moon,
+    deals: Tag,
 };
 /**
  * The ONLY sanctioned glyph sizes.

package/dist/utils/action-response.d.ts

@@ -1,4 +1,4 @@
-import type { ActionResult } from "../core/server-action";
+import type { ActionResult } from "../_internal/shared/types/action-result";
 export type { ActionResult };
 type ActionErrorResult = Extract<ActionResult<never>, {
     ok: false;

package/dist/utils/media-url.d.ts

@@ -7,6 +7,55 @@
 export declare const FIREBASE_STORAGE_HOST = "firebasestorage.googleapis.com";
 /** Google Cloud Storage host (used by public-asset URLs). */
 export declare const GCS_HOST = "storage.googleapis.com";
+/**
+ * The canonical stored form of every media reference: `/media/<slug>`.
+ *
+ * `POST /api/media/finalize` mints exactly this, `next.config.js` rewrites
+ * `/media/:path*` → `/api/media/:path*`, and CLAUDE.md § Media Architecture
+ * makes it mandatory ("never write raw firebasestorage.googleapis.com URLs
+ * into Firestore"). Exported so validation can name the same prefix the
+ * resolver below branches on, instead of re-typing the literal.
+ */
+export declare const MEDIA_PROXY_PREFIX = "/media/";
+/** Cap for any stored media reference. Matches the previous schema bound. */
+export declare const MEDIA_URL_MAX_LENGTH = 2048;
+/**
+ * Absolute hosts a stored media reference may point at.
+ *
+ * These exist for BACK-COMPAT only — rows written before the `/media/` proxy,
+ * and `seedExtMedia()` fixtures pointing at third-party sample assets. New
+ * writes should always be producing `/media/<slug>`. This list was previously
+ * duplicated in `appkit/src/validation/schemas.ts` and
+ * `src/validation/request-schemas.ts`; it lives here now so there is one copy.
+ */
+export declare const APPROVED_MEDIA_DOMAINS: readonly string[];
+export declare const MEDIA_URL_MESSAGE = "Must be a stored media reference (/media/<slug>) or a URL on an approved CDN domain";
+/**
+ * Is `value` something we are willing to PERSIST as a media reference?
+ *
+ * The single definition of that rule — `mediaUrlSchema` in both validation
+ * modules refines on it, and everything that stores an image/video URL should
+ * go through one of those.
+ *
+ * Accepts:
+ *  - `/media/<slug>` — the canonical form (`/api/media/finalize` output);
+ *  - an absolute URL on an approved host — see `APPROVED_MEDIA_DOMAINS`.
+ *
+ * Rejects:
+ *  - `blob:` / `data:` — valid only in the tab that created them. Persisting
+ *    one stores a reference that is already dead by the time anyone reads it;
+ *  - `/api/media/ext?url=…` — a RENDER-time transform produced by
+ *    `resolveMediaUrl` below. Storing it double-wraps on the next render and
+ *    pins the value to a proxy route rather than to the asset;
+ *  - anything else, including bare relative paths that are not `/media/`.
+ *
+ * NOTE this is deliberately a strict SUPERSET of the rule it replaced (which
+ * was `.url()` + an approved-host check). That old rule rejected the canonical
+ * `/media/<slug>` form outright — which is what made every avatar save fail —
+ * while happily accepting the raw Storage URLs CLAUDE.md bans. No value that
+ * validated before stops validating now.
+ */
+export declare function isStoredMediaRef(value: string): boolean;
 export interface ResolveMediaUrlOptions {
     /**
      * When false, a URL we do not own is returned UNCHANGED instead of being sent

package/dist/utils/media-url.js

@@ -9,7 +9,78 @@ import { normalizeError } from "../errors/normalize";
 export const FIREBASE_STORAGE_HOST = "firebasestorage.googleapis.com";
 /** Google Cloud Storage host (used by public-asset URLs). */
 export const GCS_HOST = "storage.googleapis.com";
-const PROXY_PREFIX = "/media/";
+/**
+ * The canonical stored form of every media reference: `/media/<slug>`.
+ *
+ * `POST /api/media/finalize` mints exactly this, `next.config.js` rewrites
+ * `/media/:path*` → `/api/media/:path*`, and CLAUDE.md § Media Architecture
+ * makes it mandatory ("never write raw firebasestorage.googleapis.com URLs
+ * into Firestore"). Exported so validation can name the same prefix the
+ * resolver below branches on, instead of re-typing the literal.
+ */
+export const MEDIA_PROXY_PREFIX = "/media/";
+const PROXY_PREFIX = MEDIA_PROXY_PREFIX;
+/** Cap for any stored media reference. Matches the previous schema bound. */
+export const MEDIA_URL_MAX_LENGTH = 2048;
+/**
+ * Absolute hosts a stored media reference may point at.
+ *
+ * These exist for BACK-COMPAT only — rows written before the `/media/` proxy,
+ * and `seedExtMedia()` fixtures pointing at third-party sample assets. New
+ * writes should always be producing `/media/<slug>`. This list was previously
+ * duplicated in `appkit/src/validation/schemas.ts` and
+ * `src/validation/request-schemas.ts`; it lives here now so there is one copy.
+ */
+export const APPROVED_MEDIA_DOMAINS = [
+    FIREBASE_STORAGE_HOST,
+    GCS_HOST,
+    "res.cloudinary.com",
+    "images.unsplash.com",
+];
+export const MEDIA_URL_MESSAGE = "Must be a stored media reference (/media/<slug>) or a URL on an approved CDN domain";
+/**
+ * Is `value` something we are willing to PERSIST as a media reference?
+ *
+ * The single definition of that rule — `mediaUrlSchema` in both validation
+ * modules refines on it, and everything that stores an image/video URL should
+ * go through one of those.
+ *
+ * Accepts:
+ *  - `/media/<slug>` — the canonical form (`/api/media/finalize` output);
+ *  - an absolute URL on an approved host — see `APPROVED_MEDIA_DOMAINS`.
+ *
+ * Rejects:
+ *  - `blob:` / `data:` — valid only in the tab that created them. Persisting
+ *    one stores a reference that is already dead by the time anyone reads it;
+ *  - `/api/media/ext?url=…` — a RENDER-time transform produced by
+ *    `resolveMediaUrl` below. Storing it double-wraps on the next render and
+ *    pins the value to a proxy route rather than to the asset;
+ *  - anything else, including bare relative paths that are not `/media/`.
+ *
+ * NOTE this is deliberately a strict SUPERSET of the rule it replaced (which
+ * was `.url()` + an approved-host check). That old rule rejected the canonical
+ * `/media/<slug>` form outright — which is what made every avatar save fail —
+ * while happily accepting the raw Storage URLs CLAUDE.md bans. No value that
+ * validated before stops validating now.
+ */
+export function isStoredMediaRef(value) {
+    if (!value || value.length > MEDIA_URL_MAX_LENGTH)
+        return false;
+    if (value.startsWith(MEDIA_PROXY_PREFIX))
+        return true;
+    if (value.startsWith("blob:") || value.startsWith("data:"))
+        return false;
+    if (value.startsWith(MEDIA_ENDPOINTS.EXT))
+        return false;
+    try {
+        const { hostname } = new URL(value);
+        return APPROVED_MEDIA_DOMAINS.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
+    }
+    catch (_err) {
+        void normalizeError(_err); // not an absolute URL, and not /media/ — reject
+        return false;
+    }
+}
 /**
  * Our own Storage bucket, as it appears as the first path segment of a
  * `storage.googleapis.com` URL. Only URLs pointing at THIS bucket may have that

package/dist/validation/schemas.d.ts

@@ -20,8 +20,21 @@ export declare const paginationQuerySchema: z.ZodObject<{
 }>;
 export declare const objectIdSchema: z.ZodString;
 export declare const urlSchema: z.ZodString;
-/** Default approved media domains. Extend via `createMediaUrlSchema`. */
-export declare const APPROVED_MEDIA_DOMAINS: string[];
+/**
+ * A media reference we are willing to PERSIST.
+ *
+ * The rule lives in `isStoredMediaRef` (`utils/media-url.ts`) so this schema
+ * and its zod-4 twin in `src/validation/request-schemas.ts` cannot drift —
+ * the two Zod major versions mean the schema object can't be shared, but the
+ * predicate can.
+ *
+ * This used to be `.url()` + an approved-host refine, which rejected the
+ * canonical `/media/<slug>` form that `/api/media/finalize` actually mints.
+ * That is what made every avatar save fail with a bare "Validation failed".
+ *
+ * For a genuine EXTERNAL link (a brand website, a social handle, a tracking
+ * URL) use `urlSchema` above — not this.
+ */
 export declare const mediaUrlSchema: z.ZodEffects<z.ZodString, string, string>;
 export declare const dateStringSchema: z.ZodString;
 /** Discount percentage — 0–100. */

package/dist/validation/schemas.js

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import { normalizeError } from "../errors/normalize";
 // ============================================
 // COMMON SCHEMAS
 // ============================================
@@ -12,29 +11,26 @@ export const paginationQuerySchema = z.object({
 });
 export const objectIdSchema = z.string().regex(/^[a-z0-9-]+$/);
 export const urlSchema = z.string().url().max(2048);
-import { FIREBASE_STORAGE_HOST, GCS_HOST } from "../utils/media-url";
-/** Default approved media domains. Extend via `createMediaUrlSchema`. */
-export const APPROVED_MEDIA_DOMAINS = [
-    FIREBASE_STORAGE_HOST,
-    GCS_HOST,
-    "res.cloudinary.com",
-    "images.unsplash.com",
-    // Add site-specific CDN domains by calling createMediaUrlSchema(extraDomains)
-];
+import { isStoredMediaRef, MEDIA_URL_MAX_LENGTH, MEDIA_URL_MESSAGE, } from "../utils/media-url";
+/**
+ * A media reference we are willing to PERSIST.
+ *
+ * The rule lives in `isStoredMediaRef` (`utils/media-url.ts`) so this schema
+ * and its zod-4 twin in `src/validation/request-schemas.ts` cannot drift —
+ * the two Zod major versions mean the schema object can't be shared, but the
+ * predicate can.
+ *
+ * This used to be `.url()` + an approved-host refine, which rejected the
+ * canonical `/media/<slug>` form that `/api/media/finalize` actually mints.
+ * That is what made every avatar save fail with a bare "Validation failed".
+ *
+ * For a genuine EXTERNAL link (a brand website, a social handle, a tracking
+ * URL) use `urlSchema` above — not this.
+ */
 export const mediaUrlSchema = z
     .string()
-    .url()
-    .max(2048)
-    .refine((url) => {
-    try {
-        const { hostname } = new URL(url);
-        return APPROVED_MEDIA_DOMAINS.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
-    }
-    catch (_err) {
-        void normalizeError(_err);
-        return false;
-    }
-}, { message: "Image or video URL must be hosted on an approved CDN domain" });
+    .max(MEDIA_URL_MAX_LENGTH)
+    .refine(isStoredMediaRef, { message: MEDIA_URL_MESSAGE });
 export const dateStringSchema = z.string().datetime();
 // ============================================
 // SHARED PRIMITIVES (W2-4 — 2026-05-23)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.29.0",
+  "version": "4.30.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/scripts/seed-cli.mjs

@@ -108,9 +108,17 @@ if (!SERVICE_ACCOUNT_OVERRIDE && missing.length > 0) {
 
 // PII keys are mandatory for collections that encrypt fields
 const PII_REQUIRED = ["users", "addresses", "storeAddresses", "products", "orders", "reviews", "bids", "payouts", "eventEntries"];
-const PII_KEY_PRESENT = Boolean(process.env.PII_SECRET || process.env.PII_ENCRYPTION_KEY);
+// PII_ENCRYPTION_KEY ONLY. `PII_SECRET` used to be accepted here as an
+// alternative and is read by no runtime code — so a machine with only that set
+// passed this check and then threw at the first encrypt, mid-load, with some
+// collections already written.
+const PII_KEY_PRESENT = Boolean(process.env.PII_ENCRYPTION_KEY);
 if (ACTION === "load" && !PII_KEY_PRESENT) {
-  console.warn("⚠ PII_SECRET / PII_ENCRYPTION_KEY not set — collections with PII fields will fail.");
+  // A hard stop, not a warning. Loading without the key does not skip the PII
+  // collections — it writes some and then throws, leaving a half-seeded
+  // database that looks like a successful run until someone reads it.
+  console.error("✖ PII_ENCRYPTION_KEY is not set — users, addresses, orders, reviews, bids, payouts and eventEntries all encrypt fields at write time.");
+  process.exit(2);
 }
 
 // ---------------------------------------------------------------------------