@mohasinac/appkit 4.59.0 → 4.60.1

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

@@ -598,13 +598,13 @@ export async function CategoryDetailPageView({ slug }) {
     const ldFaq = category?.faqs && category.faqs.length > 0
         ? faqJsonLd(category.faqs.map((f) => ({ question: f.question, answer: f.answer })))
         : null;
-    return (_jsxs(Main, { children: [_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldBreadcrumb) } }), _jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldCollection) } }), ldFaq && (_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldFaq) } })), _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" })] })), !hasCover && hasMosaic && (_jsx(Div, { className: "relative z-10 max-w-7xl mx-auto", padding: "x-md", children: _jsx(Div, { padding: "t-lg", children: _jsx(ImageMosaic, { images: mosaicImages, alt: `${category?.name ?? slug} on LetItRip` }) }) })), _jsxs(Div, { className: "relative z-10 max-w-7xl mx-auto", paddingY: hasCover ? "y-3xl" : "y-xl", padding: "x-md", children: [_jsx(BreadcrumbTrail, { crumbs: trail, className: "mb-4", tone: hasCover ? "on-media" : "default" }), category?.id && _jsx(LastCategoryBeacon, { categoryId: category.id }), category?.id && (_jsx(RecordOwnerQuickActions, { resource: "CATEGORY", recordId: category.id, placement: "detail", 
+    return (_jsxs(Main, { children: [_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldBreadcrumb) } }), _jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldCollection) } }), ldFaq && (_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldFaq) } })), _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" })] })), !hasCover && hasMosaic && (_jsx(Div, { className: "relative z-10 max-w-7xl mx-auto", padding: "x-md", children: _jsx(Div, { padding: "t-lg", children: _jsx(ImageMosaic, { images: mosaicImages, alt: `${category?.name ?? slug} on LetItRip` }) }) })), _jsxs(Div, { className: "relative z-10 max-w-7xl mx-auto", paddingY: hasCover ? "y-3xl" : "y-xl", padding: "x-md", children: [_jsx(BreadcrumbTrail, { crumbs: trail, className: "mb-4", tone: hasCover ? "on-media" : "default" }), category?.id && _jsx(LastCategoryBeacon, { categoryId: category.id }), _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?.id && (_jsx(RecordOwnerQuickActions, { resource: "CATEGORY", recordId: category.id, placement: "detail", 
                                 /*
                                  * Same flag the rest of this hero branches on. Without it the
                                  * pencil renders `ghost` (zinc-600) on the dark cover and is
                                  * invisible — see Root Cause #67 and `OwnerQuickActions.onMedia`.
                                  */
