@mohasinac/appkit 4.44.0 → 4.46.0

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,
+};

package/dist/features/parts/utils/colourway-match.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Compare colourways the way a human would type them.
+ *
+ * 🛑 The vocabulary is OPEN-ENDED and seller-entered — deliberately not a
+ * `productFeature`, because that vocabulary is ~169 curated terms in 14 groups
+ * and colourways are per-part, which would give a facet hundreds of single-use
+ * values (the long-tail-tag anti-pattern this project rejected when redeyemerch
+ * was crawled).
+ *
+ * Open-ended means "Transparent Black", "transparent-black" and
+ * "transparent black" are the same colour typed three ways, and a strict `===`
+ * would call a buildable bey unbuildable. Normalising is not a nicety here; it
+ * is the difference between a working rollup and one that reports nothing.
+ */
+export declare function normaliseColourway(value: string | null | undefined): string;
+export interface SlotRequirement {
+    /** The `partGlossary` id the slot needs. */
+    partId?: string;
+    /** The colourway it needs. Absent means ANY colourway will do. */
+    expectedColourway?: string;
+}
+export interface PartHolding {
+    /** The part listing's own product id. */
+    productId: string;
+    partGlossaryId?: string;
+    colourway?: string;
+    /**
+     * 🛑 AVAILABLE, never `stockQuantity`. 10 in stock with 3 reserved is SEVEN
+     * assemblable, and building from the wrong field assembles a bey out of parts
+     * somebody has already bought — A4's bug through a new door.
+     */
+    availableQuantity: number;
+}
+/**
+ * Does this holding satisfy that slot?
+ *
+ * Two rules, and the second is the one that gets written wrong:
+ *
+ *   1. the glossary id must match — a Driver is not a Bit;
+ *   2. the colourway must match **when the slot names one**. 🛑 A slot with no
+ *      `expectedColourway` accepts ANY, including a holding that declares one.
+ *      The reverse — a slot that names a colour accepting a holding that
+ *      declares none — is REFUSED, because "colour unknown" is not evidence of
+ *      the right colour, and this is exactly where a cheerful default produces
+ *      the wrong physical part.
+ */
+export declare function satisfiesSlot(slot: SlotRequirement, holding: PartHolding): boolean;
+export interface SlotMatch {
+    slot: SlotRequirement;
+    /** Every holding that satisfies the slot, richest first. */
+    candidates: PartHolding[];
+    /** How many complete units this slot alone could supply. */
+    buildable: number;
+}
+/**
+ * Match one slot against what a seller holds.
+ *
+ * `buildable` is the SUM across candidates, because two listings of the same
+ * part in the same colourway are two piles of the same thing — a seller with
+ * 2 silver MBs in one listing and 3 in another can build five.
+ */
+export declare function matchSlotToHoldings(slot: SlotRequirement, holdings: readonly PartHolding[]): SlotMatch;

package/dist/features/parts/utils/colourway-match.js

