@mohasinac/appkit 4.45.0 → 4.46.0

package/dist/features/parts/components/ModelCompositionPanel.d.ts

@@ -0,0 +1,37 @@
+/**
+ * D12 — what a bey is MADE OF, rendered on its model page and its listings.
+ *
+ * The corpus knows the composition of 259 models down to the slot, with a
+ * per-part weight on 98 of them. Until this existed that data had no reader,
+ * and a buyer reading "Storm Pegasus 105RF" had no way to learn that `105` is
+ * a spin-track height and `RF` is a rubber flat tip.
+ *
+ * ── 🛑 THE SLOT SET IS DATA, AND IT MERGES ─────────────────────────────────
+ *
+ * Nothing here enumerates slots. A `Record<Generation, Slot[]>` cannot express
+ * what the corpus actually contains — `Spin Gear + Blade Base → RUNNING CORE`
+ * (HMS) and `SPIN TRACK + TIP combined: F:D` (4D) — so the rows are whatever
+ * the document carries, in the order it carries them, and `slotMerges` is
+ * rendered as a note rather than being flattened away. A system with a
+ * combined module genuinely has fewer rows, and padding it to a fixed five
+ * would claim a part that does not exist.
+ *
+ * ── 🛑 NO MONEY ON THIS PANEL ──────────────────────────────────────────────
+ *
+ * It renders on a PUBLIC page, so a price here would need `<GatedPrice>` and
+ * would make a server component a client one. A part's own page carries its
+ * listings; this panel carries facts about mouldings. There is nothing to gate
+ * because there is nothing to leak.
+ */
+import React from "react";
+import { type ModelCompositionDocument, type PartGlossaryDocument } from "../schemas/firestore";
+export interface ModelCompositionPanelProps {
+    compositions: readonly ModelCompositionDocument[];
+    /** Glossary rows for the slots' `partId`s, so a row can link and show weight. */
+    parts?: Map<string, PartGlossaryDocument>;
+    /** `(slot, codeOrName)` → the part's page. Supplied by the consumer's route map. */
+    hrefForPart: (slot: string, tail: string) => string;
+    /** Heading level, so this sits correctly inside a tab or a page section. */
+    headingLevel?: 2 | 3 | 4;
+}
+export declare function ModelCompositionPanel({ compositions, parts, hrefForPart, headingLevel, }: ModelCompositionPanelProps): React.JSX.Element | null;

package/dist/features/parts/components/ModelCompositionPanel.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Stack, Row, Div, Heading, Text, Span, TextLink, Badge } from "../../../ui/index.js";
+import { PART_SLOT_LABEL, } from "../schemas/firestore.js";
+/** `performance-tip--rf` → `rf`. The id's tail IS the URL segment. */
+function tailOf(partId) {
+    const i = partId.indexOf("--");
+    return i >= 0 ? partId.slice(i + 2) : partId;
+}
+/**
+ * One slot row.
+ *
+ * Extracted because `audit-code-quality` flagged the inline version at
+ * brace-depth 6, and it was right — "for each composition, for each slot, if
+ * the part resolved, if a weight exists" is four questions in one block, and
+ * the nesting is what hides the two judgements this row actually makes: which
+ * weight wins, and whether the corpus's own slot label adds anything.
+ */
+function SlotRow({ slot, part, hrefForPart, }) {
+    // The slot's own figure wins over the glossary's: a composition records the
+    // weight of the part AS FITTED, and a glossary row records the mould.
+    const weight = slot.weightG ?? part?.weightG;
+    const canonical = PART_SLOT_LABEL[slot.slotKey] ?? slot.slotKey;
+    const showCorpusLabel = Boolean(slot.slotLabel) && slot.slotLabel.toLowerCase() !== canonical.toLowerCase();
+    return (_jsxs(Row, { gap: "md", align: "start", padding: "inline", surface: "card", rounded: "md", border: "subtle", className: "min-w-0", children: [_jsxs(Div, { className: "w-36 flex-shrink-0", children: [_jsx(Text, { size: "xs", color: "muted", transform: "uppercase", children: canonical }), showCorpusLabel && (_jsx(Text, { size: "xs", color: "faint", children: slot.slotLabel }))] }), _jsxs(Div, { className: "flex-1 min-w-0", children: [slot.partId ? (_jsx(TextLink, { href: hrefForPart(slot.slotKey, tailOf(slot.partId)), children: slot.partName })) : (_jsx(Text, { color: "primary", children: slot.partName })), typeof weight === "number" && (_jsxs(Span, { size: "xs", color: "muted", children: [" ", "\u00B7 ", weight, " g"] }))] })] }));
+}
+export function ModelCompositionPanel({ compositions, parts, hrefForPart, headingLevel = 3, }) {
+    if (compositions.length === 0)
+        return null;
+    return (_jsx(Stack, { gap: "lg", className: "min-w-0", children: compositions.map((comp) => {
+            const slots = comp.slots ?? [];
+            const merges = comp.slotMerges ?? [];
+            return (_jsxs(Stack, { gap: "sm", className: "min-w-0", children: [compositions.length > 1 && (_jsx(Heading, { level: headingLevel, children: comp.name })), _jsxs(Row, { gap: "xs", wrap: true, align: "center", className: "min-w-0", children: [comp.system && _jsx(Badge, { variant: "default", children: comp.system }), comp.series && _jsx(Badge, { variant: "default", children: comp.series }), comp.productCode && _jsx(Badge, { variant: "info", children: comp.productCode })] }), slots.length === 0 ? (_jsx(Text, { color: "muted", size: "sm", children: "No part breakdown recorded for this model yet." })) : (_jsx(Stack, { gap: "xs", className: "min-w-0", children: slots.map((s, i) => (_jsx(SlotRow, { slot: s, part: s.partId ? parts?.get(s.partId) : undefined, hrefForPart: hrefForPart }, `${comp.id}-${s.slotKey}-${i}`))) })), merges.length > 0 && (_jsx(Text, { size: "xs", color: "muted", children: merges.map((m, i) => (_jsxs(Span, { children: [i > 0 ? " · " : "", m.merges.map((x) => PART_SLOT_LABEL[x] ?? x).join(" + "), " are one moulded module here (", PART_SLOT_LABEL[m.into] ?? m.into, ")."] }, i))) }))] }, comp.id));
+        }) }));
+}

