@mohasinac/appkit 4.38.0 → 4.39.0

package/dist/_internal/server/jobs/core/onCategoryWrite.js

@@ -4,6 +4,39 @@ import { normalizeError } from "../../../../errors/normalize";
  * CREATE → insert into parent's subtree + shift later siblings;
  * DELETE → shift back; MOVE → mark `positionDirty` so the nightly reconcile
  * job rebuilds.
+ *
+ * trigger-self-write-ok: terminates at depth 1 — the only branch that writes is
+ * gated on `parentIds` CHANGING, and none of this handler's own writes touch
+ * `parentIds`.
+ *
+ * 🛑 WHY THAT IS SAFE, SPELLED OUT — this is a `documentWritten` trigger on
+ * `categories` that writes back to `categories`, including to the triggering
+ * document (L110). That is the shape of Root Cause #92, which logged 1,017,548
+ * invocations in 24 hours, so it deserves an explicit argument rather than trust:
+ *
+ *   CREATE writes → sibling `position`s, own `position`/`subtreeSize`, ancestor
+ *                   `subtreeSize`. Every one re-enters as an UPDATE.
+ *   DELETE writes → sibling `position`s, ancestor `subtreeSize`. Same.
+ *   UPDATE        → writes ONLY when `beforeParent !== afterParent`. None of the
+ *                   writes above change `parentIds`, so the re-entry compares
+ *                   equal and does nothing. The cascade stops.
+ *   MOVE          → writes `positionDirty`, which is also not `parentIds`, so its
+ *                   own re-entry likewise does nothing. One extra hop, then stop.
+ *
+ * The guard is STRUCTURAL, not a value comparison — that is what makes it stronger
+ * than #92's. `onShipmentHeaderWrite` recomputed and rewrote the same derived field
+ * every time and relied on `JSON.stringify` equality to notice it had not changed;
+ * key-order sensitivity made that comparison always false, so it re-triggered
+ * forever. Here there is nothing to compare: the handler cannot write the field it
+ * branches on.
+ *
+ * 🛑 If you ever make this handler write `parentIds`, it becomes a true loop. Do
+ * not — a move is deliberately deferred to the nightly reconcile for this reason.
+ *
+ * Not free, though: creating one category writes to its siblings, its ancestors and
+ * itself, and each of those writes spawns a no-op invocation. A full reseed of the
+ * 58-category forest therefore costs on the order of thousands of invocations, all
+ * of them terminating. That is a cost worth knowing before a reseed, not a runaway.
  */
 import { FieldValue } from "firebase-admin/firestore";
 import { BATCH_LIMIT } from "../handlers/messages";

package/dist/_internal/server/jobs/core/onProductWrite.js

@@ -23,48 +23,102 @@ async function getParentIds(categoryId) {
         return [];
     return (await categoriesRepository.findById(categoryId))?.parentIds ?? [];
 }
