@mohasinac/appkit 4.45.0 → 4.46.0

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;

package/dist/features/parts/utils/part-breakdown.js

@@ -0,0 +1,77 @@
+/**
+ * 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 { PART_SLOT_LABEL } from "../schemas/firestore.js";
+/** The slot name, in ONE place — the endpoint, the formatter and the seeded bodies all key on it. */
+export 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 function formatPartBreakdown(compositions, parts) {
+    // The first composition only. A remake shares a model's name and not its
+    // parts, so concatenating two would describe a bey that does not exist.
+    const comp = compositions[0];
+    const slots = comp?.slots ?? [];
+    if (slots.length === 0)
+        return "";
+    const pieces = slots
+        .map((s) => {
+        const label = PART_SLOT_LABEL[s.slotKey] ?? s.slotKey;
+        const name = (s.partName ?? "").trim();
+        if (!name)
+            return null;
+        const weight = s.weightG ?? (s.partId ? parts?.get(s.partId)?.weightG : undefined);
+        return `${label} — ${name}${typeof weight === "number" ? ` (${weight} g)` : ""}`;
+    })
+        .filter((p) => p !== null);
+    return pieces.join(" · ");
+}
+/**
+ * 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 function stripSlotLine(body, slot) {
+    const needle = `{{${slot}}}`;
+    return body
+        .split("\n")
+        .filter((line) => !line.includes(needle))
+        .join("\n");
+}

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

@@ -9,6 +9,19 @@ export interface ProductDetailPageViewProps {
      * When absent, the component falls back to fetching by slug (backward compat).
      */
     initialProduct?: import("../schemas/firestore").ProductDocument | null;
+    /**
+     * D12 — the part composition for this listing's model, as a ready node.
+     *
+     * 🛑 A NODE, not a document: the composition is a Firestore read and this
+     * component is already at its read budget, so the page resolves it (where
+     * it is already reading the product) and passes the rendered panel down.
+     * Passing the raw documents would make this component read too, and a
+     * second reader of the same data is the drift this codebase keeps closing.
+     *
+     * Absent for every listing that is not filed under a named-model leaf,
+     * which is most of them — the tab then does not render at all.
+     */
+    compositionContent?: React.ReactNode;
     /**
      * Render prop for offer UI. Receives the resolved product fields.
      *
@@ -65,4 +78,4 @@ export interface ProductDetailPageViewProps {
      */
     emiEnabled?: boolean;
 }
-export declare function ProductDetailPageView({ slug, initialProduct, renderOfferAction, renderPrimaryActions, productFeatures, codEnabled, emiEnabled, }: ProductDetailPageViewProps): Promise<import("react").JSX.Element>;
+export declare function ProductDetailPageView({ slug, initialProduct, renderOfferAction, renderPrimaryActions, compositionContent, productFeatures, codEnabled, emiEnabled, }: ProductDetailPageViewProps): Promise<import("react").JSX.Element>;

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