@@ -0,0 +1,98 @@
+/*
+ * WHY: one part code can be two physically different units that are not
+ *      interchangeable. The user's case, and the fixture pair to build first:
+ *
+ *        performance-tip--mb  "Metal Ball"
+ *          -> silver             ships with L-Drago Guardian S130MB (rare, costly)
+ *          -> transparent-black  ships with Poison Zurafa S130MB
+ *
+ *      Same mould, same weight, same stats, same behaviour. To build an L-Drago
+ *      you need the silver one; the black one will not do. Same for their S130
+ *      tracks.
+ *
+ * WHAT: the ONE predicate for "does this part listing satisfy this composition
+ *       slot". Pure, so the case above is assertable without a database.
+ *
+ * EXPORTS: normaliseColourway, satisfiesSlot, matchSlotToHoldings
+ *
+ * ── 🛑 WHY THIS IS A SEPARATE MODULE AND NOT AN INLINE `===` ───────────────
+ *
+ * Because it will be needed in at least three places that must agree — the
+ * "buildable now" rollup, the assembly drawer's per-slot picker, and (once it
+ * bands by colourway) the price index. An inline comparison is Root Cause #75's
+ * shape: the copy made before a rule was added never learns about it, and the
+ * rule here has two non-obvious halves (unset means ANY, and comparison is
+ * normalised).
+ *
+ * @tag domain:parts
+ * @tag layer:util
+ * @tag pattern:none
+ * @tag access:shared
+ * @tag consumers:buildable-now rollup, assembly drawer, priceIndexRollup
+ * @tag sideEffects:none
+ */
+/**
+ * Compare colourways the way a human would type them.
+ *
+ * 🛑 The vocabulary is OPEN-ENDED and seller-entered — deliberately not a
+ * `productFeature`, because that vocabulary is ~169 curated terms in 14 groups
+ * and colourways are per-part, which would give a facet hundreds of single-use
+ * values (the long-tail-tag anti-pattern this project rejected when redeyemerch
+ * was crawled).
+ *
+ * Open-ended means "Transparent Black", "transparent-black" and
+ * "transparent black" are the same colour typed three ways, and a strict `===`
+ * would call a buildable bey unbuildable. Normalising is not a nicety here; it
+ * is the difference between a working rollup and one that reports nothing.
+ */
+export function normaliseColourway(value) {
+    if (!value)
+        return "";
+    return value
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Does this holding satisfy that slot?
+ *
+ * Two rules, and the second is the one that gets written wrong:
+ *
+ *   1. the glossary id must match — a Driver is not a Bit;
+ *   2. the colourway must match **when the slot names one**. 🛑 A slot with no
+ *      `expectedColourway` accepts ANY, including a holding that declares one.
+ *      The reverse — a slot that names a colour accepting a holding that
+ *      declares none — is REFUSED, because "colour unknown" is not evidence of
+ *      the right colour, and this is exactly where a cheerful default produces
+ *      the wrong physical part.
+ */
+export function satisfiesSlot(slot, holding) {
+    if (!slot.partId)
+        return false;
+    if (holding.partGlossaryId !== slot.partId)
+        return false;
+    if (holding.availableQuantity <= 0)
+        return false;
+    const want = normaliseColourway(slot.expectedColourway);
+    if (!want)
+        return true; // the slot is colour-agnostic
+    return normaliseColourway(holding.colourway) === want;
+}
+/**
+ * Match one slot against what a seller holds.
+ *
+ * `buildable` is the SUM across candidates, because two listings of the same
+ * part in the same colourway are two piles of the same thing — a seller with
+ * 2 silver MBs in one listing and 3 in another can build five.
+ */
+export function matchSlotToHoldings(slot, holdings) {
+    const candidates = holdings
+        .filter((h) => satisfiesSlot(slot, h))
+        .sort((a, b) => b.availableQuantity - a.availableQuantity);
+    return {
+        slot,
+        candidates,
+        buildable: candidates.reduce((sum, h) => sum + h.availableQuantity, 0),
+    };
+}

package/dist/features/parts/utils/part-breakdown.d.ts

@@ -0,0 +1,53 @@
+/**
+ * D12 — the `{{partBreakdown}}` description slot.
+ *
+ * A listing filed under a named-model leaf can state what the bey is made of,
+ * from the same `modelComposition` the model page renders. The corpus knows
+ * 259 models down to the slot; before this, a seller's auto-filled description
+ * could say the series and the system and not one part.
+ *
+ * ── 🛑 WHY A SERVER-RESOLVED SLOT AND NOT A CLIENT ONE ─────────────────────
+ *
+ * Every other `{{slot}}` is resolved by the seller form from the draft it is
+ * already holding — title, brand, condition, the category path. A part
+ * breakdown is a Firestore read, so the form cannot compute it, and asking the
+ * form to fetch it would be a second request per category change on a surface
+ * that already makes one. It rides the template endpoint's existing response.
+ *
+ * ── 🛑 ABSENCE REMOVES THE LINE, IT DOES NOT EMPTY IT ──────────────────────
+ *
+ * 49 of 259 compositions did not join to a category, and most of the
+ * catalogue is not a Beyblade at all. `interpolate` resolves an unfilled slot
+ * to an empty string, so a body carrying `<li><strong>Parts:</strong>
+ * {{partBreakdown}}</li>` would render an **empty bullet** on every listing
+ * without a composition — a visible artifact that reads as broken data.
+ *
+ * So the endpoint strips the whole line instead. That is why the strip is
+ * LINE-based rather than element-based: the seeded bodies are template
+ * literals with exactly one `<li>` or `<p>` per source line, which makes
+ * "the line containing the slot" an exact, predictable unit. A body that put
+ * two elements on one line would lose both — stated here rather than guarded
+ * against, because the guard would be a second HTML parser.
+ */
+import { type ModelCompositionDocument, type PartGlossaryDocument } from "../schemas/firestore";
+/** The slot name, in ONE place — the endpoint, the formatter and the seeded bodies all key on it. */
+export declare const PART_BREAKDOWN_SLOT = "partBreakdown";
+/**
+ * `Attack Ring — Metal Attack Ring (19 g) · Weight Disk — CWD Chain Attacker`
+ *
+ * 🛑 ONE LINE, not a `<ul>`. A slot that emits markup breaks the moment a
+ * template author drops it mid-sentence, and a second HTML-shaped slot beside
+ * a plain one is two things that must agree about the same data. One
+ * composable value, usable anywhere.
+ *
+ * Returns `""` when there is nothing to say, which is the signal the caller
+ * uses to strip the line.
+ */
+export declare function formatPartBreakdown(compositions: readonly ModelCompositionDocument[], parts?: Map<string, PartGlossaryDocument>): string;
+/**
+ * Remove the source line that carries `{{slot}}`.
+ *
+ * Used when the slot has no value, so the body arrives without the line rather
+ * than with an empty one. See the header for why this is line-based.
+ */
+export declare function stripSlotLine(body: string, slot: string): string;