@mohasinac/appkit 4.53.0 → 4.53.1

package/dist/features/categories/api/[id]/price-guidance/route.d.ts

@@ -0,0 +1,42 @@
+/**
+ * feat-categories — GET /api/categories/[id]/price-guidance
+ *
+ * The seller-facing price hint `description-template/route.ts`'s own
+ * docstring names as "C1's job, from a surface that knows who is asking" —
+ * this is that surface. It is deliberately a SEPARATE endpoint rather than a
+ * field added back to the public, CDN-cached template route: that route's
+ * whole point is that anyone can fetch it, and `priceGuidance` is withheld
+ * from signed-out visitors for the same reason a listing's own price is
+ * (CLAUDE.md § "Guest price gating") — publishing the competitor-derived
+ * market band on an unauthenticated, publicly-cacheable response would be
+ * exactly the "a neighbouring surface publishes the range" leak that gate
+ * exists to close, even though the number is advisory rather than a real
+ * price.
+ *
+ * Consumer stub:
+ * ```ts
+ * // src/app/api/categories/[id]/price-guidance/route.ts
+ * export { categoryPriceGuidanceGET as GET } from "@mohasinac/appkit";
+ * ```
+ *
+ * ## What this does NOT resolve
+ *
+ * `PriceGuidanceBasis.gstRate` — "the rate that will be written onto this
+ * listing, resolved the same way `deriveTaxonomy` resolves it" — is left
+ * `undefined` here on purpose. `deriveTaxonomy` is a private method on
+ * `ProductRepository`, tightly coupled to the product WRITE path (it also
+ * applies `DEFAULT_GST_RATE` as a last resort, which is correct for a
+ * document being saved and would be a guess presented as fact on a read-only
+ * hint). `describePriceGuidanceBasis` already handles an unresolved rate
+ * correctly and safely: for the common case (a seller whose prices already
+ * include GST — the schema default), the rate is never consulted at all, so
+ * this omission costs nothing. Only an EXCLUSIVE-pricing seller sees the
+ * honest "could not be resolved" note instead of a converted figure — which
+ * is the behaviour `price-guidance.ts`'s own docstring prescribes for exactly
+ * this situation, not a half-measure standing in for the real resolution.
+ */
+export declare const GET: (request: Request, context?: {
+    params: Promise<{
+        id: string;
+    }>;
+} | undefined) => Promise<Response>;

package/dist/features/categories/api/[id]/price-guidance/route.js

@@ -0,0 +1,113 @@
+/**
+ * feat-categories — GET /api/categories/[id]/price-guidance
+ *
+ * The seller-facing price hint `description-template/route.ts`'s own
+ * docstring names as "C1's job, from a surface that knows who is asking" —
+ * this is that surface. It is deliberately a SEPARATE endpoint rather than a
+ * field added back to the public, CDN-cached template route: that route's
+ * whole point is that anyone can fetch it, and `priceGuidance` is withheld
+ * from signed-out visitors for the same reason a listing's own price is
+ * (CLAUDE.md § "Guest price gating") — publishing the competitor-derived
+ * market band on an unauthenticated, publicly-cacheable response would be
+ * exactly the "a neighbouring surface publishes the range" leak that gate
+ * exists to close, even though the number is advisory rather than a real
+ * price.
+ *
+ * Consumer stub:
+ * ```ts
+ * // src/app/api/categories/[id]/price-guidance/route.ts
+ * export { categoryPriceGuidanceGET as GET } from "@mohasinac/appkit";
+ * ```
+ *
+ * ## What this does NOT resolve
+ *
+ * `PriceGuidanceBasis.gstRate` — "the rate that will be written onto this
+ * listing, resolved the same way `deriveTaxonomy` resolves it" — is left
+ * `undefined` here on purpose. `deriveTaxonomy` is a private method on
+ * `ProductRepository`, tightly coupled to the product WRITE path (it also
+ * applies `DEFAULT_GST_RATE` as a last resort, which is correct for a
+ * document being saved and would be a guess presented as fact on a read-only
+ * hint). `describePriceGuidanceBasis` already handles an unresolved rate
+ * correctly and safely: for the common case (a seller whose prices already
+ * include GST — the schema default), the rate is never consulted at all, so
+ * this omission costs nothing. Only an EXCLUSIVE-pricing seller sees the
+ * honest "could not be resolved" note instead of a converted figure — which
+ * is the behaviour `price-guidance.ts`'s own docstring prescribes for exactly
+ * this situation, not a half-measure standing in for the real resolution.
+ */
+import { NextResponse } from "next/server.js";
+import { normalizeError } from "../../../../../errors/normalize.js";
+import { serverLogger } from "../../../../../monitoring/index.js";
+import { createRouteHandler } from "../../../../../next/api/routeHandler.js";
+import { getProviders } from "../../../../../contracts/index.js";
+import { categoriesRepository } from "../../../repository/categories.repository.js";
+import { isAdminUser } from "../../../../auth/role-predicates.js";
+import { priceGuidanceOnSellerBasis, describePriceGuidanceBasis, } from "../../../../../_internal/shared/features/categories/price-guidance.js";
+const MAX_ANCESTORS = 8;
+/**
+ * Nearest-first ancestor walk for `priceGuidance`, same shape as
+ * `description-template/route.ts`'s `resolveInherited` — the leaf's own band
+ * wins, and only a leaf with none falls back to the nearest ancestor that has
+ * one. ONE bounded `findByIds`, not a sequential walk: a seller form hitting
+ * this on every category change should not pay up to eight round trips for it.
+ */
+async function resolveInheritedGuidance(leaf) {
+    if (leaf.productDefaults?.priceGuidance)
+        return leaf.productDefaults.priceGuidance;
+    const parentIds = (leaf.parentIds ?? []).slice(0, MAX_ANCESTORS);
+    if (parentIds.length === 0)
+        return undefined;
+    const nearestFirst = [...parentIds].reverse();
+    const ancestors = await categoriesRepository.findByIds(nearestFirst);
+    const byId = new Map(ancestors.map((a) => [a.id, a]));
+    for (const pid of nearestFirst) {
+        const guidance = byId.get(pid)?.productDefaults?.priceGuidance;
+        if (guidance)
+            return guidance;
+    }
+    return undefined;
+}
+export const GET = createRouteHandler({
+    roles: ["seller", "admin", "moderator"],
+    handler: async ({ user, params }) => {
+        try {
+            const categoryId = params?.id;
+            if (!categoryId) {
+                return NextResponse.json({ success: false, error: "Missing category id" }, { status: 400 });
+            }
+            const leafDoc = await categoriesRepository.findById(categoryId);
+            if (!leafDoc) {
+                return NextResponse.json({ success: false, error: "Category not found" }, { status: 404 });
+            }
+            const guidance = await resolveInheritedGuidance(leafDoc);
+            if (!guidance) {
+                return NextResponse.json({ success: true, data: { guidance: null, basisNote: null } });
+            }
+            /*
+             * One read, admin exempted (no store to look up). `pricesIncludeGst`
+             * absent means `true` — matching the schema default and the store
+             * route's own `?? true` (see `PriceGuidanceBasis.sellerIncludesGst`'s
+             * docstring for why this must stay consistent everywhere it's read).
+             */
+            let sellerIncludesGst;
+            if (!isAdminUser(user)) {
+                const { db } = getProviders();
+                const storesRepo = db?.getRepository("stores");
+                const result = await storesRepo?.findAll({ filters: `ownerId==${user.uid}`, pageSize: 1 });
+                sellerIncludesGst = result?.data[0]?.pricesIncludeGst;
+            }
+            const basis = { sellerIncludesGst, gstRate: undefined };
+            const onSellerBasis = priceGuidanceOnSellerBasis(guidance, basis);
+            const basisNote = describePriceGuidanceBasis(basis);
+            return NextResponse.json({ success: true, data: { guidance: onSellerBasis, basisNote } }, {
+                // Per-seller basis, so never shared across callers.
+                headers: { "Cache-Control": "private, max-age=3600" },
+            });
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            serverLogger.error("price-guidance read failed", { message: e.message });
+            return NextResponse.json({ success: false, error: "Could not load price guidance" }, { status: 500 });
+        }
+    },
+});

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

