@mohasinac/appkit 4.29.0 → 4.30.0

package/dist/security/pii-encrypt.js

@@ -9,7 +9,9 @@
  * Ciphertext format: "enc:v1:<iv_b64>:<ciphertext_b64>:<authtag_b64>"
  * Blind index format: "hmac-sha256:<sha256_hex>"
  */
-import { ENC_PREFIX, HMAC_PREFIX, isPiiEncrypted } from "./pii-mask";
+import { ENC_PREFIX, HMAC_PREFIX, isPiiEncrypted, encEnvelopeKind } from "./pii-mask";
+import { serverLogger } from "../monitoring/server-logger";
+import { normalizeError } from "../errors/normalize";
 // Re-exported for backward-compat with existing direct imports of these
 // symbols from this file — the actual crypto-free definitions live in
 // pii-mask.ts (see that file's header comment for why the split exists).
@@ -50,10 +52,32 @@ function getEncKey() {
     const hex = normalizePiiSecretValue(process.env.PII_ENCRYPTION_KEY);
     return Buffer.from(hex, "hex");
 }
+/**
+ * Blind-index key. Normalised and validated exactly like `getEncKey`.
+ *
+ * It previously read the env var RAW while `getEncKey` normalised the same
+ * value — so the two keys were derived from one variable by two different code
+ * paths. `Buffer.from(x, "hex")` does not throw on bad input; it truncates
+ * silently at the first non-hex byte. A BOM or trailing CR (a problem this repo
+ * has hit before — see scripts/_fix-vercel-env-bom.mjs) would therefore give
+ * the encryptor a 32-byte key and the indexer a 0-byte one, and every blind
+ * index written from that moment would be unmatchable against the existing
+ * ones. `findByEmail` would simply stop finding people — indistinguishable
+ * from "no such user", with nothing logged.
+ *
+ * Verified before changing: on the current environment the raw and normalised
+ * reads produce byte-identical keys, so this is a no-op for every index
+ * already in Firestore.
+ */
 function getHmacKey() {
-    const raw = process.env["PII_HMAC_KEY"] ?? process.env["PII_ENCRYPTION_KEY"] ?? "";
+    const raw = normalizePiiSecretValue(process.env["PII_HMAC_KEY"] ?? process.env["PII_ENCRYPTION_KEY"] ?? "");
     if (!raw)
         throw new Error("PII_HMAC_KEY env var is not set — cannot generate blind PII index");
+    if (!/^[0-9a-fA-F]{64}$/.test(raw))
+        // Fail loudly at the boundary. A startup error is recoverable; a silently
+        // truncated key is not.
+        throw new Error("PII_HMAC_KEY (or its PII_ENCRYPTION_KEY fallback) must be a 64-character hex string — " +
+            `got ${raw.length} chars. Buffer.from would truncate this silently and desync every blind index.`);
     return Buffer.from(raw, "hex");
 }
 /** Encrypt a plaintext string with AES-256-GCM. */
