@mohasinac/appkit 4.45.0 → 4.46.0

package/dist/features/categories/utils/breadcrumb-chain.js

@@ -0,0 +1,202 @@
+/**
+ * D4b — ONE breadcrumb chain builder, for the category page, the brand page and
+ * the product detail pages.
+ *
+ * 🛑 A `BreadcrumbList` is the one JSON-LD node whose entire value is the ORDER,
+ * and it is now emitted over a 416-node / 5-tier / 39-root forest rather than
+ * the 47-node / 2-tier tree it was written against. Measured 2026-10-12:
+ *
+ *   per tier: t0=39  t1=23  t2=65  t3=71  t4=218
+ *   deepest node -> 7 crumbs:
+ *     Home > Categories > Spinning Tops > Beyblade Burst > Burst Tops > GT
+ *       > Ace Dragon Sting Charge Zan
+ *
+ * Three surfaces render this chain and they must agree, or a crawler and a
+ * visitor are shown different hierarchies for one page — which is worse than
+ * emitting no breadcrumb, because a mismatched `BreadcrumbList` is a
+ * structured-data error against a page that looks fine:
+ *
+ *   1. the visible `BreadcrumbTrail`
+ *   2. this `BreadcrumbList`
+ *   3. `categoryNames[]` on a product — the denormalised display cache
+ *
+ * 🛑 AND THE THIRD IS STORED LEAF-FIRST. Measured:
+ *
+ *     categorySlugs: category-x-basic > category-x-tops > … > category-spinning-tops
+ *     categoryNames: Basic Line > Beyblade X Tops > … > Spinning Tops
+ *
+ * So anything rendering `categoryNames` in stored order shows the trail
+ * BACKWARDS. Every current consumer takes `[0]` — the leaf — which is correct
+ * for a single chip and is exactly why the reversal has never shown up. This
+ * module reverses it once, here, so no call site has to remember.
+ *
+ * 🛑 `ancestors[]` IS THE SOURCE FOR A CATEGORY; `categoryNames`+`categorySlugs`
+ * FOR A PRODUCT. Both `ancestors[]` and `parentIds[]` exist on a category and
+ * describe the same chain — verified equal in length on all 416 live rows — so
+ * neither is wrong, but two owners of one fact is Root Cause #42 waiting. The
+ * choice is `ancestors[]` because it carries the display NAME, so the visible
+ * trail needs no extra read; `parentIds[]` is ids only and stays what the
+ * repository derives `categorySlugs` from.
+ */
+/**
+ * Root → leaf, from a category's `ancestors[]`.
+ *
+ * 🛑 SORTED BY TIER, never taken as stored. An earlier revision of the category
+ * page asserted `ancestors[]` is stored root-first and used it as given; the
+ * visible `BreadcrumbTrail` on that same page had always sorted first, so the
+ * stored order was relied on nowhere. Sorting is the only safe reading, and a
+ * reversed breadcrumb is worse than none.
+ *
+ * 🛑 A BROKEN ANCESTOR IS OMITTED, NOT RENDERED AS A GAP. An entry with no id
+ * or no name cannot be linked or labelled, and emitting `{ name: "" }` puts an
+ * empty crumb in the middle of the trail — which reads as a missing level
+ * rather than as an absent one. `deriveTaxonomy` warns and leaves a chain alone
+ * when a leaf does not resolve (Root Cause #101), so a partial chain is a state
+ * that really occurs. Measured 0 in production today, which is why the branch
+ * needs a test rather than trust.
+ *
+ * A ROOT yields just itself — 39 of the 416 live rows are tier 0 (6 category
+ * roots plus 28 brands and 5 bundles), so this is the common case, not an edge.
+ * The caller's `Home` / `Categories` prefix is what keeps it a valid list.
+ */
+export function categoryCrumbs(input) {
+    const ancestors = (input.ancestors ?? [])
+        .filter((a) => !!a && !!a.id && !!a.name)
+        .slice()
+        .sort((a, b) => (a.tier ?? 0) - (b.tier ?? 0));
+    const out = ancestors.map((a) => ({
+        name: String(a.name),
+        url: input.hrefFor(String(a.id)),
+    }));
+    if (input.name)
+        out.push({ name: input.name, url: input.url });
+    return out;
+}
+/**
+ * Root → leaf, from a product's stored chain.
+ *
+ * 🛑 THE TWO ARRAYS ARE PARALLEL AND MAY DISAGREE IN LENGTH. `deriveTaxonomy`
+ * writes both together, but a row written before it existed — or one whose leaf
+ * did not resolve — can carry a `categorySlugs` with no matching name. Pairing
+ * by index past the shorter array would label one category with another's name,
+ * which is a wrong hierarchy rendered confidently. So the chain stops at the
+ * shorter of the two, and a slug with no name is dropped rather than shown as
+ * its raw id.
+ *
+ * 🛑 A LOT FILES AT A NON-LEAF (G3a), so its chain is genuinely SHORTER and the
+ * last crumb is a line or generation node rather than a named model. That is
+ * correct and must not be padded: fabricating a leaf to fill the final position
+ * would claim the lot is one specific model, which is the same false claim the
+ * filing rule refuses at the write. Nothing here looks at `isLot` — the chain
+ * is simply as long as it is, which is why no special case is needed.
+ */
+export function productCrumbs(input) {
+    const slugs = input.categorySlugs ?? [];
+    const names = input.categoryNames ?? [];
+    const n = Math.min(slugs.length, names.length);
+    const out = [];
+    // Stored leaf-first; reverse ONCE, here, so no call site has to know.
+    for (let i = n - 1; i >= 0; i--) {
+        const slug = slugs[i];
+        const name = names[i];
+        if (!slug || !name)
+            continue;
+        out.push({ name: String(name), url: input.hrefFor(String(slug)) });
+    }
+    return out;
+}
+/**
+ * I5b — 🛑 WHY `productCrumbs` NEEDED NO CHANGE FOR MULTI-ASSIGNMENT, and why
+ * that must be asserted rather than admired.
+ *
+ * A product's `categorySlugs` is now the CLOSURE over every assignment, while
+ * `categoryNames` is the DEFAULT chain only. Pairing by index would be a bug if
+ * the closure were a set — but it is ordered default-chain-first, so
+ * `min(slugs.length, names.length)` clamps to exactly the default chain and the
+ * indices line up. Measured: a 7-entry closure with 5 names yields the 5-crumb
+ * default trail, root-first.
+ *
+ * That is correct BY CONSTRUCTION and it is also fragile-looking, which is the
+ * dangerous combination — someone will eventually "fix" the pairing or make the
+ * closure a set. `verify-breadcrumb-chain.mjs` asserts it so that change fails
+ * loudly instead of silently relabelling a hierarchy.
+ */
+/**
+ * Crumbs to show before the middle collapses behind a dropdown.
+ *
+ * 🛑 A real measurement, not a preference: a tier-4 part leaf is **7 crumbs**
+ * (`Home > Categories > Spinning Tops > Beyblade Metal > Metal Parts >
+ * Performance Tips > Rubber Flat`) and 390px cannot hold it. D4b measured that
+ * depth and never addressed how it wraps.
+ *
+ * 5 keeps `Home`, one collapsed group, and the last two — which is the pattern
+ * every large catalogue converges on, because the last two are the only crumbs
+ * a visitor navigates by.
+ */
+export const TRAIL_COLLAPSE_THRESHOLD = 5;
+/**
+ * Split a trail into lead / collapsed / tail for ONE row of crumbs.
+ *
+ * 🛑 Presentation only. The JSON-LD must still emit the FULL trail — a crawler
+ * never receives a truncated hierarchy just because a phone cannot show it.
+ */
+export function collapseTrail(crumbs, threshold = TRAIL_COLLAPSE_THRESHOLD) {
+    if (crumbs.length <= threshold) {
+        return { lead: [...crumbs], collapsed: [], tail: [] };
+    }
+    return {
+        lead: [crumbs[0]],
+        collapsed: crumbs.slice(1, crumbs.length - 2),
+        tail: crumbs.slice(crumbs.length - 2),
+    };
+}
+/**
+ * The assignments that are NOT the default, as one crumb's worth of links.
+ *
+ * *"if it is less than 3 we can add a single crumb to show them all, for more
+ * than that we can just add a dropdown"* — so ≤2 alternates render inline and
+ * 3 (the maximum, since `MAX_CATEGORY_ASSIGNMENTS` is 4) opens a dropdown.
+ *
+ * 🛑 ONE ROW, never stacked trails. Two rows of crumbs above a product title is
+ * a pattern no competitor in the crawl uses and it costs vertical space above
+ * the fold on a phone.
+ *
+ * 🛑 And the links must be REAL `<a>` elements in the server-rendered DOM, which
+ * is this function's whole reason for returning data rather than a component: a
+ * crawler does not open menus, so alternates injected on open would trade the
+ * SEO this exists for against tidiness.
+ */
+export function alternateAssignments(input) {
+    const ids = input.categoryIds ?? [];
+    const names = input.categoryIdNames ?? [];
+    // Index 0 is the default — it is already the visible trail's last crumb.
+    const items = [];
+    for (let i = 1; i < Math.min(ids.length, names.length); i++) {
+        const id = ids[i];
+        const name = names[i];
+        // A name-less assignment is dropped rather than shown as its raw id, the
+        // same rule `productCrumbs` applies for the same reason.
+        if (!id || !name)
+            continue;
+        items.push({ name: String(name), url: input.hrefFor(String(id)) });
+    }
+    if (items.length === 0)
+        return { mode: "none", items: [] };
+    return { mode: items.length > 2 ? "dropdown" : "inline", items };
+}
+/**
+ * Prepend the two fixed crumbs every trail starts with, and drop the final
+ * crumb's URL.
+ *
+ * The last crumb must not be a link — it is the page you are on, and Google's
+ * own guidance is that the final breadcrumb identifies the current page. Doing
+ * it here rather than at three call sites is what stops one of them forgetting.
+ */
+export function withTrailHead(crumbs, head) {
+    const all = [...head, ...crumbs];
+    if (all.length > 0) {
+        const last = all[all.length - 1];
+        all[all.length - 1] = { name: last.name };
+    }
+    return all;
+}

