@mohasinac/appkit 4.45.0 → 4.47.0

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

package/dist/features/products/repository/category-assignment.js

@@ -0,0 +1,304 @@
+/*
+ * WHY: a product could be filed under exactly ONE category, and the ancestor
+ *      chain was derived onto it. That cannot express "this is a Dragoon G AND
+ *      it is Beyblade" — two independent axes, which is what the franchise root
+ *      exists for. Phase I makes assignment multiple.
+ *
+ * WHAT: the pure half of multi-category assignment — resolve the authored list,
+ *       refuse the two shapes that are not allowed, pick the DEFAULT, and build
+ *       the derived closure. No Firestore, no I/O, so every rule here is
+ *       testable without a database.
+ *
+ * EXPORTS: MAX_CATEGORY_ASSIGNMENTS, ENFORCE_LEAF_FILING, ResolvedCategory,
+ *          readAssignments, assertAssignmentShape, pickDefaultAssignment,
+ *          buildTaxonomyClosure, findLeafRuleOffenders
+ *
+ * ── 🛑 THE CLOSURE IS ORDERED, AND THAT IS NOT COSMETIC ────────────────────
+ *
+ * `categorySlugs[0]` is read as "the leaf" in ~30 places across both repos —
+ * measured, not assumed: the order-item snapshot (`expand-order-items.ts`,
+ * whose own comment says *"`categorySlugs[0]` is the leaf — the chain is stored
+ * self-first"*), BOTH count writers (`category-counts.ts`,
+ * `countersReconcile.ts`), BOTH triggers (`onProductWrite.ts`), eight detail
+ * views, `ProductForm.tsx` x5, the price-index data path,
+ * `listing-adapters.ts`, `productTableColumns.tsx`, `CompareOverlay.tsx`, and
+ * `rewriteProductChains`'s own `current[0]`.
+ *
+ * A set-shaped union of two chains destroys that invariant SILENTLY. Nothing
+ * throws; the order snapshot simply starts recording whichever id happened to
+ * land first, and the realised-price band moves with it. So the closure is
+ * ordered DEFAULT CHAIN FIRST and index 0 stays the default leaf — every one of
+ * those readers remains correct by construction rather than by being found.
+ *
+ * ── 🛑 ONE ASSIGNMENT PER ROOT ─────────────────────────────────────────────
+ *
+ * The user's rule, verbatim: *"a category can be multiple, they should not be
+ * under same tree."* It is also the only rule under which `categoryCounts`'
+ * invariant `own + sum(children.total) === total` still holds: a product
+ * assigned to both an ancestor and its descendant would be counted `own` at the
+ * ancestor AND contribute `total` up from the descendant, so the parent's two
+ * figures would overlap and no invariant could be asserted.
+ *
+ * @tag domain:products
+ * @tag layer:repository
+ * @tag pattern:none
+ * @tag access:server-only
+ * @tag consumers:ProductRepository.deriveTaxonomy
+ * @tag sideEffects:none
+ */
+import { ConflictError, ValidationError } from "../../../errors/index.js";
+/**
+ * 🛑 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 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 const ENFORCE_LEAF_FILING = false;
+/**
+ * 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 function readAssignments(input) {
+    const raw = Array.isArray(input.categoryIds) && input.categoryIds.length > 0
+        ? input.categoryIds
+        : input.category
+            ? [input.category]
+            : Array.isArray(input.categorySlugs) && input.categorySlugs.length > 0
+                ? /*
+                   * Only the HEAD, never the whole array. `categorySlugs` is a derived
+                   * closure: treating its ancestors as assignments would file a product
+                   * at every tier of its own chain, which the one-per-root rule would
+                   * then immediately refuse.
+                   */
+                    [input.categorySlugs[0]]
+                : [];
+    const seen = new Set();
+    const out = [];
+    for (const id of raw) {
+        const trimmed = typeof id === "string" ? id.trim() : "";
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return out;
+}
+/** Which assignments break the leaf rule, and why. Reporting shape, no throw. */
+export function findLeafRuleOffenders(resolved, isLot) {
+    const out = [];
+    for (const c of resolved) {
+        if (isLot) {
+            if (c.isLeaf === true)
+                out.push({ id: c.id, name: c.name, reason: "lot-at-leaf" });
+            continue;
+        }
+        if (c.isLeaf === true)
+            continue;
+        out.push({
+            id: c.id,
+            name: c.name,
+            reason: c.isLeaf === undefined ? "not-indexed" : "single-at-branch",
+        });
+    }
+    return out;
+}
+/**
+ * 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 function assertAssignmentShape(resolved, isLot, opts = {}) {
+    if (resolved.length > MAX_CATEGORY_ASSIGNMENTS) {
+        throw new ValidationError(`A listing can be filed under at most ${MAX_CATEGORY_ASSIGNMENTS} categories; this one names ${resolved.length}.`);
+    }
+    /*
+     * One per root. Grouped on `rootId` rather than on an ancestor walk, because
+     * `rootId` is already on every category document and a walk would cost a read
+     * per assignment on the write path.
+     *
+     * A row with no `rootId` is skipped rather than refused: like `isLeaf`, its
+     * absence means the tree has not been rebuilt, and refusing a write over our
+     * own stale derived field turns a maintenance gap into a seller-facing error.
+     */
+    const byRoot = new Map();
+    for (const c of resolved) {
+        if (!c.rootId)
+            continue;
+        const group = byRoot.get(c.rootId);
+        if (group)
+            group.push(c);
+        else
+            byRoot.set(c.rootId, [c]);
+    }
+    for (const group of byRoot.values()) {
+        if (group.length < 2)
+            continue;
+        const named = group.map((c) => `"${c.name ?? c.id}"`).join(" and ");
+        throw new ValidationError(`${named} are in the same category tree, so a listing cannot be filed under both. ` +
+            `Pick one, or pick the category above them that covers both.`);
+    }
+    const offenders = findLeafRuleOffenders(resolved, isLot);
+    if (offenders.length === 0)
+        return;
+    /*
+     * The lot half has been enforced since G3a and stays enforced regardless of
+     * the flag — it is the half measurement VALIDATED, and the argument is about
+     * the items rather than about counting: filing "12 assorted Burst beys" under
+     * `category-dragoon-g` asserts all twelve are Dragoon G.
+     */
+    const lotAtLeaf = offenders.find((o) => o.reason === "lot-at-leaf");
+    if (lotAtLeaf) {
+        throw new ValidationError(`A lot holds several different items, so it cannot be filed under "${lotAtLeaf.name ?? lotAtLeaf.id}", ` +
+            `which is a single-item category. Pick a broader category — its parent.`);
+    }
+    if (!opts.enforceLeafFiling) {
+        opts.warn?.("Product files at a non-leaf category — allowed today, refused once ENFORCE_LEAF_FILING flips", { offenders });
+        return;
+    }
+    const notIndexed = offenders.find((o) => o.reason === "not-indexed");
+    if (notIndexed) {
+        /*
+         * 409, not 400: the request is well formed and the seller is not confused —
+         * OUR category tree has not been rebuilt, so we cannot tell whether that
+         * node is a leaf. The correct next action is to rebuild the tree, not to
+         * fix a field. Same distinction as removing a booked lottery slot.
+         */
+        throw new ConflictError(`"${notIndexed.name ?? notIndexed.id}" has not been indexed yet, so we cannot tell whether it is a ` +
+            `single-item category. Rebuild the category tree and try again.`);
+    }
+    const first = offenders[0];
+    throw new ValidationError(`"${first.name ?? first.id}" has subcategories, so it describes a group rather than one item. ` +
+        `Pick the specific category this listing belongs to — or mark it as a lot if it holds several different items.`);
+}
+/**
+ * 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 function pickDefaultAssignment(resolved, counts) {
+    if (resolved.length <= 1)
+        return 0;
+    let best = 0;
+    for (let i = 1; i < resolved.length; i += 1) {
+        const a = resolved[i];
+        const b = resolved[best];
+        const tierA = a.tier ?? -1;
+        const tierB = b.tier ?? -1;
+        if (tierA > tierB) {
+            best = i;
+            continue;
+        }
+        if (tierA < tierB)
+            continue;
+        /*
+         * `undefined` is not 0 here either: a category with no counts row has not
+         * been counted, and defaulting it to 0 would let an uncounted node lose a
+         * tie it might have won. Absent on BOTH sides falls through to authored
+         * order, which is level 3.
+         */
+        const countA = counts?.get(a.id);
+        const countB = counts?.get(b.id);
+        if (countA !== undefined && (countB === undefined || countA > countB))
+            best = i;
+    }
+    return best;
+}
+/**
+ * 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 function buildTaxonomyClosure(resolved, defaultIdx) {
+    if (resolved.length === 0) {
+        return { categorySlugs: [], categoryNames: [], categoryIdNames: [] };
+    }
+    const def = resolved[defaultIdx] ?? resolved[0];
+    const ordered = [def, ...resolved.filter((c) => c.id !== def.id)];
+    const categorySlugs = [];
+    const seen = new Set();
+    for (const c of ordered) {
+        // Self first, root last — byte-identical to what the seed hand-writes and
+        // to what `rewriteProductChains` produces. Those three must agree.
+        for (const id of [c.id, ...c.parentIds.slice().reverse()]) {
+            if (!id || seen.has(id))
+                continue;
+            seen.add(id);
+            categorySlugs.push(id);
+        }
+    }
+    const categoryNames = [def.name, ...def.ancestorNames.slice().reverse()].filter((n) => !!n);
+    /*
+     * I5b — one display name per ASSIGNMENT, in the same order, so the breadcrumb
+     * row can offer the other categories as links without a second read on a
+     * cached page. Deliberately NOT their full chains: the alternate crumb shows
+     * the other categories, not N stacked trails.
+     */
+    const categoryIdNames = ordered.map((c) => c.name ?? c.id);
+    return { categorySlugs, categoryNames, categoryIdNames };
+}