@mohasinac/appkit 4.53.1 → 4.54.0-next.0

package/dist/features/price-index/components/PriceIndexToolView.js

@@ -8,13 +8,20 @@ import { Badge } from "../../../ui/components/Badge.js";
 import { Button } from "../../../ui/components/Button.js";
 import { Form } from "../../../ui/components/Form.js";
 import { FieldInput } from "../../../ui/forms/FieldInput.js";
+import { PaginatedSelect } from "../../../ui/components/PaginatedSelect.js";
+import { TextLink } from "../../../ui/components/TextLink.js";
 import { MediaImage } from "../../media/MediaImage.js";
 import { TOOL_ENDPOINTS } from "../../../constants/api-endpoints.js";
 import { apiClient } from "../../../http/ApiClient.js";
 import { useSiteSearch } from "../../search/hooks/useSiteSearch.js";
+import { useSearchIndex } from "../../search/hooks/useSearchIndex.js";
+import { searchIndex } from "../../../_internal/shared/search/match.js";
+import { useOptionalSession } from "../../../react/contexts/SessionContext.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
 import { normalizeError } from "../../../errors/normalize.js";
 import { toUserMessage } from "../../../errors/error-display-map.js";
+import { PRICE_LOOKUP_INDEX_TYPES, priceLookupTargetFor } from "../lookup-target.js";
 /** Human labels. Falls back to the raw value so a new condition still renders. */
 const CONDITION_LABEL = {
     new: "New",
@@ -47,6 +54,14 @@ const __O = {
     xAuto: "overflow-x-auto",
     hidden: "overflow-hidden",
 };
+/**
+ * How many options the dropdown offers.
+ *
+ * Larger than `PRICE_INDEX_SEARCH_LIMIT`'s 8 because this is a PICK list rather
+ * than a result set — the cost of an extra row is a line of text, not a
+ * Firestore document, so the bound that matters is what a person will read.
+ */
+const DROPDOWN_LIMIT = 20;
 const money = (v) => formatCurrency(v, "INR");
 function relativeDay(iso) {
     if (!iso)
@@ -79,22 +94,71 @@ function BandCard({ band, threshold }) {
                                 ? ` · via ${band.lastSold.via}`
                                 : ""] }))] })) : (_jsx(LowConfidence, { sampleSize: band.sampleSize, threshold: threshold })), band.byCondition && band.byCondition.length > 0 && (_jsx(ConditionTable, { rows: band.byCondition, threshold: threshold }))] }));
 }