@@ -7,6 +7,7 @@ import { ROUTES } from "../../../next/routing/route-map.js";
 import { Anchor, Container, Div, Dl, Dt, Dd, Heading, Main, Nav, Section, Span, Stack, Text } from "../../../ui/index.js";
 import { DynamicBgDiv } from "../../../ui/components/DynamicBgDiv.js";
 import { MediaImage } from "../../media/MediaImage.js";
+import { RichTextRenderer } from "../../../ui/rich-text/RichTextRenderer.js";
 import { BrandDetailTabs } from "./BrandDetailTabs.js";
 import { CategoryGrid } from "./CategoryGrid.js";
 import { CategoryHighlightsAndFaqSection } from "./CategoryHighlightsAndFaqSection.js";
@@ -27,8 +28,23 @@ export async function BrandDetailPageView({ slug, initialBrand }) {
     // The brand IS this page's subject — a read failure must surface rather than
     // render an anonymous, empty brand page. `undefined` still means "no such
     // brand slug".
-    const brand = (initialBrand ?? (await categoriesRepository
-        .getCategoryBySlug(slug)) ?? undefined);
+    const brandDoc = initialBrand ?? (await categoriesRepository.getCategoryBySlug(slug)) ?? undefined;
+    const brand = (brandDoc ?? undefined);
+    /*
+     * 🛑 Read from the DOCUMENT, not from the `CategoryItem` cast — the same rule
+     * `CategoryDetailPageView` states for this exact field.
+     *
+     * `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. Widening `CategoryItem` to satisfy one render site
+     * is exactly the invitation that comment warns about — and it is what the
+     * first attempt at this did, which `tsc` caught.
+     *
+     * No extra read: this page already holds the whole document (`initialBrand`,
+     * or the fetch above). Only the local cast hid it.
+     */
+    const brandContentBody = typeof brandDoc?.contentBody === "string" ? brandDoc.contentBody : null;
     const brandName = brand?.name;
     const [productsResult, tabCounts, allBundles, activeBrands, groupedListings, settings] = await Promise.all([
         brandName
@@ -152,5 +168,5 @@ export async function BrandDetailPageView({ slug, initialBrand }) {
     const ldFaq = brand?.faqs && brand.faqs.length > 0
         ? faqJsonLd(brand.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" })] })), !hasCover && (_jsx(DynamicBgDiv, { color: brandColor, className: "absolute inset-0 opacity-10" })), _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.BRANDS), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 transition-colors", children: "Brands" }), _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: brand?.name ?? slug })] }), _jsxs(Row, { className: "mb-3", align: "center", gap: "md", children: [brand?.display?.icon && (_jsx(Span, { className: "leading-none", size: "5xl", children: brand.display.icon })), _jsxs(_Fragment, { children: [_jsx(Heading, { color: "inverse", level: 1, className: `${hasCover ? "" : "text-[var(--appkit-color-text)]"}`, size: "3xl", mdSize: "4xl", weight: "bold", children: brand?.name ?? slug }), brand?.description && typeof brand.description === "string" && !brand.description.startsWith("{") && (_jsx(Text, { color: hasCover ? "inverse" : "muted", className: `max-w-2xl mt-1 ${hasCover ? "/80" : ""}`, size: "base", children: brand.description }))] })] }), _jsxs(Row, { gap: "sm", wrap: true, className: "mt-3", children: [(counts.products ?? 0) > 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: [counts.products.toLocaleString(), " ", counts.products === 1 ? "product" : "products"] })), (counts.auctions ?? 0) > 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: [counts.auctions.toLocaleString(), " ", counts.auctions === 1 ? "auction" : "auctions"] })), (counts["pre-orders"] ?? 0) > 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: [counts["pre-orders"].toLocaleString(), " ", counts["pre-orders"] === 1 ? "pre-order" : "pre-orders"] })), totalItems === 0 && (_jsx(Span, { size: "sm", className: hasCover ? "text-white/60" : "text-zinc-400", children: "No items listed yet" }))] })] })] }), (brand?.brandWebsite || brand?.brandCountry || brand?.brandFounded) && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", padding: "y-md", children: _jsx(Container, { size: "xl", children: _jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "sm", weight: "semibold", color: "muted", transform: "uppercase", children: "About this brand" }), _jsxs(Dl, { divide: "subtle", rounded: "xl", border: "subtle", className: "overflow-hidden max-w-lg", children: [brand?.brandWebsite && (_jsxs(Row, { gap: "md", oddEven: "zebra", surface: "default", padding: "inline", children: [_jsx(Dt, { className: "w-32 flex-shrink-0", color: "primary", weight: "medium", children: "Website" }), _jsx(Dd, { className: "flex-1", children: _jsx(Anchor, { href: brand.brandWebsite, tone: "brand", underline: "hover", children: brand.brandWebsite }) })] })), brand?.brandCountry && (_jsxs(Row, { gap: "md", oddEven: "zebra", surface: "default", padding: "inline", children: [_jsx(Dt, { className: "w-32 flex-shrink-0", color: "primary", weight: "medium", children: "Country" }), _jsx(Dd, { className: "flex-1", color: "muted", children: brand.brandCountry })] })), brand?.brandFounded && (_jsxs(Row, { gap: "md", oddEven: "zebra", surface: "default", padding: "inline", children: [_jsx(Dt, { className: "w-32 flex-shrink-0", color: "primary", weight: "medium", children: "Founded" }), _jsx(Dd, { className: "flex-1", color: "muted", children: brand.brandFounded })] }))] })] }) }) })), _jsx(CategoryHighlightsAndFaqSection, { highlights: brand?.highlights, faqs: brand?.faqs }), _jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: brandName ? (_jsx(BrandDetailTabs, { brandName: brandName, initialProductsData: productsResult ?? undefined, initialBundles: brandBundles, counts: counts, enabledListingTypes: enabledListingTypes(settings), enabledCategoryTypes: enabledCategoryTypes(settings) })) : (_jsx(Text, { paddingY: "3xl", color: "muted", size: "sm", align: "start", children: "Brand not found." })) }) }), groupedListings.length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(GroupedListingsCarousel, { groups: groupedListings }) }) })), relatedBrands.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-t", padding: "y-lg", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 2, className: "mb-4", size: "xl", weight: "semibold", children: "Related Brands" }), _jsx(CategoryGrid, { categories: relatedBrands, getHref: (b) => String(ROUTES.PUBLIC.BRAND_DETAIL(b.slug)) })] }) }))] }));