package/dist/features/parts/components/PartDetailPageView.d.ts

@@ -0,0 +1,48 @@
+/**
+ * D12 — one part's public page.
+ *
+ * The question it answers is *"what does RF mean on a Beyblade"*, which is a
+ * real search with a real answer nobody in the fifteen-site crawl owns. It
+ * also answers the commerce question beside it: raikages is the ONLY source in
+ * the crawl with component-level pricing (energy rings ₹149–249, tips
+ * ₹129–149), and they sell parts without ever explaining them.
+ *
+ * ── 🛑 NO PRICES ON THIS PAGE, DELIBERATELY ────────────────────────────────
+ *
+ * Prices are hidden from signed-out visitors, so every amount on a public
+ * surface needs `<GatedPrice>` — a client component. The listing rows here
+ * carry a title, a condition and a link; the price lives one click away on the
+ * listing itself, where the gate already is. Same rule as `/search`: a row
+ * with nothing to gate has nothing to leak, and this stays a server component.
+ *
+ * ── 🛑 "USED BY" IS A STORED ARRAY, NOT A QUERY ────────────────────────────
+ *
+ * `usedBy` is written by the seed generator, so the model list is one
+ * `getAll` over ids already in hand — no index, no scan, bounded by how many
+ * models really use the part. 681 of 753 parts carry one.
+ */
+import React from "react";
+import { type PartGlossaryDocument, type ModelCompositionDocument } from "../schemas/firestore";
+/** One live listing row. Deliberately money-free — see the header. */
+export interface PartListingRow {
+    id: string;
+    title: string;
+    slug?: string;
+    condition?: string;
+    href: string;
+}
+export interface PartDetailPageViewProps {
+    part: PartGlossaryDocument;
+    /** Models that use it, hydrated from `usedBy`. */
+    usedBy: readonly ModelCompositionDocument[];
+    /** Live listings matching the part, from the shared public product query. */
+    listings: readonly PartListingRow[];
+    /** `total` is a FLOOR when the bounded fetch saturated. */
+    listingsTruncated?: boolean;
+    /** Where "see all listings" goes — a real search, not a fabricated filter. */
+    allListingsHref: string;
+    /** A model's own page, when the composition resolved to a category. */
+    hrefForModel: (categoryId: string) => string;
+    hrefForClassification: (slot: string) => string;
+}
+export declare function PartDetailPageView({ part, usedBy, listings, listingsTruncated, allListingsHref, hrefForModel, hrefForClassification, }: PartDetailPageViewProps): React.JSX.Element;

