@mohasinac/appkit 4.53.1 → 4.53.2

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.53.1",
-  "head": "d45b9f65d4b73c4c4a079a8ee5553600ddd0c251",
+  "version": "4.53.2",
+  "head": "94f4715428f35ab362a11a468072ef933ca8a46d",
   "branch": "main",
   "dirty": false,
-  "builtAt": "2026-10-19T21:36:59.723Z"
+  "builtAt": "2026-10-19T22:24:09.397Z"
 }

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/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/price-index/market.d.ts

@@ -0,0 +1,57 @@
+import { PRICE_GUIDANCE_TAX_BASIS } from "../../../shared/features/categories/price-guidance";
+export interface PriceIndexMarketRow {
+    categoryId: string;
+    /**
+     * The typical ASK, not a transaction.
+     *
+     * 🛑 `median` is the only required figure, and the three optional ones are
+     * optional because the crawl genuinely did not measure them everywhere — Hot
+     * Wheels has a median over n=7,418 and a RANGE, never quartiles, and the
+     * Beyblade-top table carries no per-leaf `n` at all. An absent field must
+     * render as absent; filling one in to make the shape look complete is the
+     * single thing `price-bands.md` warns about most.
+     */
+    median: number;
+    p25?: number;
+    p75?: number;
+    sampleSize?: number;
+    asOf?: string;
+    /**
+     * The share of competitor listings at this level that are SOLD OUT (0.85,
+     * measured across the five largest catalogues).
+     *
+     * Carried because it is what stops the band being read as a clearing price:
+     * most asks at this level did not convert. The renderer must say so.
+     */
+    soldOutShare?: number;
+    /** Which crawl, and any caveat — pooling, a disagreeing source, a small n. */
+    source?: string;
+    /**
+     * `true` when the band came from an ANCESTOR rather than this leaf.
+     *
+     * 🛑 Load-bearing, not decoration. `MARKET_BANDS` is keyed on era and part
+     * leaves, never on the ~216 named-model leaves, so a model lookup resolves
+     * its generation's band — "typical for Burst DB" is a true statement and
+     * "typical for Rage Longinus" is not. The renderer names the source leaf so
+     * the reader can tell which they are being told.
+     */
+    inherited: boolean;
+    /** The ancestor the band actually came from, when `inherited`. */
+    viaCategoryId?: string;
+    viaName?: string;
+    /** The basis every figure above is on. Always inclusive; stated, not assumed. */
+    taxBasis: typeof PRICE_GUIDANCE_TAX_BASIS;
+}
+/**
+ * Market bands for the leaves the client already resolved.
+ *
+ * Bounded by `PRICE_INDEX_SEARCH_LIMIT` — the same cap the public half uses, so
+ * a crafted request cannot demand an unbounded read, and the two halves of one
+ * lookup can never disagree about how many rows a lookup covers.
+ *
+ * A leaf with no band at any level is ABSENT from the result rather than
+ * present with a null band. "We have no market evidence for this" and "this id
+ * does not exist" are different answers and the caller renders them
+ * differently; collapsing them is how a missing band becomes a confident ₹0.
+ */
+export declare function getPriceIndexMarketForIds(rawIds: readonly string[]): Promise<PriceIndexMarketRow[]>;

package/dist/_internal/server/features/price-index/market.js

