@mohasinac/appkit 4.45.0 → 4.46.0

package/dist/features/categories/schemas/category-counts.d.ts

@@ -0,0 +1,155 @@
+/**
+ * G3b — LISTING COUNTS, maintained incrementally leaf→root.
+ *
+ * 🛑 WHY THIS IS A SIBLING COLLECTION AND NOT A FIELD ON `categories`.
+ *
+ * `handleCategoryWrite` calls `notifyRevalidate({ collection: "categories" })`
+ * as its FIRST statement, unconditionally, before any branch — so ANY write to
+ * a category document drops that category page's ISR entry. Under leaf→root,
+ * publishing one listing touches up to five ancestors, so it would drop five
+ * ISR entries per publish. This project was paused with **ISR writes at 3.1M
+ * against a 200K cap (15.5×)**, which settles the question.
+ *
+ * It also removes the Root Cause #92 hazard outright: a trigger that writes
+ * back to the collection it watches produced 1,017,548 invocations in 24 hours
+ * and a billing denial that blocked `firebase deploy`.
+ *
+ * 🛑 AND `metrics.*` ON `categories` STAYS — a constraint the plan did not
+ * record. Two Sieve SORTS order by `metrics.productCount` through Firestore
+ * (`CategoriesIndexListing`'s "Most Products" and
+ * `AdminSublistingCategoriesView`'s "Most listings"), and a sibling collection
+ * cannot serve an `orderBy` on the categories query. So:
+ *
+ *   - `metrics.*`      — written ONLY by the nightly `countersReconcile`, as
+ *                        today. The two sorts keep working at exactly today's
+ *                        accuracy, so there is no regression, and the ISR cost
+ *                        is unchanged from the status quo (one drop per
+ *                        category per night, already happening).
+ *   - `categoryCounts` — the LIVE value, written per product mutation. Fires no
+ *                        revalidation, because nothing triggers on it.
+ *
+ * Readers prefer `categoryCounts` and fall back to `metrics`. That ordering is
+ * what makes the feature additive: a category with no counts document yet
+ * renders exactly as it does today rather than as zero.
+ *
+ * 🛑 HOW FRESH IT ACTUALLY IS, stated precisely rather than as "live".
+ *
+ * The count is of AVAILABLE rows — `isListingRowAvailable`, the same predicate
+ * `countersReconcile` and the listing query use. That predicate is partly
+ * TIME-dependent: `auction` is the one type with an inequality clause
+ * (`auctionEndDate`), so an auction becomes unavailable by the clock with no
+ * product write, and no incremental counter can observe that.
+ *
+ * In practice the window is minutes, not a day: `auctionSettlement` writes
+ * `isSold: true` when it settles, and that write re-evaluates the counter.
+ * Every other type's unavailability is write-driven (stock, `isSold`,
+ * `digitalCode.codesAvailable`, the prize-draw reveal status).
+ *
+ * So: instant for every write-driven change, and bounded by the settlement
+ * cadence for a just-ended auction. That is strictly better than today, where
+ * every change is up to 24h stale. The nightly reconciler stays as the
+ * authority and the audit — its `drifted` counter becomes a real signal that
+ * an increment was missed.
+ */
+import type { ListingType } from "../../products/types";
+export declare const CATEGORY_COUNTS_COLLECTION = "categoryCounts";
+/**
+ * Per-listing-type counters.
+ *
+ * 🛑 `Partial` on purpose: an absent key means "zero observed". Writing nine
+ * explicit zeros on every row is noise, and it would also make an untouched
+ * category indistinguishable from one measured as empty.
+ *
+ * A MAP rather than scalar fields, because own+total across nine listing types
+ * is 18 fields that grow with the union — and the union has grown twice
+ * already. A map needs no schema change for a tenth type.
+ */
+export type ListingTypeCounts = Partial<Record<ListingType, number>>;
+/**
+ * 🛑 THE INVARIANT, and the one way to get this wrong:
+ *
+ *     total  =  own  +  (every descendant's own)
+ *
+ * **`total` ALREADY INCLUDES `own`. Never add them.** `own + total` double-counts
+ * every item filed directly under the row, and on a leaf — where `total === own`
+ * — it doubles the whole number.
+ *
+ * So there are three questions and only two stored fields, because the third is
+ * a subtraction and a stored mirror of it would drift the first time one half
+ * was written without the other (Root Cause #42):
+ *
+ * | Question | Read |
+ * |---|---|
+ * | "how many are filed right here?" | `own` |
+ * | "how many are under my subcategories?" | **`descendantCountsFor()`** — `total − own`, derived |
+ * | "how many will clicking this show me?" | `total` |
+ *
+ * The third is the one a buyer means, which is why `liveTotalFor` returns it
+ * and why the category chips and grid read it. The second exists because the
+ * distinction is genuinely useful to an admin — `CategoryTableColumns` already
+ * renders "own (total)" explicitly — and because deriving it is the only way to
+ * show it without a third counter to keep in step.
+ */
+export interface CategoryCountsDocument {
+    /** === the category's document id. */
+    id: string;
+    /** Listings filed DIRECTLY under this category, by type. */
+    own: ListingTypeCounts;
+    /**
+     * Own + every descendant's, by type. Equals `own` on a leaf.
+     *
+     * 🛑 INCLUDES `own` — see the invariant above. Never `own + total`.
+     */
+    total: ListingTypeCounts;
+    /**
+     * Multi-item LOTS, counted separately from singles.
+     *
+     * 🛑 This separation is what makes a count mean one thing, and it is why the
+     * filing rule in `deriveTaxonomy` only has to refuse a lot at a LEAF rather
+     * than also refusing a single at a non-leaf. A lot and a single are never
+     * summed into one number, so "12 listings here" is unambiguous wherever they
+     * are filed. (Measured: 58 of 70 live products file at a non-leaf, so the
+     * symmetric rule the plan first specified would have rejected most of the
+     * catalogue — see the `isLot` docstring on `ProductDocument`.)
+     *
+     * Scalars rather than a per-type map: a lot is not type-specific in any way
+     * a buyer or a seller filters on, and there is no reader for "lots of
+     * auctions".
+     */
+    lots: {
+        own: number;
+        total: number;
+    };
+    updatedAt: Date;
+}
+/** Sum a counts map — what a category page renders as "N listings". */
+export declare function sumCounts(counts: ListingTypeCounts | undefined): number;
+/**
+ * The display count for a category, preferring the live document.
+ *
+ * 🛑 `undefined` means "no counts document yet", NOT zero — so the caller falls
+ * back to `metrics`. Returning 0 here would render a confident zero on every
+ * category until the first mutation, which is Root Cause #72's lesson (a count
+ * that failed must never be indistinguishable from a count of nothing).
+ */
+export declare function liveTotalFor(doc: Pick<CategoryCountsDocument, "total" | "lots"> | null | undefined): number | undefined;
+/** Filed directly here, lots included. The "N here" half of "N here, M below". */
+export declare function ownTotalFor(doc: Pick<CategoryCountsDocument, "own" | "lots"> | null | undefined): number | undefined;
+/**
+ * How many sit under this row's DESCENDANTS and not directly on it — `total − own`.
+ *
+ * 🛑 DERIVED, never stored, and that is the point: a third stored counter would
+ * be a mirror of a subtraction, and a mirror drifts the moment one half is
+ * written without the other (Root Cause #42). It is also the function that
+ * makes the invariant un-missable — anyone reaching for "own plus children"
+ * finds this instead of writing `own + total`, which double-counts every item
+ * filed directly on the row.
+ *
+ * Clamped at 0. A negative value is real and means the counters drifted (an
+ * increment lost between the leaf write and an ancestor's), and surfacing
+ * "−3 in subcategories" to a visitor is worse than showing none — the nightly
+ * reconciler's `countsWritten` is where that drift is meant to be seen.
+ */
+export declare function descendantTotalFor(doc: Pick<CategoryCountsDocument, "own" | "total" | "lots"> | null | undefined): number | undefined;
+/** The per-type descendant split, same derivation and the same clamp. */
+export declare function descendantCountsFor(doc: Pick<CategoryCountsDocument, "own" | "total"> | null | undefined): ListingTypeCounts | undefined;

