@mohasinac/appkit 4.46.0 → 4.48.0

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

@@ -1,11 +1,24 @@
 import React from "react";
 import type { CategoryItem } from "../types";
+import { type BreadcrumbCrumb } from "../utils/breadcrumb-chain";
 export interface BreadcrumbTrailProps {
     /**
-     * The current (leaf) category whose ancestry should be shown as breadcrumbs.
-     * Uses `category.ancestors` if present, otherwise only the category itself.
+     * The chain to render, root-first, with the final crumb carrying no `url`.
+     *
+     * 🛑 PREFER THIS over `category`. It is the same array the page hands to
+     * `breadcrumbJsonLd`, which is what makes the visible trail, the markup and
+     * `categoryNames` agree by construction rather than by discipline — D4b's
+     * rule. Before this prop existed the category page and the product page each
+     * hand-rolled their own `<Nav>`, and the product one rendered three crumbs
+     * (`Home / Products / Category`) while its JSON-LD carried all eight.
      */
-    category: CategoryItem;
+    crumbs?: readonly BreadcrumbCrumb[];
+    /**
+     * Legacy input: a category whose `ancestors` array becomes the chain.
+     * Kept because it is the published prop shape; `crumbs` wins when both are
+     * passed.
+     */
+    category?: CategoryItem;
     /**
      * Label for the implicit root item prepended to the trail.
      * Default: "All Categories"
@@ -28,21 +41,53 @@ 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 EIGHT
+     * crumbs (`Home > Categories > Spinning Tops > Beyblade Metal > Metal Parts >
+     * Performance Tips > Rubber Flat > <title>`) 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;
+    };
+    /**
+     * `"on-media"` when the trail sits over a cover photo — the category hero
+     * does. Forwarded to the `Breadcrumb` primitive, which owns the ink.
+     */
+    tone?: "default" | "on-media";
 }
 /**
- * BreadcrumbTrail — a category-aware breadcrumb component.
+ * BreadcrumbTrail — one row of crumbs, with the middle and the alternates
+ * collapsed behind real `<details>` dropdowns.
+ *
+ * 🛑 BOTH DROPDOWNS CONTAIN REAL `<a>` ELEMENTS IN THE SERVER-RENDERED DOM.
+ * `<details>`/`<summary>` is native, needs no JavaScript, works on a keyboard,
+ * and — the reason it was chosen over a hover menu — a crawler parsing the HTML
+ * sees every link whether or not anything ever opens it. Links injected on
+ * open would trade the SEO this exists for against tidiness, which is the
+ * opposite of *"better for both crawler and users"*.
  *
- * Renders the full ancestor chain for a category using the `ancestors` array
- * stored on `CategoryItem`. Falls back gracefully when `ancestors` is absent
- * (shows only the root + current category).
+ * 🛑 Collapsing is PRESENTATION ONLY. The JSON-LD is emitted by the page from
+ * the full chain and must stay that way: a crawler never receives a truncated
+ * hierarchy because a phone could not show it.
  *
  * @example
  * ```tsx
- * <BreadcrumbTrail
- * category={category}
- * rootHref="/categories"
- * basePath="/categories"
- * />
+ * <BreadcrumbTrail crumbs={withTrailHead(categoryCrumbs(category), HEAD)} />
  * ```
  */
-export declare function BreadcrumbTrail({ category, rootLabel, rootHref, basePath, showCurrent, className, }: BreadcrumbTrailProps): React.JSX.Element;
+export declare function BreadcrumbTrail({ crumbs, category, rootLabel, rootHref, basePath, showCurrent, className, collapse, alternates, tone, }: BreadcrumbTrailProps): React.JSX.Element | null;

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

@@ -1,36 +1,73 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
 import { Breadcrumb } from "../../../ui/index.js";
+import { Details, Summary, Div, Row, Stack } from "../../../ui/index.js";
+import { Span } 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.
+ * BreadcrumbTrail — one row of crumbs, with the middle and the alternates
+ * collapsed behind real `<details>` dropdowns.
  *