@@ -0,0 +1,120 @@
+/*
+ * WHY: The realised-price tool rendered "No completed sales recorded here yet"
+ *      for every single lookup, because the only data it read was OUR completed
+ *      sales and we have none for most leaves. Meanwhile the competitor crawl
+ *      measured ~60 real bands (`MARKET_BANDS` in
+ *      `seed/_helpers/category-content.ts`, evidence in
+ *      `docs/research/competitor-crawl-2026-10/price-bands.md`) which were
+ *      seeded onto the taxonomy and then read by exactly one surface — the
+ *      seller form's hint. The tool had a starting point the whole time and
+ *      never looked at it.
+ * WHAT: The MARKET half of the tool, resolved by the shared nearest-first
+ *       ancestor walk. Signed-in only — see the gate note below.
+ *
+ * EXPORTS:
+ *   PriceIndexMarketRow           — one leaf's market band, API shape
+ *   getPriceIndexMarketForIds     — N category ids -> their market bands
+ *
+ * ── 🛑 WHY THIS IS A SEPARATE, AUTHENTICATED ENDPOINT ───────────────────────
+ *
+ * The sold half (`searchPriceIndex`, `getPriceIndexBandsForIds`) is PUBLIC and
+ * edge-cached, deliberately: a day-stale aggregate of our own completed sales
+ * is the strongest content we can publish and is not what the guest price gate
+ * protects. The market half is the opposite call, and the reasoning is already
+ * written down at `categories/api/[id]/price-guidance/route.ts`: publishing a
+ * competitor-derived band on an unauthenticated, publicly-cacheable response
+ * "would be exactly the 'a neighbouring surface publishes the range' leak that
+ * gate exists to close".
+ *
+ * So the two halves cannot share a response. Merging `market` into
+ * `getPriceIndexBandsForIds` would either poison that public cache with
+ * viewer-dependent content — one signed-in lookup populating the entry every
+ * guest then reads, the exact failure `cachedPublicRead`'s rules exist to
+ * prevent — or force the public half to go private and lose its cache. A
+ * sibling endpoint keeps both postures correct, and it is the same split the
+ * codebase already uses for `description-template` (public) against
+ * `price-guidance` (gated).
+ *
+ * ── 🛑 WHAT IS NOT DONE HERE: the seller tax-basis conversion ───────────────
+ *
+ * The seller route restates the band on the caller's own `pricesIncludeGst`
+ * basis. This one does not, for two reasons. The figures are tax-inclusive
+ * (`PRICE_GUIDANCE_TAX_BASIS`) and so is every price a buyer sees anywhere on
+ * the site, so for the tool's audience no conversion is the correct answer
+ * rather than a missing feature. And the conversion needs a store read per
+ * lookup, which on a tool that resolves up to eight leaves at a time would be
+ * a per-request cost paid to restate a number most callers want as stored. The
+ * renderer labels the basis instead.
+ *
+ * @tag domain:price-index
+ * @tag layer:server
+ * @tag pattern:projection
+ * @tag access:server-only
+ * @tag consumers:api/tools/price-index/market
+ * @tag sideEffects:none
+ */
+import { resolveInheritedGuidanceMany } from "../categories/price-guidance-resolve.js";
+import { PRICE_GUIDANCE_TAX_BASIS } from "../../../shared/features/categories/price-guidance.js";
+import { PRICE_INDEX_SEARCH_LIMIT } from "./search.js";
+/**
+ * Market bands for the leaves the client already resolved.
+ *
+ * Bounded by `PRICE_INDEX_SEARCH_LIMIT` — the same cap the public half uses, so
+ * a crafted request cannot demand an unbounded read, and the two halves of one
+ * lookup can never disagree about how many rows a lookup covers.
+ *
+ * A leaf with no band at any level is ABSENT from the result rather than
+ * present with a null band. "We have no market evidence for this" and "this id
+ * does not exist" are different answers and the caller renders them
+ * differently; collapsing them is how a missing band becomes a confident ₹0.
+ */
+export async function getPriceIndexMarketForIds(rawIds) {
+    const ids = [...new Set(rawIds.filter((id) => typeof id === "string" && id.length > 0))].slice(0, PRICE_INDEX_SEARCH_LIMIT);
+    if (ids.length === 0)
+        return [];
+    const guidanceById = await resolveInheritedGuidanceMany(ids);
+    const rows = [];
+    for (const id of ids) {
+        const resolved = guidanceById.get(id);
+        const market = resolved?.guidance.market;
+        // No band anywhere up the chain. Omitted, never zeroed.
+        if (!market || !resolved)
+            continue;
+        rows.push({
+            categoryId: id,
+            median: market.median,
+            ...(market.p25 === undefined ? {} : { p25: market.p25 }),
+            ...(market.p75 === undefined ? {} : { p75: market.p75 }),
+            ...(market.sampleSize === undefined ? {} : { sampleSize: market.sampleSize }),
+            ...(toIso(market.asOf) ? { asOf: toIso(market.asOf) } : {}),
+            ...(market.soldOutShare === undefined ? {} : { soldOutShare: market.soldOutShare }),
+            ...(market.source ? { source: market.source } : {}),
+            inherited: resolved.inherited,
+            /*
+             * Only when inherited. Naming the leaf as its own source would be noise
+             * on a card that is already headed by that leaf's name.
+             */
+            ...(resolved.inherited
+                ? {
+                    viaCategoryId: resolved.fromCategoryId,
+                    ...(resolved.fromName ? { viaName: resolved.fromName } : {}),
+                }
+                : {}),
+            taxBasis: PRICE_GUIDANCE_TAX_BASIS,
+        });
+    }
+    return rows;
+}
+/** Firestore `Timestamp` | `Date` | ISO string -> ISO string. */
+function toIso(v) {
+    if (!v)
+        return undefined;
+    if (v instanceof Date)
+        return v.toISOString();
+    if (typeof v === "string")
+        return v;
+    const t = v;
+    if (typeof t.toDate === "function")
+        return t.toDate().toISOString();
+    return undefined;
+}