+    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 && (_jsx(DynamicBgDiv, { color: brandColor, className: "absolute inset-0 opacity-10" })), _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 dark:hover:text-primary-400 transition-colors", children: "Home" }), _jsx(Span, { className: hasCover ? "text-white/40" : "text-zinc-400", children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.BRANDS), className: hasCover ? "text-white/70 hover:text-white transition-colors" : "text-[var(--appkit-color-text-muted)] hover:text-primary-600 dark:hover:text-primary-400 transition-colors", children: "Brands" }), _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: brand?.name ?? slug })] }), _jsxs(Row, { className: "mb-3", align: "center", gap: "md", children: [brand?.display?.icon && (_jsx(Span, { className: "leading-none", size: "5xl", children: brand.display.icon })), _jsxs(_Fragment, { children: [_jsx(Heading, { color: "inverse", level: 1, className: `${hasCover ? "" : "text-[var(--appkit-color-text)]"}`, size: "3xl", mdSize: "4xl", weight: "bold", children: brand?.name ?? slug }), brand?.description && typeof brand.description === "string" && !brand.description.startsWith("{") && (_jsx(Text, { color: hasCover ? "inverse" : "muted", className: `max-w-2xl mt-1 ${hasCover ? "/80" : ""}`, size: "base", children: brand.description }))] })] }), _jsxs(Row, { gap: "sm", wrap: true, className: "mt-3", children: [(counts.products ?? 0) > 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: [counts.products.toLocaleString(), " ", counts.products === 1 ? "product" : "products"] })), (counts.auctions ?? 0) > 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: [counts.auctions.toLocaleString(), " ", counts.auctions === 1 ? "auction" : "auctions"] })), (counts["pre-orders"] ?? 0) > 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: [counts["pre-orders"].toLocaleString(), " ", counts["pre-orders"] === 1 ? "pre-order" : "pre-orders"] })), totalItems === 0 && (_jsx(Span, { size: "sm", className: hasCover ? "text-white/60" : "text-zinc-400", children: "No items listed yet" }))] })] })] }), (brand?.brandWebsite || brand?.brandCountry || brand?.brandFounded) && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", padding: "y-md", children: _jsx(Container, { size: "xl", children: _jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "sm", weight: "semibold", color: "muted", transform: "uppercase", children: "About this brand" }), _jsxs(Dl, { divide: "subtle", rounded: "xl", border: "subtle", className: "overflow-hidden max-w-lg", children: [brand?.brandWebsite && (_jsxs(Row, { gap: "md", oddEven: "zebra", surface: "default", padding: "inline", children: [_jsx(Dt, { className: "w-32 flex-shrink-0", color: "primary", weight: "medium", children: "Website" }), _jsx(Dd, { className: "flex-1", children: _jsx(Anchor, { href: brand.brandWebsite, tone: "brand", underline: "hover", children: brand.brandWebsite }) })] })), brand?.brandCountry && (_jsxs(Row, { gap: "md", oddEven: "zebra", surface: "default", padding: "inline", children: [_jsx(Dt, { className: "w-32 flex-shrink-0", color: "primary", weight: "medium", children: "Country" }), _jsx(Dd, { className: "flex-1", color: "muted", children: brand.brandCountry })] })), brand?.brandFounded && (_jsxs(Row, { gap: "md", oddEven: "zebra", surface: "default", padding: "inline", children: [_jsx(Dt, { className: "w-32 flex-shrink-0", color: "primary", weight: "medium", children: "Founded" }), _jsx(Dd, { className: "flex-1", color: "muted", children: brand.brandFounded })] }))] })] }) }) })), brandContentBody && brandContentBody.trim().length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(RichTextRenderer, { html: brandContentBody }) }) })), _jsx(CategoryHighlightsAndFaqSection, { highlights: brand?.highlights, faqs: brand?.faqs }), _jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: brandName ? (_jsx(BrandDetailTabs, { brandName: brandName, initialProductsData: productsResult ?? undefined, initialBundles: brandBundles, counts: counts, enabledListingTypes: enabledListingTypes(settings), enabledCategoryTypes: enabledCategoryTypes(settings) })) : (_jsx(Text, { paddingY: "3xl", color: "muted", size: "sm", align: "start", children: "Brand not found." })) }) }), groupedListings.length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(GroupedListingsCarousel, { groups: groupedListings }) }) })), relatedBrands.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-t", padding: "y-lg", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 2, className: "mb-4", size: "xl", weight: "semibold", children: "Related Brands" }), _jsx(CategoryGrid, { categories: relatedBrands, getHref: (b) => String(ROUTES.PUBLIC.BRAND_DETAIL(b.slug)) })] }) }))] }));
 }

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