+/**
+ * 🛑 THIS IS A CROSS-COLLECTION TRIGGER AND THAT IS THE SAFETY ARGUMENT.
+ *
+ * It watches `products` and writes to `categories`, so its own writes cannot
+ * re-trigger it — there is no termination condition to get right, because there
+ * is no cycle. Contrast `onCategoryWrite`, which DOES write its own collection
+ * and is safe only because of a structural guard on `parentIds`.
+ *
+ * **Do not move this counting into `onCategoryWrite`.** A `categories` trigger
+ * that increments a `categories` document is exactly the shape of Root Cause
+ * #92 — `onShipmentHeaderWrite` recursed 1,017,548 times in 24 hours against a
+ * 2M/month quota because a key-order-sensitive `JSON.stringify` guard could
+ * never return true, and the only symptom was a billing page.
+ *
+ * Brands ride along here rather than in a second trigger: a brand IS a
+ * `categoryType:"brand"` row in the same collection, so it is the same write to
+ * the same place, and splitting it would double the invocations for nothing.
+ * A brand has no ancestors, so it is staged with an empty parent chain and its
+ * own count equals its rollup by construction.
+ */
 async function dispatchProductWriteEvent(p) {
-    const { productId, beforeCategory, afterCategory, beforeStoreId, afterStoreId, isAuction, beforeIsAuction, wasPublished, isPublished, isDelete, ctx } = p;
-    if (isDelete && wasPublished && beforeCategory) {
-        const parentIds = await getParentIds(beforeCategory);
-        const batch = ctx.db.batch();
-        categoriesRepository.updateMetricsInBatch(batch, beforeCategory, parentIds, beforeIsAuction ? 0 : -1, beforeIsAuction ? -1 : 0, productId);
+    const { productId, beforeCategory, afterCategory, beforeBrand, afterBrand, beforeStoreId, afterStoreId, isAuction, beforeIsAuction, wasPublished, isPublished, isDelete, ctx } = p;
+    /** Stage one category (and, if given, one brand) at `sign` × 1 item. */
+    const stage = (batch, categoryId, brandId, parentIds, auction, sign) => {
+        const productDelta = auction ? 0 : sign;
+        const auctionDelta = auction ? sign : 0;
+        if (categoryId) {
+            categoriesRepository.updateMetricsInBatch(batch, categoryId, parentIds, productDelta, auctionDelta, productId);
+        }
+        if (brandId) {
+            categoriesRepository.updateMetricsInBatch(batch, brandId, [], productDelta, auctionDelta, productId);
+        }
+    };
+    /*
+     * `batch.update()` REJECTS a missing document, and a batch is atomic — so one
+     * dangling ancestor id loses every increment in the batch, not just its own.
+     * That throw is caught by the caller and logged non-fatally, which is correct:
+     * a counter is not worth failing a product write over. What makes it
+     * acceptable is that `countersReconcile` now RECOUNTS FROM SCRATCH nightly and
+     * rewrites every row that disagrees, so a lost increment self-heals within a
+     * day and shows up as a non-zero `drifted` in that job's log.
+     */
+    const commit = async (batch, what, meta) => {
         await batch.commit();
+        ctx.logger.info(what, { productId, ...meta });
+    };
+    if (isDelete && wasPublished && (beforeCategory || beforeBrand)) {
+        const batch = ctx.db.batch();
+        stage(batch, beforeCategory, beforeBrand, await getParentIds(beforeCategory ?? ""), beforeIsAuction, -1);
+        await commit(batch, "Decremented counters on hard-delete", { category: beforeCategory, brand: beforeBrand, storeId: beforeStoreId });
         if (beforeStoreId)
             await storeRepository.incrementTotalProducts(beforeStoreId, -1);
-        ctx.logger.info("Decremented counters on hard-delete", { productId, category: beforeCategory, storeId: beforeStoreId });
         return;
     }
-    if (!wasPublished && isPublished && afterCategory) {
-        const parentIds = await getParentIds(afterCategory);
+    if (!wasPublished && isPublished && (afterCategory || afterBrand)) {
         const batch = ctx.db.batch();
-        categoriesRepository.updateMetricsInBatch(batch, afterCategory, parentIds, isAuction ? 0 : 1, isAuction ? 1 : 0, productId);
-        await batch.commit();
+        stage(batch, afterCategory, afterBrand, await getParentIds(afterCategory ?? ""), isAuction, 1);
+        await commit(batch, "Incremented counters on publish", { category: afterCategory, brand: afterBrand, storeId: afterStoreId });
         if (afterStoreId)
             await storeRepository.incrementTotalProducts(afterStoreId, 1);
-        ctx.logger.info("Incremented counters on publish", { productId, category: afterCategory, storeId: afterStoreId });
         return;
     }
-    if (wasPublished && !isPublished && beforeCategory) {
-        const parentIds = await getParentIds(beforeCategory);
+    if (wasPublished && !isPublished && (beforeCategory || beforeBrand)) {
         const batch = ctx.db.batch();
-        categoriesRepository.updateMetricsInBatch(batch, beforeCategory, parentIds, beforeIsAuction ? 0 : -1, beforeIsAuction ? -1 : 0, productId);
-        await batch.commit();
+        stage(batch, beforeCategory, beforeBrand, await getParentIds(beforeCategory ?? ""), beforeIsAuction, -1);
+        await commit(batch, "Decremented counters on unpublish", { category: beforeCategory, brand: beforeBrand, storeId: beforeStoreId });
         if (beforeStoreId)
             await storeRepository.incrementTotalProducts(beforeStoreId, -1);
-        ctx.logger.info("Decremented counters on unpublish", { productId, category: beforeCategory, storeId: beforeStoreId });
         return;
     }
-    if (wasPublished && isPublished && beforeCategory && afterCategory && beforeCategory !== afterCategory) {
+    /*
+     * Still published, but re-filed. This is the branch a naive trigger gets
+     * wrong — incrementing the new home without decrementing the old one is how
+     * a count drifts permanently upward with no event to blame it on. Category
+     * and brand are tested INDEPENDENTLY because either can move without the
+     * other: re-tagging the brand while the category stands still used to fall
+     * through every branch and silently leave both brand rows wrong.
+     */
+    if (wasPublished && isPublished) {
+        const categoryMoved = beforeCategory !== afterCategory;
+        const brandMoved = beforeBrand !== afterBrand;
+        if (!categoryMoved && !brandMoved)
+            return;
         const [beforeParents, afterParents] = await Promise.all([
-            getParentIds(beforeCategory),
-            getParentIds(afterCategory),
+            getParentIds(categoryMoved ? beforeCategory ?? "" : ""),
+            getParentIds(categoryMoved ? afterCategory ?? "" : ""),
         ]);
         const batch = ctx.db.batch();
-        categoriesRepository.updateMetricsInBatch(batch, beforeCategory, beforeParents, beforeIsAuction ? 0 : -1, beforeIsAuction ? -1 : 0, productId);
-        categoriesRepository.updateMetricsInBatch(batch, afterCategory, afterParents, isAuction ? 0 : 1, isAuction ? 1 : 0, productId);
-        await batch.commit();
-        ctx.logger.info("Moved product between categories", { productId, from: beforeCategory, to: afterCategory });
+        stage(batch, categoryMoved ? beforeCategory : null, brandMoved ? beforeBrand : null, beforeParents, beforeIsAuction, -1);
+        stage(batch, categoryMoved ? afterCategory : null, brandMoved ? afterBrand : null, afterParents, isAuction, 1);
+        await commit(batch, "Re-filed product", {
+            fromCategory: categoryMoved ? beforeCategory : undefined,
+            toCategory: categoryMoved ? afterCategory : undefined,
+            fromBrand: brandMoved ? beforeBrand : undefined,
+            toBrand: brandMoved ? afterBrand : undefined,
+        });
     }
 }
 export async function handleProductWrite(input, ctx) {
@@ -77,6 +131,16 @@ export async function handleProductWrite(input, ctx) {
     // no-op category metrics here. Prefer categorySlugs[0], fall back to legacy category.
     const beforeCategory = getEffectiveCategory(before);
     const afterCategory = getEffectiveCategory(after);
+    /*
+     * `brandSlug` is the brand ROW's document id in this same `categories`
+     * collection. `brand` is the display NAME and is not a key — CLAUDE.md's
+     * § "Brand matching is by DISPLAY NAME" — so it must never be used here.
+     * Nothing had ever written a brand row's metrics, while
+     * BrandDetailPageView.tsx:124 reads `brand?.metrics?.productCount` — so every
+     * brand page fell through to its tab count or to a hard 0.
+     */
+    const beforeBrand = before?.brandSlug ?? null;
+    const afterBrand = after?.brandSlug ?? null;
     const beforeStoreId = (before?.storeId || before?.sellerId) ?? null;
     const afterStoreId = (after?.storeId || after?.sellerId) ?? null;
     const isAuction = after?.listingType === PRODUCT_FIELDS.LISTING_TYPE_VALUES.AUCTION;
@@ -86,12 +150,16 @@ export async function handleProductWrite(input, ctx) {
     const isDelete = !after;
     try {
         await dispatchProductWriteEvent({
-            productId, beforeCategory, afterCategory, beforeStoreId, afterStoreId,
+            productId, beforeCategory, afterCategory, beforeBrand, afterBrand,
+            beforeStoreId, afterStoreId,
             isAuction, beforeIsAuction, wasPublished, isPublished, isDelete, ctx,
         });
     }
     catch (err) {
         void normalizeError(err);
-        ctx.logger.error("Counter update failed (non-fatal)", err, { productId });
+        // Non-fatal on purpose — a counter must never fail a product write. The
+        // healer is `countersReconcile`, which recounts from scratch nightly and
+        // reports how many rows it had to correct.
+        ctx.logger.error("Counter update failed (non-fatal — countersReconcile will heal it tonight)", err, { productId });
     }
 }

package/dist/_internal/server/notifications/send-recorder.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Record what the mailer decided, so the tester can assert on it without an inbox.
+ *
+ * ## Why this exists
+ *
+ * 21 checklist cases are about email. Reading a real mailbox over IMAP can answer
+ * some of them, but it is the wrong instrument for most:
+ *
+ *   - **Six of them assert an email should NOT arrive** (kill switch spares staff,
+ *     opt-out honoured, no employee blast, losing bidders get no mail). Over IMAP,
+ *     "nothing arrived" is unprovable — you wait N seconds and hope, and a slow
+ *     inbox is indistinguishable from a working suppression. Here it is one read.
+ *   - Delivery latency makes every other case slow and flaky for no added truth:
+ *     whether Resend accepted the handoff says nothing about whether the app made
+ *     the right decision, which is what the cases are actually about.
+ *
+ * So this records the DECISION and its inputs. A real inbox is still the only
+ * proof of real delivery, and the two or three cases that assert that keep using
+ * one (`tester/scripts/lib/inbox.mjs`).
+ *
+ * ## Why here and not in `guardSend`
+ *
+ * `SendGuardContext` carries channel/feature/audience and deliberately no
+ * recipient — the guard's own docstring explains it must not become the transport.
+ * `sendEmail()` is the one place that holds the recipient, the rendered body AND
+ * the guard's verdict, which is exactly the tuple a case needs.
+ *
+ * ## 🛑 Gated, because recording real people's mail is a privacy problem
+ *
+ * Recording recipients and bodies for actual users would be a new PII store with
+ * no retention story. So this writes ONLY when the recipient is the harness
+ * mailbox (`TESTER_EMAIL_ID`), or when `EMAIL_RECORDER_ALL` is explicitly set for
+ * local debugging. Absent that env var, this function is a no-op and costs one
+ * string comparison.
+ *
+ * Best-effort throughout: a recorder that can fail a send is worse than no
+ * recorder, so every path swallows. Same discipline as `recordAdminAction`.
+ *
+ * @tag domain:notifications,tester
+ * @tag layer:server
+ * @tag access:server-only
+ */
+/** Firestore collection holding the canonical record. */
+export declare const EMAIL_EVENTS_COLLECTION = "emailEvents";
+export type EmailSendOutcome = "sent" | "suppressed" | "failed";
+export interface EmailSendRecord {
+    /** Recipient(s), as passed to the provider. */
+    to: string | string[];
+    subject: string;
+    /** `feature` from the guard — the notification type or named flow. */
+    feature: string;
+    audience: string;
+    channel: string;
+    outcome: EmailSendOutcome;
+    /** Suppression reason (`admin_disabled`, `daily_ceiling`, …) or the error text. */
+    reason?: string;
+    /**
+     * The rendered body. Recorded so a case can assert the email has a heading, a
+     * lead line and a button rather than one bare paragraph — an assertion that is
+     * otherwise only checkable by eye in a real client.
+     */
+    html?: string;
+}
+/**
+ * Should this send be recorded at all?
+ *
+ * Exported so the audit and tests can exercise the gate directly rather than
+ * inferring it from behaviour.
+ */
+export declare function shouldRecordSend(to: string | string[]): boolean;
+/**
+ * Write the record. Never throws, never blocks the send.
+ *
+ * Firestore is canonical and RTDB is only a ping — the same split the messaging
+ * feature already uses. The body does NOT go into RTDB: `bulk_events` is
+ * uncapped and a newsletter CSV already goes there, which is the mistake not to
+ * repeat on a channel that fires on every email.
+ */
+export declare function recordSendAttempt(record: EmailSendRecord): Promise<void>;

package/dist/_internal/server/notifications/send-recorder.js

@@ -0,0 +1,126 @@
+/**
+ * Record what the mailer decided, so the tester can assert on it without an inbox.
+ *
+ * ## Why this exists
+ *
+ * 21 checklist cases are about email. Reading a real mailbox over IMAP can answer
+ * some of them, but it is the wrong instrument for most:
+ *
+ *   - **Six of them assert an email should NOT arrive** (kill switch spares staff,
+ *     opt-out honoured, no employee blast, losing bidders get no mail). Over IMAP,
+ *     "nothing arrived" is unprovable — you wait N seconds and hope, and a slow
+ *     inbox is indistinguishable from a working suppression. Here it is one read.
+ *   - Delivery latency makes every other case slow and flaky for no added truth:
+ *     whether Resend accepted the handoff says nothing about whether the app made
+ *     the right decision, which is what the cases are actually about.
+ *
+ * So this records the DECISION and its inputs. A real inbox is still the only
+ * proof of real delivery, and the two or three cases that assert that keep using
+ * one (`tester/scripts/lib/inbox.mjs`).
+ *
+ * ## Why here and not in `guardSend`
+ *
+ * `SendGuardContext` carries channel/feature/audience and deliberately no
+ * recipient — the guard's own docstring explains it must not become the transport.
+ * `sendEmail()` is the one place that holds the recipient, the rendered body AND
+ * the guard's verdict, which is exactly the tuple a case needs.
+ *
+ * ## 🛑 Gated, because recording real people's mail is a privacy problem
+ *
+ * Recording recipients and bodies for actual users would be a new PII store with
+ * no retention story. So this writes ONLY when the recipient is the harness
+ * mailbox (`TESTER_EMAIL_ID`), or when `EMAIL_RECORDER_ALL` is explicitly set for
+ * local debugging. Absent that env var, this function is a no-op and costs one
+ * string comparison.
+ *
+ * Best-effort throughout: a recorder that can fail a send is worse than no
+ * recorder, so every path swallows. Same discipline as `recordAdminAction`.
+ *
+ * @tag domain:notifications,tester
+ * @tag layer:server
+ * @tag access:server-only
+ */
+import { normalizeError } from "../../../errors/normalize";
+import { serverLogger } from "../../../monitoring";
+import { RTDB_PATHS } from "../../../providers/db-firebase/rtdb-paths";
+/** Firestore collection holding the canonical record. */
+export const EMAIL_EVENTS_COLLECTION = "emailEvents";
+/** Normalise `to` for comparison and storage. */
+function recipients(to) {
+    return (Array.isArray(to) ? to : [to]).map((t) => String(t).trim().toLowerCase()).filter(Boolean);
+}
+/**
+ * Should this send be recorded at all?
+ *
+ * Exported so the audit and tests can exercise the gate directly rather than
+ * inferring it from behaviour.
+ */
+export function shouldRecordSend(to) {
+    if (process.env.EMAIL_RECORDER_ALL === "true")
+        return true;
+    const mailbox = process.env.TESTER_EMAIL_ID?.trim().toLowerCase();
+    if (!mailbox)
+        return false;
+    return recipients(to).includes(mailbox);
+}
+/**
+ * Write the record. Never throws, never blocks the send.
+ *
+ * Firestore is canonical and RTDB is only a ping — the same split the messaging
+ * feature already uses. The body does NOT go into RTDB: `bulk_events` is
+ * uncapped and a newsletter CSV already goes there, which is the mistake not to
+ * repeat on a channel that fires on every email.
+ */
+export async function recordSendAttempt(record) {
+    if (!shouldRecordSend(record.to))
+        return;
+    try {
+        const { getAdminDb } = await import("../../../providers/db-firebase/admin");
+        const db = getAdminDb();
+        const now = new Date();
+        const doc = {
+            to: recipients(record.to),
+            subject: record.subject,
+            feature: record.feature,
+            audience: record.audience,
+            channel: record.channel,
+            outcome: record.outcome,
+            reason: record.reason ?? null,
+            html: record.html ?? null,
+            createdAt: now,
+        };
+        const ref = await db.collection(EMAIL_EVENTS_COLLECTION).add(doc);
+        /*
+         * The ping. Tiny by design: an id, the outcome and the feature are enough for
+         * a poller to know something happened and go read the Firestore row.
+         * Best-effort separately from the write above — losing the ping costs a
+         * poller one extra second, losing the record costs the case its evidence.
+         */
+        try {
+            const { getAdminRealtimeDb } = await import("../../../providers/db-firebase/admin");
+            await getAdminRealtimeDb()
+                .ref(`${RTDB_PATHS.EMAIL_EVENTS}/${ref.id}`)
+                .set({
+                id: ref.id,
+                feature: record.feature,
+                outcome: record.outcome,
+                at: now.toISOString(),
+            });
+        }
+        catch (err) {
+            // Deliberately unreported: the Firestore row above is the record, and it
+            // already succeeded by the time this runs. Losing the ping costs a poller
+            // one extra second of latency and loses no evidence, so logging it would
+            // add noise to every transient RTDB blip for no recoverable information.
+            void normalizeError(err);
+        }
+    }
+    catch (err) {
+        const n = normalizeError(err);
+        serverLogger.warn("recordSendAttempt: could not record email event", {
+            feature: record.feature,
+            outcome: record.outcome,
+            message: n.message,
+        });
+    }
+}

package/dist/client.d.ts

@@ -414,6 +414,8 @@ export { NavPermissionsManager } from "./features/site-settings/components/NavPe
 export type { NavPermissionsManagerProps, NavGroup as NavPermissionsGroup, NavItem as NavPermissionsItem } from "./features/site-settings/components/NavPermissionsManager";
 export { CodeRevealPanel } from "./_internal/client/features/digital-code/CodeRevealPanel";
 export type { CodeRevealPanelProps, RevealedCode } from "./_internal/client/features/digital-code/CodeRevealPanel";
+export { DigitalContentPoolManager } from "./_internal/client/features/digital-code/DigitalContentPoolManager";
+export type { DigitalContentPoolManagerProps, PoolEntry } from "./_internal/client/features/digital-code/DigitalContentPoolManager";
 export { PhysicalLocationModal } from "./features/seller/components/PhysicalLocationModal";
 export type { PhysicalLocation } from "./features/seller/components/PhysicalLocationModal";
 export { Toggle } from "./ui/components/Toggle";

package/dist/client.js

@@ -424,6 +424,12 @@ export { ActionPermissionsManager } from "./features/site-settings/components/Ac
 export { NavPermissionsManager } from "./features/site-settings/components/NavPermissionsManager";
 // ── Digital-code code-reveal panel (still used directly on order pages) ───────
 export { CodeRevealPanel } from "./_internal/client/features/digital-code/CodeRevealPanel";
+/*
+ * The SELLER half. Without a surface the pool routes are unreachable, which is
+ * the same "finished feature nobody can get to" gap that left the pool empty in
+ * the first place (its only writer answered 501).
+ */
+export { DigitalContentPoolManager } from "./_internal/client/features/digital-code/DigitalContentPoolManager";
 export { PhysicalLocationModal } from "./features/seller/components/PhysicalLocationModal";
 // [CLIENT-ONLY] — Toggle switch primitive.
 export { Toggle } from "./ui/components/Toggle";

package/dist/features/blog/components/BlogIndexPageView.js

@@ -14,7 +14,16 @@ export async function BlogIndexPageView({ searchParams = {} }) {
     const page = Number(sp(searchParams, "page")) || 1;
     const pageSize = Number(sp(searchParams, "pageSize")) || 24;
     const category = sp(searchParams, "category");
-    const sieveResult = await safeRead(() => blogRepository.listPublished({ ...(category ? { category } : {}) }, { sorts: sort, page, pageSize }), { route: "/blog", key: "blogPosts.listPublished", fallback: null });
+    /*
+     * 🛑 `q` MUST be read and forwarded. Without it /blog?q=anything rendered the
+     * FULL published list — the same failure the API route's own header records
+     * having already fixed on its side, never back-ported here (Root Cause #59).
+     * It cannot self-correct on the client either: this result becomes
+     * `initialData`, and the listing hook sets `staleTime: Infinity` when given
+     * SSR data, so the unfiltered first paint is frozen for that query key.
+     */
+    const q = sp(searchParams, "q").trim();
+    const sieveResult = await safeRead(() => blogRepository.listPublished({ ...(category ? { category } : {}), ...(q ? { search: q } : {}) }, { sorts: sort, page, pageSize }), { route: "/blog", key: "blogPosts.listPublished", fallback: null });
     // Sandbox posts are public rows by design — not on someone else's first paint.
     const publicSieve = sieveResult
         ? { ...sieveResult, items: hidePublicTestData(sieveResult.items) }

package/dist/features/blog/repository/blog.repository.d.ts

@@ -83,9 +83,23 @@ declare class BlogRepository extends BaseRepository<BlogPostDocument> {
             parseValue: typeof parseSieveDateValue;
         };
     };
+    /**
+     * `search` uses the same `searchTxt` push-down as `listAll` — head token as an
+     * `array-contains` clause, remaining tokens AND-refined in memory.
+     *
+     * 🛑 IT HAD NO SEARCH PARAMETER AT ALL, and that is why /blog?q= was inert.
+     * `blogGET` searches via `listAll(model, { search })`, but the SSR view calls
+     * THIS method, so the server-rendered list ignored `q` entirely — and because
+     * that result is handed to the client as `initialData` under
+     * `staleTime: Infinity`, the unfiltered first paint was frozen and never
+     * refetched. Root Cause #59: the fix went into the API route and was never
+     * back-ported to the SSR view that duplicates its job. The route's own header
+     * documents the API-side half of this exact bug.
+     */
     listPublished(opts: {
         category?: BlogPostCategory;
         featuredOnly?: boolean;
+        search?: string;
     }, model: SieveModel): Promise<FirebaseSieveResult<BlogPostDocument>>;
     /** Derived on every write path via `applyWriteHooks`. */
     protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;

package/dist/features/blog/repository/blog.repository.js

@@ -143,7 +143,25 @@ class BlogRepository extends BaseRepository {
             throw new DatabaseError(`Failed to find posts by author: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
+    /**
+     * `search` uses the same `searchTxt` push-down as `listAll` — head token as an
+     * `array-contains` clause, remaining tokens AND-refined in memory.
+     *
+     * 🛑 IT HAD NO SEARCH PARAMETER AT ALL, and that is why /blog?q= was inert.
+     * `blogGET` searches via `listAll(model, { search })`, but the SSR view calls
+     * THIS method, so the server-rendered list ignored `q` entirely — and because
+     * that result is handed to the client as `initialData` under
+     * `staleTime: Infinity`, the unfiltered first paint was frozen and never
+     * refetched. Root Cause #59: the fix went into the API route and was never
+     * back-ported to the SSR view that duplicates its job. The route's own header
+     * documents the API-side half of this exact bug.
+     */
     async listPublished(opts, model) {
+        // A search that yields no usable token must return NOTHING, not the whole
+        // published list — the same contract listAll and listForSeller keep.
+        const plan = planSearchTxt(opts?.search);
+        if (plan.empty)
+            return emptySearchResult();
         let baseQuery = this.getCollection().where(BLOG_POST_FIELDS.STATUS, "==", "published");
         if (opts?.category) {
             baseQuery = baseQuery.where(BLOG_POST_FIELDS.CATEGORY, "==", opts.category);
@@ -151,11 +169,15 @@ class BlogRepository extends BaseRepository {
         if (opts?.featuredOnly) {
             baseQuery = baseQuery.where(BLOG_POST_FIELDS.IS_FEATURED, "==", true);
         }
-        return this.sieveQuery(model, BlogRepository.SIEVE_FIELDS, {
+        if (plan.head) {
+            baseQuery = baseQuery.where(BLOG_POST_FIELDS.SEARCH_TXT, "array-contains", plan.head);
+        }
+        const result = await this.sieveQuery(model, BlogRepository.SIEVE_FIELDS, {
             baseQuery,
             defaultPageSize: 12,
             maxPageSize: 50,
         });
+        return refineSearchTxt(result, plan.rest);
     }
     /** Derived on every write path via `applyWriteHooks`. */
     buildSearchTxtFor(data) {

package/dist/features/categories/components/CategoryDetailPageView.js

@@ -155,5 +155,5 @@ export async function CategoryDetailPageView({ slug }) {
     const hasCover = Boolean(coverImage);
     return (_jsxs(Main, { children: [_jsxs(Section, { className: `relative ${__O.hidden} ${hasCover ? "min-h-[220px] md:min-h-[280px]" : "bg-[var(--appkit-color-bg)]"}`, children: [hasCover && (_jsxs(_Fragment, { children: [_jsx(Div, { className: "absolute inset-0", children: _jsx(MediaImage, { src: coverImage, alt: "", size: "banner" }) }), _jsx(Div, { surface: "overlay-md", className: "absolute inset-0" })] })), _jsxs(Div, { className: "relative z-10 max-w-7xl mx-auto", paddingY: hasCover ? "y-3xl" : "y-xl", padding: "x-md", children: [_jsxs(Nav, { layout: "flex", gap: "2xs", textSize: "sm", className: "mb-4", "aria-label": "Breadcrumb", children: [_jsx(Link, { href: String(ROUTES.HOME), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 transition-colors", children: "Home" }), _jsx(Span, { className: hasCover ? "text-white/40" : "text-zinc-400", children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORIES), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 transition-colors", children: "Categories" }), _jsx(Span, { className: hasCover ? "text-white/40" : "text-zinc-400", children: "/" }), _jsx(Span, { weight: "medium", className: hasCover ? "text-white" : "text-[var(--appkit-color-text)]", children: category?.name ?? slug })] }), _jsx(Heading, { color: "inverse", level: 1, className: `mb-2 ${hasCover ? "" : "text-[var(--appkit-color-text)]"}`, size: "3xl", mdSize: "4xl", weight: "bold", children: category?.name ?? slug }), category?.description && typeof category.description === "string" && !category.description.startsWith("{") && (_jsx(Text, { color: hasCover ? "inverse" : "muted", className: `max-w-2xl mb-4 ${hasCover ? "/80" : ""}`, size: "base", children: category.description })), _jsxs(Row, { wrap: true, gap: "sm", children: [productCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: "inverse", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "bg-primary/10 text-primary-700 dark:text-primary-400", rounded: "full", padding: "pill-sm-tall", children: [productCount.toLocaleString(), " ", productCount === 1 ? "product" : "products"] })), auctionCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "warning", surface: hasCover ? undefined : "warning-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [auctionCount.toLocaleString(), " ", auctionCount === 1 ? "auction" : "auctions"] })), preOrderCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "info", surface: hasCover ? undefined : "info-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [preOrderCount.toLocaleString(), " ", preOrderCount === 1 ? "pre-order" : "pre-orders"] })), storeCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "success", surface: hasCover ? undefined : "success-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [storeCount.toLocaleString(), " ", storeCount === 1 ? "store" : "stores"] }))] })] })] }), _jsx(CategoryHighlightsAndFaqSection, { highlights: category?.highlights, faqs: category?.faqs }), childCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: "max-w-7xl mx-auto", padding: "inline", children: _jsx(Div, { layout: "flex", gap: "2", className: `.5 ${__O.xAuto} [scrollbar-width:none]`, padding: "b-2xs", children: childCategories.map((child) => (_jsxs(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(child.slug)), 
                             // audit-responsive-wrap-ok: deliberate horizontal-scroll chip row (parent has overflow-x-auto) — each chip staying single-line is the intended design, not hidden content
-                            className: "flex-shrink-0 flex items-center gap-[var(--appkit-space-1-5)] rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-elevated)] px-[var(--appkit-space-4)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-sm)] font-medium text-[var(--appkit-color-text-muted)] hover:border-primary hover:text-primary transition-colors whitespace-nowrap", children: [child.display?.icon && (_jsx(Span, { className: "leading-none", children: child.display.icon })), child.name, (child.metrics?.productCount ?? 0) > 0 && (_jsx(Span, { size: "xs", color: "muted", children: (child.metrics?.productCount ?? 0).toLocaleString() }))] }, child.id))) }) }) })), _jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(CategoryDetailTabs, { categorySlug: slug, categoryId: category?.id, initialProductsData: productsResult ?? undefined, initialBundles: bundlesResult ?? [], initialStores: categoryStores, counts: counts, enabledListingTypes: enabledListingTypes(settings), enabledCategoryTypes: enabledCategoryTypes(settings) }) }) }), groupedListings.length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(GroupedListingsCarousel, { groups: groupedListings }) }) })), relatedCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-t", padding: "y-lg", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 2, className: "mb-4", size: "xl", weight: "semibold", children: "Related Categories" }), _jsx(CategoryGrid, { categories: relatedCategories, getHref: (c) => String(ROUTES.PUBLIC.CATEGORY_DETAIL(c.slug)) })] }) }))] }));
+                            className: "flex-shrink-0 flex items-center gap-[var(--appkit-space-1-5)] rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-elevated)] px-[var(--appkit-space-4)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-sm)] font-medium text-[var(--appkit-color-text-muted)] hover:border-primary hover:text-primary transition-colors whitespace-nowrap", children: [child.display?.icon && (_jsx(Span, { className: "leading-none", children: child.display.icon })), child.name, (child.metrics?.totalProductCount ?? child.metrics?.productCount ?? 0) > 0 && (_jsx(Span, { size: "xs", color: "muted", children: (child.metrics?.totalProductCount ?? child.metrics?.productCount ?? 0).toLocaleString() }))] }, child.id))) }) }) })), _jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(CategoryDetailTabs, { categorySlug: slug, categoryId: category?.id, initialProductsData: productsResult ?? undefined, initialBundles: bundlesResult ?? [], initialStores: categoryStores, counts: counts, enabledListingTypes: enabledListingTypes(settings), enabledCategoryTypes: enabledCategoryTypes(settings) }) }) }), groupedListings.length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(GroupedListingsCarousel, { groups: groupedListings }) }) })), relatedCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-t", padding: "y-lg", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 2, className: "mb-4", size: "xl", weight: "semibold", children: "Related Categories" }), _jsx(CategoryGrid, { categories: relatedCategories, getHref: (c) => String(ROUTES.PUBLIC.CATEGORY_DETAIL(c.slug)) })] }) }))] }));
 }

package/dist/features/categories/components/CategoryTree.js

@@ -20,7 +20,7 @@ function CategoryTreeNode({ item, children = [], activeId, onSelect, depth = 0,
                     if (hasChildren)
                         setExpanded((p) => !p);
                     onSelect?.(item);
-                }, className: `cursor-pointer py-[var(--appkit-space-1-5)] transition select-none ${depthPl} ${isActive ? "bg-primary-50 text-primary-700 dark:bg-primary-900/30 dark:text-primary-400" : " hover:bg-surface-hover text-[var(--appkit-color-text-muted)]"}`, align: "center", gap: "xs", padding: "x-xs", rounded: "md", children: [hasChildren && (_jsx(Span, { size: "xs", "aria-hidden": "true", className: `transition-transform duration-150 ${expanded ? "rotate-90" : ""}`, color: "faint", children: "\u25B6" })), !hasChildren && _jsx(Span, { className: "w-3" }), item.display?.icon && (_jsx(Span, { size: "base", "aria-hidden": "true", className: "flex-shrink-0", children: item.display.icon })), _jsx(Text, { className: "flex-1 truncate", children: item.name }), item.metrics && (_jsx(Span, { size: "xs", className: "ml-auto flex-shrink-0 tabular-nums", color: "faint", children: item.metrics.productCount }))] }), hasChildren && expanded && (_jsx(Div, { role: "group", children: children.map((child) => (_jsx(CategoryTreeNode, { item: child, activeId: activeId, onSelect: onSelect, depth: depth + 1 }, child.id))) }))] }));
+                }, className: `cursor-pointer py-[var(--appkit-space-1-5)] transition select-none ${depthPl} ${isActive ? "bg-primary-50 text-primary-700 dark:bg-primary-900/30 dark:text-primary-400" : " hover:bg-surface-hover text-[var(--appkit-color-text-muted)]"}`, align: "center", gap: "xs", padding: "x-xs", rounded: "md", children: [hasChildren && (_jsx(Span, { size: "xs", "aria-hidden": "true", className: `transition-transform duration-150 ${expanded ? "rotate-90" : ""}`, color: "faint", children: "\u25B6" })), !hasChildren && _jsx(Span, { className: "w-3" }), item.display?.icon && (_jsx(Span, { size: "base", "aria-hidden": "true", className: "flex-shrink-0", children: item.display.icon })), _jsx(Text, { className: "flex-1 truncate", children: item.name }), item.metrics && (_jsx(Span, { size: "xs", className: "ml-auto flex-shrink-0 tabular-nums", color: "faint", children: item.metrics.totalProductCount ?? item.metrics.productCount }))] }), hasChildren && expanded && (_jsx(Div, { role: "group", children: children.map((child) => (_jsx(CategoryTreeNode, { item: child, activeId: activeId, onSelect: onSelect, depth: depth + 1 }, child.id))) }))] }));
 }
 /**
  * CategoryTree — hierarchical expandable navigation for categories.

package/dist/features/categories/repository/categories.repository.d.ts

@@ -32,9 +32,41 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      */
     updateMetricsInBatch(batch: import("firebase-admin/firestore").WriteBatch, categoryId: string, parentIds: string[], productDelta: number, auctionDelta: number, productId?: string): void;
     /**
-     * Cloud Functions: full-overwrite category metrics (used by nightly reconciliation job).
+     * Cloud Functions: full-overwrite category metrics (nightly reconciliation).
+     *
+     * 🛑 THE OWN COUNT AND THE ROLLUP ARE SEPARATE ARGUMENTS, and they must be.
+     *
+     * This method used to take ONE pair of numbers and write it to both
+     * `productCount` and `totalProductCount` — so it could not express the
+     * distinction the live trigger (`updateMetricsInBatch`, just above) carefully
+     * maintains: `productCount` is the category's OWN items, `totalProductCount`
+     * is own + every descendant's. The nightly job therefore overwrote correct
+     * values with wrong ones every night:
+     *
+     *   - on a leaf it was accidentally right (a leaf has no descendants);
+     *   - on an ancestor it wrote the DESCENDANT sum into both, so a category
+     *     with 5 of its own and 15 below reported `productCount: 15` (should be
+     *     5) and `totalProductCount: 15` (should be 20 — its own 5 were never
+     *     added, because the caller's aggregate only walked other rows' leaves);
+     *   - on a row that is both a leaf and an ancestor, `setMetrics` was called
+     *     twice and last-write-won.
+     *
+     * Measured on production 2026-09-14 before the fix: **19 of 65 category rows
+     * disagreed with a recount**, every one of them low — the root read 56 against
+     * a true 65. Nothing errored, and no page looked broken; a wrong number is
+     * simply a number.
      */
-    setMetrics(categoryId: string, productCount: number, auctionCount: number, productIds: string[], auctionIds: string[]): Promise<void>;
+    setMetrics(categoryId: string, m: {
+        /** Items filed DIRECTLY under this category. */
+        productCount: number;
+        auctionCount: number;
+        /** Own + every descendant's. Equals the own count on a leaf. */
+        totalProductCount: number;
+        totalAuctionCount: number;
+        /** Own only — the ids are used for spot-checking, never for the rollup. */
+        productIds: string[];
+        auctionIds: string[];
+    }): Promise<void>;
     /** SB-UNI — discriminator-keyed listing (sublistings, brands, bundles). */
     listByType(type: import("../types").CategoryType, opts?: {
         limit?: number;