package/dist/features/categories/schemas/category-counts.js

@@ -0,0 +1,116 @@
+/**
+ * G3b — LISTING COUNTS, maintained incrementally leaf→root.
+ *
+ * 🛑 WHY THIS IS A SIBLING COLLECTION AND NOT A FIELD ON `categories`.
+ *
+ * `handleCategoryWrite` calls `notifyRevalidate({ collection: "categories" })`
+ * as its FIRST statement, unconditionally, before any branch — so ANY write to
+ * a category document drops that category page's ISR entry. Under leaf→root,
+ * publishing one listing touches up to five ancestors, so it would drop five
+ * ISR entries per publish. This project was paused with **ISR writes at 3.1M
+ * against a 200K cap (15.5×)**, which settles the question.
+ *
+ * It also removes the Root Cause #92 hazard outright: a trigger that writes
+ * back to the collection it watches produced 1,017,548 invocations in 24 hours
+ * and a billing denial that blocked `firebase deploy`.
+ *
+ * 🛑 AND `metrics.*` ON `categories` STAYS — a constraint the plan did not
+ * record. Two Sieve SORTS order by `metrics.productCount` through Firestore
+ * (`CategoriesIndexListing`'s "Most Products" and
+ * `AdminSublistingCategoriesView`'s "Most listings"), and a sibling collection
+ * cannot serve an `orderBy` on the categories query. So:
+ *
+ *   - `metrics.*`      — written ONLY by the nightly `countersReconcile`, as
+ *                        today. The two sorts keep working at exactly today's
+ *                        accuracy, so there is no regression, and the ISR cost
+ *                        is unchanged from the status quo (one drop per
+ *                        category per night, already happening).
+ *   - `categoryCounts` — the LIVE value, written per product mutation. Fires no
+ *                        revalidation, because nothing triggers on it.
+ *
+ * Readers prefer `categoryCounts` and fall back to `metrics`. That ordering is
+ * what makes the feature additive: a category with no counts document yet
+ * renders exactly as it does today rather than as zero.
+ *
+ * 🛑 HOW FRESH IT ACTUALLY IS, stated precisely rather than as "live".
+ *
+ * The count is of AVAILABLE rows — `isListingRowAvailable`, the same predicate
+ * `countersReconcile` and the listing query use. That predicate is partly
+ * TIME-dependent: `auction` is the one type with an inequality clause
+ * (`auctionEndDate`), so an auction becomes unavailable by the clock with no
+ * product write, and no incremental counter can observe that.
+ *
+ * In practice the window is minutes, not a day: `auctionSettlement` writes
+ * `isSold: true` when it settles, and that write re-evaluates the counter.
+ * Every other type's unavailability is write-driven (stock, `isSold`,
+ * `digitalCode.codesAvailable`, the prize-draw reveal status).
+ *
+ * So: instant for every write-driven change, and bounded by the settlement
+ * cadence for a just-ended auction. That is strictly better than today, where
+ * every change is up to 24h stale. The nightly reconciler stays as the
+ * authority and the audit — its `drifted` counter becomes a real signal that
+ * an increment was missed.
+ */
+export const CATEGORY_COUNTS_COLLECTION = "categoryCounts";
+/** Sum a counts map — what a category page renders as "N listings". */
+export function sumCounts(counts) {
+    if (!counts)
+        return 0;
+    let n = 0;
+    for (const v of Object.values(counts))
+        n += v ?? 0;
+    return n;
+}
+/**
+ * The display count for a category, preferring the live document.
+ *
+ * 🛑 `undefined` means "no counts document yet", NOT zero — so the caller falls
+ * back to `metrics`. Returning 0 here would render a confident zero on every
+ * category until the first mutation, which is Root Cause #72's lesson (a count
+ * that failed must never be indistinguishable from a count of nothing).
+ */
+export function liveTotalFor(doc) {
+    if (!doc)
+        return undefined;
+    return sumCounts(doc.total) + (doc.lots?.total ?? 0);
+}
+/** Filed directly here, lots included. The "N here" half of "N here, M below". */
+export function ownTotalFor(doc) {
+    if (!doc)
+        return undefined;
+    return sumCounts(doc.own) + (doc.lots?.own ?? 0);
+}
+/**
+ * How many sit under this row's DESCENDANTS and not directly on it — `total − own`.
+ *
+ * 🛑 DERIVED, never stored, and that is the point: a third stored counter would
+ * be a mirror of a subtraction, and a mirror drifts the moment one half is
+ * written without the other (Root Cause #42). It is also the function that
+ * makes the invariant un-missable — anyone reaching for "own plus children"
+ * finds this instead of writing `own + total`, which double-counts every item
+ * filed directly on the row.
+ *
+ * Clamped at 0. A negative value is real and means the counters drifted (an
+ * increment lost between the leaf write and an ancestor's), and surfacing
+ * "−3 in subcategories" to a visitor is worse than showing none — the nightly
+ * reconciler's `countsWritten` is where that drift is meant to be seen.
+ */
+export function descendantTotalFor(doc) {
+    if (!doc)
+        return undefined;
+    const total = liveTotalFor(doc) ?? 0;
+    const own = ownTotalFor(doc) ?? 0;
+    return Math.max(0, total - own);
+}
+/** The per-type descendant split, same derivation and the same clamp. */
+export function descendantCountsFor(doc) {
+    if (!doc)
+        return undefined;
+    const out = {};
+    for (const k of Object.keys(doc.total ?? {})) {
+        const d = (doc.total[k] ?? 0) - (doc.own?.[k] ?? 0);
+        if (d > 0)
+            out[k] = d;
+    }
+    return out;
+}

