@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.52.5",
-  "head": "7b24e76346651ca12f0a941e0d1ca87bb173a242",
+  "version": "4.53.1",
+  "head": "d45b9f65d4b73c4c4a079a8ee5553600ddd0c251",
   "branch": "main",
-  "dirty": true,
-  "builtAt": "2026-10-16T16:23:26.992Z"
+  "dirty": false,
+  "builtAt": "2026-10-19T21:36:59.723Z"
 }

package/dist/_internal/client/features/sticker-trace/canvas-codec.d.ts

@@ -0,0 +1,2 @@
+import type { ImageCodec } from "../../../shared/features/sticker-trace/codec";
+export declare const canvasCodec: ImageCodec;

package/dist/_internal/client/features/sticker-trace/canvas-codec.js

@@ -0,0 +1,148 @@
+"use client";
+/*
+ * One message, three throw sites. A 2d context is only ever null when the
+ * browser refuses the canvas outright (memory pressure, or a hardened
+ * environment), so all three mean the same thing and should read the same.
+ */
+const NO_CONTEXT = "OffscreenCanvas 2d context unavailable";
+/** RGBA out of a canvas, in exactly the layout DecodedRaster promises. */
+function toRaster(bitmap, dpi) {
+    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+    const ctx = canvas.getContext("2d", { willReadFrequently: true });
+    if (!ctx)
+        throw new Error(NO_CONTEXT);
+    ctx.drawImage(bitmap, 0, 0);
+    const data = ctx.getImageData(0, 0, bitmap.width, bitmap.height).data;
+    bitmap.close();
+    return {
+        width: canvas.width,
+        height: canvas.height,
+        data: new Uint8Array(data.buffer),
+        ...(dpi !== undefined ? { dpi } : {}),
+    };
+}
+async function encode(canvas, format) {
+    const type = format === "webp" ? "image/webp" : "image/png";
+    const blob = await canvas.convertToBlob({ type, ...(format === "webp" ? { quality: 0.82 } : {}) });
+    return { bytes: new Uint8Array(await blob.arrayBuffer()), contentType: type };
+}
+function canvasOf(raster) {
+    const canvas = new OffscreenCanvas(raster.width, raster.height);
+    const ctx = canvas.getContext("2d");
+    if (!ctx)
+        throw new Error(NO_CONTEXT);
+    ctx.putImageData(new ImageData(new Uint8ClampedArray(raster.data), raster.width, raster.height), 0, 0);
+    return canvas;
+}
+export const canvasCodec = {
+    /**
+     * 🛑 `declaredDpi` is ALWAYS absent here, and that is the one real asymmetry
+     * with the sharp codec.
+     *
+     * sharp reads the file's density header; a browser exposes no such API, and
+     * parsing EXIF/pHYs by hand would be a second metadata implementation whose
+     * disagreements with sharp nobody would notice. So the browser reports
+     * dimensions only — which costs nothing, because the operator confirms dpi
+     * anyway (five of the nine reference scans declare 72 or 96, an encoder
+     * default rather than a measurement) and a sheet with no trustworthy dpi
+     * already renders `bboxMm: null` rather than a fabricated figure.
+     *
+     * Also NOT header-only, unlike sharp's: `createImageBitmap` decodes. A
+     * browser cannot read a header without decoding, so this is dimensions at
+     * the cost of a decode — acceptable for one file the user just picked, and
+     * the reason the server probe exists for the upload path.
+     */
+    async probe(source) {
+        const bitmap = await createImageBitmap(new Blob([source]));
+        const result = { width: bitmap.width, height: bitmap.height };
+        bitmap.close();
+        return result;
+    },
+    async decode(source, opts) {
+        const blob = new Blob([source]);
+        // Probe dimensions first so the resize preserves aspect ratio and never
+        // ENLARGES — upscaling would invent sub-pixel detail the ridge detector
+        // would then find cut lines in.
+        const probe = await createImageBitmap(blob);
+        const longEdge = Math.max(probe.width, probe.height);
+        probe.close();
+        if (longEdge <= opts.maxLongEdge) {
+            return toRaster(await createImageBitmap(blob));
+        }
+        const k = opts.maxLongEdge / longEdge;
+        return toRaster(await createImageBitmap(blob, {
+            resizeWidth: Math.max(1, Math.round(probe.width * k)),
+            resizeHeight: Math.max(1, Math.round(probe.height * k)),
+            resizeQuality: "high",
+        }));
+    },
+    /**
+     * No resize — a tile is already bounded by the caller, and the `max` tier
+     * tiles precisely so it can read native pixels.
+     */
+    async decodeTile(source, tile) {
+        return toRaster(await createImageBitmap(new Blob([source]), {
+            sx: tile.x,
+            sy: tile.y,
+            sw: tile.width,
+            sh: tile.height,
+        }));
+    },
+    async encodePng(raster) {
+        return encode(canvasOf(raster), "png");
+    },
+    async encodePngRegion(source, region, alpha) {
+        const expected = region.width * region.height;
+        if (alpha.length !== expected) {
+            // Loud, matching the sharp codec: a silent mismatch yields a part with a
+            // plausible outline and the wrong transparency, invisible until it is cut.
+            throw new Error(`alpha mask is ${alpha.length} px, expected ${expected} for ${region.width}x${region.height}`);
+        }
+        const raster = await this.decodeTile(source, region);
+        const px = raster.data;
+        for (let i = 0; i < expected; i++)
+            px[i * 4 + 3] = alpha[i];
+        return encode(canvasOf({ width: region.width, height: region.height, data: px }), "png");
+    },
+    async encodePreview(source, opts) {
+        const raster = await this.decode(source, { maxLongEdge: opts.maxLongEdge });
+        return encode(canvasOf(raster), opts.format);
+    },
+    /**
+     * Uniform-cell grid, identical in layout to the sharp codec's — the frames
+     * map is a contract the review UI reads, so the two must agree on geometry
+     * even though they agree on nothing about how they draw.
+     */
+    async encodeAtlas(tiles, opts) {
+        if (tiles.length === 0) {
+            // A zero-part run is a real outcome; a valid 1x1 beats throwing.
+            return {
+                image: await encode(new OffscreenCanvas(1, 1), "png"),
+                frames: {},
+            };
+        }
+        const cols = Math.ceil(Math.sqrt(tiles.length));
+        const rows = Math.ceil(tiles.length / cols);
+        const cell = Math.max(1, Math.min(Math.floor(opts.maxLongEdge / cols), ...tiles.map((t) => Math.max(t.raster.width, t.raster.height))));
+        const canvas = new OffscreenCanvas(cols * cell, rows * cell);
+        const ctx = canvas.getContext("2d");
+        if (!ctx)
+            throw new Error(NO_CONTEXT);
+        const frames = {};
+        for (let i = 0; i < tiles.length; i++) {
+            const t = tiles[i];
+            const left = (i % cols) * cell;
+            const top = Math.floor(i / cols) * cell;
+            // `fit: inside` equivalent — preserve aspect, never enlarge.
+            const k = Math.min(cell / t.raster.width, cell / t.raster.height, 1);
+            const w = Math.max(1, Math.round(t.raster.width * k));
+            const h = Math.max(1, Math.round(t.raster.height * k));
+            ctx.drawImage(canvasOf(t.raster), left, top, w, h);
+            // The frame is the tile's ACTUAL size, not the cell: a wide sticker does
+            // not fill a square cell, and a client slicing by `cell` would include
+            // its neighbours' padding.
+            frames[t.ordinal] = { x: left, y: top, width: w, height: h };
+        }
+        return { image: await encode(canvas, "png"), frames };
+    },
+};

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/server/features/auctions/actions.js