- * Renders the full ancestor chain for a category using the `ancestors` array
- * stored on `CategoryItem`. Falls back gracefully when `ancestors` is absent
- * (shows only the root + current category).
+ * 🛑 BOTH DROPDOWNS CONTAIN REAL `<a>` ELEMENTS IN THE SERVER-RENDERED DOM.
+ * `<details>`/`<summary>` is native, needs no JavaScript, works on a keyboard,
+ * and — the reason it was chosen over a hover menu — a crawler parsing the HTML
+ * sees every link whether or not anything ever opens it. Links injected on
+ * open would trade the SEO this exists for against tidiness, which is the
+ * opposite of *"better for both crawler and users"*.
+ *
+ * 🛑 Collapsing is PRESENTATION ONLY. The JSON-LD is emitted by the page from
+ * the full chain and must stay that way: a crawler never receives a truncated
+ * hierarchy because a phone could not show it.
  *
  * @example
  * ```tsx
- * <BreadcrumbTrail
- * category={category}
- * rootHref="/categories"
- * basePath="/categories"
- * />
+ * <BreadcrumbTrail crumbs={withTrailHead(categoryCrumbs(category), HEAD)} />
  * ```
  */
-export function BreadcrumbTrail({ category, rootLabel = "All Categories", rootHref = String(ROUTES.PUBLIC.CATEGORIES), basePath = String(ROUTES.PUBLIC.CATEGORIES), showCurrent = true, className, }) {
-    const items = [
-        // Root
-        { label: rootLabel, href: rootHref },
-        // Ancestors (sorted by tier ascending so root → leaf order)
-        ...(category.ancestors ?? [])
-            .slice()
-            .sort((a, b) => a.tier - b.tier)
-            .map((ancestor) => ({
-            label: ancestor.name,
-            href: `${basePath}/${ancestor.id}`,
-        })),
-        // Current category (no href so it renders as the active item)
-        ...(showCurrent ? [{ label: category.name }] : []),
-    ];
-    return _jsx(Breadcrumb, { items: items, className: className });
+export function BreadcrumbTrail({ crumbs, category, rootLabel = "All Categories", rootHref = String(ROUTES.PUBLIC.CATEGORIES), basePath = String(ROUTES.PUBLIC.CATEGORIES), showCurrent = true, className, collapse = true, alternates, tone = "default", }) {
+    const chain = crumbs?.length
+        ? [...crumbs]
+        : category
+            ? [
+                { name: rootLabel, url: rootHref },
+                ...(category.ancestors ?? [])
+                    .slice()
+                    .sort((a, b) => a.tier - b.tier)
+                    .map((ancestor) => ({
+                    name: ancestor.name,
+                    url: `${basePath}/${ancestor.id}`,
+                })),
+                ...(showCurrent ? [{ name: category.name }] : []),
+            ]
+            : [];
+    if (chain.length === 0)
+        return null;
+    /*
+     * 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}`,
+    });
+    const split = collapse ? collapseTrail(chain) : null;
+    const hasCollapsed = Boolean(split && split.collapsed.length > 0);
+    const visible = hasCollapsed
+        ? [...split.lead.map(fromCrumb), ...split.tail.map(fromCrumb)]
+        : chain.map(fromCrumb);
+    /*
+     * The collapsed middle is injected AFTER the lead rather than rendered as a
+     * label-only crumb, so the hidden ancestors stay clickable. The previous
+     * version rendered `… 3 more` as plain text, which told the visitor what was
+     * missing and gave them no way to reach it.
+     */
+    const leadCount = hasCollapsed ? split.lead.length : 0;
+    return (_jsxs(Div, { className: className, children: [_jsxs(Row, { align: "center", gap: "xs", wrap: true, children: [_jsx(Breadcrumb, { items: visible.slice(0, leadCount), tone: tone }), hasCollapsed && (_jsxs(Details, { tone: "card", padding: "sm", rounded: "lg", children: [_jsx(Summary, { size: "xs", color: "muted", ariaLabel: `Show ${split.collapsed.length} hidden category levels`, children: `… ${split.collapsed.length} more` }), _jsx(Div, { padding: "t-xs", children: _jsx(Stack, { align: "start", gap: "xs", children: split.collapsed.map((c) => (_jsx(TextLink, { href: c.url ?? rootHref, size: "xs", children: c.name }, c.url ?? c.name))) }) })] })), _jsx(Breadcrumb, { items: hasCollapsed ? visible.slice(leadCount) : visible, tone: tone })] }), alt.mode === "inline" && (_jsxs(Span, { size: "xs", color: "muted", children: ["Also in", " ", alt.items.map((a, i) => (_jsxs(React.Fragment, { children: [i > 0 && " · ", _jsx(TextLink, { href: a.url ?? rootHref, size: "xs", children: a.name })] }, a.url ?? a.name)))] })), alt.mode === "dropdown" && (_jsxs(Details, { tone: "card", padding: "sm", rounded: "lg", children: [_jsx(Summary, { size: "xs", color: "muted", ariaLabel: "Other categories this listing is filed under", children: `Also in ${alt.items.length} more` }), _jsx(Div, { padding: "t-xs", children: _jsx(Stack, { align: "start", gap: "xs", children: alt.items.map((a) => (_jsx(TextLink, { href: a.url ?? rootHref, size: "xs", children: a.name }, a.url ?? a.name))) }) })] }))] }));
+}
+function fromCrumb(c) {
+    return c.url ? { label: c.name, href: c.url } : { label: c.name };
 }

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

@@ -5,11 +5,14 @@ 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 { Container, Div, Heading, Main, Nav, Section, Span, Stack, Text } from "../../../ui/index.js";
+import { Container, Div, Heading, ImageMosaic, Main, MOSAIC_MIN, Section, Span, SplitTile, Stack, Text } from "../../../ui/index.js";
 import { MediaImage } from "../../media/MediaImage.js";
+import { RichTextRenderer } from "../../../ui/rich-text/RichTextRenderer.js";
 import { CategoryDetailTabs } from "./CategoryDetailTabs.js";
 import { CategoryGrid } from "./CategoryGrid.js";
 import { CategoryHighlightsAndFaqSection } from "./CategoryHighlightsAndFaqSection.js";
+import { BreadcrumbTrail } from "./BreadcrumbTrail.js";
+import { LastCategoryBeacon } from "./LastCategoryBeacon.js";
 import { GroupedListingsCarousel } from "../../grouped/components/GroupedListingsCarousel.js";
 import { ModelCompositionPanel } from "../../parts/components/ModelCompositionPanel.js";
 import { getCompositionsForCategory } from "../../../_internal/server/features/parts/data.js";
@@ -21,11 +24,14 @@ import { enabledCategoryTypes, enabledListingTypes } from "../../../_internal/sh
 import { siteSettingsRepository } from "../../../repositories/index.js";
 import { safeRead } from "../../../errors/safe-read.js";
 import { breadcrumbJsonLd, collectionPageJsonLd, faqJsonLd, } from "../../../seo/json-ld.js";
+import { toStoreListItem } from "../../../_internal/server/features/stores/adapters.js";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
 const __O = {
     hidden: "overflow-hidden",
     xAuto: "overflow-x-auto",
 };
+/** The page's content width, repeated across every section on this view. */
+const __W = "max-w-7xl mx-auto";
 /**
  * Read and display bounds for this page. Every one of these replaced an
  * unbounded read — see the comments at each use site for what each one cost.
@@ -40,8 +46,20 @@ export async function CategoryDetailPageView({ slug }) {
     // The category IS this page's subject — a read failure must surface rather
     // than render an anonymous, empty category page. `undefined` still means
     // "no such category slug".
-    const category = ((await categoriesRepository
-        .getCategoryBySlug(slug)) ?? undefined);
+    const categoryDoc = await categoriesRepository.getCategoryBySlug(slug);
+    const category = (categoryDoc ?? undefined);
+    /*
+     * 🛑 Read from the DOCUMENT, not from the `CategoryItem` cast.
+     *
+     * `contentBody` is deliberately PRIVATE on the list projection — it is
+     * 400–900 chars of HTML per row and `CategoryInlineSelect` fetches 200 rows
+     * on every seller-form open, so publishing it there would be the
+     * Fast-Origin-Transfer shape of Root Cause #104. Adding it to `CategoryItem`
+     * to satisfy this one render site would invite exactly that. The detail page
+     * holds the whole document server-side, which is what the adapter's own
+     * comment says this field's reader does.
+     */
+    const contentBody = typeof categoryDoc?.contentBody === "string" ? categoryDoc.contentBody : null;
     // Products carry their FULL ancestor chain in `categorySlugs`, so matching on
     // this category's own id already returns the whole subtree — no descendant
     // expansion needed. Expanding it was also a latent outage: `categoriesIn` is
@@ -212,41 +230,27 @@ export async function CategoryDetailPageView({ slug }) {
         seen.add(s.id);
         return true;
     })