package/dist/features/categories/schemas/firestore.d.ts

@@ -108,7 +108,6 @@ export interface CategoryDocument extends BaseDocument {
      */
     subtreeSize: number;
     metrics: CategoryDocumentMetrics;
-    viewCount?: number;
     isFeatured: boolean;
     featuredPriority?: number;
     /** @deprecated Use categoryType === "brand". Will be removed once seed + admin form fully migrate. */
@@ -329,7 +328,6 @@ export declare const CATEGORY_FIELDS: {
     readonly FEATURED_PRIORITY: "featuredPriority";
     readonly SEO: "seo";
     readonly DISPLAY: "display";
-    readonly VIEW_COUNT: "viewCount";
     readonly IS_ACTIVE: "isActive";
     readonly IS_SEARCHABLE: "isSearchable";
     readonly SEARCH_TXT: "searchTxt";

package/dist/features/categories/schemas/firestore.js

@@ -210,7 +210,6 @@ export const CATEGORY_FIELDS = {
     FEATURED_PRIORITY: "featuredPriority",
     SEO: "seo",
     DISPLAY: "display",
-    VIEW_COUNT: "viewCount",
     IS_ACTIVE: "isActive",
     IS_SEARCHABLE: "isSearchable",
     SEARCH_TXT: "searchTxt",

package/dist/features/categories/utils/breadcrumb-chain.d.ts

@@ -0,0 +1,194 @@
+/**
+ * D4b — ONE breadcrumb chain builder, for the category page, the brand page and
+ * the product detail pages.
+ *
+ * 🛑 A `BreadcrumbList` is the one JSON-LD node whose entire value is the ORDER,
+ * and it is now emitted over a 416-node / 5-tier / 39-root forest rather than
+ * the 47-node / 2-tier tree it was written against. Measured 2026-10-12:
+ *
+ *   per tier: t0=39  t1=23  t2=65  t3=71  t4=218
+ *   deepest node -> 7 crumbs:
+ *     Home > Categories > Spinning Tops > Beyblade Burst > Burst Tops > GT
+ *       > Ace Dragon Sting Charge Zan
+ *
+ * Three surfaces render this chain and they must agree, or a crawler and a
+ * visitor are shown different hierarchies for one page — which is worse than
+ * emitting no breadcrumb, because a mismatched `BreadcrumbList` is a
+ * structured-data error against a page that looks fine:
+ *
+ *   1. the visible `BreadcrumbTrail`
+ *   2. this `BreadcrumbList`
+ *   3. `categoryNames[]` on a product — the denormalised display cache
+ *
+ * 🛑 AND THE THIRD IS STORED LEAF-FIRST. Measured:
+ *
+ *     categorySlugs: category-x-basic > category-x-tops > … > category-spinning-tops
+ *     categoryNames: Basic Line > Beyblade X Tops > … > Spinning Tops
+ *
+ * So anything rendering `categoryNames` in stored order shows the trail
+ * BACKWARDS. Every current consumer takes `[0]` — the leaf — which is correct
+ * for a single chip and is exactly why the reversal has never shown up. This
+ * module reverses it once, here, so no call site has to remember.
+ *
+ * 🛑 `ancestors[]` IS THE SOURCE FOR A CATEGORY; `categoryNames`+`categorySlugs`
+ * FOR A PRODUCT. Both `ancestors[]` and `parentIds[]` exist on a category and
+ * describe the same chain — verified equal in length on all 416 live rows — so
+ * neither is wrong, but two owners of one fact is Root Cause #42 waiting. The
+ * choice is `ancestors[]` because it carries the display NAME, so the visible
+ * trail needs no extra read; `parentIds[]` is ids only and stays what the
+ * repository derives `categorySlugs` from.
+ */
+export interface BreadcrumbCrumb {
+    name: string;
+    /** Absent on the final crumb — the current page is not a link. */
+    url?: string;
+}
+/** The shape `CategoryDocument.ancestors[]` entries have. */
+export interface AncestorLike {
+    id?: string | null;
+    name?: string | null;
+    tier?: number | null;
+}
+export interface CategoryChainInput {
+    /** The category's own display name. */
+    name?: string | null;
+    /** Its own URL. Omitted on the last crumb, so pass it and let the caller decide. */
+    url?: string;
+    ancestors?: readonly AncestorLike[] | null;
+    /** Builds a URL from an ancestor id. */
+    hrefFor: (id: string) => string;
+}
+/**
+ * Root → leaf, from a category's `ancestors[]`.
+ *
+ * 🛑 SORTED BY TIER, never taken as stored. An earlier revision of the category
+ * page asserted `ancestors[]` is stored root-first and used it as given; the
+ * visible `BreadcrumbTrail` on that same page had always sorted first, so the
+ * stored order was relied on nowhere. Sorting is the only safe reading, and a
+ * reversed breadcrumb is worse than none.
+ *
+ * 🛑 A BROKEN ANCESTOR IS OMITTED, NOT RENDERED AS A GAP. An entry with no id
+ * or no name cannot be linked or labelled, and emitting `{ name: "" }` puts an
+ * empty crumb in the middle of the trail — which reads as a missing level
+ * rather than as an absent one. `deriveTaxonomy` warns and leaves a chain alone
+ * when a leaf does not resolve (Root Cause #101), so a partial chain is a state
+ * that really occurs. Measured 0 in production today, which is why the branch
+ * needs a test rather than trust.
+ *
+ * A ROOT yields just itself — 39 of the 416 live rows are tier 0 (6 category
+ * roots plus 28 brands and 5 bundles), so this is the common case, not an edge.
+ * The caller's `Home` / `Categories` prefix is what keeps it a valid list.
+ */
+export declare function categoryCrumbs(input: CategoryChainInput): BreadcrumbCrumb[];
+export interface ProductChainInput {
+    /** `[leaf, …ancestors, root]` — the STORED order. */
+    categorySlugs?: readonly string[] | null;
+    /** Parallel to `categorySlugs`, same stored leaf-first order. */
+    categoryNames?: readonly string[] | null;
+    hrefFor: (slug: string) => string;
+}
+/**
+ * Root → leaf, from a product's stored chain.
+ *
+ * 🛑 THE TWO ARRAYS ARE PARALLEL AND MAY DISAGREE IN LENGTH. `deriveTaxonomy`
+ * writes both together, but a row written before it existed — or one whose leaf
+ * did not resolve — can carry a `categorySlugs` with no matching name. Pairing
+ * by index past the shorter array would label one category with another's name,
+ * which is a wrong hierarchy rendered confidently. So the chain stops at the
+ * shorter of the two, and a slug with no name is dropped rather than shown as
+ * its raw id.
+ *
+ * 🛑 A LOT FILES AT A NON-LEAF (G3a), so its chain is genuinely SHORTER and the
+ * last crumb is a line or generation node rather than a named model. That is
+ * correct and must not be padded: fabricating a leaf to fill the final position
+ * would claim the lot is one specific model, which is the same false claim the
+ * filing rule refuses at the write. Nothing here looks at `isLot` — the chain
+ * is simply as long as it is, which is why no special case is needed.
+ */
+export declare function productCrumbs(input: ProductChainInput): BreadcrumbCrumb[];
+/**
+ * I5b — 🛑 WHY `productCrumbs` NEEDED NO CHANGE FOR MULTI-ASSIGNMENT, and why
+ * that must be asserted rather than admired.
+ *
+ * A product's `categorySlugs` is now the CLOSURE over every assignment, while
+ * `categoryNames` is the DEFAULT chain only. Pairing by index would be a bug if
+ * the closure were a set — but it is ordered default-chain-first, so
+ * `min(slugs.length, names.length)` clamps to exactly the default chain and the
+ * indices line up. Measured: a 7-entry closure with 5 names yields the 5-crumb
+ * default trail, root-first.
+ *
+ * That is correct BY CONSTRUCTION and it is also fragile-looking, which is the
+ * dangerous combination — someone will eventually "fix" the pairing or make the
+ * closure a set. `verify-breadcrumb-chain.mjs` asserts it so that change fails
+ * loudly instead of silently relabelling a hierarchy.
+ */
+/**
+ * Crumbs to show before the middle collapses behind a dropdown.
+ *
+ * 🛑 A real measurement, not a preference: a tier-4 part leaf is **7 crumbs**
+ * (`Home > Categories > Spinning Tops > Beyblade Metal > Metal Parts >
+ * Performance Tips > Rubber Flat`) and 390px cannot hold it. D4b measured that
+ * depth and never addressed how it wraps.
+ *
+ * 5 keeps `Home`, one collapsed group, and the last two — which is the pattern
+ * every large catalogue converges on, because the last two are the only crumbs
+ * a visitor navigates by.
+ */
+export declare const TRAIL_COLLAPSE_THRESHOLD = 5;
+export interface CollapsedTrail {
+    /** Always the first crumb. Never collapsed — it is the only guaranteed exit. */
+    lead: BreadcrumbCrumb[];
+    /** The middle, to be rendered behind a dropdown. Empty when the trail is short. */
+    collapsed: BreadcrumbCrumb[];
+    /** The last two: the parent you would click, and the page you are on. */
+    tail: BreadcrumbCrumb[];
+}
+/**
+ * Split a trail into lead / collapsed / tail for ONE row of crumbs.
+ *
+ * 🛑 Presentation only. The JSON-LD must still emit the FULL trail — a crawler
+ * never receives a truncated hierarchy just because a phone cannot show it.
+ */
+export declare function collapseTrail(crumbs: readonly BreadcrumbCrumb[], threshold?: number): CollapsedTrail;
+export interface AlternateTrailsInput {
+    /** Every assignment, default first. */
+    categoryIds?: readonly string[] | null;
+    /** One display name per assignment, parallel to `categoryIds`. */
+    categoryIdNames?: readonly string[] | null;
+    hrefFor: (slug: string) => string;
+}
+export interface AlternateTrails {
+    /**
+     * `none` when there is one assignment — which is the overwhelming majority,
+     * and the case that must render EXACTLY as before with no extra crumb and no
+     * post-hydration shift.
+     */
+    mode: "none" | "inline" | "dropdown";
+    items: BreadcrumbCrumb[];
+}
+/**
+ * The assignments that are NOT the default, as one crumb's worth of links.
+ *
+ * *"if it is less than 3 we can add a single crumb to show them all, for more
+ * than that we can just add a dropdown"* — so ≤2 alternates render inline and
+ * 3 (the maximum, since `MAX_CATEGORY_ASSIGNMENTS` is 4) opens a dropdown.
+ *
+ * 🛑 ONE ROW, never stacked trails. Two rows of crumbs above a product title is
+ * a pattern no competitor in the crawl uses and it costs vertical space above
+ * the fold on a phone.
+ *
+ * 🛑 And the links must be REAL `<a>` elements in the server-rendered DOM, which
+ * is this function's whole reason for returning data rather than a component: a
+ * crawler does not open menus, so alternates injected on open would trade the
+ * SEO this exists for against tidiness.
+ */
+export declare function alternateAssignments(input: AlternateTrailsInput): AlternateTrails;
+/**
+ * Prepend the two fixed crumbs every trail starts with, and drop the final
+ * crumb's URL.
+ *
+ * The last crumb must not be a link — it is the page you are on, and Google's
+ * own guidance is that the final breadcrumb identifies the current page. Doing
+ * it here rather than at three call sites is what stops one of them forgetting.
+ */
+export declare function withTrailHead(crumbs: readonly BreadcrumbCrumb[], head: readonly BreadcrumbCrumb[]): BreadcrumbCrumb[];