@@ -35,6 +35,16 @@ const GENERIC_TAB_LISTING_TYPES = {
     [pluginFor("digital-code").tabSlug]: ["digital-code"],
     [pluginFor("live").tabSlug]: ["live"],
     [pluginFor("art").tabSlug]: ART_STICKERS_LISTING_TYPES,
+    /*
+     * Spares render generically — a product grid is the whole story, unlike an
+     * auction (countdown, bid history) or a prize draw (entries remaining).
+     *
+     * 🛑 Hand-written map; a missing entry is a tab you can CLICK that renders an
+     * empty panel. `audit-tab-body-coverage` exists for exactly this, after this
+     * file silently DROPPED four types while its `CategoryDetailTabs` twin
+     * rendered them as blank panels — two spellings of one gap.
+     */
+    [pluginFor("spares").tabSlug]: ["spares"],
 };
 export function BrandDetailTabs({ brandName, initialProductsData, initialBundles = [], counts, enabledListingTypes, enabledCategoryTypes, }) {
     const countFor = (id) => counts?.[id];

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

@@ -4,7 +4,7 @@ import { useState, useCallback, useMemo } from "react";
 import { useCategoriesFiltered } from "../hooks/useCategories.js";
 import { CATEGORY_TABS, DEFAULT_CATEGORY_TAB, matchesCategoryTab, } from "../constants/category-tabs.js";
 import { ROUTES } from "../../../next/routing/route-map.js";
-import { Button, Div, Grid, ListingFilterDrawer, ListingToolbar, Pagination, Row, Stack, Text, StickyToolbar } from "../../../ui/index.js";
+import { Div, Grid, ListingFilterDrawer, ListingToolbar, OverflowRow, Pagination, Row, Stack, Text, StickyToolbar } from "../../../ui/index.js";
 import { CategoryCard } from "./CategoryGrid.js";
 import { CategoryFilters } from "./CategoryFilters.js";
 import { useUrlTable } from "../../../react/hooks/useUrlTable.js";
@@ -170,13 +170,28 @@ export function CategoriesIndexListing({ brandsOnly = false }) {
         pageSize: PAGE_SIZE,
     });
     const activeSearch = table.get(TABLE_KEYS.QUERY) || "";
