@mohasinac/appkit 4.44.0 → 4.46.0

package/dist/features/orders/types/index.d.ts

@@ -65,6 +65,36 @@ export interface OrderItem {
      */
     hsnCode?: string;
     gstRate?: 0 | 5 | 12 | 18 | 28;
+    /**
+     * I8 — the TAXONOMY snapshot, surfaced for the first time.
+     *
+     * 🛑 The third instance of Root Cause #57 in this one adapter. `categorySlug`
+     * has been snapshotted onto the order document since C1, with a recorded
+     * reason — *"a product re-categorised next year must not retroactively move
+     * last year's sale into a band it was never part of"* — and
+     * `orderDocumentToOrder` forwarded 13 fields, none of them this one. So the
+     * data was right on the document and reached no client surface, which is why
+     * no order or invoice page could show a category even though the facts were
+     * there.
+     *
+     * `categoryName` and `brand` are new. A slug survives a rename; a NAME is
+     * what a receipt must show, and re-resolving it at render time would let a
+     * renamed or deleted category change what a past invoice says. Snapshotting
+     * is the whole point: *"the transaction data still keeps it."*
+     */
+    categorySlug?: string;
+    categoryName?: string;
+    brand?: string;
+    /** Snapshotted condition — the price-index band's dominant variable. */
+    condition?: string;
+    /**
+     * The grouped-line keys. `groupOrderItemsByLine` collapses a bundle or a
+     * grouped cart line for the receipt and keys on exactly these, so without
+     * them a client renders N rows where the buyer bought one thing.
+     */
+    groupSlug?: string;
+    groupTitle?: string;
+    groupSource?: "bundle" | "product-group" | "grouped-listing";
 }
 /**
  * One entry on an order's timeline — the client-facing shape of
@@ -201,6 +231,9 @@ export interface Order {
     giftWrapMessage?: string;
     shipmentProtectionAddon?: boolean;
     shipmentProtectionFee?: number;
+    /** Sale protection — the item itself rather than the transit (C5e). */
+    saleProtectionAddon?: boolean;
+    saleProtectionFee?: number;
     /** Buyer-facing platform commission apportioned to this order. */
     platformFee?: number;
     /** COD handling fee, charged only on cash-on-delivery orders. */

package/dist/features/orders/utils/order-splitter.js