package/dist/features/parts/components/PartDetailPageView.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Section, Container, Stack, Row, Div, Heading, Text, Span, TextLink, Badge, } from "../../../ui/index.js";
+import { PART_SLOT_LABEL, } from "../schemas/firestore.js";
+export function PartDetailPageView({ part, usedBy, listings, listingsTruncated, allListingsHref, hrefForModel, hrefForClassification, }) {
+    const classification = PART_SLOT_LABEL[part.slot] ?? part.classification ?? part.slot;
+    /*
+     * 🛑 Only 23 of 753 parts carry a code, and that is a fact about the sources
+     * rather than missing data. So the code renders as a badge when present and
+     * nothing stands in for it when absent — an em-dash beside "Code" would
+     * imply we looked it up and found none.
+     */
+    const aliases = (part.aliases ?? []).filter((a) => a && a !== part.name && a !== part.code);
+    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: [_jsx(Text, { size: "sm", color: "muted", children: _jsx(TextLink, { href: hrefForClassification(part.slot), children: classification }) }), _jsx(Heading, { level: 1, children: part.name }), _jsxs(Row, { gap: "xs", wrap: true, align: "center", className: "min-w-0", children: [part.code && _jsx(Badge, { variant: "info", children: part.code }), typeof part.weightG === "number" && (_jsxs(Badge, { variant: "default", children: [part.weightG, " g"] }))] }), aliases.length > 0 && (_jsxs(Text, { size: "sm", color: "muted", children: ["Also written: ", aliases.join(" · ")] }))] }), _jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: usedBy.length > 0
+                                    ? `Used by ${usedBy.length} ${usedBy.length === 1 ? "model" : "models"}`
+                                    : "Used by" }), usedBy.length === 0 ? (_jsx(Text, { color: "muted", size: "sm", children: "No model in our database records this part yet." })) : (_jsx(Stack, { gap: "xs", className: "min-w-0", children: usedBy.map((m) => (_jsxs(Row, { gap: "sm", align: "center", padding: "inline", surface: "card", rounded: "md", border: "subtle", className: "min-w-0", children: [_jsxs(Div, { className: "flex-1 min-w-0", children: [m.categoryId ? (_jsx(TextLink, { href: hrefForModel(m.categoryId), children: m.name })) : (
+                                                /* 49 of 259 compositions did not join to a category.
+                                                   A link to a page that does not exist is worse than
+                                                   plain text, so the name renders unlinked. */
+                                                _jsx(Text, { color: "primary", children: m.name })), m.system && (_jsxs(Span, { size: "xs", color: "muted", children: [" ", "\u00B7 ", m.system] }))] }), m.productCode && (_jsx(Text, { size: "xs", color: "faint", className: "flex-shrink-0", children: m.productCode }))] }, m.id))) }))] }), _jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsxs(Row, { justify: "between", align: "center", wrap: true, gap: "sm", className: "min-w-0", children: [_jsxs(Heading, { level: 2, size: "lg", children: ["Listings", listingsTruncated && (_jsxs(Span, { size: "sm", color: "muted", children: [" ", "(", listings.length, "+)"] }))] }), listings.length > 0 && (_jsx(TextLink, { href: allListingsHref, children: "See all listings \u2192" }))] }), listings.length === 0 ? (_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsx(Text, { color: "muted", size: "sm", children: "Nobody is selling this part right now." }), _jsx(TextLink, { href: allListingsHref, children: "Search the catalogue \u2192" })] })) : (_jsx(Stack, { gap: "xs", className: "min-w-0", children: listings.map((l) => (_jsxs(Div, { surface: "card", padding: "sm", rounded: "md", border: "subtle", className: "min-w-0", children: [_jsx(TextLink, { href: l.href, children: l.title }), l.condition && (_jsx(Text, { size: "xs", color: "muted", children: l.condition }))] }, l.id))) }))] }), part.source && (_jsxs(Text, { size: "xs", color: "faint", children: ["Source: ", part.source] }))] }) }) }));
+}

package/dist/features/parts/components/PartsIndexPageView.d.ts

@@ -0,0 +1,33 @@
+/**
+ * D12 — the parts database index, and one classification's listing.
+ *
+ * ── 🛑 THE INDEX COSTS ZERO FIRESTORE READS ────────────────────────────────
+ *
+ * The 20 classifications come from `ALL_PART_SLOTS` + `PART_SLOT_LABEL`, both
+ * compile-checked, so the index is static. The tempting alternative — showing
+ * a count per classification — is one query per slot, or a 753-document scan,
+ * on a page that exists only to route. Rule #6 budgets ~3 round trips for a
+ * whole render; 20 is not a rounding error.
+ *
+ * A count would also be the thing most likely to be wrong later: it is a
+ * denormalised mirror of a collection the seed rewrites (Root Cause #42), and
+ * the honest version of "we don't know how many" is to not say a number.
+ *
+ * The classification page below DOES read — one equality, bounded at 120,
+ * which clears the largest real bucket (87 attack rings, measured).
+ */
+import React from "react";
+import { type PartGlossaryDocument, type PartSlot } from "../schemas/firestore";
+export interface PartsIndexPageViewProps {
+    hrefForClassification: (slot: string) => string;
+}
+export declare function PartsIndexPageView({ hrefForClassification }: PartsIndexPageViewProps): React.JSX.Element;
+export interface PartClassificationPageViewProps {
+    slot: PartSlot;
+    parts: readonly PartGlossaryDocument[];
+    /** The bounded fetch saturated, so the count renders as a floor. */
+    truncated?: boolean;
+    hrefForPart: (slot: string, tail: string) => string;
+    partsIndexHref: string;
+}
+export declare function PartClassificationPageView({ slot, parts, truncated, hrefForPart, partsIndexHref, }: PartClassificationPageViewProps): React.JSX.Element;