@@ -69,7 +69,7 @@ function StarRating({ value }) {
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-export async function ProductDetailPageView({ slug, initialProduct, renderOfferAction, renderPrimaryActions, productFeatures, codEnabled, emiEnabled, }) {
+export async function ProductDetailPageView({ slug, initialProduct, renderOfferAction, renderPrimaryActions, compositionContent, productFeatures, codEnabled, emiEnabled, }) {
     // Use pre-fetched data when available to avoid a redundant repository call.
     // The page layer wraps getProductForDetail in React.cache(), so both
     // generateMetadata() and this component share the same in-flight promise.
@@ -102,6 +102,25 @@ export async function ProductDetailPageView({ slug, initialProduct, renderOfferA
     const inStock = effectiveStock !== null ? effectiveStock > 0 : p.status === "published";
     const avgRating = typeof p.avgRating === "number" ? p.avgRating : null;
     const reviewCount = typeof p.reviewCount === "number" ? p.reviewCount : null;
+    /*
+     * D8/H2 — real social proof. "N people viewed this in the last week" is a
+     * number we MEASURED, which is what makes it usable: H2's whole boundary is
+     * "use persuasion that is TRUE, refuse persuasion that is FALSE", and
+     * nobody in the fifteen-site crawl shows this despite 76–93% of their
+     * catalogues being sold out.
+     *
+     * 🛑 `typeof === "number"`, not truthiness. `undefined` means the nightly
+     * pass has not rolled this product up yet; `0` means measured and nobody
+     * looked. Rendering "0 people viewed this" is worse than rendering nothing,
+     * and `?? 0` is exactly how the admin Top Products table came to show
+     * "0 views" on every row as though it were a measurement (A5).
+     *
+     * 🛑 And a floor of 2, so a single visitor is never told "1 person viewed
+     * this" — which on a quiet listing is usually them. Below the floor there is
+     * no claim rather than a technically-true one that reads as desperate.
+     */
+    const views7d = typeof p.views7d === "number" ? p.views7d : null;
+    const showViews = views7d !== null && views7d >= 2;
     const category = typeof p.category === "string" ? p.category : null;
     const categoryName = typeof p.categoryName === "string" ? p.categoryName : null;
     // categorySlugs/categoryNames: multi-category support (S-uni-formshell-prep)
@@ -212,7 +231,7 @@ export async function ProductDetailPageView({ slug, initialProduct, renderOfferA
                                                         ? "Refurbished"
                                                         : condition === "used"
                                                             ? "Used"
-                                                            : condition })), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title || "Untitled Product" })] }), avgRating !== null ? (_jsxs(Row, { align: "center", gap: "sm", children: [_jsx(StarRating, { value: avgRating }), _jsxs(Span, { size: "sm", color: "muted", children: [avgRating.toFixed(1), reviewCount ? ` (${reviewCount} reviews)` : ""] }), _jsxs(Span, { size: "xs", weight: "medium", surface: inStock ? "success-surface" : "danger-surface", className: `ml-auto ${inStock ? "text-success" : "text-error"}`, padding: "pill-sm", rounded: "full", children: [inStock ? "✓ In Stock" : "✗ Out of Stock", inStock && effectiveStock !== null && effectiveStock <= 10
+                                                            : condition })), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title || "Untitled Product" })] }), avgRating !== null ? (_jsxs(Row, { align: "center", gap: "sm", children: [_jsx(StarRating, { value: avgRating }), _jsxs(Span, { size: "sm", color: "muted", children: [avgRating.toFixed(1), reviewCount ? ` (${reviewCount} reviews)` : ""] }), showViews && (_jsxs(Span, { size: "sm", color: "muted", children: ["\u00B7 ", views7d.toLocaleString(), " viewed this week"] })), _jsxs(Span, { size: "xs", weight: "medium", surface: inStock ? "success-surface" : "danger-surface", className: `ml-auto ${inStock ? "text-success" : "text-error"}`, padding: "pill-sm", rounded: "full", children: [inStock ? "✓ In Stock" : "✗ Out of Stock", inStock && effectiveStock !== null && effectiveStock <= 10
                                                     ? ` — only ${effectiveStock} left`
                                                     : ""] })] })) : (_jsxs(Span, { layout: "inline-flex", gap: "xs", className: `w-fit .5 ${inStock ? CLS_STOCK_IN : CLS_STOCK_OUT}`, rounded: "full", padding: "pill-md", size: "xs", weight: "medium", children: [inStock ? "✓ In Stock" : "✗ Out of Stock", inStock && effectiveStock !== null && effectiveStock <= 10
                                             ? ` — only ${effectiveStock} left`
@@ -267,7 +286,7 @@ export async function ProductDetailPageView({ slug, initialProduct, renderOfferA
                             ? () => (_jsx(SublistingCarouselSection, { sublistingCategoryId: sublistingCategoryId, currentListingId: String(product.id) }))
                             : undefined, renderGroupSection: groupId
                             ? () => (_jsx(ShowGroupSection, { groupId: groupId, currentSlug: String(p.slug ?? product.id), isParent: isGroupParent, groupTitle: groupTitle }))
-                            : undefined, renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: allSpecs.length > 0 ? (_jsx(Dl, { divide: "subtle", rounded: "xl", border: "subtle", className: "overflow-hidden", children: allSpecs.map((s, i) => (_jsxs(Row, { gap: "md", oddEven: "zebra", surface: "default", padding: "inline", children: [_jsx(Dt, { className: "w-36 flex-shrink-0", color: "primary", weight: "medium", children: s.name }), _jsxs(Dd, { className: "flex-1", color: "muted", children: [s.value, s.unit ? ` ${s.unit}` : ""] })] }, i))) })) : undefined, ingredientsContent: ingredients.length > 0 ? (_jsx(Ul, { spacing: "comfortable", children: ingredients.map((item, i) => (_jsxs(Li, { layout: "flex-start", gap: "2", children: [_jsx(Span, { className: "mt-1 flex-shrink-0 h-1.5 w-1.5 bg-primary-400", rounded: "full" }), item] }, i))) })) : undefined, howToUseContent: howToUse.length > 0 ? (_jsx(Ol, { spacing: "loose", children: howToUse.map((step, i) => (_jsxs(Li, { layout: "flex-start", gap: "3", textSize: "sm", color: "muted", children: [_jsx(Span, { layout: "flex-center", size: "xs", weight: "bold", className: "flex-shrink-0 h-6 w-6 bg-primary-100 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", children: i + 1 }), step] }, i))) })) : undefined, reviewsContent: _jsx(ReviewsListingPanel, { source: { kind: "product", productId: product.id }, stateMode: "local", context: "listing", initialData: initialReviews, emptyLabel: "No reviews yet \u2014 be the first to review this product." }), customTabs: customSections.map((s) => ({
+                            : undefined, renderTabs: () => (_jsx(ProductTabsShell, { partsContent: compositionContent, descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: allSpecs.length > 0 ? (_jsx(Dl, { divide: "subtle", rounded: "xl", border: "subtle", className: "overflow-hidden", children: allSpecs.map((s, i) => (_jsxs(Row, { gap: "md", oddEven: "zebra", surface: "default", padding: "inline", children: [_jsx(Dt, { className: "w-36 flex-shrink-0", color: "primary", weight: "medium", children: s.name }), _jsxs(Dd, { className: "flex-1", color: "muted", children: [s.value, s.unit ? ` ${s.unit}` : ""] })] }, i))) })) : undefined, ingredientsContent: ingredients.length > 0 ? (_jsx(Ul, { spacing: "comfortable", children: ingredients.map((item, i) => (_jsxs(Li, { layout: "flex-start", gap: "2", children: [_jsx(Span, { className: "mt-1 flex-shrink-0 h-1.5 w-1.5 bg-primary-400", rounded: "full" }), item] }, i))) })) : undefined, howToUseContent: howToUse.length > 0 ? (_jsx(Ol, { spacing: "loose", children: howToUse.map((step, i) => (_jsxs(Li, { layout: "flex-start", gap: "3", textSize: "sm", color: "muted", children: [_jsx(Span, { layout: "flex-center", size: "xs", weight: "bold", className: "flex-shrink-0 h-6 w-6 bg-primary-100 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", children: i + 1 }), step] }, i))) })) : undefined, reviewsContent: _jsx(ReviewsListingPanel, { source: { kind: "product", productId: product.id }, stateMode: "local", context: "listing", initialData: initialReviews, emptyLabel: "No reviews yet \u2014 be the first to review this product." }), customTabs: customSections.map((s) => ({
                                 id: s.id,
                                 label: s.title,
                                 content: _jsx(CustomSectionTabContent, { section: s }),

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

@@ -7,6 +7,8 @@ export interface CustomTabDef {
 export interface ProductTabsShellProps {
     descriptionContent?: React.ReactNode;
     specsContent?: React.ReactNode;
+    /** D12 — part composition. Pass non-null to surface the tab. */
+    partsContent?: React.ReactNode;
     /** W1-34 — grading tab content (PSA/BGS/CGC etc). Pass non-null to surface the tab. */
     gradingContent?: React.ReactNode;
     ingredientsContent?: React.ReactNode;
@@ -18,4 +20,4 @@ export interface ProductTabsShellProps {
     customTabs?: CustomTabDef[];
     className?: string;
 }
-export declare function ProductTabsShell({ descriptionContent, specsContent, gradingContent, ingredientsContent, howToUseContent, reviewsContent, qaContent, customTabs, className, }: ProductTabsShellProps): React.JSX.Element | null;
+export declare function ProductTabsShell({ descriptionContent, specsContent, partsContent, gradingContent, ingredientsContent, howToUseContent, reviewsContent, qaContent, customTabs, className, }: ProductTabsShellProps): React.JSX.Element | null;

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

@@ -6,6 +6,8 @@ import { Tabs, TabsList, TabsTrigger } from "../../../ui/components/Tabs.js";
 const STATIC_TABS = [
     { id: "description", label: "Description" },
     { id: "specs", label: "Specifications" },
+    /** D12 — the part composition, when the listing is filed under a named model. */
+    { id: "parts", label: "Parts" },
     { id: "grading", label: "Grading" },
     { id: "ingredients", label: "Ingredients" },
     { id: "howToUse", label: "How to Use" },
@@ -13,10 +15,11 @@ const STATIC_TABS = [
     // W1-34 — Q&A tab; consumers pass `qaContent` to surface it.
     { id: "qa", label: "Q&A" },
 ];
-export function ProductTabsShell({ descriptionContent, specsContent, gradingContent, ingredientsContent, howToUseContent, reviewsContent, qaContent, customTabs = [], className = "", }) {
+export function ProductTabsShell({ descriptionContent, specsContent, partsContent, gradingContent, ingredientsContent, howToUseContent, reviewsContent, qaContent, customTabs = [], className = "", }) {
     const staticContentMap = {
         description: descriptionContent,
         specs: specsContent,
+        parts: partsContent,
         grading: gradingContent,
         ingredients: ingredientsContent,
         howToUse: howToUseContent,

package/dist/features/products/repository/category-assignment.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 🛑 A CAP, because the closure is `array-contains`-indexed and Firestore's
+ * `array-contains-any` takes at most 30 comparison values.
+ *
+ * 4 assignments x 5 tiers (0-4) = 20 closure entries worst case, which leaves
+ * headroom under that 30. It also bounds the index-entry cost: the seed loader
+ * commits at most 20,000 array elements per batch, and every closure entry is
+ * one index entry per product.
+ */
+export declare const MAX_CATEGORY_ASSIGNMENTS = 4;
+/**
+ * 🛑 THE FLIP. `false` = the leaf/non-leaf rule REPORTS; `true` = it refuses.
+ *
+ * It ships `false` and is flipped only once the data is clean, and the reason is
+ * a measurement: **70 of the 71 hand-authored products file at a non-leaf
+ * today** and not one of them is a lot. Enforcing first would make the whole
+ * catalogue unsaveable — and worse, it would make the very seed writes that fix
+ * the data fail, because those also go through `deriveTaxonomy`.
+ *
+ * This is the G3a lesson, which cost a symmetric rule its credibility: the plan
+ * specified "a lot takes a non-leaf while singles take leaves", measurement
+ * rejected the second half, and the half-rule has been live since. The rule is
+ * right; enforcing it before its data is not.
+ *
+ * Flip procedure, and it is a ratchet rather than a judgement call: run
+ * `findLeafRuleOffenders` over every seeded row, confirm **0**, then set `true`.
+ * A hand count is not the measurement — the earlier one said 58 of 70 and this
+ * pass measured 70 of 71.
+ */
+export declare const ENFORCE_LEAF_FILING = false;
+/** A category document, reduced to the fields assignment actually needs. */
+export interface ResolvedCategory {
+    id: string;
+    name?: string;
+    /** The tree this assignment belongs to. Two assignments may not share one. */
+    rootId?: string;
+    /** Depth. Decides the default: deepest wins, because depth is specificity. */
+    tier?: number;
+    /**
+     * 🛑 `undefined` is NOT `false` here. It means `buildCategoryTree` has not
+     * rebuilt the tree, which is a fact about our data rather than about the
+     * caller's input — so it gets its own refusal once enforcement is on.
+     */
+    isLeaf?: boolean;
+    /** Root-first / nearest-last, as `category-tree.ts` writes it. */
+    parentIds: string[];
+    /** Root-first, parallel to `parentIds`. */
+    ancestorNames: string[];
+}
+/**
+ * The authored assignment list, from whichever field the caller used.
+ *
+ * Deliberately tolerant of all three existing shapes, because every one of them
+ * is live today and none should need editing to keep working:
+ *
+ *   - `categoryIds: [a, b]`      the new multi-select
+ *   - `category: "a"`            what `CategoryInlineSelect` writes, and what
+ *                                `productCreateSchema` declares
+ *   - `categorySlugs: [a, ...]`  the seed, and the admin `.passthrough()` route
+ *
+ * 🛑 The scalar still WINS over `categorySlugs`, unchanged from before this
+ * change and for the recorded reason: the seller edit form sends a stale
+ * derived chain alongside a fresh `category`, so preferring the chain resolved
+ * the OLD leaf and wrote it back over the user's choice.
+ *
+ * Duplicates are deduped rather than refused. A duplicate assignment is exactly
+ * equivalent to not having it, so there is no semantic question for the caller
+ * to answer — unlike a duplicate assembly component, which would change
+ * arithmetic.
+ */
+export declare function readAssignments(input: {
+    categoryIds?: string[];
+    category?: string;
+    categorySlugs?: string[];
+}): string[];
+/** Which assignments break the leaf rule, and why. Reporting shape, no throw. */
+export declare function findLeafRuleOffenders(resolved: ResolvedCategory[], isLot: boolean): {
+    id: string;
+    name?: string;
+    reason: "lot-at-leaf" | "single-at-branch" | "not-indexed";
+}[];
+/**
+ * Refuse the shapes that are not allowed. Throws; never corrects.
+ *
+ * 🛑 REFUSED, never corrected — silently dropping a second assignment, or
+ * re-filing one tier up, decides a taxonomy question on the seller's behalf and
+ * leaves them a listing they can no longer find (Root Cause #76 inverted).
+ */
+export declare function assertAssignmentShape(resolved: ResolvedCategory[], isLot: boolean, opts?: {
+    enforceLeafFiling?: boolean;
+    warn?: (msg: string, meta?: object) => void;
+}): void;
+/**
+ * Which assignment owns the breadcrumb, the canonical chain and index 0.
+ *
+ * Three deterministic levels:
+ *   1. the DEEPEST assignment (highest `tier`);
+ *   2. tie -> the highest listing count, which the caller supplies;
+ *   3. still tied -> the order the seller picked.
+ *
+ * 🛑 "Most listings" CANNOT be the first criterion, and this is the one place
+ * the instruction had to be corrected. A franchise node spans every product
+ * type, so `category-beyblade` outranks `category-dragoon-g` on count for
+ * EVERY Beyblade product — which would put `Home > Franchises > Beyblade` above
+ * every listing and silently widen the realised-price band from "Dragoon G" to
+ * "all Beyblade", because that band is keyed on the snapshotted
+ * `categorySlugs[0]`.
+ *
+ * Depth decides because depth IS specificity, which is also the rule singles
+ * are filed by. A model leaf is tier 4 and a franchise leaf is tier 1, so the
+ * tie-break only ever runs between two equally specific assignments — exactly
+ * where "which is busier" is the right question.
+ *
+ * `counts` is consulted ONLY on a tie, so the common single-assignment case
+ * costs no extra read at all.
+ */
+export declare function pickDefaultAssignment(resolved: ResolvedCategory[], counts?: Map<string, number>): number;
+/**
+ * The derived closure and the display names.
+ *
+ * `categorySlugs` = the default chain leaf-first, then each remaining chain
+ * leaf-first, deduped. See the header for why the order is load-bearing.
+ *
+ * `categoryNames` = the DEFAULT chain only. A union has no readable path, and
+ * the breadcrumb builder reverses this array to render root-first — so keeping
+ * it single-chain is what leaves every existing breadcrumb byte-identical.
+ */
+export declare function buildTaxonomyClosure(resolved: ResolvedCategory[], defaultIdx: number): {
+    categorySlugs: string[];
+    categoryNames: string[];
+    categoryIdNames: string[];
+};