-    const TABS = CATEGORY_TABS;
-    return (_jsxs(Div, { className: "min-h-screen", children: [!brandsOnly && (_jsx(Row, { gap: "xs", border: "default", className: "border-b mb-2", children: TABS.map((tab) => (_jsx(Button, { variant: "ghost", type: "button", onClick: () => switchTab(tab.key), paddingX: "md", paddingY: "y-xs-tall", textSize: "sm", weight: "medium", className: [
-                        "transition-colors border-b-2 -mb-px rounded-none",
-                        activeTab === tab.key
-                            ? "border-primary text-primary dark:text-primary-400 dark:border-primary-400"
-                            : "border-transparent text-[var(--appkit-color-text-muted)] hover:text-zinc-800 text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text-muted)]",
-                    ].join(" "), children: tab.label }, tab.key))) })), _jsx(ListingToolbar, { filterCount: activeFilterCount, onFiltersClick: openFilters, searchValue: searchInput, searchPlaceholder: activeTab === "brands" || brandsOnly ? "Search brands..." : "Search categories...", onSearchChange: setSearchInput, onSearchCommit: commitSearch, sortValue: sort, sortOptions: SORT_OPTIONS, onSortChange: (v) => { table.set(TABLE_KEYS.SORT, v); }, view: view, onViewChange: handleViewToggle, onResetAll: resetAll, hasActiveState: hasActiveState, toggles: [
+    /*
+     * 🛑 `<OverflowRow>`, not a hand-rolled row of ghost Buttons.
+     *
+     * This was five `<Button variant="ghost">`s in a `<Row>` with a hand-written
+     * underline — no `role="tablist"`, no `role="tab"`, and no overflow
+     * behaviour at all, so on a narrow viewport the last tabs simply ran past
+     * the right edge with no scrollbar and no affordance. The Known-TS-Patterns
+     * table bans exactly that shape ("A hand-rolled overflow-x-auto row of
+     * pills/tabs → <OverflowRow>"), and the primitive built for it had shipped
+     * three weeks earlier without this surface being migrated.
+     *
+     * `variant="tabs"` because these swap a panel in place — they rewrite the
+     * `tab` URL param and re-partition one already-cached payload; they do not
+     * navigate. That is also why the items carry `onSelect` rather than `href`,
+     * and therefore why `linkProps`/`scroll` do not apply here.
+     */
+    const tabItems = CATEGORY_TABS.map((tab) => ({
+        id: tab.key,
+        label: tab.label,
+        onSelect: () => switchTab(tab.key),
+    }));
+    return (_jsxs(Div, { className: "min-h-screen", children: [!brandsOnly && (_jsx(Div, { className: "mb-2", children: _jsx(OverflowRow, { items: tabItems, activeId: activeTab, variant: "tabs", ariaLabel: "Category index sections", searchPlaceholder: "Search sections\u2026" }) })), _jsx(ListingToolbar, { filterCount: activeFilterCount, onFiltersClick: openFilters, searchValue: searchInput, searchPlaceholder: activeTab === "brands" || brandsOnly ? "Search brands..." : "Search categories...", onSearchChange: setSearchInput, onSearchCommit: commitSearch, sortValue: sort, sortOptions: SORT_OPTIONS, onSortChange: (v) => { table.set(TABLE_KEYS.SORT, v); }, view: view, onViewChange: handleViewToggle, onResetAll: resetAll, hasActiveState: hasActiveState, toggles: [
                     { label: "Featured only", active: table.get(TABLE_KEYS.IS_FEATURED) === "true", onChange: (next) => table.set(TABLE_KEYS.IS_FEATURED, next ? "true" : "") },
                 ] }), totalPages > 1 && (_jsx(StickyToolbar, { offset: "header+pagination", tone: "translucent", border: true, padding: "toolbar", children: _jsx(Row, { justify: "center", children: _jsx(Pagination, { currentPage: page, totalPages: totalPages, onPageChange: (p) => table.setPage(p) }) }) })), _jsx(Div, { padding: "y-lg", children: renderCategoryGrid({ isLoading, categories, view, activeSearch, activeTab, brandsOnly }) }), renderCategoryFilterDrawer({ filterOpen, setFilterOpen, activeFilterCount, clearFilters, applyFilters, pendingTable })] }));
 }

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

@@ -7,8 +7,8 @@ import { categoriesRepository, productRepository, storeRepository, } from "../..
 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 { OverflowRow } from "../../../ui/index.js";
 import { resolveTaxonomyVisual } from "../utils/taxonomy-visual.js";
+import { SubcategoryCardRow } from "./SubcategoryCardRow.js";
 import { CategoryDetailTabs } from "./CategoryDetailTabs.js";
 import { CategoryGrid } from "./CategoryGrid.js";
 import { CategoryHighlightsAndFaqSection } from "./CategoryHighlightsAndFaqSection.js";
@@ -49,17 +49,73 @@ const __W = "max-w-7xl mx-auto";
  * Admin surfaces that genuinely need both still show both —
  * `CategoryTableColumns` renders "own (total)" explicitly.
  */
-function toSubcategoryItems(children) {
+/*
+ * 🛑 products + auctions, SUMMED.
+ *
+ * `metrics.productCount` EXCLUDES auctions — `Tally` keeps `productIds` and
+ * `auctionIds` as separate arrays and writes `auctionCount` /
+ * `totalAuctionCount` alongside, so the comparable "how much is in here"
+ * figure is the sum of both. Reading only the product half understated every
+ * subcategory holding an auction, and understated it silently: the chip
+ * showed a plausible smaller number rather than anything that looked wrong.
+ *
+ * This page already derives its own header figures correctly that way
+ * (`productCount` and `auctionCount` resolved separately further down); this
+ * was the one place that took the product half for the whole.
+ *
+ * Prefer the rollup (`total*`) over the own-count for both halves, because a
+ * chip is a navigational promise about the whole subtree you are about to
+ * enter, not about what happens to be filed at that exact node. Shared by
+ * `toSubcategoryItems` (the chip's badge count) and the scroller's own
+ * filter below, so the two can't disagree about what "has listings" means.
+ */
+function listingCountFor(child) {
+    const products = child.metrics?.totalProductCount ?? child.metrics?.productCount ?? 0;
+    const auctions = child.metrics?.totalAuctionCount ?? child.metrics?.auctionCount ?? 0;
+    return products + auctions;
+}
+/**
+ * Direct children → the Subcategory card row's items.
+ *
+ * `descendants` is the SAME array the page already fetched, passed in so each
+ * card can carry its own direct children's names for the filter. One level
+ * only — see `SubcategoryCardRow`'s header for why matching the whole subtree
+ * would surface cards for names the visitor never sees.
+ */
+function toSubcategoryItems(children, descendants) {
+    /*
+     * Grandchildren indexed by parent in ONE pass. The alternative — filtering
+     * `descendants` inside the map — is O(children x descendants), and on the
+     * spinning-tops root that is 5 x ~1,200 per render for a list that never
+     * changes.
+     *
+     * 🛑 Keyed on `parentIds[last]`, the IMMEDIATE parent. `parentIds` holds the
+     * full ancestor chain, so testing `.includes(child.id)` would match every
+     * descendant at any depth and quietly turn the one-level rule into a
+     * whole-subtree match.
+     */
+    const childNamesByParent = new Map();
+    for (const d of descendants) {
+        const parent = d.parentIds?.[d.parentIds.length - 1];
+        if (!parent)
+            continue;
+        const list = childNamesByParent.get(parent);
+        if (list)
+            list.push(d.name);
+        else
+            childNamesByParent.set(parent, [d.name]);
+    }
     return children.map((child) => {
-        const count = child.metrics?.totalProductCount ?? child.metrics?.productCount ?? 0;
+        const count = listingCountFor(child);
         return {
             id: child.id,
-            label: child.name,
+            name: child.name,
             // Omitted rather than rendered as 0 — `count` is "not counted" when
-            // undefined, and a chip reading "0" invites a click that lands on an
+            // undefined, and a card reading "0" invites a click that lands on an
             // empty page.
             count: count > 0 ? count : undefined,
             href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(child.slug)),
+            childNames: childNamesByParent.get(child.id) ?? [],
             ...resolveTaxonomyVisual(child),
         };
     });
@@ -216,9 +272,76 @@ export async function CategoryDetailPageView({ slug }) {
             })
             : Promise.resolve([]),
     ]);
+    // 🛑 SAME TIER ONLY. `rootSiblingCategories` spans the whole root subtree —
+    // siblings AND cousins across every depth — so without a tier check this
+    // rendered deeper descendants (children, grandchildren) as "related",
+    // which reads as a second, redundant Subcategories row rather than a set
+    // of actual peers. A category with no siblings at its own tier correctly
+    // shows nothing here; the tier-grouped descendant tabs above already cover
+    // "what's below this category".
     const relatedCategories = rootSiblingCategories
-        .filter((c) => c.id !== category?.id && (!c.categoryType || c.categoryType === "category"))
+        .filter((c) => c.id !== category?.id &&
+        (!c.categoryType || c.categoryType === "category") &&
+        c.tier === category?.tier)
         .slice(0, RELATED_CATEGORY_LIMIT);
+    // 🛑 ONLY children that actually have something in them. A direct child
+    // with zero listings anywhere in its own subtree is a dead end — clicking
+    // it opens an empty category page — so it's dropped from the chip row
+    // rather than rendered with no count badge. `listingCountFor` reads the
+    // ROLLUP (own + descendants), so a child that merely has no listings of
+    // its OWN but does further down is correctly kept.
+    const directChildrenWithListings = childCategories
+        .filter((c) => c.tier === (category?.tier ?? 0) + 1)
+        .filter((c) => listingCountFor(c) > 0);
+    /*
+     * The ancestor chain as cards, root first.
+     *
+     * 🛑 `ancestor.id` is used as the slug, which is correct HERE and is not a
+     * general licence: categories are one of this codebase's "pure slug"
+     * collections (`id === slug`), so the two are interchangeable for a category
+     * row. `CategoryAncestor` carries only `{id, name, tier}` — no slug field —
+     * so the alternative would be a lookup per ancestor for a value already in
+     * hand.
+     *
+     * `tier` comes from the stored ancestor rather than the array index: the
+     * index is only the depth if the chain is complete, and a chain that skipped
+     * a tier would silently relabel every level below it (the closure-skip case
+     * CLAUDE.md records under the counters invariant).
+     */
+    /*
+     * `CategoryAncestor` is `{id, name, tier}` and carries no display block, so
+     * the artwork is looked up in rows this page ALREADY fetched —
+     * `rootSiblingCategories` spans the whole root subtree, which is where an
+     * ancestor lives. A miss simply yields no visual and the card falls back,
+     * which is why this is a plain lookup and not another read.
+     */
+    const rowsById = new Map();
+    for (const c of [...rootSiblingCategories, ...childCategories]) {
+        if (c?.id)
+            rowsById.set(c.id, c);
+    }
+    /*
+     * 🛑 The IMMEDIATE parent only — one card, never the chain.
+     *
+     * `ancestors` is ordered root-first, so the last entry is the direct parent
+     * and everything before it is a grandparent. Rendering the whole ladder put
+     * four cards on a tier-4 page for a path the breadcrumb at the top of the
+     * page already spells out in full, and the uncles/grandparents are not
+     * places you step to from here — the one move this row needs to afford is
+     * "up one".
+     */
+    const immediateParent = (category?.ancestors ?? []).at(-1);
+    const parentLadder = immediateParent
+        ? [
+            {
+                id: immediateParent.id,
+                name: immediateParent.name,
+                href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(immediateParent.id)),
+                level: immediateParent.tier,
+                ...resolveTaxonomyVisual(rowsById.get(immediateParent.id) ?? null),
+            },
+        ]
+        : [];
     // Stores tab — stores whose storeCategory is this category or ANY descendant.
     //
     // `storeCategory` is a single slug with no ancestor chain (unlike a product's
@@ -282,7 +405,16 @@ export async function CategoryDetailPageView({ slug }) {
          * and it cast `createdAt` through `as unknown as string` where the adapter
          * converts a Timestamp properly.
          */
-        .map((s) => toStoreListItem(s));
+        .map((s) => toStoreListItem(s))
+        // 🛑 `storeCategory` is a one-time "primarily sells this" tag, not proof
+        // of current stock — a store can match the category and still have
+        // nothing listed right now (the exact shape of the empty-store report
+        // this filter closes). Listing it here sends a visitor into a store page
+        // with nothing to buy, so only stores that actually have products are
+        // kept. `totalProducts` is the denormalised `stats.totalProducts`
+        // counter, incremented atomically on create/delete — cheap to read here,
+        // unlike a per-store query.
+        .filter((s) => (s.totalProducts ?? 0) > 0);
     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
@@ -430,7 +562,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" })] })), !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)) })] }) }) })), (() => {
+    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"] }))] })] })] }), category?.hasbroName && (_jsx(Section, { padding: "y-md", children: _jsx(Container, { size: "xl", children: _jsxs(Row, { gap: "md", align: "center", wrap: true, children: [category.hasbroCoverImage && (_jsx(MediaImage, { src: category.hasbroCoverImage, alt: `${category.hasbroName} logo`, size: "thumbnail", className: "h-12 w-auto flex-shrink-0" })), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", transform: "uppercase", weight: "medium", children: "Also known as" }), _jsx(Text, { weight: "semibold", children: category.hasbroName }), _jsxs(Text, { size: "xs", color: "muted", children: ["The same wave, named differently outside Japan \u2014 Takara-Tomy releases it as ", category.name, ", Hasbro as ", category.hasbroName, ". Both names find these listings."] })] })] }) }) })), 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);
@@ -455,10 +587,5 @@ export async function CategoryDetailPageView({ slug }) {
                                 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: (() => {
-                        const directChildren = childCategories.filter((c) => c.tier === (category?.tier ?? 0) + 1);
-                        if (directChildren.length === 0)
-                            return null;
-                        return (_jsxs(Div, { padding: "b-2xs", children: [_jsx(Text, { size: "xs", color: "muted", weight: "medium", className: "mb-[var(--appkit-space-1-5)]", children: "Subcategories" }), _jsx(OverflowRow, { items: toSubcategoryItems(directChildren), ariaLabel: "Subcategories", variant: "nav", placeholder: "Browse subcategories", searchPlaceholder: "Search subcategories\u2026", noResultsText: "No matching subcategory" })] }));
-                    })() }) })), _jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(CategoryDetailTabs, { categorySlug: slug, categoryId: category?.id, initialProductsData: productsResult ?? undefined, initialBundles: bundlesResult ?? [], initialStores: categoryStores, counts: counts, enabledListingTypes: enabledListingTypes(settings), enabledCategoryTypes: enabledCategoryTypes(settings) }) }) }), groupedListings.length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(GroupedListingsCarousel, { groups: groupedListings }) }) })), relatedCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-t", padding: "y-lg", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 2, className: "mb-4", size: "xl", weight: "semibold", children: "Related Categories" }), _jsx(CategoryGrid, { categories: relatedCategories, getHref: (c) => String(ROUTES.PUBLIC.CATEGORY_DETAIL(c.slug)) })] }) }))] }));
+            })(), directChildrenWithListings.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: __W, padding: "inline", children: _jsxs(Div, { padding: "b-2xs", children: [parentLadder.length > 0 && (_jsx(Div, { padding: "b-2xs", children: _jsx(SubcategoryCardRow, { items: parentLadder, label: "Parent category" }) })), _jsx(SubcategoryCardRow, { items: toSubcategoryItems(directChildrenWithListings, childCategories) })] }) }) })), _jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(CategoryDetailTabs, { categorySlug: slug, categoryId: category?.id, initialProductsData: productsResult ?? undefined, initialBundles: bundlesResult ?? [], initialStores: categoryStores, counts: counts, enabledListingTypes: enabledListingTypes(settings), enabledCategoryTypes: enabledCategoryTypes(settings) }) }) }), groupedListings.length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(GroupedListingsCarousel, { groups: groupedListings }) }) })), relatedCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-t", padding: "y-lg", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 2, className: "mb-4", size: "xl", weight: "semibold", children: "Related Categories" }), _jsx(CategoryGrid, { categories: relatedCategories, getHref: (c) => String(ROUTES.PUBLIC.CATEGORY_DETAIL(c.slug)) })] }) }))] }));
 }

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