package/dist/features/parts/components/PartsIndexPageView.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Section, Container, Stack, Row, Div, Grid, Heading, Text, Span, TextLink, Badge, } from "../../../ui/index.js";
+import { ALL_PART_SLOTS, PART_SLOT_LABEL, } from "../schemas/firestore.js";
+export function PartsIndexPageView({ hrefForClassification }) {
+    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", children: [_jsx(Heading, { level: 1, children: "Parts database" }), _jsxs(Text, { color: "muted", children: ["Every component we have a record of, by what it is. A code like", " ", _jsx(Span, { weight: "semibold", children: "RF" }), " or ", _jsx(Span, { weight: "semibold", children: "105" }), " means different things in different generations, so parts are grouped by their classification rather than by code."] })] }), _jsx(Grid, { cols: "navTiles", gap: "sm", className: "min-w-0", children: ALL_PART_SLOTS.map((slot) => (_jsx(Div, { surface: "card", padding: "sm", rounded: "md", border: "subtle", className: "min-w-0", children: _jsx(TextLink, { href: hrefForClassification(slot), children: PART_SLOT_LABEL[slot] }) }, slot))) })] }) }) }));
+}
+/** `performance-tip--rf` → `rf`. The id's tail IS the URL segment. */
+function tailOf(partId) {
+    const i = partId.indexOf("--");
+    return i >= 0 ? partId.slice(i + 2) : partId;
+}
+export function PartClassificationPageView({ slot, parts, truncated, hrefForPart, partsIndexHref, }) {
+    const label = PART_SLOT_LABEL[slot] ?? slot;
+    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", children: [_jsx(Text, { size: "sm", color: "muted", children: _jsx(TextLink, { href: partsIndexHref, children: "Parts" }) }), _jsx(Heading, { level: 1, children: label }), _jsx(Text, { color: "muted", size: "sm", children: parts.length === 0
+                                    ? "No parts recorded in this classification yet."
+                                    : `${parts.length}${truncated ? "+" : ""} recorded.` })] }), parts.length > 0 && (_jsx(Stack, { gap: "xs", className: "min-w-0", children: parts.map((p) => (_jsxs(Row, { gap: "sm", align: "center", padding: "inline", surface: "card", rounded: "md", border: "subtle", className: "min-w-0", children: [_jsxs(Div, { className: "flex-1 min-w-0", children: [_jsx(TextLink, { href: hrefForPart(p.slot, tailOf(p.id)), children: p.name }), typeof p.weightG === "number" && (_jsxs(Span, { size: "xs", color: "muted", children: [" ", "\u00B7 ", p.weightG, " g"] }))] }), p.code && (_jsx(Badge, { variant: "info", className: "flex-shrink-0", children: p.code }))] }, p.id))) }))] }) }) }));
+}

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