-        .map((s) => ({
-        id: s.id,
-        storeSlug: s.storeSlug ?? s.id,
-        ownerId: s.ownerId,
-        storeName: s.storeName,
-        storeDescription: s.storeDescription,
-        storeCategory: s.storeCategory,
-        storeLogoURL: s.storeLogoURL,
-        storeBannerURL: s.storeBannerURL,
-        status: s.status,
-        isPublic: s.isPublic ?? true,
-        totalProducts: s.stats?.totalProducts,
-        itemsSold: s.stats?.itemsSold,
-        totalReviews: s.stats?.totalReviews,
-        averageRating: s.stats?.averageRating,
         /*
-         * 🛑 This whole `.map()` is a SIXTH hand-rolled copy of
-         * `toStoreListItem` — the adapter Root Cause #70 created precisely to
-         * collapse the three that existed then, and which three public store
-         * APIs now share. It is recorded as an F1 defect rather than fixed here
-         * (the defect policy: a found defect goes in the backlog, not in the
-         * step's commit), and the reason it cannot be a drive-by is a boundary:
-         * the adapter lives in `_internal/server/` and this file is in
-         * `features/`, so adopting it is an import-graph decision, not a rename.
+         * 🛑 F1 #28 CLOSED — this was a SIXTH hand-rolled copy of
+         * `toStoreListItem`, the adapter Root Cause #70 created to collapse the
+         * three that existed then and which three public store APIs now share.
          *
-         * These two fields are added rather than deferred because `tsc` demands
-         * them — which is the whole value of having made them REQUIRED on
-         * `StoreListItem`: the compiler enumerated every copy, and this is the
-         * one the audit's "union of what the registered builders emit" check
-         * cannot see.
+         * It was recorded as "not a drive-by fix" because the adapter lives in
+         * `_internal/server/` and this file in `features/`, making adoption an
+         * import-graph decision. MEASURED, that decision is free: the adapter
+         * module's only imports are two `import type` lines, and this file already
+         * imports four other `_internal/server/*` modules (parts, grouped,
+         * listing-tab-counts, tester visibility). So the boundary argument did not
+         * apply to this particular module, and the copy stayed alive on a
+         * hypothetical.
+         *
+         * The behavioural differences the copy carried, both now gone: it defaulted
+         * `storeSlug` to the id and `isPublic` to `true` (the adapter forwards what
+         * the document says, and a store with no `isPublic` is not assumed public),
+         * and it cast `createdAt` through `as unknown as string` where the adapter
+         * converts a Timestamp properly.
          */
-        supportsShippingProtection: s.supportsShippingProtection ?? false,
-        supportsSaleProtection: s.supportsSaleProtection ?? false,
-        createdAt: s.createdAt,
-    }));
+        .map((s) => toStoreListItem(s));
     const storeCount = categoryStores.length;
     // `tabCounts` is keyed by tabSlug and already covers every listing type plus
     // bundles; `stores` is added here because this page resolves its store list
