@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.53.0",
-  "head": "78e72eb24243b0ee3afea21614fbbadee45d2b51",
+  "version": "4.53.2",
+  "head": "94f4715428f35ab362a11a468072ef933ca8a46d",
   "branch": "main",
   "dirty": false,
-  "builtAt": "2026-10-19T12:44:44.499Z"
+  "builtAt": "2026-10-19T22:24:09.397Z"
 }

package/dist/_internal/client/scaffolds/AppShell.js

@@ -6,5 +6,5 @@ export function AppShell({ children, slotHeader, slotFooter, slotSidebar, render
     const header = renderHeader ? renderHeader(ctx) : slotHeader;
     const footer = renderFooter ? renderFooter(ctx) : slotFooter;
     const sidebar = renderSidebar ? renderSidebar(ctx) : slotSidebar;
-    return (_jsxs(Stack, { className: `appkit-app-shell min-h-screen ${className ?? ""}`, children: [header ? (_jsx(BlockHeader, { className: "sticky top-0 z-30 w-full", "data-appshell-slot": "header", children: header })) : null, _jsxs(Div, { layout: "flex", className: "flex-1", children: [sidebar ? (_jsx(Aside, { className: "hidden lg:block lg:w-64 lg:shrink-0", "data-appshell-slot": "sidebar", children: sidebar })) : null, _jsx(Main, { className: "min-w-0 flex-1", "data-appshell-slot": "main", children: children })] }), footer ? (_jsx(BlockFooter, { className: "w-full", "data-appshell-slot": "footer", children: footer })) : null] }));
+    return (_jsxs(Stack, { className: `min-h-screen ${className ?? ""}`, children: [header ? (_jsx(BlockHeader, { className: "sticky top-0 z-30 w-full", "data-appshell-slot": "header", children: header })) : null, _jsxs(Div, { layout: "flex", className: "flex-1", children: [sidebar ? (_jsx(Aside, { className: "hidden lg:block lg:w-64 lg:shrink-0", "data-appshell-slot": "sidebar", children: sidebar })) : null, _jsx(Main, { className: "min-w-0 flex-1", "data-appshell-slot": "main", children: children })] }), footer ? (_jsx(BlockFooter, { className: "w-full", "data-appshell-slot": "footer", children: footer })) : null] }));
 }

package/dist/_internal/client/theme/ThemeProvider.js

@@ -20,7 +20,21 @@ function readModePreference() {
     catch (_err) {
         void normalizeError(_err); /* localStorage unavailable in privacy/iframe context */
     }
-    return "auto";
+    /*
+     * 🛑 LIGHT, not "auto" — a product decision, not a technical one.
+     *
+     * "auto" follows `prefers-color-scheme`, and most phones and an increasing
+     * share of desktops now report dark. That made dark the de-facto default
+     * for a storefront whose product photography is shot on white: every
+     * listing tile rendered a bright cut-out against a near-black card, which
+     * is the opposite of how the catalogue was designed to read.
+     *
+     * This changes the DEFAULT only. A visitor who has chosen either mode has
+     * "light"/"dark"/"auto" in localStorage and is returned above, untouched —
+     * including anyone who deliberately picked "auto". The dark theme itself is
+     * unchanged and one click away.
+     */
+    return "light";
 }
 function resolveEffectiveMode(preference) {
     if (preference === "light" || preference === "dark")

package/dist/_internal/server/features/auctions/og.d.ts

@@ -8,7 +8,9 @@ interface AuctionDocLike {
     title?: string | null;
     auctionEndDate?: Date | string | null;
     mainImage?: string | null;
-    images?: (string | null | undefined)[] | null;
+    images?: ({
+        url: string;
+    } | string | null | undefined)[] | null;
 }
 /** High-level OG renderer — accepts the raw auction document from `getAuctionForDetail`. */
 export declare function renderAuctionOg(doc: AuctionDocLike | null | undefined, opts: {

package/dist/_internal/server/features/auctions/og.js

@@ -14,7 +14,9 @@ export function renderAuctionOg(doc, opts) {
     return renderAuctionOgImage({
         title: doc?.title ?? "Live Auction",
         endsLabel,
-        imageUrl: resolveOgImageUrl(doc?.mainImage || doc?.images?.[0] || null, opts.baseUrl),
+        imageUrl: resolveOgImageUrl(doc?.mainImage ||
+            (typeof doc?.images?.[0] === "string" ? doc.images[0] : doc?.images?.[0]?.url) ||
+            null, opts.baseUrl),
     }, opts.siteName);
 }
 export function renderAuctionOgImage(data, siteName) {

package/dist/_internal/server/features/bundles/actions.js

@@ -68,7 +68,7 @@ quantity = 1) {
         quantity: 1,
         unitPrice: p.price,
         title: p.title,
-        image: p.images?.[0] ?? p.mainImage,
+        image: p.images?.[0]?.url ?? p.mainImage,
         gstRate: p.gstRate,
         hsnCode: p.hsnCode,
         listingType: normalizeListingType(p),

package/dist/_internal/server/features/business-documents/download.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Reads a statutory business document — GST certificate, Udyam registration,
+ * bank passbook — and decrypts it for an admin.
+ *
+ * 🛑 WHY THIS EXISTS rather than a `/media/{slug}` URL. Same two facts that
+ * forced `digital-code/download.ts` into the same shape, and either alone is
+ * enough:
+ *
+ *   1. `storage.rules` grants `allow read: if true` on EVERY object in the
+ *      bucket. All real access goes through the Admin SDK, so that is an
+ *      acceptable safety net — but it means Storage itself protects nothing.
+ *   2. `GET /api/media/[...slug]` performs NO authentication. It is a bare
+ *      handler with no session read, deliberately, because its job is public
+ *      product photography.
+ *
+ * So the bytes live under a private prefix that mints no `mediaAssets` row —
+ * and the row IS the public slug, so no row means no public URL — and are read
+ * only from here, after the route has checked the caller is an admin.
+ *
+ * On top of that, and unlike the digital-code case, these objects are stored
+ * ENCRYPTED: a bank passbook sitting in plaintext in a bucket whose rules say
+ * `read: if true` would depend entirely on nobody ever minting a slug for it.
+ */
+export interface BusinessDocumentResolution {
+    ok: boolean;
+    status?: number;
+    message?: string;
+    buffer?: Buffer;
+    contentType?: string;
+    fileName?: string;
+}
+/**
+ * Resolve, download and decrypt the document with id `documentId`.
+ *
+ * The caller is responsible for the authorization check — the route wraps this
+ * in `createRouteHandler({ roles: ROLES_ADMIN_ONLY, permission: "settings:write" })`.
+ * This function deliberately takes no viewer: there is no per-row ownership to
+ * evaluate, so inventing a `viewerUid` parameter it never reads would imply a
+ * check that is not happening here.
+ */
+export declare function resolveBusinessDocument(documentId: string): Promise<BusinessDocumentResolution>;

package/dist/_internal/server/features/business-documents/download.js

@@ -0,0 +1,91 @@
+/**
+ * Reads a statutory business document — GST certificate, Udyam registration,
+ * bank passbook — and decrypts it for an admin.
+ *
+ * 🛑 WHY THIS EXISTS rather than a `/media/{slug}` URL. Same two facts that
+ * forced `digital-code/download.ts` into the same shape, and either alone is
+ * enough:
+ *
+ *   1. `storage.rules` grants `allow read: if true` on EVERY object in the
+ *      bucket. All real access goes through the Admin SDK, so that is an
+ *      acceptable safety net — but it means Storage itself protects nothing.
+ *   2. `GET /api/media/[...slug]` performs NO authentication. It is a bare
+ *      handler with no session read, deliberately, because its job is public
+ *      product photography.
+ *
+ * So the bytes live under a private prefix that mints no `mediaAssets` row —
+ * and the row IS the public slug, so no row means no public URL — and are read
+ * only from here, after the route has checked the caller is an admin.
+ *
+ * On top of that, and unlike the digital-code case, these objects are stored
+ * ENCRYPTED: a bank passbook sitting in plaintext in a bucket whose rules say
+ * `read: if true` would depend entirely on nobody ever minting a slug for it.
+ */
+import { getAdminStorage } from "../../../../providers/db-firebase/index.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { decryptBuffer, isBufferEncrypted } from "../../../../security/settings-encryption.js";
+import { businessDocumentsRepository } from "../../../../features/business-documents/repository/business-documents.repository.js";
+/**
+ * Resolve, download and decrypt the document with id `documentId`.
+ *
+ * The caller is responsible for the authorization check — the route wraps this
+ * in `createRouteHandler({ roles: ROLES_ADMIN_ONLY, permission: "settings:write" })`.
+ * This function deliberately takes no viewer: there is no per-row ownership to
+ * evaluate, so inventing a `viewerUid` parameter it never reads would imply a
+ * check that is not happening here.
+ */
+export async function resolveBusinessDocument(documentId) {
+    const record = await businessDocumentsRepository.findById(documentId);
+    if (!record) {
+        return { ok: false, status: 404, message: "Document not found" };
+    }
+    let stored;
+    try {
+        const file = getAdminStorage().bucket().file(record.storagePath);
+        const [buffer] = await file.download();
+        stored = buffer;
+    }
+    catch (err) {
+        void normalizeError(err);
+        return { ok: false, status: 404, message: "Document is no longer available" };
+    }
+    /*
+     * Branch on the RECORDED flag, never on sniffing the buffer.
+     *
+     * `isBufferEncrypted` is used only to catch disagreement: a row that claims
+     * encryption over an object that has none means the upload half-failed or
+     * the object was replaced by hand, and handing those bytes back as though
+     * nothing were wrong is how a plaintext passbook gets served while every log
+     * line says it was encrypted. Refuse and say which way the mismatch runs.
+     */
+    if (record.encrypted !== isBufferEncrypted(stored)) {
+        return {
+            ok: false,
+            status: 500,
+            message: record.encrypted
+                ? "Stored document is not encrypted but its record says it is — refusing to serve it."
+                : "Stored document is encrypted but its record says it is not — refusing to guess.",
+        };
+    }
+    let plaintext;
+    if (record.encrypted) {
+        try {
+            plaintext = decryptBuffer(stored);
+        }
+        catch (err) {
+            // A GCM auth failure means the wrong key or a tampered object. Both are
+            // worth a 500 and a log; neither is worth telling the caller which.
+            void normalizeError(err);
+            return { ok: false, status: 500, message: "Document could not be decrypted" };
+        }
+    }
+    else {
+        plaintext = stored;
+    }
+    return {
+        ok: true,
+        buffer: plaintext,
+        contentType: record.contentType || "application/octet-stream",
+        fileName: record.fileName || "document",
+    };
+}

package/dist/_internal/server/features/categories/adapters.d.ts

@@ -31,7 +31,7 @@ import type { CategoryItem } from "../../../../features/categories/types/index";
  * the object literal in `toCategoryListItem` — the audit asserts both
  * directions.
  */
-export declare const PUBLIC_CATEGORY_FIELDS: readonly ["id", "name", "slug", "description", "rootId", "parentIds", "childrenIds", "tier", "path", "order", "isLeaf", "ancestors", "categoryType", "itemCode", "isFeatured", "featuredPriority", "seo", "display", "isActive", "highlights", "faqs", "brandWebsite", "brandCountry", "brandFounded", "metrics", "createdAt", "updatedAt"];
+export declare const PUBLIC_CATEGORY_FIELDS: readonly ["id", "name", "slug", "description", "rootId", "parentIds", "childrenIds", "tier", "path", "order", "isLeaf", "ancestors", "categoryType", "itemCode", "isFeatured", "featuredPriority", "seo", "display", "isActive", "highlights", "faqs", "brandWebsite", "brandCountry", "brandFounded", "hasbroName", "hasbroCoverImage", "metrics", "createdAt", "updatedAt"];
 /**
  * Fields withheld, each with the reason. Never remove one without replacing
  * the reason — "it seemed unused" is how a field ends up public by accident.

package/dist/_internal/server/features/categories/adapters.js

@@ -37,6 +37,14 @@ export const PUBLIC_CATEGORY_FIELDS = [
     "brandWebsite",
     "brandCountry",
     "brandFounded",
+    /*
+     * The Hasbro alternate name and its cover, rendered as "Also known as" by
+     * `CategoryDetailPageView`. Public because the whole point of the field is
+     * that a buyer who only knows the Hasbro season name can SEE the
+     * correspondence — a name on a toy box is not sensitive.
+     */
+    "hasbroName",
+    "hasbroCoverImage",
     // Rollup counts only — see `metrics` in the private list.
     "metrics",
     "createdAt",
@@ -217,6 +225,8 @@ export function toCategoryListItem(doc) {
         brandWebsite: doc.brandWebsite,
         brandCountry: doc.brandCountry,
         brandFounded: doc.brandFounded,
+        hasbroName: doc.hasbroName,
+        hasbroCoverImage: doc.hasbroCoverImage,
         metrics: toPublicMetrics(doc.metrics),
         // 🛑 `CategoryDocument` stores Dates; `CategoryItem` declares strings —
         // this projection is also the serialisation boundary. Converting here

package/dist/_internal/server/features/categories/price-guidance-resolve.d.ts

@@ -0,0 +1,66 @@
+import type { CategoryPriceGuidance } from "../../../../features/categories/schemas/category-content";
+/**
+ * How far up the chain to look.
+ *
+ * `parentIds` holds the FULL ancestor chain (CLAUDE.md § "Category Tree"), and
+ * the forest is four tiers, so eight is slack rather than a limit. It exists so
+ * a malformed chain cannot turn one lookup into an unbounded read.
+ */
+export declare const MAX_GUIDANCE_ANCESTORS = 8;
+/** The fields of a category document this resolution reads. */
+export interface GuidanceLeafDoc {
+    id?: string;
+    name?: string;
+    parentIds?: string[];
+    productDefaults?: {
+        priceGuidance?: CategoryPriceGuidance;
+    };
+}
+/**
+ * A resolved band together with WHERE it came from.
+ *
+ * 🛑 The provenance is not decoration, and a caller that drops it will
+ * misattribute. `MARKET_BANDS` is keyed on era and part leaves, never on the
+ * ~216 named-model leaves, so a model lookup almost always resolves an
+ * ancestor's band — "typical for Burst DB" is a true statement about the data
+ * and "typical for Rage Longinus" is not. A renderer needs to be able to say
+ * which one it is showing.
+ */
+export interface ResolvedGuidance {
+    guidance: CategoryPriceGuidance;
+    /** The node the band was read off — the leaf itself, or an ancestor. */
+    fromCategoryId: string;
+    fromName?: string;
+    /** `false` when the leaf carried its own band. */
+    inherited: boolean;
+}
+/**
+ * Nearest-first ancestor walk for one leaf.
+ *
+ * The leaf's own band wins; only a leaf with none falls back to the nearest
+ * ancestor that has one.
+ *
+ * 🛑 ONE bounded `findByIds`, never a sequential walk. A seller form hits this
+ * on every category change, and paying up to eight round trips for a hint is
+ * how a hint becomes the slowest thing on the page.
+ *
+ * 🛑 `parentIds` is stored ROOT-FIRST, so it is reversed to walk nearest-first.
+ * Walking it as stored would hand a model leaf the ROOT's band — and since the
+ * root carries a tax default but no market band, that would usually resolve to
+ * nothing and read as "no data" for a leaf whose era has a measured band.
+ */
+export declare function resolveInheritedGuidance(leaf: GuidanceLeafDoc): Promise<CategoryPriceGuidance | undefined>;
+/**
+ * The same resolution for MANY leaves, in two batched reads total.
+ *
+ * Read 1 fetches the leaves; read 2 fetches the UNION of every ancestor id
+ * none of them resolved locally. A per-leaf `resolveInheritedGuidance` would be
+ * N+1 reads against Rule #6's ~3-round-trip budget, and the tool resolves up to
+ * `PRICE_INDEX_SEARCH_LIMIT` leaves at once.
+ *
+ * Leaves that resolve to nothing are ABSENT from the returned map rather than
+ * present with `undefined` — the caller distinguishes "no band applies here"
+ * from "this id does not exist", and both are legitimate answers it must be
+ * able to tell apart.
+ */
+export declare function resolveInheritedGuidanceMany(ids: readonly string[]): Promise<Map<string, ResolvedGuidance>>;

package/dist/_internal/server/features/categories/price-guidance-resolve.js

@@ -0,0 +1,138 @@
+/*
+ * WHY: Two surfaces now need "the price guidance that applies to this leaf":
+ *      the seller form's hint (`/api/categories/[id]/price-guidance`) and the
+ *      public realised-price tool's gated market half
+ *      (`/api/tools/price-index/market`). The ancestor walk was written
+ *      privately inside the first of those, which is exactly the shape Root
+ *      Cause #75 describes — a rule reachable by copy-paste gets copied, and
+ *      the copy never learns about the branch added later.
+ * WHAT: The nearest-first inherited `priceGuidance` resolution, for one leaf
+ *       and for many, in one place.
+ *
+ * EXPORTS:
+ *   MAX_GUIDANCE_ANCESTORS      — the walk bound
+ *   ResolvedGuidance            — a band PLUS which node it came from
+ *   resolveInheritedGuidance    — one leaf document -> its applicable guidance
+ *   resolveInheritedGuidanceMany — N leaf ids -> a Map, two batched reads
+ *
+ * 🛑 Why a leaf's OWN band wins. `MARKET_BANDS` is keyed on era / part /
+ *    launcher / stadium leaves (`category-burst-db`, `category-metal-energy-rings`),
+ *    never on the ~216 named-model leaves — the crawl measured a generation,
+ *    not a bey. So a model leaf has no band of its own and inherits its era's,
+ *    which is the whole reason this walk exists rather than a direct read.
+ *
+ * @tag domain:categories
+ * @tag layer:server
+ * @tag pattern:resolver
+ * @tag access:server-only
+ * @tag consumers:categories/api/[id]/price-guidance,price-index/market
+ * @tag sideEffects:none
+ */
+import { categoriesRepository } from "../../../../features/categories/repository/categories.repository.js";
+/**
+ * How far up the chain to look.
+ *
+ * `parentIds` holds the FULL ancestor chain (CLAUDE.md § "Category Tree"), and
+ * the forest is four tiers, so eight is slack rather than a limit. It exists so
+ * a malformed chain cannot turn one lookup into an unbounded read.
+ */
+export const MAX_GUIDANCE_ANCESTORS = 8;
+/**
+ * Nearest-first ancestor walk for one leaf.
+ *
+ * The leaf's own band wins; only a leaf with none falls back to the nearest
+ * ancestor that has one.
+ *
+ * 🛑 ONE bounded `findByIds`, never a sequential walk. A seller form hits this
+ * on every category change, and paying up to eight round trips for a hint is
+ * how a hint becomes the slowest thing on the page.
+ *
+ * 🛑 `parentIds` is stored ROOT-FIRST, so it is reversed to walk nearest-first.
+ * Walking it as stored would hand a model leaf the ROOT's band — and since the
+ * root carries a tax default but no market band, that would usually resolve to
+ * nothing and read as "no data" for a leaf whose era has a measured band.
+ */
+export async function resolveInheritedGuidance(leaf) {
+    if (leaf.productDefaults?.priceGuidance)
+        return leaf.productDefaults.priceGuidance;
+    const parentIds = (leaf.parentIds ?? []).slice(0, MAX_GUIDANCE_ANCESTORS);
+    if (parentIds.length === 0)
+        return undefined;
+    const nearestFirst = [...parentIds].reverse();
+    const ancestors = await categoriesRepository.findByIds(nearestFirst);
+    const byId = new Map(ancestors.map((a) => [a.id, a]));
+    for (const pid of nearestFirst) {
+        const guidance = byId.get(pid)?.productDefaults?.priceGuidance;
+        if (guidance)
+            return guidance;
+    }
+    return undefined;
+}
+/**
+ * The same resolution for MANY leaves, in two batched reads total.
+ *
+ * Read 1 fetches the leaves; read 2 fetches the UNION of every ancestor id
+ * none of them resolved locally. A per-leaf `resolveInheritedGuidance` would be
+ * N+1 reads against Rule #6's ~3-round-trip budget, and the tool resolves up to
+ * `PRICE_INDEX_SEARCH_LIMIT` leaves at once.
+ *
+ * Leaves that resolve to nothing are ABSENT from the returned map rather than
+ * present with `undefined` — the caller distinguishes "no band applies here"
+ * from "this id does not exist", and both are legitimate answers it must be
+ * able to tell apart.
+ */
+export async function resolveInheritedGuidanceMany(ids) {
+    const out = new Map();
+    const unique = [...new Set(ids.filter((id) => typeof id === "string" && id.length > 0))];
+    if (unique.length === 0)
+        return out;
+    const leaves = (await categoriesRepository.getManyByIds(unique));
+    /*
+     * Everything still unanswered after the leaves' own bands, paired with the
+     * nearest-first chain it needs — collected before the second read so that
+     * read is one call for every leaf at once.
+     */
+    const pending = [];
+    const wanted = new Set();
+    for (const leaf of leaves) {
+        const id = leaf.id;
+        if (!id)
+            continue;
+        const own = leaf.productDefaults?.priceGuidance;
+        if (own) {
+            out.set(id, {
+                guidance: own,
+                fromCategoryId: id,
+                ...(leaf.name ? { fromName: leaf.name } : {}),
+                inherited: false,
+            });
+            continue;
+        }
+        const chain = [...(leaf.parentIds ?? []).slice(0, MAX_GUIDANCE_ANCESTORS)].reverse();
+        if (chain.length === 0)
+            continue;
+        pending.push({ id, chain });
+        for (const pid of chain)
+            wanted.add(pid);
+    }
+    if (pending.length === 0)
+        return out;
+    const ancestors = (await categoriesRepository.findByIds([...wanted]));
+    const byId = new Map(ancestors.filter((a) => a.id).map((a) => [a.id, a]));
+    for (const { id, chain } of pending) {
+        for (const pid of chain) {
+            const ancestor = byId.get(pid);
+            const guidance = ancestor?.productDefaults?.priceGuidance;
+            if (guidance) {
+                out.set(id, {
+                    guidance,
+                    fromCategoryId: pid,
+                    ...(ancestor?.name ? { fromName: ancestor.name } : {}),
+                    inherited: true,
+                });
+                break;
+            }
+        }
+    }
+    return out;
+}

package/dist/_internal/server/features/checkout/actions.d.ts

@@ -39,6 +39,20 @@ export declare function resolveShippingCost(storeId: string | undefined): Promis
     storeState: string | undefined;
     /** C5b — the resolved policy, so a caller can quote with the cart in hand. */
     shippingPolicy: StoreShippingPolicy;
+    /**
+     * The seller's own tax registration, from the store read this function
+     * already performs.
+     *
+     * Returned here rather than re-fetched in `createOrderForGroup` so the
+     * checkout path pays no extra Firestore read for data already in scope
+     * (Rule #6). Raw fields, not a resolved identity — the seller-vs-platform
+     * decision belongs to `resolveSupplierIdentity` alone.
+     */
+    storeTaxIdentity: {
+        gstin?: string;
+        legalName?: string;
+        registeredAddress?: string;
+    } | undefined;
     /**
      * 🛑 True when the mode is `estimate` and no carrier rate was supplied.
      *