@@ -0,0 +1,257 @@
+/**
+ * E4/D12 — the PART GLOSSARY and MODEL COMPOSITION collections.
+ *
+ * Seeded from `docs/research/part-composition-2026-10/`, which is extracted
+ * from the local corpus by two committed scripts. Nothing here is hand-typed.
+ *
+ * ── 🛑 KEYED ON (classification, code), NEVER ON THE CODE ALONE ────────────
+ *
+ * `105` is a Metal Fight spin-track height, a bare number in Burst is a disc,
+ * and `1-60` is a Beyblade X ratchet. Code-alone would explain a Burst disc as
+ * a spin track — the same namespacing argument as the feature `group` field,
+ * and the reason the document id carries both halves.
+ *
+ * ── 🛑 WHY `modelComposition` IS A SIBLING, NOT A FIELD ON `categories` ────
+ *
+ * A named model IS a category leaf (section 4.4), so composition "belongs" to that
+ * document — and putting it there is still wrong for two measured reasons.
+ * `handleCategoryWrite` calls `notifyRevalidate` as its FIRST statement,
+ * unconditionally, so any write to a category drops that page's ISR entry on a
+ * project paused at 15.5× its ISR cap. And `CategoryDetailPageView` is already
+ * at Rule #6's read ceiling with seven parallel reads. Same conclusion as
+ * `categoryCounts` and `priceIndex`, for the same reasons.
+ *
+ * ── 🛑 THE SLOT SET IS DATA, KEYED ON `system` ─────────────────────────────
+ *
+ * Slots MERGE: the corpus contains `Spin Gear + Blade Base → RUNNING CORE`
+ * (HMS) and `SPIN TRACK + TIP combined: F:D` (4D), 13 such lines extracted. So
+ * a fixed field-set per generation cannot express the data, and a
+ * `Record<Generation, Slot[]>` would be the hand-written enumeration of Root
+ * Cause #61 with a merge case it structurally cannot hold.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const PART_GLOSSARY_COLLECTION: "partGlossary";
+export declare const MODEL_COMPOSITION_COLLECTION: "modelComposition";
+/**
+ * The canonical slot keys, as extracted. Mirrors `SLOT_VOCAB` in
+ * `scripts/extract-part-composition.mjs` — the script is the source and this
+ * is the type, so a slot that appears in one and not the other is a
+ * compile-visible gap rather than a silent one.
+ */
+export declare const PART_SLOT_VALUES: {
+    readonly BIT_CHIP: "bit-chip";
+    readonly ATTACK_RING: "attack-ring";
+    readonly WEIGHT_DISK: "weight-disk";
+    readonly SPIN_GEAR: "spin-gear";
+    readonly ENGINE_GEAR: "engine-gear";
+    readonly BLADE_BASE: "blade-base";
+    readonly RUNNING_CORE: "running-core";
+    readonly FACE_BOLT: "face-bolt";
+    readonly ENERGY_RING: "energy-ring";
+    readonly FUSION_WHEEL: "fusion-wheel";
+    readonly CHROME_WHEEL: "chrome-wheel";
+    readonly SPIN_TRACK: "spin-track";
+    readonly PERFORMANCE_TIP: "performance-tip";
+    readonly LAYER: "layer";
+    readonly DISC: "disc";
+    readonly DRIVER: "driver";
+    readonly ARMOUR: "armour";
+    readonly BLADE: "blade";
+    readonly RATCHET: "ratchet";
+    readonly BIT: "bit";
+};
+export type PartSlot = (typeof PART_SLOT_VALUES)[keyof typeof PART_SLOT_VALUES];
+/**
+ * Buyer-facing label per slot.
+ *
+ * 🛑 A `Record<PartSlot, string>`, so a 21st slot is a COMPILE ERROR rather
+ * than a page heading that reads `performance-tip`. That is the whole reason
+ * it is not derived by title-casing the key: "Armour" is not "armour"
+ * title-cased in the corpus, and `bit-chip` is "Bit Chip" rather than
+ * "Bit-chip".
+ *
+ * Every label here was read off the live documents' own `classification`
+ * field, not invented — all 20 slots are populated (87 attack rings down to
+ * 4 armour pieces), so none of these is a guess about an empty bucket.
+ */
+export declare const PART_SLOT_LABEL: Record<PartSlot, string>;
+/**
+ * Which CATEGORY node a part of this classification is filed under.
+ *
+ * ── 🛑 A PART IS A PLAIN CATEGORY LEAF, `categoryType` OMITTED ──────────────
+ *
+ * The user's instruction was *"treat parts as also categories, let admins
+ * create or add more of them"*, and this map is how both halves are answered at
+ * once: a part leaf under these nodes gets `deriveTaxonomy`'s ancestor chain,
+ * `countersReconcile`'s tally, the sitemap, breadcrumbs, SEO, an OG image and
+ * **the existing admin category editor** — create, edit and delete included —
+ * for no new code.
+ *
+ * 🛑 `categoryType` is OMITTED rather than given a new `"part"` value, and that
+ * is the decisive design point. 92 files read `categoryType`, and section 4.4
+ * records that `categoryType: "sublisting"` carries SEVEN live defects
+ * precisely because a new discriminator value opts out of every path that
+ * works — `deriveTaxonomy` never reads it, `countersReconcile` leaves its count
+ * permanently 0, and the sitemap excludes it by name. An omitted type changes
+ * none of those 92 files and inherits every one of those paths.
+ *
+ * ── 🛑 KEYED ON THE SLOT ALONE, NOT ON (slot, generation) ───────────────────
+ *
+ * The first version derived a part's generation from its `usedBy` models, which
+ * measured **681 of 753 placeable, 72 unplaceable and 1 spanning two
+ * generations**. That was solving a problem that does not exist: each of the 20
+ * classification names belongs to exactly ONE generation's vocabulary. A
+ * "Performance Tip" is Metal-era by definition, a "Driver" is Burst, a "Bit" is
+ * X and a "Bit Chip" is Plastic Gen — the words are not shared. Keying on the
+ * slot places **all 753** and cannot be wrong about a part whose `usedBy` is
+ * thin.
+ *
+ * A `Record<PartSlot, string>`, so a 21st classification cannot compile without
+ * being given a home — and a part leaf with no parent is a tier-0 orphan, which
+ * is the live defect the store sublisting POST still has.
+ */
+export declare const PART_SLOT_CATEGORY: Record<PartSlot, string>;
+/** Every slot key, for an index page that must not hand-write the list. */
+export declare const ALL_PART_SLOTS: readonly PartSlot[];
+/**
+ * A URL segment to a slot, or `null`.
+ *
+ * 🛑 Returns `null` rather than casting. A bare `as PartSlot` on a URL segment
+ * is how `/parts/nonsense/x` becomes a doc read for `nonsense--x` that quietly
+ * misses — the route must 404, which it can only do if the guard says so.
+ */
+export declare function partSlotFromSegment(segment: string): PartSlot | null;
+/** One part. */
+export interface PartGlossaryDocument extends BaseDocument {
+    /** `${slot}--${codeOrSlug}` — both halves, because a code is not unique. */
+    id: string;
+    /** Buyer-facing label: "Performance Tip", "Fusion Wheel". */
+    classification: string;
+    /** The canonical slot key this classification maps to. */
+    slot: PartSlot;
+    /**
+     * The short code as printed on the part. `null` for a part the corpus knows
+     * only by name.
+     *
+     * 🛑 `null`, not `""`. An empty string reads as a declared empty code; 736
+     * of 759 parts genuinely have no code in any source we hold, and that is a
+     * fact about the sources rather than missing data.
+     */
+    code: string | null;
+    /** The spoken name — what a buyer types. */
+    name: string;
+    /** Grams, when a source confirmed one. 97 of 759 do. */
+    weightG?: number;
+    /**
+     * Model ids that use this part — the single most useful thing a part page
+     * says, and the reason the glossary is worth having as a collection rather
+     * than a lookup table.
+     */
+    usedBy?: string[];
+    /** Code, name and the spoken form of the code — feeds `searchTxt`. */
+    aliases?: string[];
+    /** Which extractor source contributed the row. */
+    source?: string;
+    searchTxt?: string[];
+}
+/** One slot of one model's composition. */
+export interface ModelSlot {
+    slotKey: PartSlot;
+    /** The corpus's own term for the slot, e.g. "METAL ATTACK RING (MAR)". */
+    slotLabel: string;
+    partName: string;
+    weightG?: number;
+    /** The `partGlossary` id, when the part resolved to a glossary row. */
+    partId?: string;
+    /**
+     * I9 — which COLOURWAY of that part this model needs.
+     *
+     * ── 🛑 THE CASE THIS EXISTS FOR, in the user's own words ────────────────
+     *
+     * *"there is a part called metal ball, it comes with 2 beyblades — Poison
+     * Zurafa S130MB and L-Drago Guardian S130MB. But the L-Drago version is very
+     * rare and costly and is in silver, while the Zurafa one is transparent black
+     * with a metal tip. Both behave the same way and have the same design, but to
+     * make an L-Drago bey I need the silver one and for Zurafa the black
+     * transparent one. Same with their S130s."*
+     *
+     * So: ONE glossary row (`performance-tip--mb`), same mould, same weight, same
+     * stats — and TWO physical variants that are NOT interchangeable and differ
+     * wildly in value. No stat distinguishes them.
+     *
+     * ── 🛑 WHY THIS FIELD RATHER THAN MATCHING ON `partId` ALONE ────────────
+     *
+     * The "buildable now" rollup would otherwise report *"you can build an
+     * L-Drago Guardian S130MB"* while the only MB on the shelf is the Zurafa
+     * black. A confident, specific, wrong answer with no error anywhere — and the
+     * seller discovers it holding the wrong part. Matching has to be
+     * `(partId, colourway)`.
+     *
+     * ── 🛑 UNSET MEANS "ANY", AND NEVER "THE FIRST ONE FOUND" ───────────────
+     *
+     * Most slots are genuinely colour-agnostic. Forcing a value everywhere would
+     * invent a constraint the corpus does not support, and defaulting to whatever
+     * happened to be in the bin is the same class of guess the price index
+     * refuses when its sample is too small.
+     */
+    expectedColourway?: string;
+}
+/**
+ * Two slots collapsing into one, in systems where they are a single moulded
+ * module.
+ *
+ * 🛑 This is why the slot set cannot be a per-generation constant: HMS has a
+ * `RUNNING CORE` where Plastic Gen has a separate Spin Gear and Blade Base,
+ * and 4D has a combined `4D Bottom` where MFB has a Spin Track and a tip.
+ */
+export interface ModelSlotMerge {
+    into: PartSlot;
+    merges: PartSlot[];
+}
+export interface ModelCompositionDocument extends BaseDocument {
+    /** The corpus doc id, e.g. `gen2-mfb-big-bang-pegasus`. */
+    id: string;
+    name: string;
+    /** `gen1` … `gen4`, normalised — never the raw freeform header. */
+    generation: string | null;
+    /**
+     * The parenthetical from the raw header, kept because it is often the
+     * interesting part — but never a value anything groups or filters on
+     * (Root Cause #33).
+     */
+    generationNote?: string;
+    system?: string | null;
+    series?: string | null;
+    productCode?: string | null;
+    slots: ModelSlot[];
+    slotMerges?: ModelSlotMerge[];
+    /** The corpus file, so a claim can be traced back. */
+    source?: string;
+    /** The named-model category this composition describes, when one exists. */
+    categoryId?: string;
+    searchTxt?: string[];
+}
+/** `(slot, code|name)` → document id. The ONE place this is composed. */
+export declare function partGlossaryId(slot: PartSlot, codeOrName: string): string;
+/**
+ * Whether a listing of this TYPE is the physical assembly the composition
+ * describes.
+ *
+ * 🛑 Found by measuring rather than by reasoning, and it is a real defect the
+ * first version of D12 shipped: of 71 live products exactly ONE files under a
+ * leaf that has a composition, and that one is
+ * `art-dranzer-phoenix-poster` — so the only listing in the whole catalogue
+ * that got a "Parts" tab was a POSTER, offering an attack ring, a weight disk
+ * and a blade base as its contents. Nothing errored; it rendered a correct
+ * part list for the wrong kind of object.
+ *
+ * The distinction is whether the listing IS the model or merely DEPICTS or
+ * REFERENCES it. A print, a sticker sheet and a redemption code all sit under
+ * the model's leaf on purpose (section 4.4: a sticker sheet belongs beside the
+ * bey it is for) and none of them is made of its parts.
+ *
+ * 🛑 A `Record<ListingType, boolean>`, so a tenth listing type cannot compile
+ * without answering the question — the lesson of Root Cause #61, which this
+ * codebase has paid for ten hand-written enumerations of one union.
+ */
+export declare const LISTING_TYPE_HAS_COMPOSITION: Record<import("../../products/types/index").ListingType, boolean>;

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