@@ -283,6 +287,24 @@ export async function CategoryDetailPageView({ slug }) {
     const showCountSplit = ownHere !== undefined && inSubcategories !== undefined && inSubcategories > 0;
     const coverImage = category?.display?.coverImage;
     const hasCover = Boolean(coverImage);
+    /*
+     * D3 — when the category has no cover photo of its own, the hero draws a
+     * mosaic of the products ALREADY fetched for the grid below. Zero extra
+     * reads: these are the same rows, and the band was otherwise a flat colour
+     * strip on roughly 1,100 categories that have no photographer.
+     *
+     * 🛑 Only when there are at least `MOSAIC_MIN` images. Two thumbnails beside
+     * a title is not a pattern, it is two thumbnails — the component returns null
+     * below the floor and the hero keeps its plain background, which is a correct
+     * answer rather than a half-built one.
+     */
+    const mosaicImages = hasCover
+        ? []
+        : (productsResult?.items ?? [])
+            .map((row) => row.mainImage ?? row.images?.[0] ?? null)
+            .filter((src) => !!src)
+            .slice(0, 5);
+    const hasMosaic = mosaicImages.length >= MOSAIC_MIN;
     /*
      * ── D4: structured data. This page emitted NONE ─────────────────────────
      *
@@ -324,7 +346,7 @@ export async function CategoryDetailPageView({ slug }) {
      * 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({
+    const trail = withTrailHead(categoryCrumbs({
         name: category?.name ?? "Category",
         url: categoryPath,
         ancestors: category?.ancestors,
@@ -332,7 +354,14 @@ export async function CategoryDetailPageView({ slug }) {
     }), [
         { name: "Home", url: "/" },
         { name: "Categories", url: String(ROUTES.PUBLIC.CATEGORIES) },
-    ]));
+    ]);
+    /*
+     * 🛑 ONE ARRAY, two surfaces. The visible trail below renders `trail` and the
+     * markup here serialises the same `trail` — so they cannot disagree, which is
+     * exactly what happened while the page hand-rolled a three-crumb `<Nav>`
+     * beside an eight-crumb `BreadcrumbList`.
+     */
+    const ldBreadcrumb = breadcrumbJsonLd(trail);
     /*
      * 🛑 Items are the CHILD CATEGORIES, not the products.
      *
@@ -369,7 +398,32 @@ 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"] })), 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)))
+    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" })] })), !hasCover && hasMosaic && (_jsx(Div, { className: "relative z-10 max-w-7xl mx-auto", padding: "x-md", children: _jsx(Div, { padding: "t-lg", children: _jsx(ImageMosaic, { images: mosaicImages, alt: `${category?.name ?? slug} on LetItRip` }) }) })), _jsxs(Div, { className: "relative z-10 max-w-7xl mx-auto", paddingY: hasCover ? "y-3xl" : "y-xl", padding: "x-md", children: [_jsx(BreadcrumbTrail, { crumbs: trail, className: "mb-4", tone: hasCover ? "on-media" : "default" }), category?.id && _jsx(LastCategoryBeacon, { categoryId: category.id }), _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"] }))] })] })] }), contentBody && contentBody.trim().length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(RichTextRenderer, { html: contentBody }) }) })), _jsx(CategoryHighlightsAndFaqSection, { highlights: category?.highlights, faqs: category?.faqs }), compositions.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: __W, 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)) })] }) }) })), (() => {
+                if (category?.tier !== 0)
+                    return null;
+                const branches = childCategories.filter((c) => c.tier === 1);
+                if (branches.length !== 2)
+                    return null;
+                const [a, b] = branches;
+                const coverOf = (c) => c?.display?.coverImage;
+                if (!a || !b || !coverOf(a) || !coverOf(b))
+                    return null;
+                const countOf = (c) => {
+                    const n = c?.metrics?.totalProductCount ?? c?.metrics?.productCount ?? 0;
+                    return n > 0 ? `${n.toLocaleString()} listing${n === 1 ? "" : "s"}` : undefined;
+                };
+                return (_jsx(Section, { padding: "y-lg", children: _jsx(Div, { className: __W, padding: "x-md", children: _jsx(SplitTile, { left: {
+                                href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(a.slug)),
+                                label: a.name,
+                                imageUrl: coverOf(a),
+                                countLabel: countOf(a),
+                            }, right: {
+                                href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(b.slug)),
+                                label: b.name,
+                                imageUrl: coverOf(b),
+                                countLabel: countOf(b),
+                            } }) }) }));
+            })(), childCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: __W, 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"

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

@@ -0,0 +1,62 @@
+import React from "react";
+import type { BreadcrumbCrumb } from "../utils/breadcrumb-chain";
+/**
+ * I5b — the visible trail follows the path the visitor actually took, when
+ * that path is one this listing is genuinely filed under.
+ *
+ * ## 🛑 Why this is CLIENT-side, and why the markup is not
+ *
+ * A product can be filed under several categories, so there are several valid
+ * trails to one page. The resolution keeps D4b's rule (*the visible trail, the
+ * JSON-LD and `categoryNames` must agree*) by making exactly ONE of the three
+ * contextual, and never the markup:
+ *
+ *   - `categoryNames`, the JSON-LD and the FIRST PAINT all render the DEFAULT
+ *     chain. Always, for everyone.
+ *   - only the visible trail, AFTER hydration, may swap to the trail matching
+ *     the category page the visitor came from.
+ *
+ * Doing it on the server is not available: the product routes are CACHED, so a
+ * referrer-dependent trail computed server-side would be baked into the cache
+ * entry and then served to everyone who shared that URL. And a crawler has no
+ * history, so it would get the default anyway.
+ *
+ * There is no flash, because the default is a REAL answer rather than a
+ * placeholder — the same three-state shape the guest-price gate uses.
+ *
+ * ## 🛑 `sessionStorage`, not a Firestore write and not the `history` collection
+ *
+ * One key holding the last category page visited. A navigation crumb is not
+ * worth a write per page view (Root Cause #94 is the record of what per-page-view
+ * client work costs here), and the `history` collection stores *viewed
+ * products* — not the path taken to them.
+ *
+ * ## 🛑 Suppressed entirely for a single assignment
+ *
+ * Which is the overwhelming majority of rows. Otherwise every product page
+ * gains a possible post-hydration layout shift in its first crumb row for a
+ * feature that applies to a handful.
+ *
+ * @tag domain:categories
+ * @tag layer:client-component
+ * @tag access:client-only
+ */
+/** The `sessionStorage` key. Read here, written by `<LastCategoryBeacon>`. */
+export declare const LAST_CATEGORY_KEY = "letitrip:last-category";
+export interface ContextualTrailProps {
+    /**
+     * One entry per assignment, DEFAULT FIRST. Each carries the assignment's
+     * category id and the full crumb chain for it.
+     */
+    trails: ReadonlyArray<{
+        categoryId: string;
+        crumbs: readonly BreadcrumbCrumb[];
+    }>;
+    /** Forwarded to `BreadcrumbTrail` for the alternates crumb. */
+    alternates?: {
+        ids?: readonly string[] | null;
+        names?: readonly string[] | null;
+    };
+    className?: string;
+}
+export declare function ContextualTrail({ trails, alternates, className }: ContextualTrailProps): React.JSX.Element | null;

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

@@ -0,0 +1,81 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from "react";
+import { storageManager } from "../../../core/StorageManager.js";
+import { BreadcrumbTrail } from "./BreadcrumbTrail.js";
+/**
+ * I5b — the visible trail follows the path the visitor actually took, when
+ * that path is one this listing is genuinely filed under.
+ *
+ * ## 🛑 Why this is CLIENT-side, and why the markup is not
+ *
+ * A product can be filed under several categories, so there are several valid
+ * trails to one page. The resolution keeps D4b's rule (*the visible trail, the
+ * JSON-LD and `categoryNames` must agree*) by making exactly ONE of the three
+ * contextual, and never the markup:
+ *
+ *   - `categoryNames`, the JSON-LD and the FIRST PAINT all render the DEFAULT
+ *     chain. Always, for everyone.
+ *   - only the visible trail, AFTER hydration, may swap to the trail matching
+ *     the category page the visitor came from.
+ *
+ * Doing it on the server is not available: the product routes are CACHED, so a
+ * referrer-dependent trail computed server-side would be baked into the cache
+ * entry and then served to everyone who shared that URL. And a crawler has no
+ * history, so it would get the default anyway.
+ *
+ * There is no flash, because the default is a REAL answer rather than a
+ * placeholder — the same three-state shape the guest-price gate uses.
+ *
+ * ## 🛑 `sessionStorage`, not a Firestore write and not the `history` collection
+ *
+ * One key holding the last category page visited. A navigation crumb is not
+ * worth a write per page view (Root Cause #94 is the record of what per-page-view
+ * client work costs here), and the `history` collection stores *viewed
+ * products* — not the path taken to them.
+ *
+ * ## 🛑 Suppressed entirely for a single assignment
+ *
+ * Which is the overwhelming majority of rows. Otherwise every product page
+ * gains a possible post-hydration layout shift in its first crumb row for a
+ * feature that applies to a handful.
+ *
+ * @tag domain:categories
+ * @tag layer:client-component
+ * @tag access:client-only
+ */
+/** The `sessionStorage` key. Read here, written by `<LastCategoryBeacon>`. */
+export const LAST_CATEGORY_KEY = "letitrip:last-category";
+export function ContextualTrail({ trails, alternates, className }) {
+    // Index 0 is the default chain and is what the server rendered.
+    const [index, setIndex] = React.useState(0);
+    const multi = trails.length > 1;
+    React.useEffect(() => {
+        // One assignment: nothing can be swapped to, so never touch state — that is
+        // what guarantees no post-hydration shift on the common row.
+        if (!multi)
+            return;
+        /*
+         * 🛑 Through `storageManager`, not a private `try/catch` around
+         * `window.sessionStorage`. It already owns the three failure modes (SSR, a
+         * cross-origin iframe, a security policy that throws on mere ACCESS),
+         * returns `null` for all of them, and normalises what it catches — so this
+         * component needs no catch at all and there is one implementation of
+         * "storage might not exist" rather than a second, quieter copy.
+         */
+        const last = storageManager.get(LAST_CATEGORY_KEY, { type: "session" });
+        if (!last)
+            return;
+        const match = trails.findIndex((t) => t.categoryId === last);
+        // 🛑 Only swap to a trail this listing is REALLY filed under. A visitor who
+        // arrived from an unrelated category keeps the default, because inventing a
+        // trail through a category the product is not in would be a lie about the
+        // taxonomy, not a convenience.
+        if (match > 0)
+            setIndex(match);
+    }, [multi, trails]);
+    const active = trails[index] ?? trails[0];
+    if (!active)
+        return null;
+    return (_jsx(BreadcrumbTrail, { crumbs: active.crumbs, alternates: alternates, className: className }));
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Record which category page the visitor is on, for `<ContextualTrail>`.
+ *
+ * 🛑 `sessionStorage`, one key, one write per category page view — not a
+ * Firestore write and not the `history` collection (which stores viewed
+ * PRODUCTS, not the path taken). Root Cause #94 is the record of what
+ * per-page-view client work costs on this project.
+ *
+ * Renders nothing. It is a component rather than an effect inside the category
+ * page because that page is a Server Component and must stay one.
+ *
+ * @tag domain:categories
+ * @tag layer:client-component
+ * @tag access:client-only
+ */
+export declare function LastCategoryBeacon({ categoryId }: {
+    categoryId: string;
+}): null;

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

@@ -0,0 +1,33 @@
+"use client";
+import React from "react";
+import { storageManager } from "../../../core/StorageManager.js";
+import { LAST_CATEGORY_KEY } from "./ContextualTrail.js";
+/**
+ * Record which category page the visitor is on, for `<ContextualTrail>`.
+ *
+ * 🛑 `sessionStorage`, one key, one write per category page view — not a
+ * Firestore write and not the `history` collection (which stores viewed
+ * PRODUCTS, not the path taken). Root Cause #94 is the record of what
+ * per-page-view client work costs on this project.
+ *
+ * Renders nothing. It is a component rather than an effect inside the category
+ * page because that page is a Server Component and must stay one.
+ *
+ * @tag domain:categories
+ * @tag layer:client-component
+ * @tag access:client-only
+ */
+export function LastCategoryBeacon({ categoryId }) {
+    React.useEffect(() => {
+        if (!categoryId)
+            return;
+        /*
+         * Through `storageManager`, which already handles SSR, a cross-origin
+         * iframe and a policy that throws on access — so there is no catch here
+         * and no second copy of that logic. A `false` return means the visitor
+         * keeps the default trail, which is a correct answer.
+         */
+        storageManager.set(LAST_CATEGORY_KEY, categoryId, { type: "session" });
+    }, [categoryId]);
+    return null;
+}

package/dist/features/categories/repository/categories.repository.d.ts

@@ -11,6 +11,27 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
         search?: string;
     }): Promise<FirebaseSieveResult<CategoryDocument>>;
     createWithHierarchy(input: CategoryCreateInput): Promise<CategoryDocument>;