-function ResultCard({ row, threshold }) {
-    return (_jsxs(Stack, { gap: "md", padding: "card", rounded: "lg", surface: "card", border: "subtle", className: "min-w-0", children: [_jsxs(Row, { gap: "md", align: "start", className: "min-w-0", children: [row.coverImage && (_jsx(Div, { rounded: "lg", className: `w-16 h-16 flex-shrink-0 ${__O.hidden}`, children: _jsx(MediaImage, { src: row.coverImage, alt: row.name, size: "thumbnail" }) })), _jsxs(Stack, { gap: "none", className: "flex-1 min-w-0", children: [_jsx(Heading, { level: 3, children: row.name }), row.path && (_jsx(Text, { size: "xs", color: "muted", className: "min-w-0 break-words", children: row.path }))] })] }), row.bands && row.bands.length > 0 ? (_jsxs(_Fragment, { children: [_jsx(Stack, { gap: "sm", className: "min-w-0", children: row.bands.map((b) => (_jsx(BandCard, { band: b, threshold: threshold }, b.listingType))) }), _jsxs(Text, { size: "xs", color: "muted", children: ["Completed sales on LetItRip", row.windowDays ? ` over the last ${row.windowDays} days` : "", row.computedAt ? ` · as of ${new Date(row.computedAt).toLocaleDateString("en-IN")}` : ""] })] })) : (
+/**
+ * The competitor-crawl band: what this thing is typically ASKED for.
+ *
+ * ## 🛑 Side by side with the sold band, never averaged with it
+ *
+ * `price-bands.md` states the rule this component exists to honour: "They are
+ * rendered side by side and never averaged. The gap between them is the most
+ * useful thing we can tell a seller." An ask and a sale are different events,
+ * and a blended figure would be a statistic describing neither.
+ *
+ * ## 🛑 "Sold out" is not "sold"
+ *
+ * 76–93% of the crawled catalogues are sold out, and a sold-out row proves the
+ * item is GONE, not that it changed hands at that price. So `soldOutShare` is
+ * rendered as prose rather than dropped — without it, a reader takes the median
+ * for a clearing price, which is the single wrong conclusion this data invites.
+ *
+ * ## 🛑 An inherited band says whose band it is
+ *
+ * `MARKET_BANDS` is keyed on era and part-group leaves, never on the ~216
+ * named-model leaves — the crawl measured a generation, not a bey. So a model
+ * lookup resolves its era's band, and the card must attribute it: "typical for
+ * Burst DB" is true, "typical for Rage Longinus" is not.
+ */
+function MarketCard({ market }) {
+    const hasRange = market.p25 !== undefined && market.p75 !== undefined;
+    const soldOutPct = market.soldOutShare === undefined ? null : Math.round(market.soldOutShare * 100);
+    return (_jsxs(Stack, { gap: "sm", padding: "sm", rounded: "lg", border: "default", className: "min-w-0", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", wrap: true, className: "min-w-0", children: [_jsx(Badge, { variant: "secondary", children: "Typical asking price" }), market.sampleSize !== undefined && (_jsxs(Text, { size: "xs", color: "muted", children: [market.sampleSize, " ", market.sampleSize === 1 ? "listing" : "listings"] }))] }), _jsxs(Row, { gap: "lg", wrap: true, className: "min-w-0", children: [hasRange && _jsx(Figure, { label: "Usual low", value: money(market.p25) }), _jsx(Figure, { label: "Typical ask", value: money(market.median) }), hasRange && _jsx(Figure, { label: "Usual high", value: money(market.p75) })] }), market.inherited && (_jsxs(Text, { size: "sm", color: "muted", children: ["Measured for", " ", _jsx(Span, { weight: "semibold", children: market.viaName ?? market.viaCategoryId }), " as a whole \u2014 the crawl priced the generation, not this exact item."] })), soldOutPct !== null && (_jsxs(Text, { size: "sm", color: "muted", children: ["These are asking prices from other shops, and about ", soldOutPct, "% of listings at this level are sold out \u2014 so an ask is not proof anything changed hands at it."] })), _jsxs(Text, { size: "xs", color: "muted", className: "min-w-0 break-words", children: [market.source ? `Source: ${market.source}. ` : "", "Tax-inclusive", market.asOf
+                        ? ` · measured ${new Date(market.asOf).toLocaleDateString("en-IN")}`
+                        : ""] })] }));
+}
+/**
+ * What a signed-out visitor sees where the market band would be.
+ *
+ * 🛑 This is NOT the guest price gate. The sold band above it is public by
+ * decision (see this file's header). The market band is withheld for a
+ * different reason, already settled at
+ * `categories/api/[id]/price-guidance/route.ts`: it is competitor-derived, and
+ * publishing it on an unauthenticated, cacheable surface is the "neighbouring
+ * surface publishes the range" leak. The copy therefore says what is behind
+ * sign-in and why it is worth having, rather than implying no data exists.
+ */
+function MarketSignInPrompt() {
+    return (_jsxs(Stack, { gap: "xs", padding: "sm", rounded: "lg", surface: "muted", className: "min-w-0", children: [_jsx(Text, { size: "sm", weight: "semibold", children: "Asking prices elsewhere" }), _jsxs(Text, { size: "sm", color: "muted", children: ["We measured what other Indian shops ask for this, from a crawl of fifteen catalogues.", " ", _jsx(TextLink, { href: String(ROUTES.AUTH.LOGIN), children: "Sign in" }), " to see the range."] })] }));
+}
+function ResultCard({ row, threshold, market, canSeeMarket, }) {
+    return (_jsxs(Stack, { gap: "md", padding: "card", rounded: "lg", surface: "card", border: "subtle", className: "min-w-0", children: [_jsxs(Row, { gap: "md", align: "start", className: "min-w-0", children: [row.coverImage && (_jsx(Div, { rounded: "lg", className: `w-16 h-16 flex-shrink-0 ${__O.hidden}`, children: _jsx(MediaImage, { src: row.coverImage, alt: row.name, size: "thumbnail" }) })), _jsxs(Stack, { gap: "none", className: "flex-1 min-w-0", children: [_jsx(Heading, { level: 3, children: row.name }), row.path && (_jsx(Text, { size: "xs", color: "muted", className: "min-w-0 break-words", children: row.path }))] })] }), (!row.bands || row.bands.length === 0) &&
+                (market ? _jsx(MarketCard, { market: market }) : canSeeMarket ? null : _jsx(MarketSignInPrompt, {})), row.bands && row.bands.length > 0 ? (_jsxs(_Fragment, { children: [_jsx(Stack, { gap: "sm", className: "min-w-0", children: row.bands.map((b) => (_jsx(BandCard, { band: b, threshold: threshold }, b.listingType))) }), market ? _jsx(MarketCard, { market: market }) : canSeeMarket ? null : _jsx(MarketSignInPrompt, {}), _jsxs(Text, { size: "xs", color: "muted", children: ["Completed sales on LetItRip", row.windowDays ? ` over the last ${row.windowDays} days` : "", row.computedAt ? ` · as of ${new Date(row.computedAt).toLocaleDateString("en-IN")}` : ""] })] })) : (
             /*
              * 🛑 "No sales recorded yet" — never ₹0, and never a blank card. The
              * absence of a band means nothing has sold here, which is a fact about
              * our marketplace and not a failure of the lookup.
+             *
+             * 🛑 The wording is DIFFERENT when a market band is showing above it.
+             * "Prices appear once something sells" was written for a card that had
+             * nothing else on it; printed under a real asking-price band it reads
+             * as though the band were not a price, which is the opposite of what
+             * this card now says.
              */
-            _jsx(Text, { size: "sm", color: "muted", children: "No completed sales recorded here yet. Prices appear once something sells on LetItRip." }))] }));
+            _jsx(Text, { size: "sm", color: "muted", children: market
+                    ? "Nothing has sold here on LetItRip yet, so the figures above are asking prices elsewhere rather than our own sales."
+                    : "No completed sales recorded here yet. Prices appear once something sells on LetItRip." }))] }));
 }
 /** Stable identity — a `useMemo` dependency inside `useSiteSearch`. */
 const identityLabel = (typeKey) => typeKey;