@@ -37,6 +37,18 @@ const GENERIC_TAB_LISTING_TYPES = {
     [pluginFor("live").tabSlug]: ["live"],
     // The combined Art & Stickers tab spans both types under the `art` slug.
     [pluginFor("art").tabSlug]: ART_STICKERS_LISTING_TYPES,
+    /*
+     * Spares render generically — there is nothing type-specific to show beyond
+     * a product grid, unlike an auction (countdown, bid history) or a prize draw
+     * (entries remaining).
+     *
+     * 🛑 This map is hand-written and a missing entry is a tab you can CLICK that
+     * renders an empty panel. It is covered — `audit-tab-body-coverage` exists
+     * for precisely this, after `CategoryDetailTabs` showed a blank panel for
+     * four types while `BrandDetailTabs` silently dropped the same four — so the
+     * eleventh type will be caught rather than discovered.
+     */
+    [pluginFor("spares").tabSlug]: ["spares"],
 };
 export function CategoryDetailTabs({ categorySlug, categoryId, initialProductsData, initialBundles = [], initialStores = [], counts, enabledListingTypes, enabledCategoryTypes, }) {
     const countFor = (id) => counts?.[id];

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

@@ -18,7 +18,16 @@ export function CategoryCard({ category, href, onClick, className = "", }) {
     // own-node-only productCount so a parent category's card shows the same
     // "N products" a visitor actually sees once they open the page.
     const productCount = category.metrics?.totalProductCount ?? category.metrics?.productCount ?? category.productCount ?? 0;
-    const inner = (_jsxs(Stack, { className: "h-full", children: [_jsxs(Div, { surface: "muted", className: `relative aspect-[4/3] w-full ${__O.hidden} flex-shrink-0`, children: [(category.display?.mosaicImages?.length ?? 0) >= MOSAIC_MIN ? (_jsx(ImageMosaic, { images: category.display.mosaicImages, alt: category.name, className: "h-full w-full" })) : category.display?.coverImage ? (_jsx(MediaImage, { src: category.display.coverImage, alt: category.name, size: "card", className: "transition-transform duration-300 group-hover:scale-105" })) : category.display?.color ? (_jsx(DynamicBgDiv, { color: category.display.color, className: "h-full w-full opacity-80" })) : null, category.display?.icon && (_jsx(Row, { textSize: "4xl", className: "absolute inset-0", align: "center", justify: "center", children: category.display.icon })), category.isFeatured && (_jsx(Span, { size: "xs", className: CLS_FEATURED_DOT, children: "\u2605" }))] }), _jsxs(Stack, { className: `flex-1 ${__P.p3}.5`, children: [_jsx(Text, { color: "inverse", className: `leading-snug text-[var(--appkit-color-text)] dark:`, truncate: 2, size: "sm", weight: "semibold", children: category.name }), category.description && (_jsx(Text, { className: `mt-1 flex-1`, color: "muted", truncate: 2, size: "xs", children: category.description })), _jsxs(Row, { className: "mt-2", align: "center", justify: "between", gap: "sm", children: [_jsxs(Text, { size: "xs", color: "faint", children: [productCount.toLocaleString(), " ", productCount === 1 ? "item" : "items"] }), _jsxs(Span, { layout: "inline-flex", gap: "xs", size: "xs", weight: "medium", border: "default", className: "group-hover:bg-primary group-hover:border-primary group-hover:text-white transition-colors", rounded: "md", padding: "pill-sm-tall", color: "muted", children: ["Browse ", _jsx(ArrowRight, { className: "h-3 w-3" })] })] })] })] }));
+    /*
+     * Is a real picture going to render in the image area? Drives the emoji
+     * overlay below, which must not paint over artwork. Deliberately mirrors the
+     * first two branches of the chain rather than being derived from it — the
+     * `color` branch is a flat tint, which an emoji on top of is still the
+     * intended look.
+     */
+    const hasArtwork = (category.display?.mosaicImages?.length ?? 0) >= MOSAIC_MIN ||
+        Boolean(category.display?.coverImage);
+    const inner = (_jsxs(Stack, { className: "h-full", children: [_jsxs(Div, { surface: "muted", className: `relative aspect-[4/3] w-full ${__O.hidden} flex-shrink-0`, children: [(category.display?.mosaicImages?.length ?? 0) >= MOSAIC_MIN ? (_jsx(ImageMosaic, { images: category.display.mosaicImages, alt: category.name, className: "h-full w-full" })) : category.display?.coverImage ? (_jsx(MediaImage, { src: category.display.coverImage, alt: category.name, size: "card", className: "transition-transform duration-300 group-hover:scale-105" })) : category.display?.color ? (_jsx(DynamicBgDiv, { color: category.display.color, className: "h-full w-full opacity-80" })) : null, category.display?.icon && !hasArtwork && (_jsx(Row, { textSize: "4xl", className: "absolute inset-0", align: "center", justify: "center", children: category.display.icon })), category.isFeatured && (_jsx(Span, { size: "xs", className: CLS_FEATURED_DOT, children: "\u2605" }))] }), _jsxs(Stack, { className: `flex-1 ${__P.p3}.5`, children: [_jsx(Text, { color: "inverse", className: `leading-snug text-[var(--appkit-color-text)] dark:`, truncate: 2, size: "sm", weight: "semibold", children: category.name }), category.description && (_jsx(Text, { className: `mt-1 flex-1`, color: "muted", truncate: 2, size: "xs", children: category.description })), _jsxs(Row, { className: "mt-2", align: "center", justify: "between", gap: "sm", children: [_jsxs(Text, { size: "xs", color: "faint", children: [productCount.toLocaleString(), " ", productCount === 1 ? "item" : "items"] }), _jsxs(Span, { layout: "inline-flex", gap: "xs", size: "xs", weight: "medium", border: "default", className: "group-hover:bg-primary group-hover:border-primary group-hover:text-white transition-colors", rounded: "md", padding: "pill-sm-tall", color: "muted", children: ["Browse ", _jsx(ArrowRight, { className: "h-3 w-3" })] })] })] })] }));
     const cardClass = `group relative flex flex-col overflow-hidden rounded-xl border border-neutral-200 bg-[var(--appkit-color-surface)] border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] shadow-sm transition hover:shadow-md h-full ${className}`;
     if (href) {
         return (_jsx(Link, { href: href, className: cardClass, children: inner }));

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

@@ -0,0 +1,29 @@
+import React from "react";
+export interface PriceGuidanceHintProps {
+    /** Leaf category id/slug the listing is filed under. */
+    categoryId: string;
+    currency?: string;
+    className?: string;
+}
+/**
+ * The seller-facing price hint `description-template/route.ts`'s own
+ * docstring names as "C1's job, from a surface that knows who is asking" —
+ * renders the inherited competitor-derived market band beside the price
+ * field, on the SELLER'S own tax basis (the `/price-guidance` endpoint does
+ * that conversion server-side; this component only formats what it returns).
+ *
+ * Mounted via `ProductForm`'s `renderPriceGuidance` slot rather than fetched
+ * unconditionally inside the form — `ProductForm` has no data-fetching of its
+ * own (every app-specific concern is a render-prop), and this component is
+ * seller/admin-only, not something the form itself should assume a caller
+ * wants.
+ *
+ * 🛑 NEVER mount this on a public page (category/brand detail). A
+ * competitor-derived market band is exactly the "a neighbouring surface
+ * publishes the range" leak the guest price gate exists to close (CLAUDE.md
+ * § "Guest price gating"), even though the figure is advisory rather than a
+ * real listing price — which is also why `/price-guidance` itself is
+ * seller/admin/moderator-gated, not a public, edge-cached endpoint like its
+ * `description-template` sibling.
+ */
+export declare function PriceGuidanceHint({ categoryId, currency, className, }: PriceGuidanceHintProps): React.JSX.Element | null;