@@ -1,5 +1,5 @@
-import { getListingRule, offerRule, auctionRule, } from "../../../_internal/shared/checkout/rules";
-import { CART_LANE, laneOf } from "../../../_internal/shared/checkout/lanes";
+import { getListingRule, offerRule, auctionRule, } from "../../../_internal/shared/checkout/rules/index.js";
+import { CART_LANE, laneOf } from "../../../_internal/shared/checkout/lanes.js";
 /**
  * Split a sequence of cart-items into order groups by `OrderType`.
  *

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

@@ -0,0 +1,107 @@
+/**
+ * D13 — build a complete bey from parts you already hold, or break one down.
+ *
+ * ── 🛑 THE SLOT SET COMES FROM THE MODEL, NOT FROM A FIXED FIELD LIST ──────
+ *
+ * The rows are whatever `modelComposition` says this model's slots are, which
+ * is why the composition had to exist first: an HMS bey has a Running Core
+ * where a Plastic-Gen bey has a separate Spin Gear and Blade Base, and a 4D bey
+ * has a combined bottom. A hard-coded five-row form could not express either.
+ *
+ * When the model has no recorded composition the drawer still works — the
+ * seller adds free rows — because 37 of 259 compositions did not join to a
+ * category and a seller holding those parts should not be blocked by our data
+ * gap.
+ *
+ * ── 🛑 IT SHOWS AVAILABLE, NOT STOCK, AND SAYS WHY ────────────────────────
+ *
+ * The server gates on `availableQuantity`: a component with 10 in stock and 3
+ * reserved has SEVEN assemblable. So the picker shows the available figure and
+ * labels it, because a seller looking at "10 in stock" and being refused at 8
+ * would read that as a bug. The client never decides — it previews what the
+ * server will say.
+ *
+ * ── 🛑 IT IS A `<SectionForm>`, NOT A HAND-ROLLED FORM ────────────────────
+ *
+ * `audit-form-sectionised` caught the first version rendering `FieldSelect` and
+ * `FieldInput` directly, and it was right: a hand-rolled form gets no
+ * `FormShellContext`, so no `aria-invalid` wiring, no error summary, no
+ * jump-to-field and no pinned mobile action bar.
+ *
+ * The slots are DATA (one row per `modelComposition` slot), so
+ * `buildSectionsFromSchema` cannot express them — but `SectionDef.render` can,
+ * and `SectionForm` takes explicit sections. So this is a real adoption rather
+ * than a marker: the dynamic rows live inside one `render` slot and the form
+ * machinery is inherited. A suppression here would have hidden the violation
+ * instead of removing it (Root Cause #22).
+ *
+ * ── 🛑 AND IT REPORTS THE ARITHMETIC AFTERWARDS ───────────────────────────
+ *
+ * The route returns `before` / `after` / `taken` per component, and this
+ * renders all three. A toast reading "built 2" is the shape of silent
+ * wrongness this codebase keeps paying for: it is indistinguishable from a
+ * build that consumed the wrong parts.
+ */
+import React from "react";
+import { type ModelCompositionDocument } from "../schemas/firestore";
+/** A part listing the seller holds, as the picker needs it. */
+export interface AssemblyPartOption {
+    productId: string;
+    title: string;
+    /** 🛑 AVAILABLE, not stock. The server gates on this. */
+    availableQuantity: number;
+    colourway?: string;
+    /** The `partGlossary` id, so a row can be pre-matched to its slot. */
+    partGlossaryId?: string;
+    slotKey?: string;
+}
+export interface AssemblyRow {
+    slotKey: string;
+    slotLabel: string;
+    /** Empty until the seller picks a part listing. */
+    productId: string;
+    quantity: number;
+    /** The part name the composition expects, as a hint. */
+    expectedPartName?: string;
+}
+/** What the route sends when a 409 names a shortfall. */
+export interface AssemblyErrorDetail {
+    code?: string;
+    kind?: "component" | "part-out";
+    productId?: string;
+    needs?: number;
+    has?: number;
+}
+export interface AssemblyOutcome {
+    unitsBuilt: number;
+    consumed: Array<{
+        productId: string;
+        before: number;
+        after: number;
+        taken: number;
+    }>;
+}
+export interface AssemblyDrawerProps {
+    isOpen: boolean;
+    onClose: () => void;
+    direction: "assemble" | "part-out";
+    /** The complete-bey listing being built or broken down. */
+    targetTitle: string;
+    /** Its own available figure — a part-out cannot exceed it. */
+    targetAvailable?: number;
+    /** The model's composition, when one is recorded. */
+    compositions: readonly ModelCompositionDocument[];
+    /** Part listings the seller holds. */
+    options: readonly AssemblyPartOption[];
+    /** Resolves to the route's result, or throws with a readable message. */
+    onSubmit: (input: {
+        direction: "assemble" | "part-out";
+        components: Array<{
+            slotKey: string;
+            productId: string;
+            quantity: number;
+        }>;
+        units: number;
+    }) => Promise<AssemblyOutcome>;
+}
+export declare function AssemblyDrawer({ isOpen, onClose, direction, targetTitle, targetAvailable, compositions, options, onSubmit, }: AssemblyDrawerProps): React.JSX.Element;

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