-/** `/categories/{slug}` -> `{slug}`. Category documents are pure slugs (id === slug). */
-function categoryIdFromHref(href) {
-    const m = /^\/categories\/([^/?#]+)/.exec(href);
-    return m ? m[1] : null;
-}
 export function PriceIndexToolView({ initialQuery = "", initialData = null, searchIndexEnabled, }) {
     const [draft, setDraft] = useState(initialQuery);
     /**
@@ -105,24 +169,108 @@ export function PriceIndexToolView({ initialQuery = "", initialData = null, sear
      * keystroke against a route that holds a Firestore query plus a multi-get —
      * which is Root Cause #94's recurring server bill, and `audit-client-poll-cost`
      * exists because of it. The query key only moves when somebody submits.
+     *
+     * 🛑 Still here after the dropdown landed, because it drives the FALLBACK
+     * path: the dropdown's options come from the local search artifact, so when
+     * that artifact is disabled or fails to load there is nothing to pick from
+     * and the tool must still work. Deleting this would have made a kill-switch
+     * flip turn the whole page into an empty combobox.
      */
     const [term, setTerm] = useState(initialQuery.trim());
+    /**
+     * What the dropdown picked: the category id to price, plus its label.
+     *
+     * 🛑 The LABEL is kept alongside the id, not looked up again. The option list
+     * is rebuilt per keystroke inside `loadOptions`, so by the time results
+     * arrive the option that produced the selection may no longer be in the list
+     * — and `PaginatedSelect` renders the trigger from the value it was given.
+     * Without this the chosen item's name would vanish from the control the
+     * moment the query that found it changed.
+     */
+    const [picked, setPicked] = useState(null);
+    /** Signed in? Decides whether the market half is requested at all. */
+    const session = useOptionalSession();
+    const canSeeMarket = Boolean(session?.user?.uid);
     /*
-     * 🛑 TIER 1 ADOPTION. `searchPriceIndex` (the fallback below) pays a
-     * `searchTxt` push-down query to turn `term` into category leaves —
-     * exactly the resolution `useSiteSearch` already does in the browser, at
-     * zero reads, for every other search surface on the site. Resolving here
-     * removes that query from the HOT path; the server is left with only the
-     * one multi-get it cannot avoid.
+     * The artifact, for the dropdown. `active` is true as soon as the control is
+     * on the page: unlike the old submit-driven flow there is no "intent"
+     * threshold to wait for — a combobox the user has just clicked must have
+     * options, and the artifact is a one-time ~420 KB load with a module-scope
+     * singleton behind it, not a per-keystroke cost.
+     */
+    const dropdownIndex = useSearchIndex({
+        active: true,
+        indexEnabled: searchIndexEnabled,
+    });
+    /**
+     * Options for the dropdown, resolved LOCALLY on every keystroke.
      *
-     * `active` mirrors `term`'s own gate (2+ chars) rather than firing on
-     * mount — consistent with every other `useSiteSearch` caller, which loads
-     * the ~420 KB artifact only once intent is shown.
+     * 🛑 `async` only to satisfy `loadOptions`' signature — nothing here awaits.
+     * `searchIndex` is a linear scan over ~3,700 prepared records, measured at
+     * 0.76 ms by `verify-search-local.mjs`, so there is no network round trip to
+     * debounce and no Firestore read to bill. This is the whole reason the
+     * dropdown can be a dropdown.
+     *
+     * 🛑 Hits that cannot be priced are DROPPED, not shown disabled. An option
+     * that selects to a card reading "no data" is worse than an absent one — it
+     * looks like the tool failed rather than like the item is not priceable. See
+     * `priceLookupTargetFor` for which types resolve and why.
+     */
+    const loadOptions = useCallback(async (query, page) => {
+        const idx = dropdownIndex.index;
+        if (!idx || !query.trim())
+            return { items: [], hasMore: false };
+        const hits = searchIndex(idx.artifact, idx.prepared, query, {
+            types: PRICE_LOOKUP_INDEX_TYPES,
+            limit: DROPDOWN_LIMIT,
+        });
+        const seen = new Set();
+        const items = [];
+        for (const hit of hits) {
+            const target = priceLookupTargetFor(hit.href);
+            if (!target || seen.has(target))
+                continue;
+            seen.add(target);
+            items.push({
+                value: target,
+                /*
+                 * The type and the detail both earn their place: `detail` is the
+                 * taxonomy path for a category and the classification for a part,
+                 * which is how a reader tells three results named "105" apart.
+                 */
+                label: `${hit.title}${hit.detail ? ` — ${hit.detail}` : ""}`,
+            });
+        }
+        // One page: the matcher already ranked and capped. Paging a ranked list
+        // would invite scrolling past the answer rather than refining the query.
+        return { items, hasMore: false, nextPage: page };
+    }, [dropdownIndex.index]);
+    /**
+     * 🛑 The dropdown is only usable with an artifact behind it. On `disabled` or
+     * `failed` the page falls back to the original text box, which hits the
+     * server-side `searchTxt` path. Reported as a state rather than silently
+     * degrading, because an empty combobox is indistinguishable from an empty
+     * catalogue.
+     */
+    const dropdownUsable = dropdownIndex.status === "ready" || dropdownIndex.status === "loading" ||
+        dropdownIndex.status === "idle";
+    /*
+     * 🛑 TIER 1 ADOPTION, kept for the FALLBACK path only.
+     *
+     * `searchPriceIndex` pays a `searchTxt` push-down query to turn a free-text
+     * term into category leaves — the resolution the local artifact does for
+     * free. When the dropdown is driving, no term is ever submitted and this
+     * stays idle; it matters when somebody lands on a shared `?q=` link.
+     *
+     * 🛑 Its `types` now come from `PRICE_LOOKUP_INDEX_TYPES`, not a hand-written
+     * `["model", "category"]`. That literal is why spares were unreachable: the
+     * index has had a `part` type the whole time and this call never asked for
+     * it, so no amount of typing a part name could surface one.
      */
     const local = useSiteSearch(term, {
         active: term.length >= 2,
         indexEnabled: searchIndexEnabled,
-        types: ["model", "category"],
+        types: PRICE_LOOKUP_INDEX_TYPES,
         label: identityLabel,
     });
     const localIds = React.useMemo(() => {
@@ -131,7 +279,13 @@ export function PriceIndexToolView({ initialQuery = "", initialData = null, sear
         const ids = new Set();
         for (const group of local.result.groups) {
             for (const hit of group.hits) {
-                const id = categoryIdFromHref(hit.href);
+                /*
+                 * 🛑 `priceLookupTargetFor`, not a bare `/categories/` regex. The old
+                 * `categoryIdFromHref` matched that one shape and returned `null` for
+                 * everything else, so a part hit was discarded here even on the rare
+                 * occasion one arrived.
+                 */
+                const id = priceLookupTargetFor(hit.href);
                 if (id)
                     ids.add(id);
             }
@@ -139,6 +293,14 @@ export function PriceIndexToolView({ initialQuery = "", initialData = null, sear
         return [...ids];
     }, [local.result]);
     const localReady = local.status === "ready";
+    /**
+     * The ids actually being looked up.
+     *
+     * A dropdown pick wins outright: it is an explicit choice of ONE thing, and
+     * mixing it with the term-resolved set would answer a question the user
+     * stopped asking the moment they picked.
+     */
+    const lookupIds = React.useMemo(() => (picked ? [picked.id] : localReady ? localIds : []), [picked, localReady, localIds]);
     /*
      * The bands-only request. Enabled ONLY once local resolution has actually
      * produced something — an empty `localIds` with the gate open would be a
@@ -146,19 +308,51 @@ export function PriceIndexToolView({ initialQuery = "", initialData = null, sear
      * but which is still a request worth not making.
      */
     const bandsQuery = useQuery({
-        queryKey: ["tool", "price-index", "bands", localIds],
-        queryFn: () => apiClient.get(TOOL_ENDPOINTS.PRICE_INDEX_BANDS(localIds)),
-        enabled: localReady && localIds.length > 0,
+        queryKey: ["tool", "price-index", "bands", lookupIds],
+        queryFn: () => apiClient.get(TOOL_ENDPOINTS.PRICE_INDEX_BANDS(lookupIds)),
+        enabled: lookupIds.length > 0,
         staleTime: Infinity,
         refetchOnWindowFocus: false,
     });
+    /**
+     * The MARKET half — a separate request, on purpose.
+     *
+     * 🛑 `enabled: canSeeMarket && …`. A guest never issues it, so the gate costs
+     * a signed-out visitor nothing and cannot 401-spam the console. The server
+     * enforces it too (`auth: true`); this is the client half of one decision,
+     * not the decision itself.
+     *
+     * 🛑 A separate request rather than two more fields on `bandsQuery`, because
+     * that route is PUBLIC and edge-cached: folding viewer-dependent content into
+     * it would let one signed-in lookup populate the entry every guest then
+     * reads. The full argument is in `price-index/market.ts`.
+     *
+     * 🛑 Its failure is deliberately NOT surfaced as the page's error. The sold
+     * band is the page; the ask is context. A 401 or a cold-start blip on the
+     * context must not replace a working result with "could not look that up".
+     */
+    const marketQuery = useQuery({
+        queryKey: ["tool", "price-index", "market", lookupIds],
+        queryFn: () => apiClient.get(TOOL_ENDPOINTS.PRICE_INDEX_MARKET(lookupIds)),
+        enabled: canSeeMarket && lookupIds.length > 0,
+        staleTime: Infinity,
+        refetchOnWindowFocus: false,
+    });
+    /** `categoryId` -> its market band, for the per-card join. */
+    const marketById = React.useMemo(() => {
+        const m = new Map();
+        for (const row of marketQuery.data?.results ?? [])
+            m.set(row.categoryId, row);
+        return m;
+    }, [marketQuery.data]);
     /*
      * The FALLBACK. Fires only when the local index is off, failed, or
      * (rarely) resolved to nothing — never alongside the local path, so a
      * working index never pays for both. Same cache posture as it always had.
      */
-    const fallbackEnabled = term.length >= 2 && (local.status === "failed" || local.status === "disabled" ||
-        (localReady && localIds.length === 0));
+    const fallbackEnabled = !picked && term.length >= 2 &&
+        (local.status === "failed" || local.status === "disabled" ||
+            (localReady && localIds.length === 0));
     const fallbackQuery = useQuery({
         queryKey: ["tool", "price-index", term],
         queryFn: () => apiClient.get(TOOL_ENDPOINTS.PRICE_INDEX_SEARCH(term)),
@@ -175,11 +369,11 @@ export function PriceIndexToolView({ initialQuery = "", initialData = null, sear
      * how many ids were resolved, so there is nothing left uncounted the way
      * the query-based path's search step could leave behind.
      */
-    const query = localReady && localIds.length > 0
+    const query = lookupIds.length > 0
         ? {
             data: bandsQuery.data
                 ? {
-                    query: term,
+                    query: picked ? picked.label : term,
                     results: bandsQuery.data.results,
                     truncated: false,
                     /*
@@ -215,5 +409,14 @@ export function PriceIndexToolView({ initialQuery = "", initialData = null, sear
         : null;
     const threshold = data?.minConfidentSamples ?? 3;
     const hasQuery = (data?.query ?? "").length > 0;
-    return (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "lg", children: _jsxs(Stack, { gap: "lg", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsxs(Row, { gap: "sm", align: "center", children: [_jsx(TrendingUp, { className: "w-5 h-5 text-primary-600", "aria-hidden": "true" }), _jsx(Heading, { level: 1, children: "What it sold for" })] }), _jsx(Text, { color: "muted", children: "Search any model, part or set to see what it actually sold for on LetItRip \u2014 the range, the median, the average and the most recent sale, broken down by condition." })] }), _jsx(Form, { onSubmit: (e) => e.preventDefault(), children: () => (_jsxs(Row, { gap: "sm", align: "end", wrap: true, className: "min-w-0", children: [_jsx(Div, { className: "flex-1 min-w-[16rem]", children: _jsx(FieldInput, { name: "q", label: "Search", value: draft, onChange: setDraft, placeholder: "e.g. Dragoon G, Storm Pegasus, rubber flat\u2026" }) }), _jsxs(Button, { type: "submit", isLoading: loading, onClick: () => run(draft), children: [_jsx(Search, { className: "w-4 h-4", "aria-hidden": "true" }), "Look up"] })] })) }), error && (_jsx(Text, { size: "sm", color: "error", role: "alert", children: error })), !hasQuery && !loading && !error && (_jsxs(Stack, { gap: "xs", padding: "card", rounded: "lg", surface: "muted", className: "min-w-0", children: [_jsx(Text, { weight: "semibold", children: "Why these prices are different" }), _jsxs(Text, { size: "sm", color: "muted", children: ["Everything here is a completed sale on LetItRip \u2014 not an asking price, and not a guess. We publish a figure only once", " ", threshold, " or more sales support it, and the index is recomputed once a day, so it is deliberately a day behind."] })] })), hasQuery && data && data.results.length === 0 && !loading && (_jsxs(Text, { color: "muted", children: ["Nothing matched \u201C", data.query, "\u201D. Try a shorter term, or the model name on its own."] })), data && data.results.length > 0 && (_jsxs(Stack, { gap: "md", className: "min-w-0", children: [data.results.map((row) => (_jsx(ResultCard, { row: row, threshold: threshold }, row.categoryId))), data.truncated && (_jsxs(Text, { size: "sm", color: "muted", children: ["Showing the closest ", data.results.length, " matches. Narrow the search to see others."] }))] }))] }) }) }));
+    return (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "lg", children: _jsxs(Stack, { gap: "lg", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsxs(Row, { gap: "sm", align: "center", children: [_jsx(TrendingUp, { className: "w-5 h-5 text-primary-600", "aria-hidden": "true" }), _jsx(Heading, { level: 1, children: "What it sold for" })] }), _jsx(Text, { color: "muted", children: "Pick any bey, part or set to see what it actually sold for on LetItRip \u2014 the range, the median, the average and the most recent sale, broken down by condition \u2014 alongside what other Indian shops are asking for the same thing." })] }), dropdownUsable ? (_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsx(PaginatedSelect, { value: picked?.id ?? null, onChange: (value, option) => setPicked(value && option ? { id: value, label: option.label } : null), loadOptions: loadOptions, placeholder: "Pick a bey, part or set\u2026", searchPlaceholder: "Type a name, code or part \u2014 e.g. Dragoon G, 1B, rubber flat", noResultsText: "Nothing in our catalogue matches that.", ariaLabel: "Search the catalogue for a price lookup" }), _jsx(Text, { size: "xs", color: "muted", children: "Models, parts and spares, eras and brands \u2014 straight from our own catalogue, so what you pick is a real thing we can price." })] })) : (
+                    /*
+                     * 🛑 The fallback, for a disabled or failed search artifact. Without
+                     * it a kill-switch flip would leave an empty combobox and no way to
+                     * search at all — the dropdown has no options without the artifact,
+                     * but the server-side `searchTxt` path still works.
+                     */
+                    _jsx(Form, { onSubmit: (e) => e.preventDefault(), children: () => (_jsxs(Row, { gap: "sm", align: "end", wrap: true, className: "min-w-0", children: [_jsx(Div, { className: "flex-1 min-w-[16rem]", children: _jsx(FieldInput, { name: "q", label: "Search", value: draft, onChange: setDraft, placeholder: "e.g. Dragoon G, Storm Pegasus, rubber flat\u2026" }) }), _jsxs(Button, { type: "submit", isLoading: loading, onClick: () => run(draft), children: [_jsx(Search, { className: "w-4 h-4", "aria-hidden": "true" }), "Look up"] })] })) })), error && (_jsx(Text, { size: "sm", color: "error", role: "alert", children: error })), !hasQuery && !loading && !error && (_jsxs(Stack, { gap: "xs", padding: "card", rounded: "lg", surface: "muted", className: "min-w-0", children: [_jsx(Text, { weight: "semibold", children: "Two numbers, and the gap matters" }), _jsxs(Text, { size: "sm", color: "muted", children: [_jsx(Span, { weight: "semibold", children: "Sold" }), " is a completed sale on LetItRip \u2014 not an asking price and not a guess. We publish a figure only once ", threshold, " or more sales support it, and the index is recomputed once a day, so it is deliberately a day behind."] }), _jsxs(Text, { size: "sm", color: "muted", children: [_jsx(Span, { weight: "semibold", children: "Asked" }), " is what other Indian shops list the same thing for, measured across fifteen catalogues.", canSeeMarket
+                                        ? " Shown beside our own sales — never averaged with them, because an ask is not a sale."
+                                        : " Sign in to see it beside our own sales."] })] })), hasQuery && data && data.results.length === 0 && !loading && (_jsxs(Text, { color: "muted", children: ["Nothing matched \u201C", data.query, "\u201D. Try a shorter term, or the model name on its own."] })), data && data.results.length > 0 && (_jsxs(Stack, { gap: "md", className: "min-w-0", children: [data.results.map((row) => (_jsx(ResultCard, { row: row, threshold: threshold, market: marketById.get(row.categoryId), canSeeMarket: canSeeMarket }, row.categoryId))), data.truncated && (_jsxs(Text, { size: "sm", color: "muted", children: ["Showing the closest ", data.results.length, " matches. Narrow the search to see others."] }))] }))] }) }) }));
 }

package/dist/features/price-index/lookup-target.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The index types the price tool searches.
+ *
+ * 🛑 Exactly the types that can RESOLVE TO A PRICEABLE NODE, which is a
+ * narrower set than "everything in the index" and deliberately so:
+ *
+ *   `model`    -> its model leaf (href is `/categories/{categoryId}`)
+ *   `category` -> itself, incl. the era and part-group leaves the crawl
+ *                 actually measured
+ *   `part`     -> its part-group leaf via `PART_SLOT_CATEGORY` — this is the
+ *                 one that makes spares work, and those leaves
+ *                 (`category-metal-energy-rings`, `category-burst-layers`, …)
+ *                 are precisely where `MARKET_BANDS` has component pricing
+ *   `brand`    -> itself; brands are `categories` rows with
+ *                 `categoryType: "brand"`
+ *
+ * 🛑 What is NOT here, and why — each of these was asked for and cannot be
+ * delivered from the client index as it stands:
+ *
+ *   `group`           `groupedListings` is not a category, so no band can
+ *                     attach to it at all.
+ *   the 10 listing    A product record's href is `/products/{slug}` and the
+ *   types             record carries no `categoryId`, so resolving one needs a
+ *                     server read per hit. A price band is a statement about a
+ *                     leaf, not about one seller's listing.
+ *   `bundle`,         NOT IN THE INDEX. No `IndexSource` emits them and the
+ *   `franchise`       `category` source rejects any `categoryType` other than
+ *                     `sublisting`, so adding them is an index-build change,
+ *                     not a filter here.
+ *
+ * 🛑 `brand` is included as asked, and the honest caveat is that a brand row is
+ * a tier-0 node OUTSIDE the forest with no `parentIds`, so it inherits no band
+ * and will usually resolve to "no market evidence". That renders as an honest
+ * empty rather than a wrong number, but it is a thin result and the reason is
+ * the data, not the lookup.
+ */
+export declare const PRICE_LOOKUP_INDEX_TYPES: readonly string[];
+/**
+ * The category id whose band answers a search hit, or `null` when the hit
+ * cannot be priced.
+ *
+ * 🛑 `null` is a real answer and must not be collapsed into a guess. The
+ * alternative — falling back to some ancestor, or to the hit's own slug as if
+ * it were a category id — would attach a band to a node that does not have one
+ * and render a confident number for the wrong thing. A dropped option is
+ * visible; a misattributed price is not.
+ */
+export declare function priceLookupTargetFor(href: string): string | null;

package/dist/features/price-index/lookup-target.js

@@ -0,0 +1,107 @@
+/*
+ * WHY: The realised-price tool looks prices up per CATEGORY leaf, but the thing
+ *      a person searches for is a model, a part, a brand or an era — four
+ *      different index types with four different href shapes. Turning a search
+ *      hit into "the leaf whose band answers this" was previously a single
+ *      regex over `/categories/...` inside the view, which silently dropped
+ *      every part hit; the tool asked the index for `["model", "category"]`
+ *      only, so spares were unreachable even though `part` is indexed.
+ * WHAT: One pure function from a search hit to the category id to look up, plus
+ *       the type list the tool should ask the matcher for.
+ *
+ * EXPORTS:
+ *   PRICE_LOOKUP_INDEX_TYPES — which index types the tool searches
+ *   priceLookupTargetFor     — a hit's href -> the category id, or null
+ *
+ * 🛑 Pure. No React, no Firestore, no fetch — it runs inside a `loadOptions`
+ *    callback on every keystroke.
+ *
+ * @tag domain:price-index
+ * @tag layer:feature
+ * @tag pattern:pure-function
+ * @tag access:isomorphic
+ * @tag consumers:PriceIndexToolView
+ * @tag sideEffects:none
+ */
+import { PART_SLOT_CATEGORY } from "../parts/schemas/firestore.js";
+/**
+ * The index types the price tool searches.
+ *
+ * 🛑 Exactly the types that can RESOLVE TO A PRICEABLE NODE, which is a
+ * narrower set than "everything in the index" and deliberately so:
+ *
+ *   `model`    -> its model leaf (href is `/categories/{categoryId}`)
+ *   `category` -> itself, incl. the era and part-group leaves the crawl
+ *                 actually measured
+ *   `part`     -> its part-group leaf via `PART_SLOT_CATEGORY` — this is the
+ *                 one that makes spares work, and those leaves
+ *                 (`category-metal-energy-rings`, `category-burst-layers`, …)
+ *                 are precisely where `MARKET_BANDS` has component pricing
+ *   `brand`    -> itself; brands are `categories` rows with
+ *                 `categoryType: "brand"`
+ *
+ * 🛑 What is NOT here, and why — each of these was asked for and cannot be
+ * delivered from the client index as it stands:
+ *
+ *   `group`           `groupedListings` is not a category, so no band can
+ *                     attach to it at all.
+ *   the 10 listing    A product record's href is `/products/{slug}` and the
+ *   types             record carries no `categoryId`, so resolving one needs a
+ *                     server read per hit. A price band is a statement about a
+ *                     leaf, not about one seller's listing.
+ *   `bundle`,         NOT IN THE INDEX. No `IndexSource` emits them and the
+ *   `franchise`       `category` source rejects any `categoryType` other than
+ *                     `sublisting`, so adding them is an index-build change,
+ *                     not a filter here.
+ *
+ * 🛑 `brand` is included as asked, and the honest caveat is that a brand row is
+ * a tier-0 node OUTSIDE the forest with no `parentIds`, so it inherits no band
+ * and will usually resolve to "no market evidence". That renders as an honest
+ * empty rather than a wrong number, but it is a thin result and the reason is
+ * the data, not the lookup.
+ */
+export const PRICE_LOOKUP_INDEX_TYPES = [
+    "model",
+    "category",
+    "part",
+    "brand",
+];
+/** `/categories/{id}` and `/brands/{id}` — category documents are pure slugs. */
+const DIRECT_CATEGORY_HREF = /^\/(?:categories|brands)\/([^/?#]+)/;
+/**
+ * `/parts/{classification}/{code}`.
+ *
+ * 🛑 TWO segments, and the first is the slot. `ROUTES.PUBLIC.PART_DETAIL`'s own
+ * comment explains why a code alone cannot be a URL: "`105` is a Metal Fight
+ * spin-track height, a bare number in Burst is a disc, and `1-60` is a Beyblade
+ * X ratchet." The slot is what places the part in the taxonomy.
+ */
+const PART_HREF = /^\/parts\/([^/?#]+)\/([^/?#]+)/;
+/**
+ * The category id whose band answers a search hit, or `null` when the hit
+ * cannot be priced.
+ *
+ * 🛑 `null` is a real answer and must not be collapsed into a guess. The
+ * alternative — falling back to some ancestor, or to the hit's own slug as if
+ * it were a category id — would attach a band to a node that does not have one
+ * and render a confident number for the wrong thing. A dropped option is
+ * visible; a misattributed price is not.
+ */
+export function priceLookupTargetFor(href) {
+    const direct = DIRECT_CATEGORY_HREF.exec(href);
+    if (direct)
+        return direct[1] ?? null;
+    const part = PART_HREF.exec(href);
+    if (part) {
+        const slot = part[1];
+        /*
+         * `PART_SLOT_CATEGORY` is a `Record<PartSlot, string>`, so a 21st slot is a
+         * compile error there rather than a silent miss here — but the href came
+         * off an artifact built from live documents, so a slot this build has never
+         * heard of is still possible and resolves to `null` rather than
+         * `undefined` leaking into a URL.
+         */
+        return PART_SLOT_CATEGORY[slot] ?? null;
+    }
+    return null;
+}

package/dist/features/products/api/[id]/route.js

@@ -13,6 +13,7 @@ import { NextResponse } from "next/server.js";
 import { z } from "zod";
 import { getProviders } from "../../../../contracts/index.js";
 import { createRouteHandler } from "../../../../next/api/routeHandler.js";
+import { ALL_LISTING_TYPES } from "../../../../_internal/shared/listing-types/feature-flags.js";
 import { mediaFieldSchema } from "../../../media/types/index.js";
 import { storeRepository } from "../../../stores/repository/store.repository.js";
 // SB-UNI-V — bundlesRepository deleted; bundle stock-sync moves to the
@@ -55,8 +56,14 @@ const productUpdateSchema = z
     isPromoted: z.boolean().optional(),
     allowShipBeforeEmiComplete: z.boolean().optional(),
     printMeta: printMetaSchema.optional(),
+    /*
+     * 🛑 DERIVED from `ALL_LISTING_TYPES`, never restated. This literal was
+     * wrong in both directions: `spares` missing (so the type could not be
+     * PATCHed onto a listing at all) and `bundle` still present (so a caller
+     * could write a value no registry has a branch for). Root Cause #61.
+     */
     listingType: z
-        .enum(["standard", "auction", "pre-order", "prize-draw", "bundle", "classified", "digital-code", "live", "art", "stickers"])
+        .enum(ALL_LISTING_TYPES)
         .optional(),
     media: z.array(mediaFieldSchema).optional(),
 })

package/dist/features/products/api/route.js

@@ -16,6 +16,7 @@ import { NextResponse } from "next/server.js";
 import { z } from "zod";
 import { getProviders } from "../../../contracts/index.js";
 import { createRouteHandler } from "../../../next/api/routeHandler.js";
+import { ALL_LISTING_TYPES } from "../../../_internal/shared/listing-types/feature-flags.js";
 import { mediaFieldSchema } from "../../media/types/index.js";
 import { printMetaSchema } from "../schemas/index.js";
 import { sanitizeProductsForPublic } from "../utils/sanitize.js";
@@ -50,11 +51,22 @@ const productMutateSchema = z
     sellerName: z.string().optional(),
     sellerEmail: z.string().email().optional(),
     slug: z.string().optional(),
-    // `bundle` is deliberately absent: SB-UNI-D moved bundles onto
-    // `categories` as a categoryType, so a product written with that value
-    // would match no listing-type query anywhere.
+    /*
+     * 🛑 DERIVED from `ALL_LISTING_TYPES`, never restated.
+     *
+     * The literal that used to sit here is the cautionary tale for why. Its
+     * comment correctly explained that `bundle` is absent because SB-UNI-D
+     * moved bundles onto `categories` — so the dead value had been noticed and
+     * removed — and the list was STILL wrong, because `spares` was added to the
+     * union on 2026-10-19 and never reached here. A fix for one half of the
+     * drift, documented in a comment, with the other half drifting one field
+     * over underneath it.
+     *
+     * Deriving removes both failure modes at once: a dead value cannot survive
+     * and a new member cannot be forgotten. Root Cause #61.
+     */
     listingType: z
-        .enum(["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live", "art", "stickers"])
+        .enum(ALL_LISTING_TYPES)
         .optional(),
     media: z.array(mediaFieldSchema).optional(),
 })

package/dist/features/products/components/AvailabilityScopeHint.d.ts

@@ -0,0 +1,22 @@
+import React from "react";
+import type { ListingType } from "../types/index";
+export interface AvailabilityScopeHintProps {
+    /**
+     * Every published row in this tab's scope, all availability scopes.
+     * `undefined` means the count is unknown — the hint renders nothing rather
+     * than guessing (Root Cause #72: unknown must never read as a number).
+     */
+    total?: number;
+    /** Rows the AVAILABLE scope renders. Same `undefined` rule. */
+    available?: number;
+    /**
+     * The listing types this tab spans. The hidden-rows noun ("sold", "ended",
+     * "sold & ended") is DERIVED from their plugins via `availabilityTabsFor`,
+     * which is the same function that labels the scope tabs — so the hint and
+     * the control it points at can never disagree about the word. A hand-written
+     * string here would be a tenth place the `ListingType` union is enumerated
+     * by hand (Root Cause #61).
+     */
+    types: readonly ListingType[];
+}
+export declare function AvailabilityScopeHint({ total, available, types, }: AvailabilityScopeHintProps): React.JSX.Element | null;

package/dist/features/products/components/AvailabilityScopeHint.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, Row, Text } from "../../../ui/index.js";
+import { useUrlTable } from "../../../react/hooks/useUrlTable.js";
+import { AVAILABILITY_VALUES } from "../../../constants/field-names.js";
+import { TABLE_KEYS } from "../../../constants/table-keys.js";
+import { availabilityTabsFor } from "../../../_internal/shared/listing-types/_registry.js";
+export function AvailabilityScopeHint({ total, available, types, }) {
+    const table = useUrlTable();
+    const scope = table.get(TABLE_KEYS.AVAILABILITY) ||
+        AVAILABILITY_VALUES.AVAILABLE;
+    // Only the default scope withholds anything. In Ended or All the visitor is
+    // already looking at the rows this hint would point them to.
+    if (scope !== AVAILABILITY_VALUES.AVAILABLE)
+        return null;
+    if (total === undefined || available === undefined)
+        return null;
+    const hidden = total - available;
+    if (hidden <= 0)
+        return null;
+    // availabilityTabsFor()[1] is the unavailable scope — "Sold", "Ended" or
+    // "Sold & Ended", already derived per type.
+    const noun = (availabilityTabsFor(types)[1]?.label ?? "Sold").toLowerCase();
+    return (_jsxs(Row, { align: "center", gap: "sm", padding: "sm", surface: "muted", rounded: "lg", border: "subtle", wrap: true, className: "mb-4", children: [_jsx(Text, { size: "sm", color: "muted", children: hidden === 1
+                    ? `1 listing here is ${noun} and hidden by the Available filter.`
+                    : `${hidden} listings here are ${noun} and hidden by the Available filter.` }), _jsx(Button, { variant: "ghost", size: "sm", onClick: () => table.set(TABLE_KEYS.AVAILABILITY, AVAILABILITY_VALUES.ALL), children: "Show all" })] }));
+}