@mohasinac/appkit 4.29.1 → 4.30.1

package/dist/security/settings-encryption.js

@@ -1,11 +1,32 @@
 // crypto is a Node.js built-in. Use require() to keep it out of the static
 // import graph so Next.js Edge bundler does not warn about this file.
 function nodeCrypto() { return require("crypto"); }
+import { ENC_PREFIX, encEnvelopeKind } from "./pii-mask";
 const ALGORITHM = "aes-256-gcm";
 const IV_BYTES = 12;
-const PREFIX = "enc:v1:";
+// ONE declaration of the prefix, shared with the PII system that also uses it.
+// Two independent `"enc:v1:"` literals is what let the two formats drift into
+// looking identical to every "is this encrypted" check in the codebase.
+const PREFIX = ENC_PREFIX;
+/**
+ * Strip a trailing CR/LF (literal or escaped) and surrounding whitespace —
+ * including a leading BOM, which `String.prototype.trim` removes.
+ *
+ * Mirrors `normalizePiiSecretValue` in pii-encrypt.ts rather than importing
+ * it: that module is the Node-crypto half of the PII system and this file must
+ * not depend on it. The two are four lines and must stay identical; the
+ * UNNORMALISED_HEX_KEY rule in audit-pii-crypto is what keeps them honest.
+ */
+function normalizeSecretEnvValue(raw) {
+    return (raw ?? "").replace(/(?:\\r|\\n|\r|\n)+$/g, "").trim();
+}
 function getMasterKey() {
-    const hex = process.env.SETTINGS_ENCRYPTION_KEY;
+    // Normalise before measuring AND before Buffer.from. A BOM or trailing CR
+    // makes `length !== 64` true, so this threw a confusing "must be 64
+    // characters" on a key that looks correct in the dashboard — and had the
+    // length check not been there, Buffer.from would have truncated at the first
+    // non-hex byte and produced a silently WRONG key instead.
+    const hex = normalizeSecretEnvValue(process.env.SETTINGS_ENCRYPTION_KEY);
     if (!hex || hex.length !== 64) {
         throw new Error("SETTINGS_ENCRYPTION_KEY must be a 64-character hex string (32 bytes).");
     }
@@ -27,6 +48,13 @@ export function decryptSecret(encrypted) {
     if (!encrypted.startsWith(PREFIX)) {
         return encrypted;
     }
+    // Name the actual problem. A PII-encrypted value reaching here used to throw
+    // "expected 3 parts", which describes the symptom and not the cause — it is
+    // the wrong KEY and the wrong FORMAT, not a corrupt value.
+    const kind = encEnvelopeKind(encrypted);
+    if (kind === "pii") {
+        throw new Error("Value is PII-encrypted (PII_ENCRYPTION_KEY, colon-separated), not settings-encrypted — decryptSecret cannot read it");
+    }
     const parts = encrypted.slice(PREFIX.length).split(".");
     if (parts.length !== 3) {
         throw new Error("Invalid encrypted value - expected 3 parts");
@@ -41,7 +69,7 @@ export function decryptSecret(encrypted) {
     ]).toString("utf8");
 }
 export function isSecretEncrypted(value) {
-    return value.startsWith(PREFIX);
+    return encEnvelopeKind(value) === "settings";
 }
 export function maskSecret(value) {
     if (!value || value.length < 12) {

package/dist/seed/test-utils.js

@@ -1,5 +1,6 @@
 import { runSeed } from "./runner";
 import { encryptPiiFields, decryptPiiFields, ENC_PREFIX } from "../security/pii-encrypt";
+import { hasEncPrefix } from "../security/pii-mask";
 import { DEFAULT_CATEGORIES } from "./defaults/categories";
 import { DEFAULT_FAQS } from "./defaults/faqs";
 import { makeProduct } from "./factories/product.factory";
@@ -24,8 +25,11 @@ export async function assertPiiRoundTrip(doc, piiFields) {
     const encrypted = encryptPiiFields(doc, piiFields);
     for (const field of piiFields) {
         const val = encrypted[field];
-        if (!val.startsWith(ENC_PREFIX)) {
-            throw new Error(`assertPiiRoundTrip: field "${String(field)}" was NOT encrypted. Got: ${val}`);
+        // `hasEncPrefix`, not a bare startsWith: the assertion is "this is not
+        // cleartext", which both crypto formats satisfy. And the value NEVER goes
+        // in the message — this helper runs over real fixture PII.
+        if (!hasEncPrefix(val)) {
+            throw new Error(`assertPiiRoundTrip: field "${String(field)}" was NOT encrypted (got ${val.length} chars, no ${ENC_PREFIX} prefix).`);
         }
         // Verify blind index was written
         const indexKey = `${String(field)}Index`;

package/dist/server.d.ts

@@ -462,7 +462,7 @@ export { encryptPii } from "./security/index";
 export { decryptPii } from "./security/index";
 export { isPiiEncrypted } from "./security/index";
 export { piiBlindIndex } from "./security/index";
-export { addPiiIndices } from "./security/index";
+export { piiIndicesFor } from "./security/index";
 export { getPiiConfigError } from "./security/index";
 export { encryptShippingAddress } from "./security/index";
 export { decryptShippingAddress } from "./security/index";

package/dist/server.js

@@ -1294,7 +1294,7 @@ export { encryptPii } from "./security/index";
 export { decryptPii } from "./security/index";
 export { isPiiEncrypted } from "./security/index";
 export { piiBlindIndex } from "./security/index";
-export { addPiiIndices } from "./security/index";
+export { piiIndicesFor } from "./security/index";
 export { getPiiConfigError } from "./security/index";
 export { encryptShippingAddress } from "./security/index";
 export { decryptShippingAddress } from "./security/index";

package/dist/ui/DataTable.js

@@ -108,7 +108,7 @@ pageSize: pageSizeProp, stickyHeader: stickyHeaderProp, striped: stripedProp, sh
     const renderViewToggle = () => {
         if (!showViewToggle)
             return null;
-        return (_jsxs(Div, { className: "appkit-data-table__view-toggle", role: "toolbar", "aria-label": "View mode", children: [showTableView && (_jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: () => handleViewModeChange("table"), "aria-label": tableView, "aria-pressed": activeViewMode === "table", className: `appkit-data-table__view-btn ${activeViewMode === "table" ? "appkit-data-table__view-btn--active" : ""} hidden sm:flex`, children: _jsx("svg", { className: "w-4 h-4", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 1.5, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M3 10h18M3 6h18M3 14h18M3 18h18" }) }) })), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: () => handleViewModeChange("grid"), "aria-label": gridView, "aria-pressed": activeViewMode === "grid", className: `appkit-data-table__view-btn ${activeViewMode === "grid" ? "appkit-data-table__view-btn--active" : ""}`, children: _jsx("svg", { className: "w-4 h-4", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 1.5, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M3.75 6A2.25 2.25 0 016 3.75h2.25A2.25 2.25 0 0110.5 6v2.25a2.25 2.25 0 01-2.25 2.25H6a2.25 2.25 0 01-2.25-2.25V6zM3.75 15.75A2.25 2.25 0 016 13.5h2.25a2.25 2.25 0 012.25 2.25V18a2.25 2.25 0 01-2.25 2.25H6A2.25 2.25 0 013.75 18v-2.25zM13.5 6a2.25 2.25 0 012.25-2.25H18A2.25 2.25 0 0120.25 6v2.25A2.25 2.25 0 0118 10.5h-2.25a2.25 2.25 0 01-2.25-2.25V6zM13.5 15.75a2.25 2.25 0 012.25-2.25H18a2.25 2.25 0 012.25 2.25V18A2.25 2.25 0 0118 20.25h-2.25A2.25 2.25 0 0113.5 18v-2.25z" }) }) }), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: () => handleViewModeChange("list"), "aria-label": listView, "aria-pressed": activeViewMode === "list", className: `appkit-data-table__view-btn ${activeViewMode === "list" ? "appkit-data-table__view-btn--active" : ""}`, children: _jsx("svg", { className: "w-4 h-4", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 1.5, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M8.25 6.75h12M8.25 12h12m-12 5.25h12M3.75 6.75h.007v.008H3.75V6.75zm.375 0a.375.375 0 11-.75 0 .375.375 0 01.75 0zM3.75 12h.007v.008H3.75V12zm.375 0a.375.375 0 11-.75 0 .375.375 0 01.75 0zm-.375 5.25h.007v.008H3.75v-.008zm.375 0a.375.375 0 11-.75 0 .375.375 0 01.75 0z" }) }) })] }));
+        return (_jsxs(Div, { className: "appkit-data-table__view-toggle", role: "toolbar", "aria-label": "View mode", children: [showTableView && (_jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: () => handleViewModeChange("table"), "aria-label": tableView, "aria-pressed": activeViewMode === "table", className: `appkit-data-table__view-btn ${activeViewMode === "table" ? "appkit-data-table__view-btn--active" : ""} hidden sm:flex`, children: _jsx("svg", { className: "w-4 h-4 shrink-0", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 1.5, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M3 10h18M3 6h18M3 14h18M3 18h18" }) }) })), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: () => handleViewModeChange("grid"), "aria-label": gridView, "aria-pressed": activeViewMode === "grid", className: `appkit-data-table__view-btn ${activeViewMode === "grid" ? "appkit-data-table__view-btn--active" : ""}`, children: _jsx("svg", { className: "w-4 h-4 shrink-0", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 1.5, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M3.75 6A2.25 2.25 0 016 3.75h2.25A2.25 2.25 0 0110.5 6v2.25a2.25 2.25 0 01-2.25 2.25H6a2.25 2.25 0 01-2.25-2.25V6zM3.75 15.75A2.25 2.25 0 016 13.5h2.25a2.25 2.25 0 012.25 2.25V18a2.25 2.25 0 01-2.25 2.25H6A2.25 2.25 0 013.75 18v-2.25zM13.5 6a2.25 2.25 0 012.25-2.25H18A2.25 2.25 0 0120.25 6v2.25A2.25 2.25 0 0118 10.5h-2.25a2.25 2.25 0 01-2.25-2.25V6zM13.5 15.75a2.25 2.25 0 012.25-2.25H18a2.25 2.25 0 012.25 2.25V18A2.25 2.25 0 0118 20.25h-2.25A2.25 2.25 0 0113.5 18v-2.25z" }) }) }), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: () => handleViewModeChange("list"), "aria-label": listView, "aria-pressed": activeViewMode === "list", className: `appkit-data-table__view-btn ${activeViewMode === "list" ? "appkit-data-table__view-btn--active" : ""}`, children: _jsx("svg", { className: "w-4 h-4 shrink-0", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 1.5, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M8.25 6.75h12M8.25 12h12m-12 5.25h12M3.75 6.75h.007v.008H3.75V6.75zm.375 0a.375.375 0 11-.75 0 .375.375 0 01.75 0zM3.75 12h.007v.008H3.75V12zm.375 0a.375.375 0 11-.75 0 .375.375 0 01.75 0zm-.375 5.25h.007v.008H3.75v-.008zm.375 0a.375.375 0 11-.75 0 .375.375 0 01.75 0z" }) }) })] }));
     };
     // --- Card views (grid / list) ------------------------------------------------
     const renderCardGrid = (mode) => {
@@ -158,5 +158,5 @@ function SelectableCard({ id, selectable, selected, onToggle, children, listMode
                                     selected
                                         ? "border-2 border-primary bg-primary"
                                         : "border-2 border-zinc-500 dark:border-slate-400 bg-transparent group-hover:border-primary",
-                                ].join(" "), checked: selected, onChange: (e) => onToggle(id, e.target.checked), "aria-label": "Select item" }), selected && (_jsx("svg", { className: "absolute inset-0 m-auto h-3 w-3 text-white pointer-events-none", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 3, d: "M5 13l4 4L19 7" }) }))] }) }) }), selected && (_jsx(Div, { className: "absolute inset-0 z-[var(--appkit-z-raised)] ring-2 ring-primary ring-offset-0 pointer-events-none", rounded: "xl", "aria-hidden": "true" })), children] }));
+                                ].join(" "), checked: selected, onChange: (e) => onToggle(id, e.target.checked), "aria-label": "Select item" }), selected && (_jsx("svg", { className: "absolute inset-0 m-auto h-3 w-3 text-white pointer-events-none shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 3, d: "M5 13l4 4L19 7" }) }))] }) }) }), selected && (_jsx(Div, { className: "absolute inset-0 z-[var(--appkit-z-raised)] ring-2 ring-primary ring-offset-0 pointer-events-none", rounded: "xl", "aria-hidden": "true" })), children] }));
 }

package/dist/ui/components/CollapsibleSection.js

@@ -9,7 +9,7 @@ import { Collapse } from "./Motion";
  * server-side merge/default-collapsed semantics). Purely presentational
  * here: isCollapsed/onToggle are always controlled by the caller. */
 export function CollapsibleSection({ title, isCollapsed, onToggle, renderHeaderExtra, keepMounted = false, id, className = "", children, }) {
-    return (_jsxs(Div, { id: id, className: className, rounded: "xl", border: "default", surface: "default", children: [_jsxs(Row, { align: "center", justify: "between", paddingX: "x-md", paddingY: "y-sm", children: [_jsx(Button, { type: "button", variant: "ghost", onClick: onToggle, paddingX: "none", paddingY: "none", rounded: "none", className: "min-w-0 flex-1", "aria-expanded": !isCollapsed, children: _jsxs(Row, { align: "center", justify: "between", className: "w-full", children: [_jsx(Span, { weight: "semibold", size: "sm", children: title }), _jsx("svg", { className: `w-4 h-4 transition-transform duration-150 ${isCollapsed ? "" : "rotate-180"}`, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M19 9l-7 7-7-7" }) })] }) }), renderHeaderExtra && _jsx(Div, { className: "ml-3 shrink-0", children: renderHeaderExtra() })] }), keepMounted ? (
+    return (_jsxs(Div, { id: id, className: className, rounded: "xl", border: "default", surface: "default", children: [_jsxs(Row, { align: "center", justify: "between", paddingX: "x-md", paddingY: "y-sm", children: [_jsx(Button, { type: "button", variant: "ghost", onClick: onToggle, paddingX: "none", paddingY: "none", rounded: "none", className: "min-w-0 flex-1", "aria-expanded": !isCollapsed, children: _jsxs(Row, { align: "center", justify: "between", className: "w-full", children: [_jsx(Span, { weight: "semibold", size: "sm", children: title }), _jsx("svg", { className: `w-4 h-4 transition-transform duration-150 ${isCollapsed ? "" : "rotate-180"} shrink-0`, fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M19 9l-7 7-7-7" }) })] }) }), renderHeaderExtra && _jsx(Div, { className: "ml-3 shrink-0", children: renderHeaderExtra() })] }), keepMounted ? (
             // No <Collapse>: it unmounts on close, which would discard uncommitted
             // child state (see `keepMounted` docs). `hidden` keeps the subtree
             // mounted and removes it from the a11y tree at the same time.

package/dist/ui/components/ImageGallery.js

@@ -107,7 +107,7 @@ export default function ImageGallery({ images, initialIndex = 0, showThumbnails
                                             ? "zoom-out"
                                             : "zoom-in"
                                         : "default",
-                                } }), images.length > 1 && !isZoomed && (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "ghost", onClick: goToPrevious, disabled: currentIndex === 0, className: `appkit-image-gallery__nav-btn appkit-image-gallery__nav-btn--prev ${themed.bgSecondary} ${themed.textPrimary}`, "aria-label": "Previous image", children: _jsx("svg", { className: "w-5 h-5 md:w-6 md:h-6", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M15 19l-7-7 7-7" }) }) }), _jsx(Button, { variant: "ghost", onClick: goToNext, disabled: currentIndex === images.length - 1, className: `appkit-image-gallery__nav-btn appkit-image-gallery__nav-btn--next ${themed.bgSecondary} ${themed.textPrimary}`, "aria-label": "Next image", children: _jsx("svg", { className: "w-5 h-5 md:w-6 md:h-6", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M9 5l7 7-7 7" }) }) })] })), images.length > 1 && (_jsxs("div", { className: `appkit-image-gallery__counter ${themed.bgSecondary} ${themed.textPrimary}`, "data-section": "imagegallery-div-519", children: [currentIndex + 1, " / ", images.length] })), allowZoom && isZoomed && (_jsxs("div", { className: `appkit-image-gallery__zoom-indicator ${themed.bgSecondary} ${themed.textPrimary}`, "data-section": "imagegallery-div-520", children: [Math.round(scale * 100), "%"] }))] }), showCaptions && currentImage.caption && (_jsx("div", { className: `appkit-image-gallery__caption ${themed.border}`, "data-section": "imagegallery-div-521", children: _jsx(Text, { className: themed.textSecondary, children: currentImage.caption }) }))] }), showThumbnails && images.length > 1 && (_jsx(HorizontalScroller, { snapToItems: true, className: "mt-4 pb-2", children: images.map((image, index) => (_jsx(Button, { variant: "ghost", onClick: () => goToIndex(index), className: `appkit-image-gallery__thumbnail ${index === currentIndex
+                                } }), images.length > 1 && !isZoomed && (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "ghost", onClick: goToPrevious, disabled: currentIndex === 0, className: `appkit-image-gallery__nav-btn appkit-image-gallery__nav-btn--prev ${themed.bgSecondary} ${themed.textPrimary}`, "aria-label": "Previous image", children: _jsx("svg", { className: "w-5 h-5 md:w-6 md:h-6 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M15 19l-7-7 7-7" }) }) }), _jsx(Button, { variant: "ghost", onClick: goToNext, disabled: currentIndex === images.length - 1, className: `appkit-image-gallery__nav-btn appkit-image-gallery__nav-btn--next ${themed.bgSecondary} ${themed.textPrimary}`, "aria-label": "Next image", children: _jsx("svg", { className: "w-5 h-5 md:w-6 md:h-6 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M9 5l7 7-7 7" }) }) })] })), images.length > 1 && (_jsxs("div", { className: `appkit-image-gallery__counter ${themed.bgSecondary} ${themed.textPrimary}`, "data-section": "imagegallery-div-519", children: [currentIndex + 1, " / ", images.length] })), allowZoom && isZoomed && (_jsxs("div", { className: `appkit-image-gallery__zoom-indicator ${themed.bgSecondary} ${themed.textPrimary}`, "data-section": "imagegallery-div-520", children: [Math.round(scale * 100), "%"] }))] }), showCaptions && currentImage.caption && (_jsx("div", { className: `appkit-image-gallery__caption ${themed.border}`, "data-section": "imagegallery-div-521", children: _jsx(Text, { className: themed.textSecondary, children: currentImage.caption }) }))] }), showThumbnails && images.length > 1 && (_jsx(HorizontalScroller, { snapToItems: true, className: "mt-4 pb-2", children: images.map((image, index) => (_jsx(Button, { variant: "ghost", onClick: () => goToIndex(index), className: `appkit-image-gallery__thumbnail ${index === currentIndex
                         ? "appkit-image-gallery__thumbnail--active"
                         : themed.border}`, "aria-label": `View image ${index + 1}`, children: _jsx(MediaImage, { src: image.thumbnail || image.src, alt: image.alt, size: "thumbnail", className: "w-full h-full object-cover" }) }, index))) })), _jsx("div", { className: `appkit-image-gallery__help ${themed.textMuted}`, "data-section": "imagegallery-div-522", children: allowZoom
                     ? "Swipe to navigate • Double tap to zoom"

package/dist/ui/components/ListingLayout.js

@@ -106,5 +106,5 @@ export function ListingLayout({ headerSlot, statusTabsSlot, filterContent, filte
                                 : l.applyFilters })] }), children: filterContent })), overlays] }));
 }
 function FilterIcon() {
-    return (_jsx("svg", { className: "w-4 h-4", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 2, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M3 4a1 1 0 011-1h16a1 1 0 011 1v2a1 1 0 01-.293.707L13 13.414V19a1 1 0 01-.553.894l-4 2A1 1 0 017 21v-7.586L3.293 6.707A1 1 0 013 6V4z" }) }));
+    return (_jsx("svg", { className: "w-4 h-4 shrink-0", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 2, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M3 4a1 1 0 011-1h16a1 1 0 011 1v2a1 1 0 01-.293.707L13 13.414V19a1 1 0 01-.553.894l-4 2A1 1 0 017 21v-7.586L3.293 6.707A1 1 0 013 6V4z" }) }));
 }

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

@@ -94,25 +94,6 @@ export interface UseFormShellStateResult {
      */
     markSubmitAttempted: () => void;
 }
-/**
- * `applyZodIssues` — pipe every issue from a Zod safeParse failure into the
- * FormShellContext error map. Use after `schema.safeParse(values)` returns
- * `success: false` to surface inline errors on `<FieldInput>` etc.
- *
- * 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, and no schema in this
- * codebase currently relies on one being surfaced this way.
- */
-export declare function applyZodIssues(issues: ReadonlyArray<{
-    path: ReadonlyArray<PropertyKey>;
-    message: string;
-}>, setFieldError: (name: string, error: string | null) => void): void;
 /**
  * `useFormShellState(schema?, nav?)` — caller-owned form state with optional
  * Zod validation. When a schema is supplied, `validate(values)` runs it and

package/dist/ui/forms/FormShell.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { applyZodIssues } from "./apply-zod-issues";
 // ─── Context ──────────────────────────────────────────────────────────────────
 export const FormShellContext = createContext(null);
 export function useFormShell() {
@@ -9,29 +10,9 @@ export function useFormShell() {
         throw new Error("useFormShell must be used inside <FormShell>");
     return ctx;
 }
-/**
- * `applyZodIssues` — pipe every issue from a Zod safeParse failure into the
- * FormShellContext error map. Use after `schema.safeParse(values)` returns
- * `success: false` to surface inline errors on `<FieldInput>` etc.
- *
- * 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, and no schema in this
- * codebase currently relies on one being surfaced this way.
- */
-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);
-    }
-}
+// `applyZodIssues` lives in ./apply-zod-issues — `surface-error.ts`, which is
+// deliberately React-free, needs it to route server-side validation failures
+// to inline field errors and cannot import this "use client" module.
 /**
  * `useFormShellState(schema?, nav?)` — caller-owned form state with optional
  * Zod validation. When a schema is supplied, `validate(values)` runs it and

package/dist/ui/forms/apply-zod-issues.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `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 declare function applyZodIssues(issues: ReadonlyArray<{
+    path?: ReadonlyArray<PropertyKey>;
+    message: string;
+}>, setFieldError: (name: string, error: string | null) => void): void;
+/** True when at least one issue carries a field path we can attach it to. */
+export declare function hasAttachableIssue(issues: ReadonlyArray<{
+    path?: ReadonlyArray<PropertyKey>;
+}> | undefined): boolean;

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.1",
+  "version": "4.30.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public"