-                                onMedia: hasCover, className: "mb-3", recordLabel: 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"] })), showCountSplit && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "muted", size: "xs", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [ownHere.toLocaleString(), " here \u00B7 ", inSubcategories.toLocaleString(), " in subcategories"] })), 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"] }))] })] })] }), category?.hasbroName && (_jsx(Section, { padding: "y-md", children: _jsx(Container, { size: "xl", children: _jsxs(Row, { gap: "md", align: "center", wrap: true, children: [category.hasbroCoverImage && (_jsx(MediaImage, { src: category.hasbroCoverImage, alt: `${category.hasbroName} logo`, size: "thumbnail", className: "h-12 w-auto flex-shrink-0" })), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", transform: "uppercase", weight: "medium", children: "Also known as" }), _jsx(Text, { weight: "semibold", children: category.hasbroName }), _jsxs(Text, { size: "xs", color: "muted", children: ["The same wave, named differently outside Japan \u2014 Takara-Tomy releases it as ", category.name, ", Hasbro as ", category.hasbroName, ". Both names find these listings."] })] })] }) }) })), contentBody && contentBody.trim().length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(RichTextRenderer, { html: contentBody }) }) })), _jsx(CategoryHighlightsAndFaqSection, { highlights: category?.highlights, faqs: category?.faqs }), pairedBeys.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: __W, padding: "section", children: _jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: pairedBeys.length === 1 ? "Specifications" : "Releases" }), _jsx(Stack, { gap: "xs", className: "min-w-0", children: pairedBeys.map((bey) => (_jsxs(Row, { gap: "sm", align: "center", wrap: true, className: "min-w-0", children: [_jsx(TextLink, { href: String(ROUTES.PUBLIC.BEY_DETAIL(bey.slug)), children: bey.name }), [bey.system, bey.productCodes?.[0]]
+                                onMedia: hasCover, className: "mb-3", recordLabel: category.name ?? slug })), category?.description && typeof category.description === "string" && !category.description.startsWith("{") && (_jsx(Text, { color: hasCover ? "inverse" : "muted", className: "max-w-2xl mb-4", 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"] })), showCountSplit && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "muted", size: "xs", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [ownHere.toLocaleString(), " here \u00B7 ", inSubcategories.toLocaleString(), " in subcategories"] })), 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"] }))] })] })] }), category?.hasbroName && (_jsx(Section, { padding: "y-md", children: _jsx(Container, { size: "xl", children: _jsxs(Row, { gap: "md", align: "center", wrap: true, children: [category.hasbroCoverImage && (_jsx(MediaImage, { src: category.hasbroCoverImage, alt: `${category.hasbroName} logo`, size: "thumbnail", className: "h-12 w-auto flex-shrink-0" })), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", transform: "uppercase", weight: "medium", children: "Also known as" }), _jsx(Text, { weight: "semibold", children: category.hasbroName }), _jsxs(Text, { size: "xs", color: "muted", children: ["The same wave, named differently outside Japan \u2014 Takara-Tomy releases it as ", category.name, ", Hasbro as ", category.hasbroName, ". Both names find these listings."] })] })] }) }) })), contentBody && contentBody.trim().length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(RichTextRenderer, { html: contentBody }) }) })), _jsx(CategoryHighlightsAndFaqSection, { highlights: category?.highlights, faqs: category?.faqs }), pairedBeys.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: __W, padding: "section", children: _jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: pairedBeys.length === 1 ? "Specifications" : "Releases" }), _jsx(Stack, { gap: "xs", className: "min-w-0", children: pairedBeys.map((bey) => (_jsxs(Row, { gap: "sm", align: "center", wrap: true, className: "min-w-0", children: [_jsx(TextLink, { href: String(ROUTES.PUBLIC.BEY_DETAIL(bey.slug)), children: bey.name }), [bey.system, bey.productCodes?.[0]]
                                             .filter(Boolean)
                                             .map((bit) => (_jsx(Text, { size: "sm", color: "muted", children: String(bit) }, String(bit))))] }, bey.id))) })] }) }) })), compositions.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: __W, padding: "section", children: _jsxs(Stack, { gap: "md", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: "What it is made of" }), _jsx(ModelCompositionPanel, { compositions: compositions, hrefForPart: (slot, tail) => String(ROUTES.PUBLIC.PART_DETAIL(slot, tail)) })] }) }) })), (() => {
                 if (category?.tier !== 0)

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

@@ -1,7 +1,9 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
 import { Div, FormGroup } from "../../../ui/index.js";
 import { Label, Checkbox, RichTextEditor, Text } from "../../../ui/index.js";
+import { FieldLabel } from "../../../ui/forms/index.js";
 import { ImageUpload, MediaImage, useMediaUpload } from "../../media/index.js";
 import { FormField } from "../../../ui/index.js";
 import { flattenCategories } from "../types/index.js";
@@ -25,6 +27,15 @@ const DEFAULT_LABELS = {
 export function CategoryForm({ category, allCategories, onChange, isReadonly = false, labels = {}, stackClassName = "space-y-4", }) {
     const { upload } = useMediaUpload();
     const L = { ...DEFAULT_LABELS, ...labels };
+    /*
+     * Unique per instance via `useId`, not a literal. Two CategoryForms on one
+     * page would otherwise both emit the same label id, and `aria-labelledby`
+     * resolves the FIRST match — so the second editor would be named by the
+     * first form’s label. The same defect FieldInput’s own note records
+     * fixing for `htmlFor`.
+     */
+    const reactId = useId();
+    const descriptionLabelId = `category-description-label-${reactId}`;
     const update = (partial) => {
         onChange({ ...category, ...partial });
     };
@@ -35,7 +46,7 @@ export function CategoryForm({ category, allCategories, onChange, isReadonly = f
     const handleNameChange = (value) => {
         update({ name: value, slug: makeSlug(value, category.isBrand ?? false) });
     };
-    return (_jsxs(Div, { className: stackClassName, children: [_jsxs(FormGroup, { columns: 2, children: [_jsx(FormField, { name: "name", label: L.name, type: "text", value: category.name || "", onChange: handleNameChange, disabled: isReadonly }), _jsx(FormField, { name: "slug", label: L.slug, type: "text", value: category.slug || "", onChange: (value) => update({ slug: value }), disabled: isReadonly })] }), _jsxs(Div, { className: "appkit-form-field", children: [_jsx(Label, { className: "appkit-form-field__label", children: L.description }), _jsx(RichTextEditor, { value: normalizeRichTextHtml(category.description || ""), onChange: (value) => update({ description: value }), disabled: isReadonly, minHeightClassName: "min-h-[140px]", placeholder: "Enter category description" }), _jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: "Rich text is supported for category descriptions." })] }), !isReadonly && (_jsx(ImageUpload, { currentImage: category.display?.coverImage, onUpload: (file) => upload(file, "categories", true, {
+    return (_jsxs(Div, { className: stackClassName, children: [_jsxs(FormGroup, { columns: 2, children: [_jsx(FormField, { name: "name", label: L.name, type: "text", value: category.name || "", onChange: handleNameChange, disabled: isReadonly }), _jsx(FormField, { name: "slug", label: L.slug, type: "text", value: category.slug || "", onChange: (value) => update({ slug: value }), disabled: isReadonly })] }), _jsxs(Div, { className: "appkit-form-field", children: [_jsx(FieldLabel, { id: descriptionLabelId, children: L.description }), _jsx(RichTextEditor, { value: normalizeRichTextHtml(category.description || ""), onChange: (value) => update({ description: value }), disabled: isReadonly, minHeightClassName: "min-h-[140px]", placeholder: "Enter category description", ariaLabelledBy: descriptionLabelId }), _jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: "Rich text is supported for category descriptions." })] }), !isReadonly && (_jsx(ImageUpload, { currentImage: category.display?.coverImage, onUpload: (file) => upload(file, "categories", true, {
                     type: "category-image",
                     name: category.name || "category",
                 }), onChange: (url) => update({ display: { ...category.display, coverImage: url } }), label: L.categoryImage, helperText: L.imageRecommended })), category.display?.coverImage && isReadonly && (_jsxs(Div, { children: [_jsx(Label, { className: "block mb-2", size: "sm", weight: "medium", children: L.categoryImage }), _jsx(Div, { className: `relative h-32 w-40 ${__O.hidden}`, rounded: "default", children: _jsx(MediaImage, { src: category.display.coverImage, alt: category.name || "", size: "card" }) })] })), _jsx(FormField, { name: "parentId", label: L.parentCategory, type: "select", value: category.parentId || "", onChange: (value) => update({ parentId: value || null }), disabled: isReadonly, options: [

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

@@ -70,12 +70,45 @@ function unwrap(res) {
     const body = res?.data ?? res;
     return body && typeof body === "object" && "template" in body ? body : null;
 }
-/** "2 of 9 slots could not be filled: {{year}}, {{type}}" */
-function unresolvedNote(unresolved, total) {
+/**
+ * `camelCase` / `snake_case` slot name -> words a seller reads.
+ *
+ * `categoryPath` -> "category path", `partBreakdown` -> "part breakdown".
+ * Lower-cased throughout because the note reads these mid-sentence.
+ */
+function humaniseSlot(name) {
+    return name
+        .replace(/[_-]+/g, " ")
+        .replace(/([a-z\d])([A-Z])/g, "$1 $2")
+        .trim()
+        .toLowerCase();
+}
+/**
+ * "2 details were left blank and are highlighted below: year, type"
+ *
+ * 🛑 NO `{{…}}` IN USER-FACING COPY. This printed the slot names back wrapped
+ * in braces — `2 of 9 slots could not be filled: {{year}}, {{type}}` — which
+ * is where the reported "raw {{slot}} syntax" came from. It was not a failed
+ * interpolation leaking through; the note RE-MANUFACTURED the template syntax
+ * to describe it, so the seller saw the same thing either way and no amount of
+ * fixing the templating would have removed it.
+ *
+ * "slots" went with the braces. It is the word this codebase uses for a
+ * placeholder; a seller filling in a listing has no reason to know it, and
+ * "could not be filled" reads as a system failure rather than as the three
+ * boxes they need to type in. The count stays — it is the actionable part —
+ * but it counts what is MISSING rather than reporting it as a fraction, since
+ * "2 of 9" invites the reader to wonder what the other seven were — and the
+ * denominator is why the `total` argument is gone.
+ */
+function unresolvedNote(unresolved) {
     if (unresolved.length === 0)
         return null;
-    const named = unresolved.map((n) => `{{${n}}}`).join(", ");
-    return `${unresolved.length} of ${total} slots could not be filled: ${named}`;
+    const named = unresolved.map(humaniseSlot).join(", ");
+    const count = unresolved.length;
+    return count === 1
+        ? `One detail was left blank — add the ${named} before publishing.`
+        : `${count} details were left blank — add the ${named} before publishing.`;
 }
 /** "adds 2 specification rows · sets condition to Used" */
 function describeDefaults(defaults) {
@@ -165,7 +198,7 @@ export function CategoryTemplatePicker({ categoryId, condition, context, isDescr
     if (!data || !template || !filled) {
         return (_jsx(Div, { className: PANEL_CLASS, children: _jsx(Text, { size: "xs", color: "muted", children: "No description template for this category yet \u2014 write your own, and an admin can add one so the next listing starts from it." }) }));
     }
-    const note = unresolvedNote(filled.unresolved, template.placeholders?.length ?? filled.unresolved.length);
+    const note = unresolvedNote(filled.unresolved);
     const extras = describeDefaults(data.defaults);
     const source = data.inheritedFromName
         ? `Inherited from ${data.inheritedFromName}`

package/dist/features/categories/repository/market-price-index.repository.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Market Price Index — the COMPUTED asking-price band for one leaf.
+ *
+ * The third collection in a deliberate trio, and the three are not
+ * interchangeable:
+ *
+ *   `priceObservations`  one dated sighting          (raw, append-only)
+ *   `marketPriceIndex`   what asks cluster on        (derived, this file)
+ *   `priceIndex`         what SOLD here              (derived, our own orders)
+ *
+ * 🛑 The second and third are never blended, and the rule predates this file:
+ * *"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 is not a sale — 76–93%
+ * of crawled competitor listings are sold out without ever converting — so a
+ * blended figure would describe neither event and could not be unpicked later.
+ *
+ * ## 🛑 Why this is not written onto `categories`
+ *
+ * Same reason as its two siblings, and it is a measured one rather than a
+ * stylistic preference: `onCategoryWrite` is a `documentWritten` trigger on
+ * `categories`, and Root Cause #92 is a trigger that wrote back to the
+ * collection it watched producing **1,017,548 invocations in 24 hours**.
+ * `notifyRevalidate` also fires on every category write, so a nightly band
+ * write would drop each category page's ISR entry on a project that has
+ * already been paused once for ISR-write overage.
+ *
+ * ## 🛑 It does NOT replace the seeded band — it OUTRANKS it
+ *
+ * `CategoryPriceGuidance.market` stays exactly as seeded. A computed band wins
+ * where one exists, and where one does not the seeded generation band still
+ * shows, clearly labelled as the generation's. Overwriting the seed would mean
+ * a single bad import could erase the only evidence ~60 leaves have, with no
+ * way back — the same trap as `priceIndexRollup` being forbidden from touching
+ * `market`.
+ *
+ * @tag domain:price-index
+ * @tag layer:repository
+ * @tag pattern:repository
+ * @tag access:server-only
+ * @tag consumers:marketPriceRollup,price-guidance-resolve,price-index/market
+ * @tag sideEffects:writes marketPriceIndex
+ */
+import { BaseRepository } from "../../../providers/db-firebase";
+import type { PriceObservationKind } from "./price-observation.repository";
+/** One computed band. Mirrors `MarketStats` plus its provenance. */
+export interface MarketPriceBand {
+    /**
+     * The price sightings cluster on — the headline.
+     *
+     * 🛑 Optional, and the renderer must branch. Absent means no bucket held two
+     * or more sightings, i.e. every observed price was different, so there is no
+     * "most common" to report and `median` is shown under a different label. A
+     * mode synthesised from a single sighting would be that sighting wearing a
+     * word that implies consensus.
+     */
+    mode?: number;
+    modeCount?: number;
+    median: number;
+    low: number;
+    high: number;
+    sampleSize: number;
+    /**
+     * 🛑 FALSE means low/high/mode describe ALL TIME, not the last six months —
+     * the window held too little to stand alone. The renderer must relabel. A
+     * figure drawn from a two-year-old crawl is indistinguishable from a current
+     * one once printed, which is why this travels with the band rather than being
+     * inferred from `computedAt`.
+     */
+    basedOnRecent: boolean;
+    windowDays: number;
+    /** Newest sighting in the set the band came from. Not the rollup time. */
+    lastSeenAt: Date;
+}
+export interface MarketPriceIndexDocument {
+    /** The leaf id — model, era, part group, whatever was observed. */
+    id: string;
+    currency: "INR";
+    /**
+     * Bands kept APART by event kind, never merged.
+     *
+     * Keyed by `PriceObservationKind`. `ask` is what shops list at; `sale` is
+     * what we have evidence changed hands at elsewhere. Most leaves will only
+     * ever have `ask`, and that is an honest state rather than a gap.
+     */
+    byKind: Partial<Record<PriceObservationKind, MarketPriceBand>>;
+    computedAt: Date;
+}
+export declare const MARKET_PRICE_INDEX_COLLECTION = "marketPriceIndex";
+export declare class MarketPriceIndexRepository extends BaseRepository<MarketPriceIndexDocument> {
+    constructor();
+    /**
+     * Bands for several leaves in ONE round trip.
+     *
+     * 🛑 `db.getAll`, not N `findById` calls — the same decision, for the same
+     * reason, as `PriceIndexRepository.getManyForLeaves`: the tool resolves up to
+     * `PRICE_INDEX_SEARCH_LIMIT` leaves per lookup and N sequential reads is N
+     * round trips against Rule #6's ~3-per-request budget.
+     *
+     * A missing document is OMITTED, never returned as an empty band — "no
+     * computed band here" and "this leaf does not exist" are different answers,
+     * and a zeroed band renders as a confident ₹0.
+     */
+    getManyForLeaves(leafIds: readonly string[]): Promise<Map<string, MarketPriceIndexDocument>>;
+    /**
+     * Write one leaf's bands.
+     *
+     * `byKind` is replaced WHOLESALE rather than merged: `update` merges, so a
+     * kind whose observations were all retracted would keep its stale band
+     * forever — the same reason `PriceIndexRepository.setForLeaf` passes the full
+     * map rather than a patch.
+     */
+    setForLeaf(leafId: string, byKind: MarketPriceIndexDocument["byKind"]): Promise<void>;
+    /**
+     * Drop a leaf's bands entirely.
+     *
+     * Reachable state, not defensive coding: a leaf whose observations are all
+     * retracted, or all fall below `MIN_BAND_OBSERVATIONS` after a retraction,
+     * must stop publishing a band. Leaving the last computed one in place would
+     * publish a figure derived from evidence that no longer exists.
+     */
+    clearForLeaf(leafId: string): Promise<void>;
+}
+export declare const marketPriceIndexRepository: MarketPriceIndexRepository;

package/dist/features/categories/repository/market-price-index.repository.js

@@ -0,0 +1,105 @@
+/**
+ * Market Price Index — the COMPUTED asking-price band for one leaf.
+ *
+ * The third collection in a deliberate trio, and the three are not
+ * interchangeable:
+ *
+ *   `priceObservations`  one dated sighting          (raw, append-only)
+ *   `marketPriceIndex`   what asks cluster on        (derived, this file)
+ *   `priceIndex`         what SOLD here              (derived, our own orders)
+ *
+ * 🛑 The second and third are never blended, and the rule predates this file:
+ * *"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 is not a sale — 76–93%
+ * of crawled competitor listings are sold out without ever converting — so a
+ * blended figure would describe neither event and could not be unpicked later.
+ *
+ * ## 🛑 Why this is not written onto `categories`
+ *
+ * Same reason as its two siblings, and it is a measured one rather than a
+ * stylistic preference: `onCategoryWrite` is a `documentWritten` trigger on
+ * `categories`, and Root Cause #92 is a trigger that wrote back to the
+ * collection it watched producing **1,017,548 invocations in 24 hours**.
+ * `notifyRevalidate` also fires on every category write, so a nightly band
+ * write would drop each category page's ISR entry on a project that has
+ * already been paused once for ISR-write overage.
+ *
+ * ## 🛑 It does NOT replace the seeded band — it OUTRANKS it
+ *
+ * `CategoryPriceGuidance.market` stays exactly as seeded. A computed band wins
+ * where one exists, and where one does not the seeded generation band still
+ * shows, clearly labelled as the generation's. Overwriting the seed would mean
+ * a single bad import could erase the only evidence ~60 leaves have, with no
+ * way back — the same trap as `priceIndexRollup` being forbidden from touching
+ * `market`.
+ *
+ * @tag domain:price-index
+ * @tag layer:repository
+ * @tag pattern:repository
+ * @tag access:server-only
+ * @tag consumers:marketPriceRollup,price-guidance-resolve,price-index/market
+ * @tag sideEffects:writes marketPriceIndex
+ */
+import { BaseRepository } from "../../../providers/db-firebase/index.js";
+export const MARKET_PRICE_INDEX_COLLECTION = "marketPriceIndex";
+export class MarketPriceIndexRepository extends BaseRepository {
+    constructor() {
+        super(MARKET_PRICE_INDEX_COLLECTION);
+    }
+    /**
+     * Bands for several leaves in ONE round trip.
+     *
+     * 🛑 `db.getAll`, not N `findById` calls — the same decision, for the same
+     * reason, as `PriceIndexRepository.getManyForLeaves`: the tool resolves up to
+     * `PRICE_INDEX_SEARCH_LIMIT` leaves per lookup and N sequential reads is N
+     * round trips against Rule #6's ~3-per-request budget.
+     *
+     * A missing document is OMITTED, never returned as an empty band — "no
+     * computed band here" and "this leaf does not exist" are different answers,
+     * and a zeroed band renders as a confident ₹0.
+     */
+    async getManyForLeaves(leafIds) {
+        const ids = [...new Set(leafIds.filter(Boolean))];
+        const out = new Map();
+        if (ids.length === 0)
+            return out;
+        const refs = ids.map((id) => this.db.collection(MARKET_PRICE_INDEX_COLLECTION).doc(id));
+        const snaps = await this.db.getAll(...refs);
+        for (const snap of snaps) {
+            if (!snap.exists)
+                continue;
+            out.set(snap.id, { ...snap.data(), id: snap.id });
+        }
+        return out;
+    }
+    /**
+     * Write one leaf's bands.
+     *
+     * `byKind` is replaced WHOLESALE rather than merged: `update` merges, so a
+     * kind whose observations were all retracted would keep its stale band
+     * forever — the same reason `PriceIndexRepository.setForLeaf` passes the full
+     * map rather than a patch.
+     */
+    async setForLeaf(leafId, byKind) {
+        const payload = { currency: "INR", byKind, computedAt: new Date() };
+        const existing = await this.findById(leafId);
+        if (existing)
+            await this.update(leafId, payload);
+        else
+            await this.createWithId(leafId, payload);
+    }
+    /**
+     * Drop a leaf's bands entirely.
+     *
+     * Reachable state, not defensive coding: a leaf whose observations are all
+     * retracted, or all fall below `MIN_BAND_OBSERVATIONS` after a retraction,
+     * must stop publishing a band. Leaving the last computed one in place would
+     * publish a figure derived from evidence that no longer exists.
+     */
+    async clearForLeaf(leafId) {
+        const existing = await this.findById(leafId);
+        if (existing)
+            await this.delete(leafId);
+    }
+}
+export const marketPriceIndexRepository = new MarketPriceIndexRepository();

package/dist/features/categories/repository/price-observation.repository.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Price Observations — one DATED sighting of one price for one leaf.
+ *
+ * ## Why this collection has to exist at all
+ *
+ * The competitor crawl of 2026-10 survives only as a summarised markdown table:
+ * p25/median/p75 per GENERATION, and a single `asOf` for the whole thing. That
+ * shape makes three questions permanently unanswerable, and all three were
+ * asked:
+ *
+ *   "most common price"     a mode needs the observations, not a summary of them
+ *   "last six months"       one crawl date cannot yield a window
+ *   "what does THIS bey go  a generation band cannot distinguish Dragoon MS
+ *    for"                   from Strata Dragoon MS — different beys, one number
+ *
+ * None of those is a rendering problem, which is why no amount of relabelling
+ * fixed them. They are the shape of the stored data, and this is that shape
+ * changed: the row is the unit, the summary is derived, and the derivation can
+ * be re-run with a different window whenever the question changes.
+ *
+ * ## 🛑 A sibling collection, never a field on `categories`
+ *
+ * Identical reasoning to `price-index.repository.ts`, and it is not theoretical.
+ * `onCategoryWrite` is a `documentWritten` trigger on `categories`, so a job
+ * writing a band there re-triggers it per document — Root Cause #92's shape,
+ * which produced **1,017,548 invocations in 24 hours** against a 2M/month
+ * allowance and blocked `firebase deploy` with a billing denial. Worse here:
+ * `notifyRevalidate` fires on every category write, so each rolled-up band
+ * would drop that category page's ISR entry, on a project already paused once
+ * for exceeding ISR writes by 15.5×.
+ *
+ * ## 🛑 `sourceKey` is OPAQUE, by instruction
+ *
+ * The owner's requirement is that competitors are not named on the surface. The
+ * honest way to meet that is to not carry the name into the record a renderer
+ * can reach — not to carry it and remember never to print it, which is one
+ * careless `{...row}` away from publishing (Root Cause #70: a public payload
+ * built by spreading a document publishes every field nobody thought to delete).
+ *
+ * So the stored value is a stable opaque key (`src-a`, `src-b`, …). It still
+ * does the two jobs provenance needs — telling two sources apart, and letting
+ * one be re-crawled or retracted wholesale — without the name being present to
+ * leak. The key↔name mapping is operator knowledge, kept out of the database.
+ *
+ * ## Shape
+ *
+ *   priceObservations/{observationId}
+ *
+ * One flat collection, no subcollections. Rows are queried by `categoryId` and
+ * `seenAt` and never listed wholesale, so the composite index
+ * `(categoryId, seenAt desc)` is the only one it needs.
+ *
+ * @tag domain:price-index
+ * @tag layer:repository
+ * @tag pattern:repository
+ * @tag access:server-only
+ * @tag consumers:marketPriceRollup,price-observations CLI
+ * @tag sideEffects:writes priceObservations
+ */
+import { BaseRepository } from "../../../providers/db-firebase";
+/**
+ * What kind of event the sighting was.
+ *
+ * 🛑 The distinction `price-bands.md` is built around: *"a sold-out row proves
+ * the item is GONE, not that it sold at that price"*, with 76–93% of crawled
+ * listings sold out. An ask and a sale are different events and a band that
+ * blends them describes neither — so the kind is recorded per row and the
+ * rollup groups on it rather than averaging across it.
+ */
+export type PriceObservationKind = "ask" | "sale";
+export interface PriceObservationDocument {
+    id: string;
+    /**
+     * The leaf this prices — a MODEL leaf wherever the sighting names a model.
+     *
+     * 🛑 This is the field that makes the whole collection worth building. The
+     * seeded bands hang on ~60 generation leaves, so every one of the 1,904 model
+     * leaves inherits a number measured for its entire era. Recording the model
+     * id is what lets Dragoon MS and Strata Dragoon MS hold different prices,
+     * which they do in the real market.
+     */
+    categoryId: string;
+    /** Decimal rupees, tax-inclusive — `PRICE_GUIDANCE_TAX_BASIS`. */
+    amount: number;
+    currency: "INR";
+    kind: PriceObservationKind;
+    /**
+     * When the price was SEEN, not when the row was written.
+     *
+     * 🛑 These come apart and the gap is the entire point. Back-filling a
+     * two-year-old crawl writes rows today that describe 2024 — using
+     * `createdAt` as the date would file every one of them inside the six-month
+     * window and report stale prices as current, which is the failure this
+     * collection exists to make impossible.
+     */
+    seenAt: Date;
+    /**
+     * `ProductDocument.condition` where the sighting stated one.
+     *
+     * Absent means NOT STATED — never "new". Condition is the dominant price
+     * variable in collectibles (hobson's "Without Box" group runs ₹599 against
+     * ₹4,499 for the same figures boxed), so guessing it would be guessing the
+     * price. Captured now even though the v1 rollup does not slice on it, because
+     * a column nobody recorded cannot be back-filled later.
+     */
+    condition?: string;
+    /** True when the listing was already sold out when seen. */
+    soldOut?: boolean;
+    /** Opaque, stable, never a competitor name. See the header. */
+    sourceKey: string;
+    /** Free-text operator note. Never rendered publicly. */
+    note?: string;
+    createdAt: Date;
+}
+export declare const PRICE_OBSERVATION_COLLECTION = "priceObservations";
+/**
+ * Hard ceiling on one leaf's observation read.
+ *
+ * A leaf with more sightings than this has plenty for a stable band, so the cap
+ * costs no accuracy — it exists so a mis-tagged import cannot turn one rollup
+ * iteration into an unbounded read (Rule #6).
+ */
+export declare const PRICE_OBSERVATION_SCAN_LIMIT = 500;
+export declare class PriceObservationRepository extends BaseRepository<PriceObservationDocument> {
+    constructor();
+    /**
+     * Every sighting for one leaf, newest first, bounded.
+     *
+     * 🛑 Ordered by `seenAt` and NOT filtered by it. The rollup needs both the
+     * recent window and the full history — it decides between them itself
+     * (`computeMarketStats`), because that decision has to be made once, in one
+     * place, or the job and the renderer will disagree about which window a
+     * figure came from. Pushing a date filter down here would make the historic
+     * fallback impossible without a second query.
+     *
+     * 🛑 `orderBy("seenAt")` excludes any document LACKING the field — the
+     * optional-field trap of Root Cause #100, where a store's reviews read as
+     * zero because `itemsSold` had never been written. `seenAt` is required by
+     * the write path below precisely so that exclusion can never bite.
+     */
+    findForLeaf(categoryId: string, limit?: number): Promise<PriceObservationDocument[]>;
+    /**
+     * Every leaf that has at least one observation.
+     *
+     * 🛑 Enumerates the ENTITIES, not the events — Root Cause #102's lesson, from
+     * a reconciler that built its tally from products that exist rather than
+     * categories that exist and so could only ever add. The rollup iterates this
+     * list, so a leaf whose last observation was retracted is still visited and
+     * its stale band cleared.
+     *
+     * `.select()` fetches no field data; only the ids are needed to group.
+     */
+    listLeafIdsWithObservations(scanLimit?: number): Promise<string[]>;
+    /**
+     * Record a sighting.
+     *
+     * 🛑 `seenAt` is required from the caller and is NEVER defaulted to the write
+     * time. `BaseRepository.create` stamps `createdAt` itself — which is why the
+     * two fields exist separately and why this signature cannot accept one in
+     * place of the other. Back-filling an old crawl writes rows today that
+     * describe last year; conflating the two dates would file every one of them
+     * inside the six-month window.
+     */
+    record(input: Omit<PriceObservationDocument, "id" | "createdAt" | "updatedAt" | "currency">): Promise<PriceObservationDocument>;
+}
+export declare const priceObservationRepository: PriceObservationRepository;