package/dist/_internal/server/features/products/list-public.d.ts

@@ -1,5 +1,6 @@
 import { type ViewerLike } from "../tester/visibility";
 import type { JsonValue } from "../../../../schemas/types";
+import type { UnavailableClause } from "../../../shared/listing-types/availability";
 import { type AvailabilityFilter } from "../../../../constants/field-names";
 /** Vercel Hobby Fluid Compute ceiling (CLAUDE.md Rule #6) — never fetch more at once. */
 export declare const PUBLIC_PRODUCT_MAX_PAGE_SIZE = 50;
@@ -250,6 +251,17 @@ export declare function parsePublicProductParams(params: URLSearchParams | Recor
      */
     availability?: AvailabilityFilter;
 }): PublicProductListInput;
+/** Render one `UnavailableClause` as a Sieve clause against a fixed `now`. */
+/**
+ * One unavailable clause → a Sieve fragment, with `"NOW"` bound to this
+ * query's timestamp.
+ *
+ * Exported so `listing-tab-counts` builds its clause queries with THIS
+ * function rather than a second copy. A rule reachable by copy-paste is one
+ * that gets copied wrong (Root Cause #75), and the two would only diverge the
+ * day someone adds a third `op`.
+ */
+export declare function clauseToSieve(clause: UnavailableClause, now: Date): string;
 export declare function listPublicProducts(input: PublicProductListInput, opts?: PublicProductListOptions): Promise<PublicProductListResult | null>;
 /**
  * One store tab's worth of listings.

package/dist/_internal/server/features/products/list-public.js

@@ -440,7 +440,16 @@ async function defaultExecutor(query) {
     };
 }
 /** Render one `UnavailableClause` as a Sieve clause against a fixed `now`. */
-function clauseToSieve(clause, now) {
+/**
+ * One unavailable clause → a Sieve fragment, with `"NOW"` bound to this
+ * query's timestamp.
+ *
+ * Exported so `listing-tab-counts` builds its clause queries with THIS
+ * function rather than a second copy. A rule reachable by copy-paste is one
+ * that gets copied wrong (Root Cause #75), and the two would only diverge the
+ * day someone adds a third `op`.
+ */
+export function clauseToSieve(clause, now) {
     const value = clause.value === "NOW" ? now.toISOString() : clause.value;
     return clause.op === "lt"
         ? sieveFilter(clause.field, SIEVE_OP.LT, value)

package/dist/_internal/server/features/products/listing-tab-counts.d.ts

@@ -31,6 +31,28 @@ export interface ListingTabScope {
  * `undefined` as "keep the tab visible" (Root Cause #59).
  */
 export type ListingTabCounts = Record<string, number | undefined>;
+/**
+ * The two numbers a tab bar needs, and they are NOT the same number.
+ *
+ * 🛑 A badge showing `total` while the panel below it defaults to the
+ * AVAILABLE scope is a tab that advertises rows it will not render. That was
+ * live: a category holding one `prizeRevealStatus: "closed"` draw showed
+ * "Prize Draws 1" above "No prize draws found." — accurate counting of the
+ * wrong question, Root Cause #72's family.
+ *
+ *   `available` — what the default scope will render. The BADGE.
+ *   `total`     — every published row in scope, across all availability
+ *                 scopes. The hide-at-zero decision, and the "N ended —
+ *                 view All" hint under an empty panel.
+ *
+ * 🛑 Hiding must stay keyed on `total`. A tab whose rows have all ended still
+ * has a browsable archive behind the Ended/All scopes; hiding it at
+ * `available === 0` would make that archive unreachable.
+ */
+export interface ListingTabCountResult {
+    available: ListingTabCounts;
+    total: ListingTabCounts;
+}
 /**
  * Count every tab in `tabs` within `scope`, in one parallel batch.
  *
@@ -41,4 +63,6 @@ export type ListingTabCounts = Record<string, number | undefined>;
  * `stores` is not counted here: only the category page has that tab and it
  * already resolves its store list eagerly to render the tab body.
  */
-export declare function listingTabCounts(tabs: readonly ListingTab[], scope: ListingTabScope): Promise<ListingTabCounts>;
+export declare function listingTabCounts(tabs: readonly ListingTab[], scope: ListingTabScope, opts?: {
+    now?: Date;
+}): Promise<ListingTabCountResult>;