@@ -0,0 +1,250 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * D13 — build a complete bey from parts you already hold, or break one down.
+ *
+ * ── 🛑 THE SLOT SET COMES FROM THE MODEL, NOT FROM A FIXED FIELD LIST ──────
+ *
+ * The rows are whatever `modelComposition` says this model's slots are, which
+ * is why the composition had to exist first: an HMS bey has a Running Core
+ * where a Plastic-Gen bey has a separate Spin Gear and Blade Base, and a 4D bey
+ * has a combined bottom. A hard-coded five-row form could not express either.
+ *
+ * When the model has no recorded composition the drawer still works — the
+ * seller adds free rows — because 37 of 259 compositions did not join to a
+ * category and a seller holding those parts should not be blocked by our data
+ * gap.
+ *
+ * ── 🛑 IT SHOWS AVAILABLE, NOT STOCK, AND SAYS WHY ────────────────────────
+ *
+ * The server gates on `availableQuantity`: a component with 10 in stock and 3
+ * reserved has SEVEN assemblable. So the picker shows the available figure and
+ * labels it, because a seller looking at "10 in stock" and being refused at 8
+ * would read that as a bug. The client never decides — it previews what the
+ * server will say.
+ *
+ * ── 🛑 IT IS A `<SectionForm>`, NOT A HAND-ROLLED FORM ────────────────────
+ *
+ * `audit-form-sectionised` caught the first version rendering `FieldSelect` and
+ * `FieldInput` directly, and it was right: a hand-rolled form gets no
+ * `FormShellContext`, so no `aria-invalid` wiring, no error summary, no
+ * jump-to-field and no pinned mobile action bar.
+ *
+ * The slots are DATA (one row per `modelComposition` slot), so
+ * `buildSectionsFromSchema` cannot express them — but `SectionDef.render` can,
+ * and `SectionForm` takes explicit sections. So this is a real adoption rather
+ * than a marker: the dynamic rows live inside one `render` slot and the form
+ * machinery is inherited. A suppression here would have hidden the violation
+ * instead of removing it (Root Cause #22).
+ *
+ * ── 🛑 AND IT REPORTS THE ARITHMETIC AFTERWARDS ───────────────────────────
+ *
+ * The route returns `before` / `after` / `taken` per component, and this
+ * renders all three. A toast reading "built 2" is the shape of silent
+ * wrongness this codebase keeps paying for: it is indistinguishable from a
+ * build that consumed the wrong parts.
+ */
+import React from "react";
+import { SideDrawer, Stack, Row, Div, Heading, Text, Button, Badge, FieldInput, FieldSelect, } from "../../../ui/index.js";
+import { SectionForm } from "../../shell/SectionForm.js";
+import { PART_SLOT_LABEL } from "../schemas/firestore.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { trackError, ErrorCategory, ErrorSeverity, } from "../../../monitoring/error-tracking.js";
+const MAX_COMPONENTS = 8;
+/** Rows seeded from the model's own slots, pre-matched where possible. */
+function seedRows(compositions, options) {
+    const slots = compositions[0]?.slots ?? [];
+    if (slots.length === 0) {
+        return [{ slotKey: "", slotLabel: "", productId: "", quantity: 1 }];
+    }
+    return slots.slice(0, MAX_COMPONENTS).map((s) => {
+        /*
+         * Pre-match on the glossary id when the seller's listing declares one —
+         * that is what `partGlossaryId` on a product is FOR. Falls back to nothing
+         * rather than to a name guess: picking the wrong part for the seller is
+         * worse than making them pick.
+         */
+        const hit = s.partId
+            ? options.find((o) => o.partGlossaryId === s.partId && o.availableQuantity > 0)
+            : undefined;
+        return {
+            slotKey: s.slotKey,
+            slotLabel: PART_SLOT_LABEL[s.slotKey] ?? s.slotKey,
+            productId: hit?.productId ?? "",
+            quantity: 1,
+            expectedPartName: s.partName,
+        };
+    });
+}
+export function AssemblyDrawer({ isOpen, onClose, direction, targetTitle, targetAvailable, compositions, options, onSubmit, }) {
+    const isAssemble = direction === "assemble";
+    const [rows, setRows] = React.useState(() => seedRows(compositions, options));
+    const [units, setUnits] = React.useState(1);
+    const [busy, setBusy] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const [outcome, setOutcome] = React.useState(null);
+    // Re-seed when the drawer opens on a different listing.
+    React.useEffect(() => {
+        if (isOpen) {
+            setRows(seedRows(compositions, options));
+            setUnits(1);
+            setError(null);
+            setOutcome(null);
+        }
+    }, [isOpen, compositions, options]);
+    const byId = React.useMemo(() => new Map(options.map((o) => [o.productId, o])), [options]);
+    const filled = rows.filter((r) => r.productId && r.slotKey);
+    /*
+     * 🛑 The SAME duplicate rule the server enforces, previewed rather than
+     * duplicated as a decision: two rows for one product would each be planned
+     * against the same read value and the second would overdraw, so the server
+     * refuses it. Showing that here means the seller sees why before submitting.
+     */
+    const duplicateIds = filled
+        .map((r) => r.productId)
+        .filter((id, i, a) => a.indexOf(id) !== i);
+    const shortfalls = isAssemble
+        ? filled.filter((r) => {
+            const o = byId.get(r.productId);
+            return o ? o.availableQuantity < r.quantity * units : false;
+        })
+        : [];
+    const overPartOut = !isAssemble && typeof targetAvailable === "number" && units > targetAvailable;
+    const blocked = filled.length === 0 ||
+        duplicateIds.length > 0 ||
+        shortfalls.length > 0 ||
+        overPartOut ||
+        busy;
+    const setRow = (i, patch) => setRows((prev) => prev.map((r, j) => (i === j ? { ...r, ...patch } : r)));
+    /**
+     * 🛑 The WORDS are ours; the FIGURES come from the server.
+     *
+     * `audit-raw-error-text` blocks rendering a thrown `.message`, and it is
+     * right: this codebase once rendered a Node require stack inside the
+     * "Place your bid" modal (Root Cause #86). But the one genuinely useful
+     * thing about a 409 here is the NUMBERS, which no constant can carry — so
+     * the server sends `{ needs, has }` as structured data and this composes the
+     * sentence from authored copy around them.
+     *
+     * Anything without that shape falls back to one authored line and never to
+     * server text.
+     */
+    const messageFor = (detail) => {
+        if (detail?.code === "ASSEMBLY_INSUFFICIENT" && typeof detail.needs === "number") {
+            return detail.kind === "part-out"
+                ? `Only ${detail.has} available to part out — you asked for ${detail.needs}.`
+                : `A component is short: it needs ${detail.needs} and ${detail.has} are available. Restock it, or build fewer.`;
+        }
+        return "Could not complete that. Check the components and try again.";
+    };
+    const submit = async () => {
+        setBusy(true);
+        setError(null);
+        try {
+            const result = await onSubmit({
+                direction,
+                components: filled.map((r) => ({
+                    slotKey: r.slotKey,
+                    productId: r.productId,
+                    quantity: r.quantity,
+                })),
+                units,
+            });
+            setOutcome(result);
+        }
+        catch (err) {
+            /*
+             * `normalizeError` first, per Root Cause #31 — and its result is used for
+             * REPORTING only. What the seller reads is composed by `messageFor` from
+             * the structured figures, never from `e.message`.
+             */
+            const e = normalizeError(err);
+            const detail = err && typeof err === "object" && "detail" in err
+                ? (err.detail ?? null)
+                : null;
+            setError(messageFor(detail));
+            // The raw text still reaches the recorder, which is where it belongs.
+            trackError(e.message, ErrorCategory.API, ErrorSeverity.MEDIUM, {
+                component: "AssemblyDrawer",
+                action: direction,
+            });
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    /*
+     * `SectionForm` is value-driven, and the rows are a LIST with add/remove —
+     * which a flat values object cannot express. So the values object carries the
+     * one genuinely scalar field (`units`) and the rows stay in local state,
+     * mutated inside the section's own `render`. Stated rather than worked
+     * around: pretending the list is a value would mean rebuilding it from a
+     * record on every keystroke.
+     */
+    const formValues = React.useMemo(() => ({ units }), [units]);
+    const sections = React.useMemo(() => [
+        {
+            id: "components",
+            label: isAssemble ? "Components to consume" : "Components to receive",
+            required: true,
+            // Media-free, but the rows hold uncommitted picks, so keep it mounted.
+            keepMounted: true,
+            render: () => (_jsxs(Stack, { gap: "sm", className: "min-w-0", children: [rows.map((r, i) => {
+                        const o = r.productId ? byId.get(r.productId) : undefined;
+                        const need = r.quantity * units;
+                        const short = isAssemble && o ? o.availableQuantity < need : false;
+                        return (_jsxs(Stack, { gap: "xs", padding: "sm", surface: "card", rounded: "md", border: "subtle", className: "min-w-0", children: [_jsxs(Row, { justify: "between", align: "center", gap: "sm", className: "min-w-0", children: [_jsx(Text, { size: "xs", color: "muted", transform: "uppercase", children: r.slotLabel || `Component ${i + 1}` }), r.expectedPartName && (_jsxs(Text, { size: "xs", color: "faint", className: "truncate", children: ["expects ", r.expectedPartName] }))] }), _jsx(FieldSelect, { name: `component-${i}`, label: "Part listing", value: r.productId, onChange: (v) => setRow(i, { productId: v }), options: [
+                                        { value: "", label: "— none —" },
+                                        ...options
+                                            .filter((opt) => !isAssemble || opt.availableQuantity > 0)
+                                            .map((opt) => ({
+                                            value: opt.productId,
+                                            // 🛑 "available", spelled out. A bare number reads as
+                                            // stock, and the server gates on available.
+                                            label: `${opt.title}${opt.colourway ? ` · ${opt.colourway}` : ""} — ${opt.availableQuantity} available`,
+                                        })),
+                                    ] }), _jsx(FieldInput, { name: `qty-${i}`, type: "number", label: "Per unit", value: String(r.quantity), onChange: (v) => setRow(i, { quantity: Math.max(1, Number(v) || 1) }) }), short && o && (_jsxs(Text, { size: "xs", color: "error", role: "alert", children: ["Needs ", need, ", ", o.availableQuantity, " available."] }))] }, `${r.slotKey}-${i}`));
+                    }), rows.length < MAX_COMPONENTS && (_jsx(Button, { variant: "ghost", onClick: () => setRows((prev) => [
+                            ...prev,
+                            { slotKey: "", slotLabel: "", productId: "", quantity: 1 },
+                        ]), children: "Add a component" }))] })),
+        },
+        {
+            id: "quantity",
+            label: isAssemble ? "How many to build" : "How many to part out",
+            required: true,
+            render: () => (_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsx(FieldInput, { name: "units", type: "number", label: isAssemble ? "Units to build" : "Units to part out", value: String(units), onChange: (v) => setUnits(Math.max(1, Math.min(99, Number(v) || 1))) }), duplicateIds.length > 0 && (_jsx(Text, { size: "sm", color: "error", role: "alert", children: "The same part is selected twice. Combine it into one row with the total quantity." })), overPartOut && (_jsxs(Text, { size: "sm", color: "error", role: "alert", children: ["Only ", targetAvailable, " available to part out."] })), error && (_jsx(Text, { size: "sm", color: "error", role: "alert", children: error })), blocked && !busy && (_jsx(Text, { size: "xs", color: "muted", children: "Pick at least one component, and clear any shortfall above." }))] })),
+        },
+    ], [
+        rows,
+        units,
+        options,
+        byId,
+        isAssemble,
+        duplicateIds.length,
+        overPartOut,
+        targetAvailable,
+        error,
+        blocked,
+        busy,
+    ]);
+    return (_jsx(SideDrawer, { isOpen: isOpen, onClose: onClose, title: isAssemble ? "Assemble from parts" : "Part out", children: _jsxs(Stack, { gap: "md", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsx(Heading, { level: 3, size: "base", children: targetTitle }), _jsx(Text, { size: "sm", color: "muted", children: isAssemble
+                                ? "Each component's stock goes down; this listing's goes up."
+                                : "This listing's stock goes down; each component's goes up." }), compositions.length === 0 && (_jsx(Text, { size: "xs", color: "muted", children: "We have no recorded part breakdown for this model, so the slots are blank \u2014 fill in what it is actually made of." }))] }), outcome ? (
+                /* ── the arithmetic, not a count ──────────────────────────────── */
+                _jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsxs(Badge, { variant: "success", children: [isAssemble ? "Built" : "Parted out", " ", outcome.unitsBuilt] }), _jsx(Stack, { gap: "xs", className: "min-w-0", children: outcome.consumed.map((c) => (_jsxs(Row, { gap: "sm", align: "center", padding: "inline", surface: "card", rounded: "md", border: "subtle", className: "min-w-0", children: [_jsx(Div, { className: "flex-1 min-w-0", children: _jsx(Text, { size: "sm", color: "primary", className: "truncate", children: byId.get(c.productId)?.title ?? c.productId }) }), _jsxs(Text, { size: "sm", color: "muted", numeric: true, className: "flex-shrink-0", children: [c.before, " \u2192 ", c.after] })] }, c.productId))) }), _jsx(Button, { onClick: onClose, children: "Done" })] })) : (
+                /*
+                 * ONE section holding the dynamic rows. `SectionForm` owns the
+                 * FormShellContext, the error summary and the pinned mobile action
+                 * bar; the rows themselves are data, so they live in `render`.
+                 */
+                _jsx(SectionForm, { sections: sections, values: formValues, onChange: () => {
+                        /*
+                         * The rows are held in local state because they are a LIST with
+                         * add/remove, which a flat values object cannot express. This
+                         * handler exists so `SectionForm`'s contract is satisfied; every
+                         * real mutation goes through `setRow` / `setRows` inside the
+                         * section's own render.
+                         */
+                    }, onSubmit: submit, submitLabel: isAssemble ? "Build" : "Part out", isLoading: busy, onCancel: onClose, cancelLabel: "Cancel" }))] }) }));
+}

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))) }))] }) }) }));
+}