@mohasinac/appkit 4.45.0 → 4.47.0

package/dist/features/admin/components/sections/sectionTemplates.js

@@ -0,0 +1,213 @@
+/**
+ * D1 — SECTION templates, each carrying a TYPED builder state.
+ *
+ * 🛑 WHY A TEMPLATE IS NOT A `SectionConfig`, which is the whole design.
+ *
+ * `SectionConfig` is a NON-discriminated union of 25 untagged interfaces — the
+ * tag lives on the parent `HomepageSectionDocument.type` — and
+ * `section-renderer.tsx` narrows it by unchecked cast at every one of its 25
+ * arms (`config as CarouselSectionConfig`). So a template written as a raw
+ * config gets no compile-time checking at all, and `section-renderer`'s silent
+ * `default: return null` means a wrong `type` renders NOTHING rather than
+ * erroring.
+ *
+ * Every section type already has a typed triple —
+ * `DEFAULT_<TYPE>_BUILDER` / `build<Type>Config()` / `parse<Type>Builder()`,
+ * 25 of each. A template declared as a union discriminated on `sectionType`
+ * and carrying the matching `…BuilderState` is therefore checked end to end,
+ * and the config is produced by the existing `build…Config` rather than
+ * hand-written.
+ *
+ * That is not hypothetical. `DEFAULT_FAQ_BUILDER.categories` carried
+ * `["general", "shipping", "returns"]` — **two of the three were values no FAQ
+ * document has ever had** — and collapsing the `FAQCategory` union is what
+ * surfaced it. A typed template is the kind of thing that catches.
+ *
+ * 🛑 NOT a whole-page layout. The plan's earlier `HomepageLayoutRecord` was
+ * replaced for four reasons: applying a page is all-or-nothing and discards
+ * per-row admin edits; sections are already independent documents, so the
+ * section is the natural unit of reuse and the page is not; we do not want any
+ * competitor's homepage wholesale (BAS's 5,540 words is the honest benchmark
+ * while TCI's article-inlining is an anti-pattern, and the SEO leader has the
+ * FEWEST products and words); and `AdminSectionsView` — 2,755 lines with
+ * drag-drop, a 30-deep undo stack and revert-to-server — stays untouched
+ * because a template becomes *create-with-preset*, which is a dropdown and a
+ * spread.
+ *
+ * 🛑 And deliberately NO `siteSettings.homepageLayout`. `homepageSections`
+ * stays the single source of truth for what renders; a second place a section
+ * could come from is how the page and the admin label end up disagreeing with
+ * no way to tell which lied.
+ */
+import { DEFAULT_CATEGORIES_BUILDER, DEFAULT_TRUST_INDICATORS_BUILDER, DEFAULT_FAQ_BUILDER, DEFAULT_BLOG_BUILDER, DEFAULT_PRODUCTS_BUILDER, DEFAULT_CUSTOM_CARDS_BUILDER, } from "./adminSectionsTypes.js";
+export const COMPETITOR_PROFILES = [
+    {
+        id: "worldhobbyshop",
+        label: "worldhobbyshop.in",
+        platform: "WooCommerce",
+        measured: {
+            products: 1195,
+            soldOutShare: 0.885,
+            medianPrice: 899,
+            homepageWords: 1816,
+            uniqueInternalLinks: 79,
+            jsonLdTypes: 8,
+        },
+        takeaway: "The SEO leader of the fifteen, and it has the FEWEST products and words on its homepage — 8 product cards and one rail. Its advantage is taxonomy routing (6 generation tiles plus a 25-link systems matrix) and a 10-question FAQ, not merchandising volume.",
+    },
+    {
+        id: "beybladeartshop",
+        label: "beybladeartshop.com",
+        platform: "Shopify",
+        measured: {
+            products: 1914,
+            soldOutShare: 0.811,
+            medianPrice: 1599,
+            homepageWords: 5540,
+            uniqueInternalLinks: 57,
+            jsonLdTypes: 3,
+        },
+        takeaway: "The honest benchmark for curated homepage copy at 5,540 words, and the best product prose of the fifteen (2,814 descriptions, median 346 chars). Runs anti-counterfeit copy as hero slide 5.",
+    },
+    {
+        id: "toycollectorsindia",
+        label: "toycollectorsindia.com",
+        platform: "Shopify",
+        measured: {
+            products: 15014,
+            soldOutShare: 0.87,
+            medianPrice: 899,
+            homepageWords: 7430,
+            uniqueInternalLinks: null,
+            jsonLdTypes: 4,
+        },
+        takeaway: "🛑 The word-count leader is NOT the benchmark: 3,926 of its 7,430 words are four blog posts inlined whole, duplicating its own canonical URLs. Strip those and it sits below BAS. It IS the checkout-breadth benchmark — three gateways, gift wrap, compare, express checkout.",
+    },
+    {
+        id: "tcgindia",
+        label: "tcgindia.in",
+        platform: "custom Next.js",
+        measured: {
+            products: 272,
+            soldOutShare: 0,
+            medianPrice: null,
+            homepageWords: null,
+            uniqueInternalLinks: null,
+            jsonLdTypes: 9,
+        },
+        takeaway: "The best SEO architecture of the fifteen — 15 city landing pages, a game→set hierarchy, 28 rules posts, and a per-product FAQPage. Nobody else emits per-product FAQ markup.",
+    },
+];
+/**
+ * The shipped templates.
+ *
+ * 🛑 Each one is a shape the crawl MEASURED, not a guess — and each is an
+ * independent pick. We want WHS's generation tiles, BAS's trust strip and
+ * their FAQ density separately, which is exactly what per-section templating
+ * allows and a whole-page layout does not.
+ */
+export const SECTION_TEMPLATES = [
+    {
+        id: "categories-generation-tiles",
+        label: "Shop by generation (worldhobbyshop)",
+        sectionType: "categories",
+        sourceProfileId: "worldhobbyshop",
+        notes: "Taxonomy routing, not merchandising — WHS's single biggest SEO asset. Six tiles, no autoscroll: a tile grid is a navigation aid and a moving one is harder to use, not more engaging.",
+        builder: {
+            ...DEFAULT_CATEGORIES_BUILDER,
+            title: "Shop by generation",
+            viewMoreLabel: "All categories →",
+            maxCategories: 6,
+            autoScroll: false,
+            loop: false,
+        },
+    },
+    {
+        id: "trust-strip-four",
+        label: "Four-item trust strip (beybladeartshop)",
+        sectionType: "trust-indicators",
+        sourceProfileId: "beybladeartshop",
+        notes: "BAS's hero strip. Each item is a claim this platform can actually keep — the fourth is authenticity, which is the one competitors with no labelling system cannot say.",
+        builder: {
+            ...DEFAULT_TRUST_INDICATORS_BUILDER,
+            title: "",
+            indicators: [
+                { id: "trust-originals", icon: "shield-check", title: "Authenticity, labelled", description: "Original, reproduction or unverified on every listing — never a silent claim." },
+                { id: "trust-escrow", icon: "lock", title: "Money held until delivery", description: "We hold payment in escrow, so a claim pays from funds we already have." },
+                { id: "trust-india", icon: "truck", title: "India-wide shipping", description: "Delhivery, Blue Dart, DTDC and India Post, with tracking on every order." },
+                { id: "trust-rare", icon: "search", title: "Rare and pre-owned", description: "Four generations of Beyblade, including the lines that are long out of production." },
+            ],
+        },
+    },
+    {
+        id: "faq-ten-question",
+        label: "Ten-question FAQ (worldhobbyshop)",
+        sectionType: "faq",
+        sourceProfileId: "worldhobbyshop",
+        notes: "The densest single SEO win on the page and an answer-engine surface — it feeds faqJsonLd. 🛑 `categories` is left EMPTY on purpose: it is only a fallback TAB list, and a hand-written one drifts out from under the priority-ordered slice, which is how all three homepage FAQ tabs came to render empty panels.",
+        builder: {
+            ...DEFAULT_FAQ_BUILDER,
+            title: "Frequently Asked Questions",
+            subtitle: "The questions new buyers ask most.",
+            displayCount: 10,
+            showOnHomepage: true,
+            linkToFullPage: true,
+            viewMoreLabel: "View all FAQs →",
+            categories: [],
+        },
+    },
+    {
+        id: "blog-four-excerpts",
+        label: "Four article excerpts (beybladeartshop)",
+        sectionType: "blog-articles",
+        sourceProfileId: "beybladeartshop",
+        notes: "🛑 EXCERPTS, never bodies. toycollectorsindia inlines 3,926 words of full article text into its homepage, duplicating its own canonical blog URLs — which is why its 7,430-word homepage is not the benchmark and BAS's 5,540 is.",
+        builder: {
+            ...DEFAULT_BLOG_BUILDER,
+            title: "From the collector blog",
+            viewMoreLabel: "All articles →",
+            maxArticles: 4,
+            showReadTime: true,
+            showAuthor: true,
+            showThumbnails: true,
+        },
+    },
+    {
+        id: "products-recently-added",
+        label: "One 'recently added' rail (worldhobbyshop)",
+        sectionType: "products",
+        sourceProfileId: "worldhobbyshop",
+        notes: "WHS runs exactly ONE product rail on the page and leads the fifteen on SEO. The temptation is four rails; the evidence says one, with the taxonomy tiles doing the routing.",
+        builder: {
+            ...DEFAULT_PRODUCTS_BUILDER,
+            title: "Recently added",
+            viewMoreLabel: "Browse everything →",
+            maxItems: 8,
+            status: "published",
+            featuredOnly: false,
+            inStockOnly: true,
+            autoScroll: false,
+        },
+    },
+    {
+        id: "custom-cards-systems-matrix",
+        label: "Systems matrix — 29 internal links (worldhobbyshop)",
+        sectionType: "custom-cards",
+        sourceProfileId: "worldhobbyshop",
+        notes: "Most of why WHS has 79 unique internal links against BAS's 57. 🛑 `custom-cards`, NOT `collection-cards` — the latter caps at COLLECTION_CARDS_MAX_ENTRIES = 3 and its entries are live-content queries, so it cannot express a link matrix at all. Fill the cards from the real category ids; `audit-section-config-links` fails the build on a dead one.",
+        builder: {
+            ...DEFAULT_CUSTOM_CARDS_BUILDER,
+            title: "Every system, every part family",
+        },
+    },
+];
+/** Templates offered for one section type — empty when none is shipped. */
+export function templatesForType(type) {
+    return SECTION_TEMPLATES.filter((t) => t.sectionType === type);
+}
+export function templateById(id) {
+    return SECTION_TEMPLATES.find((t) => t.id === id);
+}
+export function profileById(id) {
+    return id ? COMPETITOR_PROFILES.find((p) => p.id === id) : undefined;
+}

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