+    /**
+     * The LIVE rolled-up listing count for a bounded set of category ids.
+     *
+     * 🛑 This is the seam `getLiveCategoryCounts` was written for and never got.
+     * It had zero callers, so the five surfaces that render MANY categories at
+     * once — the `/categories` grid, the homepage tiles, the admin table, the
+     * tree and the child chips — all still read `metrics.totalProductCount`,
+     * which only the nightly reconciler writes. A listing published at 09:00 did
+     * not change any of those numbers until ~04:30 the next morning, while the
+     * category's own page (which counts live) disagreed with every one of them.
+     *
+     * It lives on the REPOSITORY because that is the one place already holding a
+     * Firestore handle: the helper needs `db.getAll`, and reaching for
+     * `getAdminDb()` from a route module would put a static firebase-admin import
+     * into a file the main barrel re-exports (Root Cause #24).
+     *
+     * 🛑 A missing id is ABSENT from the map, never 0 — the caller must fall back
+     * to `metrics`. See `liveTotalFor`: a count that is unknown must not be
+     * indistinguishable from a count of nothing (Root Cause #72).
+     */
+    liveTotalsFor(ids: readonly string[]): Promise<Map<string, number>>;
     getCategoryBySlug(slug: string): Promise<CategoryDocument | null>;
     getRootCategories(): Promise<CategoryDocument[]>;
     getLeafCategories(): Promise<CategoryDocument[]>;