@@ -31,7 +31,7 @@ export async function placeBidAction(input) {
         // marking included. It cost a full-collection query and an exception per
         // bid placed, and the real `setWinningBid(bid.id, …)` below already marks
         // every other bid for this product as outbid.)
-        const bid = await bidRepository.create({
+        const bid = await bidRepository.createBid({
             productId: auctionId,
             productTitle: product.title ?? auctionId,
             userId: user.uid,

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

@@ -63,11 +63,27 @@ export const getCategoryTree = cache(async (rootId) => {
 });
 /** Flat category list for sitemap generation. */
 export const listSitemapCategories = cache(async () => {
-    return categoriesRepository
-        .list({ filters: "isActive==true", sorts: "-updatedAt", page: 1, pageSize: CATEGORIES_SITEMAP_LIMIT })
-        .then((r) => {
-        const docs = r.data ?? [];
-        return docs.map(({ slug, updatedAt }) => ({ slug, updatedAt }));
-    })
-        .catch(() => []);
+    /*
+     * 🛑 `safeRead`, not `.catch(() => [])`. This function feeds the SITEMAP,
+     * so a swallowed Firestore failure publishes an empty category sitemap to
+     * crawlers and nothing anywhere says why — the single worst place in the
+     * app for a failure that reads as "there is no data". Root Cause #81 is
+     * what a quietly wrong sitemap costs.
+     *
+     * The fallback is still `[]` (a sitemap must render), but the degradation
+     * is now a `DEGRADED_READ` row instead of silence. The file already used
+     * `safeRead` a few lines up; this site was simply missed.
+     */
+    const r = await safeRead(() => categoriesRepository.list({
+        filters: "isActive==true",
+        sorts: "-updatedAt",
+        page: 1,
+        pageSize: CATEGORIES_SITEMAP_LIMIT,
+    }), {
+        route: "sitemap",
+        key: "categories.listSitemapCategories",
+        fallback: null,
+    });
+    const docs = r?.data ?? [];
+    return docs.map(({ slug, updatedAt }) => ({ slug, updatedAt }));
 });

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.
      *