@@ -236,6 +236,21 @@ export interface SiteSettingsIntegrations {
     googleAnalyticsId?: string;
     facebookPixelId?: string;
     gtmContainerId?: string;
+    /**
+     * D7b — Microsoft Clarity. Free session recording and heatmaps; two of the
+     * fifteen crawled competitors run it and we run nothing.
+     *
+     * It is the only way to answer empirically what section 10.4 currently argues
+     * from contrast ratios alone: whether the 13px/15px type and the borders that
+     * measure 1.22:1 against the page actually cost conversions, and where forms
+     * are abandoned.
+     *
+     * 🛑 Clarity RECORDS SESSIONS, and this site has no consent gate of any kind
+     * — not for GA, GTM or Pixel either. So it ships with `content: false`
+     * (strict masking: no text, no input values), and a real consent gate is its
+     * own follow-up because it would have to cover all four.
+     */
+    clarityProjectId?: string;
 }
 /** Admin-tunable platform caps. Enforced server-side; not buyer-facing. */
 export interface SiteSettingsPlatformLimits {

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

@@ -37,7 +37,6 @@ export interface AnalyticsTopProduct {
     title: string;
     revenue: number;
     orders: number;
-    viewCount?: number;
     mainImage?: string;
 }
 export interface AnalyticsSummary {

package/dist/features/auth/permissions/constants.d.ts

@@ -37,7 +37,7 @@ export type Permission = "admin:dashboard:view" | "admin:users:read" | "admin:us
  * mechanism — and revoking it is a permission change, which the admin audit
  * log already records.
  */
- | "tester:admin-surfaces" | "admin:events:read" | "admin:events:write" | "admin:events:delete" | "admin:event-entries:read" | "admin:event-entries:write" | "admin:support-tickets:read" | "admin:support-tickets:write" | "admin:shipments:read" | "admin:shipments:write" | "admin:catalogue:read" | "admin:catalogue:write" | "admin:grouped-listings:read" | "admin:grouped-listings:write" | "admin:support-tickets:assign" | "admin:support-tickets:close" | "admin:scammers:read" | "admin:scammers:write" | "admin:scammers:verify" | "admin:scammers:delete" | "admin:sessions:read" | "admin:sessions:delete" | "admin:notifications:read" | "admin:notifications:write" | "admin:carts:read" | "admin:wishlists:read" | "admin:feature-flags:read" | "admin:feature-flags:write" | "admin:copilot:view" | "admin:team:read" | "admin:team:write" | "admin:maintenance:view-server-errors" | "admin:maintenance:view-client-errors" | "admin:maintenance:view-function-errors" | "admin:maintenance:view-cloud-logs" | "admin:maintenance:view-payment-rollbacks" | "admin:maintenance:run-analysis" | "admin:maintenance:purge-errors";
+ | "tester:admin-surfaces" | "admin:events:read" | "admin:events:write" | "admin:events:delete" | "admin:event-entries:read" | "admin:event-entries:write" | "admin:support-tickets:read" | "admin:support-tickets:write" | "admin:shipments:read" | "admin:shipments:write" | "admin:catalogue:read" | "admin:catalogue:write" | "admin:grouped-listings:read" | "admin:grouped-listings:write" | "admin:support-tickets:assign" | "admin:support-tickets:close" | "admin:scammers:read" | "admin:scammers:write" | "admin:scammers:verify" | "admin:scammers:delete" | "admin:sessions:read" | "admin:sessions:delete" | "admin:notifications:read" | "admin:notifications:write" | "admin:carts:read" | "admin:wishlists:read" | "admin:feature-flags:read" | "admin:feature-flags:write" | "admin:team:read" | "admin:team:write" | "admin:maintenance:view-server-errors" | "admin:maintenance:view-client-errors" | "admin:maintenance:view-function-errors" | "admin:maintenance:view-cloud-logs" | "admin:maintenance:view-payment-rollbacks" | "admin:maintenance:run-analysis" | "admin:maintenance:purge-errors";
 /**
  * Granular user actions that can be soft-banned individually.
  * A user may have multiple simultaneous soft bans of different types.

package/dist/features/auth/permissions/constants.js

@@ -309,7 +309,6 @@ export const ROUTE_PERMISSION_MAP = {
     "/admin/carts": "admin:carts:read",
     "/admin/wishlists": "admin:wishlists:read",
     "/admin/feature-flags": "admin:feature-flags:read",
-    "/admin/copilot": "admin:copilot:view",
     "/admin/team": "admin:team:read",
     // Maintenance & Observability (workstream 10)
     "/admin/maintenance": "admin:maintenance:view-server-errors",
@@ -383,7 +382,6 @@ export const PERMISSION_DOMAINS = [
     },
     { label: "Events", prefix: "admin:events:|admin:event-entries:" },
     { label: "Support & Safety", prefix: "admin:support-tickets:|admin:scammers:" },
-    { label: "System", prefix: "admin:sessions:|admin:notifications:|admin:carts:|admin:wishlists:|admin:feature-flags:|admin:copilot:|admin:team:" },
 ];
 /** True when `perm` starts with any of the `|`-separated prefixes in `prefix`. */
 export function matchesDomain(perm, prefix) {

package/dist/features/categories/api/[id]/description-template/route.js

@@ -50,6 +50,8 @@ import { serverLogger } from "../../../../../monitoring/index.js";
  */
 import { categoriesRepository } from "../../../repository/categories.repository.js";
 import { usedPlaceholders } from "../../../../../_internal/shared/templating/placeholders.js";
+import { getCompositionsForCategory } from "../../../../../_internal/server/features/parts/data.js";
+import { PART_BREAKDOWN_SLOT, formatPartBreakdown, stripSlotLine, } from "../../../../parts/utils/part-breakdown.js";
 /**
  * The variants a caller may ask for.
  *
@@ -224,12 +226,49 @@ export async function GET(request, context) {
          * reaches a published description.
          */
         const placeholders = template ? usedPlaceholders(template.body) : [];
+        /*
+         * ── D12: the `{{partBreakdown}}` slot ──────────────────────────────────
+         *
+         * 🛑 READ ONLY IF THE BODY ASKS FOR IT. Nothing outside the Beyblade lines
+         * carries the slot, so this is a third read on roughly a fifth of the
+         * tree and zero reads everywhere else — a TCG set or a Hot Wheels casting
+         * pays nothing for a concept it does not have.
+         *
+         * 🛑 Resolved against the LEAF, never an ancestor. A composition describes
+         * one model; inheriting a line's would hand every Burst GT listing the
+         * parts of whichever model happened to join to the line node.
+         *
+         * 🛑 And when there is none, the LINE IS STRIPPED rather than left to
+         * interpolate to an empty string — otherwise a listing with no recorded
+         * composition renders an empty "Parts:" bullet, which reads as broken
+         * data rather than as absent data.
+         *
+         * Safe on a `public` cache: part names, slots and weights are facts about
+         * mouldings. No money, no seller identity, nothing gated.
+         */
+        let body = template?.body ?? "";
+        const slots = {};
+        if (template && placeholders.includes(PART_BREAKDOWN_SLOT)) {
+            const compositions = await getCompositionsForCategory(id);
+            const breakdown = formatPartBreakdown(compositions);
+            if (breakdown)
+                slots[PART_BREAKDOWN_SLOT] = breakdown;
+            else
+                body = stripSlotLine(body, PART_BREAKDOWN_SLOT);
+        }
         return NextResponse.json({
             success: true,
             data: {
                 template: template
-                    ? { ...template, placeholders }
+                    ? { ...template, body, placeholders: usedPlaceholders(body) }
                     : null,
+                /**
+                 * Slot values the CLIENT cannot compute, merged UNDER the form's own
+                 * context so a draft-derived value always wins — the two key spaces
+                 * are disjoint today and this is what keeps them safe if they stop
+                 * being.
+                 */
+                slots,
                 /** Null when the template came from the category itself. */
                 inheritedFrom,
                 inheritedFromName,

package/dist/features/categories/components/BrandDetailPageView.js

@@ -10,6 +10,7 @@ import { MediaImage } from "../../media/MediaImage.js";
 import { BrandDetailTabs } from "./BrandDetailTabs.js";
 import { CategoryGrid } from "./CategoryGrid.js";
 import { CategoryHighlightsAndFaqSection } from "./CategoryHighlightsAndFaqSection.js";
+import { categoryCrumbs, withTrailHead } from "../utils/breadcrumb-chain.js";
 import { breadcrumbJsonLd, collectionPageJsonLd, faqJsonLd, } from "../../../seo/json-ld.js";
 import { GroupedListingsCarousel } from "../../grouped/components/GroupedListingsCarousel.js";
 import { getGroupsForBrand } from "../../../_internal/server/features/grouped/data.js";
@@ -118,11 +119,21 @@ export async function BrandDetailPageView({ slug, initialBrand }) {
      * Costs no extra read: `brand`, `counts` and `faqs` are already in hand.
      */
     const brandPath = String(ROUTES.PUBLIC.BRAND_DETAIL(slug));
-    const ldBreadcrumb = breadcrumbJsonLd([
+    /*
+     * A brand is FLAT — tier 0, no ancestors, so the chain is genuinely three
+     * crumbs and `categoryCrumbs` returns just the brand itself. Routed through
+     * the shared builder anyway, so the last-crumb rule (no self-link) is applied
+     * once for every surface rather than remembered three times.
+     */
+    const ldBreadcrumb = breadcrumbJsonLd(withTrailHead(categoryCrumbs({
+        name: brand?.name ?? "Brand",
+        url: brandPath,
+        ancestors: brand?.ancestors,
+        hrefFor: (id) => String(ROUTES.PUBLIC.BRAND_DETAIL(id)),
+    }), [
         { name: "Home", url: "/" },
         { name: "Brands", url: String(ROUTES.PUBLIC.BRANDS) },
-        { name: brand?.name ?? "Brand", url: brandPath },
-    ]);
+    ]));
     /*
      * 🛑 No `items`, deliberately. A brand page's contents are the brand's
      * PRODUCTS, and an `ItemList` of products without prices is the weaker half

package/dist/features/categories/components/BreadcrumbTrail.d.ts

@@ -28,6 +28,29 @@ export interface BreadcrumbTrailProps {
      */
     showCurrent?: boolean;
     className?: string;
+    /**
+     * I5b — collapse the middle of a long trail behind a dropdown.
+     *
+     * 🛑 Needed independently of multi-assignment: a tier-4 part leaf is SEVEN
+     * crumbs (`All 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.
+     *
+     * Defaults ON, because the only trails long enough to collapse are the ones
+     * that already overflow.
+     */
+    collapse?: boolean;
+    /**
+     * I5b — the OTHER categories this listing is filed under, as one extra crumb.
+     *
+     * Pass `categoryIds`/`categoryIdNames` straight through from the product;
+     * `alternateAssignments` decides inline-vs-dropdown and returns nothing at
+     * all for a single assignment, which is the overwhelming majority.
+     */
+    alternates?: {
+        ids?: readonly string[] | null;
+        names?: readonly string[] | null;
+    };
 }
 /**
  * BreadcrumbTrail — a category-aware breadcrumb component.
@@ -45,4 +68,4 @@ export interface BreadcrumbTrailProps {
  * />
  * ```
  */
-export declare function BreadcrumbTrail({ category, rootLabel, rootHref, basePath, showCurrent, className, }: BreadcrumbTrailProps): React.JSX.Element;
+export declare function BreadcrumbTrail({ category, rootLabel, rootHref, basePath, showCurrent, className, collapse, alternates, }: BreadcrumbTrailProps): React.JSX.Element;

package/dist/features/categories/components/BreadcrumbTrail.js

@@ -1,6 +1,10 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React from "react";
 import { Breadcrumb } from "../../../ui/index.js";
+import { Text } from "../../../ui/components/Typography.js";
+import { TextLink } from "../../../ui/components/TextLink.js";
 import { ROUTES } from "../../../next/routing/route-map.js";
+import { alternateAssignments, collapseTrail } from "../utils/breadcrumb-chain.js";
 /**
  * BreadcrumbTrail — a category-aware breadcrumb component.
  *
@@ -17,8 +21,8 @@ import { ROUTES } from "../../../next/routing/route-map.js";
  * />
  * ```
  */
-export function BreadcrumbTrail({ category, rootLabel = "All Categories", rootHref = String(ROUTES.PUBLIC.CATEGORIES), basePath = String(ROUTES.PUBLIC.CATEGORIES), showCurrent = true, className, }) {
-    const items = [
+export function BreadcrumbTrail({ category, rootLabel = "All Categories", rootHref = String(ROUTES.PUBLIC.CATEGORIES), basePath = String(ROUTES.PUBLIC.CATEGORIES), showCurrent = true, className, collapse = true, alternates, }) {
+    const full = [
         // Root
         { label: rootLabel, href: rootHref },
         // Ancestors (sorted by tier ascending so root → leaf order)
@@ -32,5 +36,42 @@ export function BreadcrumbTrail({ category, rootLabel = "All Categories", rootHr
         // Current category (no href so it renders as the active item)
         ...(showCurrent ? [{ label: category.name }] : []),
     ];
-    return _jsx(Breadcrumb, { items: items, className: className });
+    /*
+     * I5b — the alternates become ONE extra crumb, never a second row. Two rows
+     * of crumbs above a title is a pattern no competitor in the crawl uses and it
+     * costs vertical space above the fold on a phone.
+     */
+    const alt = alternateAssignments({
+        categoryIds: alternates?.ids ?? null,
+        categoryIdNames: alternates?.names ?? null,
+        hrefFor: (slug) => `${basePath}/${slug}`,
+    });
+    /*
+     * 🛑 Collapsing is PRESENTATION. The JSON-LD is emitted elsewhere, from the
+     * full chain, and must stay that way — a crawler never receives a truncated
+     * hierarchy because a phone could not show it.
+     */
+    const split = collapse ? collapseTrail(toCrumbs(full)) : null;
+    const items = split && split.collapsed.length > 0
+        ? [
+            ...split.lead.map(fromCrumb),
+            /*
+             * The collapsed group as ONE crumb whose label names what it hides.
+             * 🛑 Rendered as a real crumb with no href rather than a menu,
+             * because `Breadcrumb` is a plain list primitive — and the hidden
+             * ancestors are still reachable: every one of them is an ancestor of
+             * the crumbs either side, so no path is lost, only shortened.
+             */
+            { label: `… ${split.collapsed.length} more` },
+            ...split.tail.map(fromCrumb),
+        ]
+        : full;
+    return (_jsxs(_Fragment, { children: [_jsx(Breadcrumb, { items: items, className: className }), alt.mode !== "none" && (_jsxs(Text, { size: "xs", color: "muted", children: ["Also in", " ", alt.items.map((a, i) => (_jsxs(React.Fragment, { children: [i > 0 && " · ", _jsx(TextLink, { href: a.url ?? "#", children: a.name })] }, a.url ?? a.name)))] }))] }));
+}
+/** `BreadcrumbItem` ⇄ `BreadcrumbCrumb` — two names for one shape. */
+function toCrumbs(items) {
+    return items.map((i) => ({ name: i.label, url: i.href }));
+}
+function fromCrumb(c) {
+    return c.url ? { label: c.name, href: c.url } : { label: c.name };
 }

package/dist/features/categories/components/CategoryDetailPageView.js

@@ -1,15 +1,19 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { Row, SIEVE_OP, sieveAnd, sieveFilter } from "@mohasinac/appkit";
 import { sortBy } from "@mohasinac/appkit";
+import { categoryCrumbs, withTrailHead } from "../utils/breadcrumb-chain.js";
+import { ownTotalFor, descendantTotalFor } from "../schemas/category-counts.js";
 import Link from "next/link.js";
 import { categoriesRepository, productRepository, storeRepository, } from "../../../repositories/index.js";
-import { ROUTES } from "../../../next/routing/route-map.js";
-import { Container, Div, Heading, Main, Nav, Section, Span, Text } from "../../../ui/index.js";
+import { Container, Div, Heading, Main, Nav, Section, Span, Stack, Text } from "../../../ui/index.js";
 import { MediaImage } from "../../media/MediaImage.js";
 import { CategoryDetailTabs } from "./CategoryDetailTabs.js";
 import { CategoryGrid } from "./CategoryGrid.js";
 import { CategoryHighlightsAndFaqSection } from "./CategoryHighlightsAndFaqSection.js";
 import { GroupedListingsCarousel } from "../../grouped/components/GroupedListingsCarousel.js";
+import { ModelCompositionPanel } from "../../parts/components/ModelCompositionPanel.js";
+import { getCompositionsForCategory } from "../../../_internal/server/features/parts/data.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
 import { getGroupsForCategory } from "../../../_internal/server/features/grouped/data.js";
 import { listingTabCounts, } from "../../../_internal/server/features/products/listing-tab-counts.js";
 import { CATEGORY_PAGE_TABS } from "../../products/constants/listing-tabs.js";
@@ -46,7 +50,7 @@ export async function CategoryDetailPageView({ slug }) {
     // tree deeper than a couple of levels would have turned into a silently blank
     // page rather than an error (Root Cause #59).
     const categoriesIn = category?.id ? [category.id] : null;
-    const [productsResult, tabCounts, bundlesResult, childCategories, rootSiblingCategories, groupedListings, settings] = await Promise.all([
+    const [productsResult, tabCounts, bundlesResult, childCategories, rootSiblingCategories, groupedListings, settings, liveCounts, compositions] = await Promise.all([
         categoriesIn
             ? safeRead(() => productRepository.list({
                 filters: sieveAnd(sieveFilter("status", SIEVE_OP.EQ, "published"), sieveFilter("listingType", SIEVE_OP.EQ, "standard")),
@@ -118,6 +122,49 @@ export async function CategoryDetailPageView({ slug }) {
             key: "category.siteSettings",
             fallback: null,
         }),
+        /*
+         * G3b — this category's OWN vs ROLLUP counts, so the page can say "1 here,
+         * 53 in subcategories" instead of one ambiguous number.
+         *
+         * 🛑 ONE document by id, not a query — `categoryCounts/{id}` holds both
+         * figures, so the distinction costs a single read and `getAll` is not even
+         * needed. Added to this `Promise.all`, so it is PARALLEL with the other
+         * seven and adds no latency: Rule #6's budget is ~3 SEQUENTIAL round trips,
+         * and the plan's warning that "a sidecar collection would add an eighth"
+         * was about latency, which parallelism answers.
+         *
+         * 🛑 `null` on failure, never a zero. An unknown count must stay
+         * distinguishable from a count of nothing (Root Cause #72), so the caller
+         * falls back to the single `metrics` figure and renders exactly as before.
+         */
+        category?.id
+            ? safeRead(() => categoriesRepository.getLiveCounts(category.id), { route: "/categories/[slug]", key: "category.liveCounts", fallback: null })
+            : Promise.resolve(null),
+        /*
+         * D12 — the PART COMPOSITION, when this category is a named model.
+         *
+         * 🛑 ONE indexed equality on `categoryId`, added to this same
+         * `Promise.all` for the reason G3b's read above records: Rule #6's budget
+         * is ~3 SEQUENTIAL round trips, and a ninth PARALLEL read adds no
+         * latency. The plan's "a sidecar collection would add an eighth read"
+         * warning was about latency; parallelism is the answer to it, and the
+         * sibling collection is what keeps `onCategoryWrite` — which calls
+         * `notifyRevalidate` unconditionally — from dropping this page's ISR
+         * entry every time a composition is reseeded.
+         *
+         * 🛑 Resolved against this category's OWN id, so only a model leaf gets a
+         * panel. A line or generation node matches nothing and renders nothing,
+         * which is correct: "Burst GT" is not made of parts, the beys under it
+         * are. 210 of 259 compositions joined to a category, so the 49 that did
+         * not simply render no panel rather than a wrong one.
+         */
+        category?.id
+            ? safeRead(() => getCompositionsForCategory(category.id), {
+                route: "/categories/[slug]",
+                key: "parts.compositionsForCategory",
+                fallback: [],
+            })
+            : Promise.resolve([]),
     ]);
     const relatedCategories = rootSiblingCategories
         .filter((c) => c.id !== category?.id && (!c.categoryType || c.categoryType === "category"))
@@ -211,6 +258,29 @@ export async function CategoryDetailPageView({ slug }) {
     const productCount = counts.products ?? category?.metrics?.totalProductCount ?? category?.metrics?.productCount ?? 0;
     const auctionCount = counts.auctions ?? category?.metrics?.totalAuctionCount ?? category?.metrics?.auctionCount ?? 0;
     const preOrderCount = counts["pre-orders"] ?? 0;
+    /*
+     * G3b — OWN vs CHILDREN, so one number stops answering two questions.
+     *
+     * 🛑 `total` ALREADY INCLUDES `own`, so these are never added: the children
+     * figure is `total − own`, derived by `descendantTotalFor`. Summing them
+     * double-counts everything filed directly here, and on a LEAF — where
+     * `total === own` — it doubles the whole count.
+     *
+     * Verified across the live tree: for all 67 branch nodes
+     * `own + Σ(direct children's total) === total` exactly, and for all 314
+     * leaves `total === own`. The root reads `own 1 + children 53 = 54`.
+     *
+     * 🛑 Shown only when there IS something below. On a leaf the children figure
+     * is 0 and "0 in subcategories" is noise that reads as a missing number
+     * rather than an inapplicable one — the same reason the invoice table hides
+     * its HSN column when no line carries one.
+     *
+     * `undefined` when no counts document exists yet, so nothing renders and the
+     * single `metrics` figure above stands unchanged.
+     */
+    const ownHere = liveCounts ? ownTotalFor(liveCounts) : undefined;
+    const inSubcategories = liveCounts ? descendantTotalFor(liveCounts) : undefined;
+    const showCountSplit = ownHere !== undefined && inSubcategories !== undefined && inSubcategories > 0;
     const coverImage = category?.display?.coverImage;
     const hasCover = Boolean(coverImage);
     /*
@@ -246,18 +316,23 @@ export async function CategoryDetailPageView({ slug }) {
      * The URL uses `ancestor.id`, matching `BreadcrumbTrail` — `CategoryAncestor`
      * carries `id`/`name`/`tier` and no `slug`.
      */
-    const ldBreadcrumb = breadcrumbJsonLd([
+    /*
+     * D4b — ONE chain builder shared with the brand page, the product pages and
+     * the visible `BreadcrumbTrail`, so a crawler and a visitor cannot be shown
+     * different hierarchies for this page. `categoryCrumbs` sorts by tier (never
+     * trusting stored order), omits an ancestor it cannot label rather than
+     * leaving a gap, and `withTrailHead` drops the last crumb's URL because the
+     * final breadcrumb is the page you are on.
+     */
+    const ldBreadcrumb = breadcrumbJsonLd(withTrailHead(categoryCrumbs({
+        name: category?.name ?? "Category",
+        url: categoryPath,
+        ancestors: category?.ancestors,
+        hrefFor: (id) => String(ROUTES.PUBLIC.CATEGORY_DETAIL(id)),
+    }), [
         { name: "Home", url: "/" },
         { name: "Categories", url: String(ROUTES.PUBLIC.CATEGORIES) },
-        ...(category?.ancestors ?? [])
-            .slice()
-            .sort((a, b) => a.tier - b.tier)
-            .map((a) => ({
-            name: a.name,
-            url: String(ROUTES.PUBLIC.CATEGORY_DETAIL(a.id)),
-        })),
-        { name: category?.name ?? "Category", url: categoryPath },
-    ]);
+    ]));
     /*
      * 🛑 Items are the CHILD CATEGORIES, not the products.
      *
@@ -294,7 +369,7 @@ export async function CategoryDetailPageView({ slug }) {
     const ldFaq = category?.faqs && category.faqs.length > 0
         ? faqJsonLd(category.faqs.map((f) => ({ question: f.question, answer: f.answer })))
         : null;
-    return (_jsxs(Main, { children: [_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldBreadcrumb) } }), _jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldCollection) } }), ldFaq && (_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldFaq) } })), _jsxs(Section, { className: `relative ${__O.hidden} ${hasCover ? "min-h-[220px] md:min-h-[280px]" : "bg-[var(--appkit-color-bg)]"}`, children: [hasCover && (_jsxs(_Fragment, { children: [_jsx(Div, { className: "absolute inset-0", children: _jsx(MediaImage, { src: coverImage, alt: "", size: "banner" }) }), _jsx(Div, { surface: "overlay-md", className: "absolute inset-0" })] })), _jsxs(Div, { className: "relative z-10 max-w-7xl mx-auto", paddingY: hasCover ? "y-3xl" : "y-xl", padding: "x-md", children: [_jsxs(Nav, { layout: "flex", gap: "2xs", textSize: "sm", className: "mb-4", "aria-label": "Breadcrumb", children: [_jsx(Link, { href: String(ROUTES.HOME), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 transition-colors", children: "Home" }), _jsx(Span, { className: hasCover ? "text-white/40" : "text-zinc-400", children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORIES), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 transition-colors", children: "Categories" }), _jsx(Span, { className: hasCover ? "text-white/40" : "text-zinc-400", children: "/" }), _jsx(Span, { weight: "medium", className: hasCover ? "text-white" : "text-[var(--appkit-color-text)]", children: category?.name ?? slug })] }), _jsx(Heading, { color: "inverse", level: 1, className: `mb-2 ${hasCover ? "" : "text-[var(--appkit-color-text)]"}`, size: "3xl", mdSize: "4xl", weight: "bold", children: category?.name ?? slug }), category?.description && typeof category.description === "string" && !category.description.startsWith("{") && (_jsx(Text, { color: hasCover ? "inverse" : "muted", className: `max-w-2xl mb-4 ${hasCover ? "/80" : ""}`, size: "base", children: category.description })), _jsxs(Row, { wrap: true, gap: "sm", children: [productCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: "inverse", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "bg-primary/10 text-primary-700 dark:text-primary-400", rounded: "full", padding: "pill-sm-tall", children: [productCount.toLocaleString(), " ", productCount === 1 ? "product" : "products"] })), auctionCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "warning", surface: hasCover ? undefined : "warning-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [auctionCount.toLocaleString(), " ", auctionCount === 1 ? "auction" : "auctions"] })), preOrderCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "info", surface: hasCover ? undefined : "info-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [preOrderCount.toLocaleString(), " ", preOrderCount === 1 ? "pre-order" : "pre-orders"] })), storeCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "success", surface: hasCover ? undefined : "success-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [storeCount.toLocaleString(), " ", storeCount === 1 ? "store" : "stores"] }))] })] })] }), _jsx(CategoryHighlightsAndFaqSection, { highlights: category?.highlights, faqs: category?.faqs }), childCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: "max-w-7xl mx-auto", padding: "inline", children: Array.from(new Set(childCategories.map((c) => c.tier)))
+    return (_jsxs(Main, { children: [_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldBreadcrumb) } }), _jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldCollection) } }), ldFaq && (_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldFaq) } })), _jsxs(Section, { className: `relative ${__O.hidden} ${hasCover ? "min-h-[220px] md:min-h-[280px]" : "bg-[var(--appkit-color-bg)]"}`, children: [hasCover && (_jsxs(_Fragment, { children: [_jsx(Div, { className: "absolute inset-0", children: _jsx(MediaImage, { src: coverImage, alt: "", size: "banner" }) }), _jsx(Div, { surface: "overlay-md", className: "absolute inset-0" })] })), _jsxs(Div, { className: "relative z-10 max-w-7xl mx-auto", paddingY: hasCover ? "y-3xl" : "y-xl", padding: "x-md", children: [_jsxs(Nav, { layout: "flex", gap: "2xs", textSize: "sm", className: "mb-4", "aria-label": "Breadcrumb", children: [_jsx(Link, { href: String(ROUTES.HOME), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 transition-colors", children: "Home" }), _jsx(Span, { className: hasCover ? "text-white/40" : "text-zinc-400", children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORIES), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 transition-colors", children: "Categories" }), _jsx(Span, { className: hasCover ? "text-white/40" : "text-zinc-400", children: "/" }), _jsx(Span, { weight: "medium", className: hasCover ? "text-white" : "text-[var(--appkit-color-text)]", children: category?.name ?? slug })] }), _jsx(Heading, { color: "inverse", level: 1, className: `mb-2 ${hasCover ? "" : "text-[var(--appkit-color-text)]"}`, size: "3xl", mdSize: "4xl", weight: "bold", children: category?.name ?? slug }), category?.description && typeof category.description === "string" && !category.description.startsWith("{") && (_jsx(Text, { color: hasCover ? "inverse" : "muted", className: `max-w-2xl mb-4 ${hasCover ? "/80" : ""}`, size: "base", children: category.description })), _jsxs(Row, { wrap: true, gap: "sm", children: [productCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: "inverse", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "bg-primary/10 text-primary-700 dark:text-primary-400", rounded: "full", padding: "pill-sm-tall", children: [productCount.toLocaleString(), " ", productCount === 1 ? "product" : "products"] })), showCountSplit && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "muted", size: "xs", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [ownHere.toLocaleString(), " here \u00B7 ", inSubcategories.toLocaleString(), " in subcategories"] })), auctionCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "warning", surface: hasCover ? undefined : "warning-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [auctionCount.toLocaleString(), " ", auctionCount === 1 ? "auction" : "auctions"] })), preOrderCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "info", surface: hasCover ? undefined : "info-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [preOrderCount.toLocaleString(), " ", preOrderCount === 1 ? "pre-order" : "pre-orders"] })), storeCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "success", surface: hasCover ? undefined : "success-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [storeCount.toLocaleString(), " ", storeCount === 1 ? "store" : "stores"] }))] })] })] }), _jsx(CategoryHighlightsAndFaqSection, { highlights: category?.highlights, faqs: category?.faqs }), compositions.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: "max-w-7xl mx-auto", padding: "section", children: _jsxs(Stack, { gap: "md", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: "What it is made of" }), _jsx(ModelCompositionPanel, { compositions: compositions, hrefForPart: (slot, tail) => String(ROUTES.PUBLIC.PART_DETAIL(slot, tail)) })] }) }) })), childCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: "max-w-7xl mx-auto", padding: "inline", children: Array.from(new Set(childCategories.map((c) => c.tier)))
                         .sort((a, b) => a - b)
                         .map((tier) => (_jsxs(Div, { padding: "b-2xs", children: [_jsx(Text, { size: "xs", color: "muted", weight: "medium", className: "mb-[var(--appkit-space-1-5)]", children: tier - (category?.tier ?? 0) === 1
                                     ? "Subcategories"