@mohasinac/appkit 4.45.0 → 4.47.0

package/dist/features/categories/utils/breadcrumb-chain.d.ts

@@ -0,0 +1,194 @@
+/**
+ * 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.
+ */
+export interface BreadcrumbCrumb {
+    name: string;
+    /** Absent on the final crumb — the current page is not a link. */
+    url?: string;
+}
+/** The shape `CategoryDocument.ancestors[]` entries have. */
+export interface AncestorLike {
+    id?: string | null;
+    name?: string | null;
+    tier?: number | null;
+}
+export interface CategoryChainInput {
+    /** The category's own display name. */
+    name?: string | null;
+    /** Its own URL. Omitted on the last crumb, so pass it and let the caller decide. */
+    url?: string;
+    ancestors?: readonly AncestorLike[] | null;
+    /** Builds a URL from an ancestor id. */
+    hrefFor: (id: string) => string;
+}
+/**
+ * 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 declare function categoryCrumbs(input: CategoryChainInput): BreadcrumbCrumb[];
+export interface ProductChainInput {
+    /** `[leaf, …ancestors, root]` — the STORED order. */
+    categorySlugs?: readonly string[] | null;
+    /** Parallel to `categorySlugs`, same stored leaf-first order. */
+    categoryNames?: readonly string[] | null;
+    hrefFor: (slug: string) => string;
+}
+/**
+ * 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 declare function productCrumbs(input: ProductChainInput): BreadcrumbCrumb[];
+/**
+ * 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 declare const TRAIL_COLLAPSE_THRESHOLD = 5;
+export interface CollapsedTrail {
+    /** Always the first crumb. Never collapsed — it is the only guaranteed exit. */
+    lead: BreadcrumbCrumb[];
+    /** The middle, to be rendered behind a dropdown. Empty when the trail is short. */
+    collapsed: BreadcrumbCrumb[];
+    /** The last two: the parent you would click, and the page you are on. */
+    tail: BreadcrumbCrumb[];
+}
+/**
+ * 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 declare function collapseTrail(crumbs: readonly BreadcrumbCrumb[], threshold?: number): CollapsedTrail;
+export interface AlternateTrailsInput {
+    /** Every assignment, default first. */
+    categoryIds?: readonly string[] | null;
+    /** One display name per assignment, parallel to `categoryIds`. */
+    categoryIdNames?: readonly string[] | null;
+    hrefFor: (slug: string) => string;
+}
+export interface AlternateTrails {
+    /**
+     * `none` when there is one assignment — which is the overwhelming majority,
+     * and the case that must render EXACTLY as before with no extra crumb and no
+     * post-hydration shift.
+     */
+    mode: "none" | "inline" | "dropdown";
+    items: BreadcrumbCrumb[];
+}
+/**
+ * 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 declare function alternateAssignments(input: AlternateTrailsInput): AlternateTrails;
+/**
+ * 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 declare function withTrailHead(crumbs: readonly BreadcrumbCrumb[], head: readonly BreadcrumbCrumb[]): BreadcrumbCrumb[];

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;