package/dist/features/corporate/schemas/index.d.ts

@@ -34,9 +34,9 @@ export declare const corporateInquirySchema: z.ZodObject<{
     customBranding: boolean;
     createdAt?: string | undefined;
     phone?: string | undefined;
+    units?: number | undefined;
     adminNote?: string | undefined;
     designation?: string | undefined;
-    units?: number | undefined;
     budgetPerUnit?: number | undefined;
     totalBudget?: number | undefined;
     deliveryDateRequired?: string | undefined;
@@ -48,9 +48,9 @@ export declare const corporateInquirySchema: z.ZodObject<{
     status?: "pending" | "contacted" | "proposal_sent" | "negotiating" | "closed_won" | "closed_lost" | undefined;
     createdAt?: string | undefined;
     phone?: string | undefined;
+    units?: number | undefined;
     adminNote?: string | undefined;
     designation?: string | undefined;
-    units?: number | undefined;
     budgetPerUnit?: number | undefined;
     totalBudget?: number | undefined;
     deliveryDateRequired?: string | undefined;
@@ -78,8 +78,8 @@ export declare const submitCorporateInquirySchema: z.ZodObject<{
     customBranding: boolean;
     message?: string | undefined;
     phone?: string | undefined;
-    designation?: string | undefined;
     units?: number | undefined;
+    designation?: string | undefined;
     budgetPerUnit?: number | undefined;
     totalBudget?: number | undefined;
     deliveryDateRequired?: string | undefined;
@@ -89,8 +89,8 @@ export declare const submitCorporateInquirySchema: z.ZodObject<{
     contactPerson: string;
     message?: string | undefined;
     phone?: string | undefined;
-    designation?: string | undefined;
     units?: number | undefined;
+    designation?: string | undefined;
     budgetPerUnit?: number | undefined;
     totalBudget?: number | undefined;
     deliveryDateRequired?: string | undefined;

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

@@ -212,6 +212,19 @@ export interface OrderDocumentItem {
      * Absent on every order written before this, which is why the rollup keeps
      * its products-map fallback rather than treating absence as a condition.
      */
+    /**
+     * I8 — the category's DISPLAY NAME at order time, beside `categorySlug`.
+     *
+     * 🛑 A slug survives a rename; a NAME does not. `categorySlug` alone lets the
+     * price index band a past sale correctly, which is what it was added for —
+     * but a receipt has to SHOW something, and re-resolving the name at render
+     * time would make a renamed or deleted category change what a past invoice
+     * says. Same reasoning as `hsnCode` / `gstRate` / `finalSale` above: a past
+     * sale's facts are fixed.
+     */
+    categoryName?: string;
+    /** I8 — the brand display name at order time, for the same reason. */
+    brand?: string;
     condition?: string;
     /** SB8-F â€" per-item reveal status; flips through pending â†' open â†' revealed/closed. */
     prizeRevealStatus?: "pending" | "open" | "closed" | "revealed";

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

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