@@ -0,0 +1,181 @@
+export const PART_GLOSSARY_COLLECTION = "partGlossary";
+export const MODEL_COMPOSITION_COLLECTION = "modelComposition";
+/**
+ * The canonical slot keys, as extracted. Mirrors `SLOT_VOCAB` in
+ * `scripts/extract-part-composition.mjs` — the script is the source and this
+ * is the type, so a slot that appears in one and not the other is a
+ * compile-visible gap rather than a silent one.
+ */
+export const PART_SLOT_VALUES = {
+    BIT_CHIP: "bit-chip",
+    ATTACK_RING: "attack-ring",
+    WEIGHT_DISK: "weight-disk",
+    SPIN_GEAR: "spin-gear",
+    ENGINE_GEAR: "engine-gear",
+    BLADE_BASE: "blade-base",
+    RUNNING_CORE: "running-core",
+    FACE_BOLT: "face-bolt",
+    ENERGY_RING: "energy-ring",
+    FUSION_WHEEL: "fusion-wheel",
+    CHROME_WHEEL: "chrome-wheel",
+    SPIN_TRACK: "spin-track",
+    PERFORMANCE_TIP: "performance-tip",
+    LAYER: "layer",
+    DISC: "disc",
+    DRIVER: "driver",
+    ARMOUR: "armour",
+    BLADE: "blade",
+    RATCHET: "ratchet",
+    BIT: "bit",
+};
+/**
+ * Buyer-facing label per slot.
+ *
+ * 🛑 A `Record<PartSlot, string>`, so a 21st slot is a COMPILE ERROR rather
+ * than a page heading that reads `performance-tip`. That is the whole reason
+ * it is not derived by title-casing the key: "Armour" is not "armour"
+ * title-cased in the corpus, and `bit-chip` is "Bit Chip" rather than
+ * "Bit-chip".
+ *
+ * Every label here was read off the live documents' own `classification`
+ * field, not invented — all 20 slots are populated (87 attack rings down to
+ * 4 armour pieces), so none of these is a guess about an empty bucket.
+ */
+export const PART_SLOT_LABEL = {
+    "bit-chip": "Bit Chip",
+    "attack-ring": "Attack Ring",
+    "weight-disk": "Weight Disk",
+    "spin-gear": "Spin Gear",
+    "engine-gear": "Engine Gear",
+    "blade-base": "Blade Base",
+    "running-core": "Running Core",
+    "face-bolt": "Face Bolt",
+    "energy-ring": "Energy Ring",
+    "fusion-wheel": "Fusion Wheel",
+    "chrome-wheel": "Chrome Wheel",
+    "spin-track": "Spin Track",
+    "performance-tip": "Performance Tip",
+    layer: "Layer",
+    disc: "Disc",
+    driver: "Driver",
+    armour: "Armour",
+    blade: "Blade",
+    ratchet: "Ratchet",
+    bit: "Bit",
+};
+/**
+ * Which CATEGORY node a part of this classification is filed under.
+ *
+ * ── 🛑 A PART IS A PLAIN CATEGORY LEAF, `categoryType` OMITTED ──────────────
+ *
+ * The user's instruction was *"treat parts as also categories, let admins
+ * create or add more of them"*, and this map is how both halves are answered at
+ * once: a part leaf under these nodes gets `deriveTaxonomy`'s ancestor chain,
+ * `countersReconcile`'s tally, the sitemap, breadcrumbs, SEO, an OG image and
+ * **the existing admin category editor** — create, edit and delete included —
+ * for no new code.
+ *
+ * 🛑 `categoryType` is OMITTED rather than given a new `"part"` value, and that
+ * is the decisive design point. 92 files read `categoryType`, and section 4.4
+ * records that `categoryType: "sublisting"` carries SEVEN live defects
+ * precisely because a new discriminator value opts out of every path that
+ * works — `deriveTaxonomy` never reads it, `countersReconcile` leaves its count
+ * permanently 0, and the sitemap excludes it by name. An omitted type changes
+ * none of those 92 files and inherits every one of those paths.
+ *
+ * ── 🛑 KEYED ON THE SLOT ALONE, NOT ON (slot, generation) ───────────────────
+ *
+ * The first version derived a part's generation from its `usedBy` models, which
+ * measured **681 of 753 placeable, 72 unplaceable and 1 spanning two
+ * generations**. That was solving a problem that does not exist: each of the 20
+ * classification names belongs to exactly ONE generation's vocabulary. A
+ * "Performance Tip" is Metal-era by definition, a "Driver" is Burst, a "Bit" is
+ * X and a "Bit Chip" is Plastic Gen — the words are not shared. Keying on the
+ * slot places **all 753** and cannot be wrong about a part whose `usedBy` is
+ * thin.
+ *
+ * A `Record<PartSlot, string>`, so a 21st classification cannot compile without
+ * being given a home — and a part leaf with no parent is a tier-0 orphan, which
+ * is the live defect the store sublisting POST still has.
+ */
+export const PART_SLOT_CATEGORY = {
+    // Plastic Generation / HMS — Takara, pre-2006.
+    "attack-ring": "category-original-attack-rings",
+    "weight-disk": "category-original-weight-disks",
+    "blade-base": "category-original-blade-bases",
+    "bit-chip": "category-original-bit-chips",
+    "spin-gear": "category-original-spin-gears",
+    "engine-gear": "category-original-engine-gears",
+    "running-core": "category-original-running-cores",
+    // Metal Fight / 4D.
+    "face-bolt": "category-metal-face-bolts",
+    "energy-ring": "category-metal-energy-rings",
+    "fusion-wheel": "category-metal-fusion-wheels",
+    "chrome-wheel": "category-metal-chrome-wheels",
+    "spin-track": "category-metal-spin-tracks",
+    "performance-tip": "category-metal-performance-tips",
+    // Burst.
+    layer: "category-burst-layers",
+    disc: "category-burst-discs",
+    driver: "category-burst-drivers",
+    armour: "category-burst-chips-armour",
+    // Beyblade X.
+    blade: "category-x-blades",
+    ratchet: "category-x-ratchets",
+    bit: "category-x-bits",
+};
+/** Every slot key, for an index page that must not hand-write the list. */
+export const ALL_PART_SLOTS = Object.values(PART_SLOT_VALUES);
+/**
+ * A URL segment to a slot, or `null`.
+ *
+ * 🛑 Returns `null` rather than casting. A bare `as PartSlot` on a URL segment
+ * is how `/parts/nonsense/x` becomes a doc read for `nonsense--x` that quietly
+ * misses — the route must 404, which it can only do if the guard says so.
+ */
+export function partSlotFromSegment(segment) {
+    const hit = ALL_PART_SLOTS.find((s) => s === segment);
+    return hit ?? null;
+}
+/** `(slot, code|name)` → document id. The ONE place this is composed. */
+export function partGlossaryId(slot, codeOrName) {
+    const tail = codeOrName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return `${slot}--${tail}`;
+}
+/**
+ * Whether a listing of this TYPE is the physical assembly the composition
+ * describes.
+ *
+ * 🛑 Found by measuring rather than by reasoning, and it is a real defect the
+ * first version of D12 shipped: of 71 live products exactly ONE files under a
+ * leaf that has a composition, and that one is
+ * `art-dranzer-phoenix-poster` — so the only listing in the whole catalogue
+ * that got a "Parts" tab was a POSTER, offering an attack ring, a weight disk
+ * and a blade base as its contents. Nothing errored; it rendered a correct
+ * part list for the wrong kind of object.
+ *
+ * The distinction is whether the listing IS the model or merely DEPICTS or
+ * REFERENCES it. A print, a sticker sheet and a redemption code all sit under
+ * the model's leaf on purpose (section 4.4: a sticker sheet belongs beside the
+ * bey it is for) and none of them is made of its parts.
+ *
+ * 🛑 A `Record<ListingType, boolean>`, so a tenth listing type cannot compile
+ * without answering the question — the lesson of Root Cause #61, which this
+ * codebase has paid for ten hand-written enumerations of one union.
+ */
+export const LISTING_TYPE_HAS_COMPOSITION = {
+    standard: true,
+    auction: true,
+    "pre-order": true,
+    "prize-draw": true,
+    classified: true,
+    live: true,
+    // Depicts the model; is not the model.
+    art: false,
+    stickers: false,
+    // A redemption code has no physical parts at all.
+    "digital-code": false,
+};