@@ -70,10 +94,19 @@ export function encryptValue(plaintext) {
 export function decryptValue(ciphertext) {
     if (!ciphertext.startsWith(ENC_PREFIX))
         return ciphertext;
+    // Name the actual problem. A settings-encrypted value shares this prefix but
+    // uses dot separators and a different key; it used to fail here as a bare
+    // part-count error, which reads like corruption rather than "wrong system".
+    if (encEnvelopeKind(ciphertext) === "settings") {
+        throw new Error("Value is settings-encrypted (SETTINGS_ENCRYPTION_KEY, dot-separated), not PII-encrypted — decryptValue cannot read it");
+    }
     const inner = ciphertext.slice(ENC_PREFIX.length);
     const parts = inner.split(":");
     if (parts.length !== 3)
-        throw new Error(`Invalid PII ciphertext: ${ciphertext}`);
+        // NEVER interpolate the value. This used to embed the whole ciphertext,
+        // which then flowed into DatabaseError and serverLogger.error — encrypted
+        // PII sitting in the logs on every malformed row. Shape only.
+        throw new Error(`Invalid PII ciphertext: expected 3 colon-separated parts after ${ENC_PREFIX}, got ${parts.length} (${ciphertext.length} chars)`);
     const [ivB64, encB64, tagB64] = parts;
     const { createDecipheriv } = nodeCrypto();
     const key = getEncKey();
@@ -124,14 +157,20 @@ function setPath(obj, path, value) {
 /**
  * Encrypt the named fields, adding a blind index alongside each top-level one.
  *
- * Supports dotted paths (`deviceInfo.ip`, `whatsappConfig.accessToken`). This
- * was a flat top-level loop that skipped anything non-string, which is why
- * nested PII stayed in plaintext — and why the exported
- * `STORE_SECRET_FIELDS = ["whatsappConfig.accessToken"]` was unusable by the
- * very function it was written for.
+ * Supports dotted paths (`deviceInfo.ip`, `location.city`). This was a flat
+ * top-level loop that skipped anything non-string, which is why nested PII
+ * stayed in plaintext.
+ *
+ * 🛑 That dotted-path support is also what made it possible to point this
+ * function at a field belonging to the OTHER crypto system. A store's
+ * `whatsappConfig.accessToken` is encrypted with SETTINGS_ENCRYPTION_KEY;
+ * passing it here would encrypt it with the PII key while
+ * `StoreRepository.decryptSecrets` kept decrypting with the settings one.
+ * Only ever pass fields from this file's own `*_PII_FIELDS` lists.
  *
- * Idempotent: a value already carrying `enc:v1:` is left alone, so re-running
- * over a partially-migrated document is safe.
+ * Idempotent: a value already carrying `enc:v1:` is left alone — whichever
+ * system wrote it — so re-running over a partially-migrated document is safe
+ * and a settings-encrypted value is never double-wrapped.
  */
 /**
  * Encrypt `itemPath` on every element of the array at `arrayPath`.
@@ -192,6 +231,33 @@ export function encryptPiiFields(doc, piiFields) {
  * Decrypt specified PII fields in a Firestore document.
  * Fields that are not encrypted (no `enc:v1:` prefix) are passed through.
  */
+/**
+ * Decrypt one value, or return a sentinel and warn.
+ *
+ * A single corrupt or foreign-format row must not take out the page. Before
+ * the sieve read path started calling `mapDoc` (which is what decrypts),
+ * a bad value was merely rendered as ciphertext — cosmetic. Once decryption
+ * actually runs on list reads, an unguarded throw inside a 100-row admin page
+ * turns that cosmetic defect into a 500 for the whole list.
+ *
+ * Same fail-soft posture `SiteSettingsRepository.getDecryptedCredentials`
+ * already takes for the settings key.
+ *
+ * The warning names the FIELD, never the value.
+ */
+function decryptOrWarn(value, field) {
+    try {
+        return decryptValue(value);
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        serverLogger.warn("PII decrypt failed — field left empty", {
+            field,
+            reason: normalized.message,
+        });
+        return "";
+    }
+}
 export function decryptPiiFields(doc, piiFields) {
     const result = { ...doc };
     for (const field of piiFields) {
@@ -211,7 +277,7 @@ export function decryptPiiFields(doc, piiFields) {
                 const clone = { ...el };
                 const value = itemPath ? getPath(clone, itemPath) : undefined;
                 if (typeof value === "string" && value.startsWith(ENC_PREFIX)) {
-                    setPath(clone, itemPath, decryptValue(value));
+                    setPath(clone, itemPath, decryptOrWarn(value, field));
                 }
                 return clone;
             }));
@@ -220,13 +286,13 @@ export function decryptPiiFields(doc, piiFields) {
         if (field.includes(".")) {
             const value = getPath(result, field);
             if (typeof value === "string" && value.startsWith(ENC_PREFIX)) {
-                setPath(result, field, decryptValue(value));
+                setPath(result, field, decryptOrWarn(value, field));
             }
             continue;
         }
         const value = result[field];
         if (typeof value === "string" && value.startsWith(ENC_PREFIX)) {
-            result[field] = decryptValue(value);
+            result[field] = decryptOrWarn(value, field);
         }
     }
     return result;

package/dist/security/pii-mask.d.ts

@@ -14,7 +14,45 @@
  */
 export declare const ENC_PREFIX = "enc:v1:";
 export declare const HMAC_PREFIX = "hmac-sha256:";
-/** Check if a value is encrypted by our PII system. */
+/**
+ * Which crypto system produced an `enc:v1:` value.
+ *
+ * TWO systems share this prefix and always have:
+ *
+ *   PII      `enc:v1:` + iv `:` ciphertext `:` tag   — PII_ENCRYPTION_KEY
+ *   settings `enc:v1:` + iv `.` tag `.` ciphertext   — SETTINGS_ENCRYPTION_KEY
+ *
+ * Different separator, different field order, different key. `isPiiEncrypted`
+ * checked only the prefix and so could not tell them apart, which made every
+ * "is this ours" test wrong for one of the two — feed a settings value to
+ * `decryptValue` and it throws on the part count; feed a PII value to
+ * `decryptSecret` and it throws on a different part count. Neither error names
+ * the actual problem.
+ *
+ * Changing either prefix is NOT an option: `enc:v1:` is stamped into every
+ * encrypted value across twelve collections, and a new prefix orphans all of
+ * it. It does not need changing. Base64's alphabet is `A-Za-z0-9+/=`, which
+ * contains neither `.` nor `:` — so the two formats are ALREADY unambiguous in
+ * the data, and this function simply reads what is there. No migration.
+ */
+export type EncEnvelopeKind = "pii" | "settings" | null;
+export declare function encEnvelopeKind(value: unknown): EncEnvelopeKind;
+/**
+ * Does this value carry the `enc:v1:` prefix at all, whichever system wrote it
+ * and even if malformed?
+ *
+ * This is the check the DISPLAY masks want. `maskName`/`maskEmail` exist so
+ * ciphertext never reaches the UI, and for that purpose "settings-encrypted"
+ * and "malformed" are just as unshowable as "PII-encrypted". Narrowing them to
+ * `kind === "pii"` would let the other two render verbatim.
+ */
+export declare function hasEncPrefix(value: unknown): boolean;
+/**
+ * Check if a value is encrypted by our PII system SPECIFICALLY.
+ *
+ * Use for crypto routing — "may I hand this to decryptValue". For "is this
+ * unshowable", use `hasEncPrefix`.
+ */
 export declare function isPiiEncrypted(value: string): boolean;
 /**
  * Mask a person's name for public display.

package/dist/security/pii-mask.js

@@ -14,10 +14,39 @@
  */
 export const ENC_PREFIX = "enc:v1:";
 export const HMAC_PREFIX = "hmac-sha256:";
-/** Check if a value is encrypted by our PII system. */
-export function isPiiEncrypted(value) {
+export function encEnvelopeKind(value) {
+    if (typeof value !== "string" || !value.startsWith(ENC_PREFIX))
+        return null;
+    const inner = value.slice(ENC_PREFIX.length);
+    const colons = inner.split(":").length - 1;
+    const dots = inner.split(".").length - 1;
+    if (colons === 2 && dots === 0)
+        return "pii";
+    if (dots === 2 && colons === 0)
+        return "settings";
+    return null; // carries the prefix but neither shape — malformed
+}
+/**
+ * Does this value carry the `enc:v1:` prefix at all, whichever system wrote it
+ * and even if malformed?
+ *
+ * This is the check the DISPLAY masks want. `maskName`/`maskEmail` exist so
+ * ciphertext never reaches the UI, and for that purpose "settings-encrypted"
+ * and "malformed" are just as unshowable as "PII-encrypted". Narrowing them to
+ * `kind === "pii"` would let the other two render verbatim.
+ */
+export function hasEncPrefix(value) {
     return typeof value === "string" && value.startsWith(ENC_PREFIX);
 }
+/**
+ * Check if a value is encrypted by our PII system SPECIFICALLY.
+ *
+ * Use for crypto routing — "may I hand this to decryptValue". For "is this
+ * unshowable", use `hasEncPrefix`.
+ */
+export function isPiiEncrypted(value) {
+    return encEnvelopeKind(value) === "pii";
+}
 /**
  * Mask a person's name for public display.
  * Each word is reduced to its first letter followed by "***".
@@ -31,7 +60,7 @@ export function isPiiEncrypted(value) {
 export function maskName(name) {
     if (!name || typeof name !== "string")
         return "Anonymous";
-    if (isPiiEncrypted(name))
+    if (hasEncPrefix(name))
         return "Anonymous";
     return name
         .trim()
@@ -47,7 +76,7 @@ export function maskName(name) {
 export function maskEmail(email) {
     if (!email || typeof email !== "string")
         return "***@***.***";
-    if (isPiiEncrypted(email))
+    if (hasEncPrefix(email))
         return "***@***.***";
     const atIdx = email.indexOf("@");
     if (atIdx < 0)

package/dist/security/pii-redact.d.ts

@@ -1,16 +1,3 @@
-/**
- * PII Redaction Utility
- *
- * Recursively sanitizes objects before logging by masking or redacting
- * known PII (Personally Identifiable Information) field names.
- *
- * - Secrets (password, token, apiKey, etc.) → "[REDACTED]"
- * - Emails → partial mask: "mo***@gmail.com"
- * - Phones → last 4 digits: "***9876"
- * - Names → first char + asterisks: "J********"
- * - Addresses, financial IDs → "[REDACTED]"
- * - IPs → first octet only: "192.***.***.***"
- */
 /**
  * Mask an IPv4 address by zeroing the last three octets. Returns
  * `[REDACTED]` for IPv6 / malformed input.

package/dist/security/pii-redact.js

@@ -1,3 +1,4 @@
+import { ENC_PREFIX } from "./pii-mask";
 /**
  * PII Redaction Utility
  *
@@ -138,7 +139,8 @@ export function redactPii(data, depth = 0) {
 // ---------------------------------------------------------------------------
 // UI display helpers
 // ---------------------------------------------------------------------------
-const ENC_TOKEN_PREFIX = "enc:v1:";
+// One declaration of the prefix, shared with the crypto that produces it.
+const ENC_TOKEN_PREFIX = ENC_PREFIX;
 /**
  * Safe display name for untrusted / possibly-encrypted PII fields.
  *

package/dist/security/pii-schemas.d.ts

@@ -66,7 +66,5 @@ export declare const CHAT_PII_FIELDS: readonly ["buyerName", "sellerName"];
 export declare const EVENT_ENTRY_PII_FIELDS: readonly ["userDisplayName", "userEmail", "ipAddress"];
 /** PII fields in lottery entries */
 export declare const LOTTERY_ENTRY_PII_FIELDS: readonly ["userPhone", "userEmail", "userDisplayName"];
-/** Store OAuth bearer tokens — encrypted via SETTINGS_ENCRYPTION_KEY */
-export declare const STORE_SECRET_FIELDS: readonly ["whatsappConfig.accessToken"];
 /** PII fields in savedPaymentMethods — full identifier (UPI VPA, card PAN, etc.) */
 export declare const PAYMENT_METHOD_PII_FIELDS: readonly ["identifier"];

package/dist/security/pii-schemas.js

@@ -99,7 +99,21 @@ export const LOTTERY_ENTRY_PII_FIELDS = [
     "userEmail",
     "userDisplayName",
 ];
-/** Store OAuth bearer tokens — encrypted via SETTINGS_ENCRYPTION_KEY */
-export const STORE_SECRET_FIELDS = ["whatsappConfig.accessToken"];
+// `STORE_SECRET_FIELDS = ["whatsappConfig.accessToken"]` was deleted here.
+//
+// It had ZERO consumers, and its presence in this file was the whole hazard:
+// it sat in the PII-field registry, formatted identically to the entries above
+// that ARE assigned to a repository's `piiFields` — while its own doc-comment
+// said it was encrypted with SETTINGS_ENCRYPTION_KEY, the other key entirely.
+//
+// Wiring it into a `piiFields` override would have encrypted every store's Meta
+// bearer token with the PII key while `StoreRepository.decryptSecrets` kept
+// decrypting with the settings key: a hard throw on every store read, and
+// live seller tokens unrecoverable without a bespoke migration. Dotted-path
+// support was added to `encryptPiiFields` in 2026-08, which is exactly what
+// made that one-line mistake possible.
+//
+// The token is handled where it belongs — `encryptSecret`/`decryptSecret` in
+// `StoreRepository`. A constant does not need to exist for that.
 /** PII fields in savedPaymentMethods — full identifier (UPI VPA, card PAN, etc.) */
 export const PAYMENT_METHOD_PII_FIELDS = ["identifier"];

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/stores-seed-data.js

@@ -178,6 +178,24 @@ const _rawstoresSeedData = [
         },
         isPublic: true,
         isVacationMode: false,
+        /*
+         * Reachable, but never advertised to search engines.
+         *
+         * This is a QA store — real enough for a tester to exercise seller flows
+         * against, and not something that belongs in Google's index. `isTestData`
+         * is what the codebase already uses to express that: the sitemap's store
+         * fetcher filters it out (it has no viewer), public store listings hide
+         * it, and `canViewTestData()` keeps it visible to testers and admins — so
+         * the checklist case linking to `/stores/store-tester-qa-seller` still
+         * resolves.
+         *
+         * 🛑 NOTE the deliberate absence of `testDataExpiresAt`. Every sandbox
+         * FIXTURE carries one; this store is permanent. `getTestDataRefs` skips
+         * docs without an expiry on the force-purge path precisely so
+         * `tester:purge-sandbox --force` cannot delete it. Do not add an expiry
+         * here — that would put a permanent seed store in range of the sweep.
+         */
+        isTestData: true,
         stats: { totalProducts: 0, itemsSold: 0, totalReviews: 0, averageRating: 0 },
         capabilities: ["host_preorders", "verified_seller", "create_coupons"],
         createdAt: daysAgo(1),

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/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;