@mohasinac/appkit 4.50.0 → 4.52.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.50.0",
-  "head": "cc3acd12565598821ab36a76ec2fe0c286ca8299",
+  "version": "4.52.0",
+  "head": "5e6e4777891284de76aa0d646e556f8aee0ff76e",
   "branch": "main",
   "dirty": false,
-  "builtAt": "2026-10-14T06:47:51.500Z"
+  "builtAt": "2026-10-14T12:39:32.737Z"
 }

package/dist/_internal/server/features/franchises/data.d.ts

@@ -0,0 +1,32 @@
+import type { CategoryDocument } from "../../../../features/categories/schemas";
+/**
+ * SSR reads for the FRANCHISE unit — what a product is FROM, where a brand is
+ * who made it.
+ *
+ * 🛑 Wrapped in `React.cache` because each of these is called by BOTH the page
+ * body and its `generateMetadata`. Without it that is two identical Firestore
+ * reads per render, on routes that are meant to be cheap (CLAUDE.md, "React.cache
+ * discipline").
+ *
+ * The argument list is the cache key, so these take the slug and nothing else —
+ * adding a viewer parameter here would give every call site its own entry and
+ * dedupe nothing.
+ *
+ * @tag domain:categories
+ * @tag layer:server
+ * @tag access:server-only
+ * @tag sideEffects:firestore-read
+ */
+/**
+ * One franchise by slug.
+ *
+ * 🛑 Deliberately NOT filtered on `isActive`. Seven of the eight seeded
+ * franchises are inactive because they have no stock yet, and the entire point
+ * of seeding them is that `/franchise/marvel` resolves instead of 404ing — the
+ * eighteen `CharacterHotspot` links pointed at a route that did not exist. The
+ * grid is where inactive rows are hidden (`findActiveFranchises`); the detail
+ * page renders them as an honest "nothing here yet".
+ */
+export declare const getFranchiseForDetail: (slug: string) => Promise<CategoryDocument | null>;
+/** Every franchise a visitor may browse — active only, so no dead facets. */
+export declare const listActiveFranchises: () => Promise<CategoryDocument[]>;

package/dist/_internal/server/features/franchises/data.js

@@ -0,0 +1,33 @@
+import { cache } from "react";
+import { categoriesRepository } from "../../../../features/categories/repository/categories.repository.js";
+/**
+ * SSR reads for the FRANCHISE unit — what a product is FROM, where a brand is
+ * who made it.
+ *
+ * 🛑 Wrapped in `React.cache` because each of these is called by BOTH the page
+ * body and its `generateMetadata`. Without it that is two identical Firestore
+ * reads per render, on routes that are meant to be cheap (CLAUDE.md, "React.cache
+ * discipline").
+ *
+ * The argument list is the cache key, so these take the slug and nothing else —
+ * adding a viewer parameter here would give every call site its own entry and
+ * dedupe nothing.
+ *
+ * @tag domain:categories
+ * @tag layer:server
+ * @tag access:server-only
+ * @tag sideEffects:firestore-read
+ */
+/**
+ * One franchise by slug.
+ *
+ * 🛑 Deliberately NOT filtered on `isActive`. Seven of the eight seeded
+ * franchises are inactive because they have no stock yet, and the entire point
+ * of seeding them is that `/franchise/marvel` resolves instead of 404ing — the
+ * eighteen `CharacterHotspot` links pointed at a route that did not exist. The
+ * grid is where inactive rows are hidden (`findActiveFranchises`); the detail
+ * page renders them as an honest "nothing here yet".
+ */
+export const getFranchiseForDetail = cache(async (slug) => categoriesRepository.findBySlugAndType(slug, "franchise"));
+/** Every franchise a visitor may browse — active only, so no dead facets. */
+export const listActiveFranchises = cache(async () => categoriesRepository.findActiveFranchises());

package/dist/_internal/server/features/franchises/index.d.ts

@@ -0,0 +1,2 @@
+export { getFranchiseForDetail, listActiveFranchises } from "./data";
+export { renderFranchiseOg } from "./og";

package/dist/_internal/server/features/franchises/index.js

@@ -0,0 +1,2 @@
+export { getFranchiseForDetail, listActiveFranchises } from "./data.js";
+export { renderFranchiseOg } from "./og.js";

package/dist/_internal/server/features/franchises/og.d.ts

@@ -0,0 +1,31 @@
+import type { ReactElement } from "react";
+/**
+ * OG card for a FRANCHISE page.
+ *
+ * 🛑 Delegates to `renderBrandOgImage` rather than copying its layout. That
+ * renderer already takes a generic `{ name, description, logoUrl }` and a
+ * franchise card is the same shape as a brand card — a cover image, a title and
+ * a line of copy. Forking it would give the two surfaces independent drift for
+ * no visual difference, which is the duplication the Rule of Three exists to
+ * prevent (two copies is observation; this is the second).
+ *
+ * If a franchise card ever needs its own treatment, the split happens at THAT
+ * point, with a reason — not pre-emptively.
+ *
+ * @tag domain:categories
+ * @tag layer:server
+ * @tag access:server-only
+ */
+interface FranchiseDocLike {
+    name?: string | null;
+    description?: string | null;
+    /** Same field as brands — `CategoryDocument` has no dedicated logo field. */
+    display?: {
+        coverImage?: string | null;
+    } | null;
+}
+export declare function renderFranchiseOg(doc: FranchiseDocLike | null | undefined, opts: {
+    siteName: string;
+    baseUrl?: string;
+}): ReactElement;
+export {};

package/dist/_internal/server/features/franchises/og.js

@@ -0,0 +1,11 @@
+import { resolveOgImageUrl } from "../seo/og.js";
+import { renderBrandOgImage } from "../brands/og.js";
+export function renderFranchiseOg(doc, opts) {
+    const name = doc?.name ?? "Franchise";
+    return renderBrandOgImage({
+        name,
+        description: doc?.description?.slice(0, 120) ??
+            `Shop ${name} collectibles on ${opts.siteName}.`,
+        logoUrl: resolveOgImageUrl(doc?.display?.coverImage ?? null, opts.baseUrl),
+    }, opts.siteName);
+}

package/dist/_internal/server/features/products/list-public.d.ts

@@ -45,6 +45,15 @@ export interface PublicProductListInput {
     q?: string;
     category?: string;
     brand?: string;
+    /**
+     * The IP the product is from, matched on `franchiseSlug`.
+     *
+     * 🛑 On the SLUG, not the display name — unlike `brand` directly above,
+     * which filters on `PRODUCT_FIELDS.BRAND` (the display name) and therefore
+     * orphans a brand's whole catalogue the moment anyone renames it. Franchise
+     * is new, so it gets the stable key rather than inheriting that trap.
+     */
+    franchiseSlug?: string;
     /** Pipe-joined multi-select (`new|used`) — emitted as an OR-group, never as AND. */
     condition?: string;
     storeId?: string;

package/dist/_internal/server/features/products/list-public.js

@@ -267,6 +267,9 @@ function buildFirestoreSafeFilters(input, opts) {
     }
     if (input.brand)
         parts.push(sieveFilter(PRODUCT_FIELDS.BRAND, SIEVE_OP.EQ, input.brand));
+    if (input.franchiseSlug) {
+        parts.push(sieveFilter(PRODUCT_FIELDS.FRANCHISE_SLUG, SIEVE_OP.EQ, input.franchiseSlug));
+    }
     if (input.condition) {
         // Pipe-joined OR-group, NOT `sieveMultiEq` — that emits
         // `condition==new,condition==used`, an AND of two equalities on one field,

package/dist/constants/field-names.d.ts

@@ -42,6 +42,8 @@ export declare const PRODUCT_FIELDS: {
     readonly SUBCATEGORY: "subcategory";
     readonly BRAND: "brand";
     readonly BRAND_SLUG: "brandSlug";
+    readonly FRANCHISE: "franchise";
+    readonly FRANCHISE_SLUG: "franchiseSlug";
     readonly PRICE: "price";
     readonly CURRENCY: "currency";
     readonly STOCK_QUANTITY: "stockQuantity";
@@ -529,6 +531,7 @@ export declare const CATEGORY_FIELDS: {
         readonly BRAND: "brand";
         readonly SUBLISTING: "sublisting";
         readonly BUNDLE: "bundle";
+        readonly FRANCHISE: "franchise";
     };
     readonly BUNDLE_STOCK_STATUS_VALUES: {
         readonly AVAILABLE: "available";

package/dist/constants/field-names.js

@@ -49,6 +49,10 @@ export const PRODUCT_FIELDS = {
     SUBCATEGORY: "subcategory",
     BRAND: "brand",
     BRAND_SLUG: "brandSlug",
+    /* The IP a product is from. Matched on the SLUG, never the display name —
+     * see the note on `ProductDocument.franchiseSlug`. */
+    FRANCHISE: "franchise",
+    FRANCHISE_SLUG: "franchiseSlug",
     PRICE: "price",
     CURRENCY: "currency",
     STOCK_QUANTITY: "stockQuantity",
@@ -604,6 +608,13 @@ export const CATEGORY_FIELDS = {
         BRAND: "brand",
         SUBLISTING: "sublisting",
         BUNDLE: "bundle",
+        /*
+         * The IP a product belongs to — Beyblade, Pokémon, Marvel. A sibling of
+         * BRAND, not of CATEGORY: both are tier-0 rows outside the forest's DFS
+         * numbering that a product points AT, rather than nodes it lives under.
+         * A brand is who MADE it (Takara-Tomy); a franchise is what it IS FROM.
+         */
+        FRANCHISE: "franchise",
     },
     BUNDLE_STOCK_STATUS_VALUES: {
         AVAILABLE: "available",

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

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 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 { CategoryCard } from "./CategoryGrid.js";
@@ -20,11 +21,16 @@ const PAGE_SIZE = 24;
 function renderCategoryGrid(props) {
     const { isLoading, categories, view, activeSearch, activeTab, brandsOnly } = props;
     const isBrandView = activeTab === "brands" || brandsOnly;
+    /* The empty state names the tab the visitor is actually on. It said
+     * "categories" on all five, so an empty Parts tab reported the wrong thing. */
+    const noun = brandsOnly
+        ? "brands"
+        : (CATEGORY_TABS.find((t) => t.key === activeTab)?.label ?? "categories").toLowerCase();
     if (isLoading) {
         return (_jsx(Grid, { cols: "categoryCards", gap: "md", children: Array.from({ length: 10 }).map((_, i) => (_jsxs(Div, { className: `${__O.hidden} animate-pulse`, border: "subtle", rounded: "xl", children: [_jsx(Div, { className: "aspect-[4/3]", surface: "subtle" }), _jsxs(Stack, { className: `${__P.p3}.5`, gap: "sm", children: [_jsx(Div, { className: "h-3.5 w-3/4", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-3 w-full", surface: "subtle", rounded: "default" })] })] }, i))) }));
     }
     if (categories.length === 0) {
-        return (_jsx(Text, { paddingY: "3xl", color: "muted", size: "sm", align: "start", children: activeSearch ? `No ${isBrandView ? "brands" : "categories"} matching "${activeSearch}"` : isBrandView ? "No brands found" : "No categories found" }));
+        return (_jsx(Text, { paddingY: "3xl", color: "muted", size: "sm", align: "start", children: activeSearch ? `No ${noun} matching "${activeSearch}"` : `No ${noun} found` }));
     }
     if (view === "list") {
         return (_jsx(Stack, { className: "divide-y divide-zinc-100 divide-[var(--appkit-color-border-subtle)]", border: "subtle", rounded: "xl", children: categories.map((category) => _jsx(CategoryCard, { category: category, href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category.slug)) }, category.id)) }));
@@ -131,12 +137,21 @@ export function CategoriesIndexListing({ brandsOnly = false }) {
     const commitSearch = useCallback(() => {
         table.set(TABLE_KEYS.QUERY, searchInput.trim());
     }, [searchInput, table]);
-    // Tab state — "all" | "categories" | "brands" (not used when brandsOnly=true)
-    const activeTab = brandsOnly ? "brands" : (table.get(TABLE_KEYS.TAB) || "all");
-    const isBrandParam = brandsOnly ? true :
-        activeTab === "brands" ? true :
-            activeTab === "categories" ? false :
-                undefined;
+    /*
+     * Tab state. Five tabs, no "All" — see `category-tabs.ts`: "All" was the
+     * default and it was what rendered 1,185 undifferentiated rows.
+     */
+    const rawTab = brandsOnly ? "brands" : table.get(TABLE_KEYS.TAB) || DEFAULT_CATEGORY_TAB;
+    const activeTab = (CATEGORY_TABS.some((t) => t.key === rawTab)
+        ? rawTab
+        : DEFAULT_CATEGORY_TAB);
+    /*
+     * 🛑 The fetch stays unfiltered (`?flat=true`) and the TABS partition that one
+     * cached response — a per-tab query would turn one request into five for the
+     * same data. `isBrand` is still sent for the brands tab because the API has a
+     * dedicated clause for it; everything else is partitioned below.
+     */
+    const isBrandParam = activeTab === "brands" ? true : undefined;
     const switchTab = (key) => {
         table.set(TABLE_KEYS.TAB, key);
     };
@@ -144,6 +159,8 @@ export function CategoriesIndexListing({ brandsOnly = false }) {
         q: table.get(TABLE_KEYS.QUERY) || undefined,
         isFeatured: table.get(TABLE_KEYS.IS_FEATURED) === "true" || undefined,
         isBrand: isBrandParam,
+        // The tab partition — applied before pagination inside the hook.
+        predicate: (c) => matchesCategoryTab(c, activeTab),
         rootOnly: table.get("rootOnly") === "true" || undefined,
         tier: getNumericParam(table, "tier"),
         minProductCount: getNumericParam(table, "minItemCount"),
@@ -153,11 +170,7 @@ export function CategoriesIndexListing({ brandsOnly = false }) {
         pageSize: PAGE_SIZE,
     });
     const activeSearch = table.get(TABLE_KEYS.QUERY) || "";
-    const TABS = [
-        { key: "all", label: "All" },
-        { key: "categories", label: "Categories" },
-        { key: "brands", label: "Brands" },
-    ];
+    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

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

@@ -4,6 +4,7 @@ import { ArrowRight } from "lucide-react";
 import { Div, Grid, Row, Span, Stack, Text } from "../../../ui/index.js";
 import { DynamicBgDiv } from "../../../ui/components/DynamicBgDiv.js";
 import { MediaImage } from "../../media/MediaImage.js";
+import { ImageMosaic, MOSAIC_MIN } from "../../../ui/components/ImageMosaic.js";
 const __P = {
     p3: "p-[var(--appkit-space-3)]",
 };
@@ -17,7 +18,7 @@ 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?.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" })] })] })] })] }));
+    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" })] })] })] })] }));
     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/FranchiseDetailPageView.d.ts

@@ -0,0 +1,25 @@
+import type { CategoryDocument } from "../schemas";
+/**
+ * A FRANCHISE page — every listing from one IP.
+ *
+ * 🛑 Products are matched on `franchiseSlug`, NOT on the display name. That is
+ * the one place this deliberately diverges from `BrandDetailPageView`, which
+ * filters `sieveFilter("brand", EQ, brandName)` and therefore orphans a brand's
+ * entire catalogue the moment anyone renames it (`_helpers/brand-rows.ts`,
+ * trap 1). Franchise is new, so it starts with the stable key.
+ *
+ * 🛑 An INACTIVE franchise still renders. Seven of the eight seeded rows have
+ * no stock and are inactive precisely so they stay out of the grid — but their
+ * pages must resolve, because `CharacterHotspot` ships eighteen `/franchise/*`
+ * links that were 404ing. An inactive row renders an honest "nothing listed
+ * yet" rather than a dead end or a lie.
+ *
+ * @tag domain:categories
+ * @tag layer:view
+ * @tag access:server-only
+ */
+export interface FranchiseDetailPageViewProps {
+    slug: string;
+    franchise: CategoryDocument;
+}
+export declare function FranchiseDetailPageView({ slug, franchise, }: FranchiseDetailPageViewProps): Promise<import("react").JSX.Element>;

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

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { listPublicProducts } from "../../../_internal/server/features/products/list-public.js";
+import { toProductItem } from "../../../_internal/shared/features/products/to-product-item.js";
+import { safeRead } from "../../../errors/safe-read.js";
+import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
+import { Container, Row, Stack } from "../../../ui/components/Layout.js";
+import { Main, Section } from "../../../ui/components/Semantic.js";
+import { Heading, Text } from "../../../ui/components/Typography.js";
+import { MediaImage } from "../../media/MediaImage.js";
+import { ProductGrid } from "../../products/components/ProductGrid.js";
+import { Alert } from "../../../ui/components/Alert.js";
+const PAGE_SIZE = 24;
+export async function FranchiseDetailPageView({ slug, franchise, }) {
+    const result = await safeRead(() => listPublicProducts({
+        franchiseSlug: slug,
+        page: 1,
+        pageSize: PAGE_SIZE,
+    }), { route: "/franchise/[slug]", key: "franchise.products", fallback: null });
+    /*
+     * Every scalar read off `result` happens HERE, before the narrowing below —
+     * `audit-projection-shadow` is right that reading the raw result after
+     * taking a projection of it is the shape that lets a repository document
+     * leak onward (Root Cause #70). These three are the only things the view
+     * needs from it.
+     */
+    const readFailed = result === null;
+    const truncated = result?.truncated === true;
+    const reportedTotal = result?.total;
+    /*
+     * `hidePublicTestData` widens to its own `TestDataFlagged` shape, which has
+     * no index signature and so does not satisfy `toProductItem`'s
+     * `FirestoreDocument` parameter. The cast is at the adapter boundary and
+     * restores the type the repository actually returned — not a claim about
+     * unknown data.
+     */
+    const rows = hidePublicTestData(result?.items ?? []);
+    const products = rows.map((r) => toProductItem(r));
+    const total = reportedTotal ?? products.length;
+    const cover = franchise.display?.coverImage;
+    return (_jsx(Main, { children: _jsx(Section, { padding: "y-2xl", children: _jsxs(Container, { size: "xl", children: [_jsxs(Row, { align: "center", gap: "comfortable", className: "mb-8", children: [cover ? (_jsx(MediaImage, { src: cover, alt: franchise.name ?? slug, size: "thumbnail", rounded: "lg" })) : null, _jsxs(Stack, { gap: "dense", children: [_jsx(Heading, { level: 1, color: "primary", size: "3xl", weight: "semibold", children: franchise.name }), franchise.description ? (_jsx(Text, { color: "muted", className: "max-w-2xl", children: franchise.description })) : null] })] }), franchise.isActive === false ? (_jsxs(Alert, { variant: "info", className: "mb-6", children: ["We are not stocking ", franchise.name, " yet. This page is here so the link works \u2014 check back, or browse what we do carry."] })) : null, readFailed ? (_jsxs(Alert, { variant: "warning", children: ["We could not load ", franchise.name, " listings just now. Please try again."] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: "muted", className: "mb-4", children: total === 0
+                                    ? "No listings yet."
+                                    : `${total}${truncated ? "+" : ""} listing${total === 1 ? "" : "s"}` }), _jsx(ProductGrid, { products: products, emptyLabel: "No listings yet." })] }))] }) }) }));
+}

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

@@ -0,0 +1,14 @@
+/**
+ * The FRANCHISE index — the IPs we carry.
+ *
+ * 🛑 ACTIVE ONLY, and that is the dead-facet guard. `brand-rows.ts` trap 3:
+ * "a row with no product is a DEAD FACET, and worse than absent — it renders
+ * as a card in the grid that opens an empty page." Seven of the eight seeded
+ * franchises have no stock yet; they stay out of here until one flag flips,
+ * while their detail pages still resolve for the links that point at them.
+ *
+ * @tag domain:categories
+ * @tag layer:view
+ * @tag access:server-only
+ */
+export declare function FranchisesIndexView(): Promise<import("react").JSX.Element>;

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

@@ -0,0 +1,33 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { listActiveFranchises } from "../../../_internal/server/features/franchises/data.js";
+import { safeRead } from "../../../errors/safe-read.js";
+import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
+import { Container, Grid } from "../../../ui/components/Layout.js";
+import { Main, Section } from "../../../ui/components/Semantic.js";
+import { Heading, Text } from "../../../ui/components/Typography.js";
+import { Div } from "../../../ui/components/Div.js";
+import { TextLink } from "../../../ui/components/TextLink.js";
+import { MediaImage } from "../../media/MediaImage.js";
+import { Alert } from "../../../ui/components/Alert.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+/**
+ * The FRANCHISE index — the IPs we carry.
+ *
+ * 🛑 ACTIVE ONLY, and that is the dead-facet guard. `brand-rows.ts` trap 3:
+ * "a row with no product is a DEAD FACET, and worse than absent — it renders
+ * as a card in the grid that opens an empty page." Seven of the eight seeded
+ * franchises have no stock yet; they stay out of here until one flag flips,
+ * while their detail pages still resolve for the links that point at them.
+ *
+ * @tag domain:categories
+ * @tag layer:view
+ * @tag access:server-only
+ */
+export async function FranchisesIndexView() {
+    const franchises = await safeRead(() => listActiveFranchises().then(hidePublicTestData), {
+        route: "/franchise",
+        key: "franchises.list",
+        fallback: null,
+    });
+    return (_jsx(Main, { children: _jsx(Section, { padding: "y-2xl", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 1, className: "mb-2", color: "primary", size: "3xl", weight: "semibold", children: "Franchises" }), _jsx(Text, { color: "muted", className: "mb-8", children: "The universes we stock. A franchise is what a collectible is from \u2014 a brand is who made it." }), franchises === null ? (_jsx(Alert, { variant: "warning", children: "We could not load the franchise list just now. Please try again." })) : franchises.length === 0 ? (_jsx(Alert, { variant: "info", children: "No franchises are live yet." })) : (_jsx(Grid, { cols: "cards", gap: "comfortable", children: franchises.map((f) => (_jsx(TextLink, { href: ROUTES.PUBLIC.FRANCHISE_DETAIL(String(f.slug ?? f.id)), children: _jsxs(Div, { surface: "card", padding: "card", rounded: "lg", border: "default", children: [f.display?.coverImage ? (_jsx(MediaImage, { src: f.display.coverImage, alt: f.name ?? "", size: "card", rounded: "md", className: "mb-3" })) : null, _jsx(Heading, { level: 2, size: "lg", weight: "semibold", children: f.name }), f.description ? (_jsx(Text, { color: "muted", size: "sm", className: "mt-1", truncate: 2, children: f.description })) : null] }) }, f.id))) }))] }) }) }));
+}

package/dist/features/categories/constants/category-tabs.d.ts

@@ -0,0 +1,64 @@
+/**
+ * How the categories index splits into tabs — ONE definition of each predicate.
+ *
+ * ## 🛑 The index shows ROOTS, not everything
+ *
+ * `/categories` used to render the whole flat forest: 1,185 rows, of which 752
+ * are part leaves and 220 are model leaves. A visitor met a wall of names with
+ * no sense of where they were. The Categories tab now shows the SIX roots and
+ * you walk down — parent to child to leaf — which is how every catalogue of
+ * this shape is browsed, and what the category detail page already supports
+ * (it fetches every descendant and renders them tier-grouped).
+ *
+ * ## 🛑 Parts cannot be matched on `categoryType`
+ *
+ * Brands, franchises and bundles each carry a discriminator. Parts deliberately
+ * DO NOT — `gen-category-parts.mjs` omits `categoryType` because 92 files read
+ * it and a new value opts a row out of every path that works. So a part is
+ * identified by its ANCESTRY: a leaf whose chain passes through one of the four
+ * `*-parts` nodes. That is a fact about where it lives, not a flag that can
+ * drift from it.
+ *
+ * ## Why the tabs partition ONE payload
+ *
+ * The listing already fetches `?flat=true` once. Deriving all five tabs from
+ * that single cached response costs no extra request — a per-tab query would
+ * turn one fetch into five for the same data.
+ *
+ * @tag domain:categories
+ * @tag layer:constants
+ * @tag pattern:shared-literal
+ * @tag sideEffects:none
+ */
+/** The tier-2 nodes every part leaf hangs beneath. */
+export declare const PART_PARENT_IDS: readonly string[];
+export type CategoryTabKey = "categories" | "brands" | "franchises" | "parts" | "bundles";
+export interface CategoryTabDef {
+    key: CategoryTabKey;
+    label: string;
+}
+/**
+ * 🛑 No "All" tab. It was the default and it was the problem — it is what
+ * rendered 1,185 undifferentiated rows. Every tab here answers a question
+ * ("which parts do you have?"); "all" answers none of them.
+ */
+export declare const CATEGORY_TABS: readonly CategoryTabDef[];
+export declare const DEFAULT_CATEGORY_TAB: CategoryTabKey;
+/** The minimum shape these predicates read. */
+interface TabbableCategory {
+    categoryType?: string | null;
+    tier?: number | null;
+    parentIds?: readonly string[] | null;
+    isLeaf?: boolean | null;
+}
+/** A leaf whose ancestry passes through a `*-parts` node. */
+export declare function isPartCategory(c: TabbableCategory): boolean;
+/**
+ * Does this row belong on the given tab?
+ *
+ * 🛑 The Categories tab is ROOTS ONLY (`tier === 0`). Brands, franchises and
+ * bundles are tier-0 too but carry a discriminator, so the type check has to
+ * come first or they would appear under Categories as well.
+ */
+export declare function matchesCategoryTab(c: TabbableCategory, tab: CategoryTabKey): boolean;
+export {};

package/dist/features/categories/constants/category-tabs.js

@@ -0,0 +1,88 @@
+/**
+ * How the categories index splits into tabs — ONE definition of each predicate.
+ *
+ * ## 🛑 The index shows ROOTS, not everything
+ *
+ * `/categories` used to render the whole flat forest: 1,185 rows, of which 752
+ * are part leaves and 220 are model leaves. A visitor met a wall of names with
+ * no sense of where they were. The Categories tab now shows the SIX roots and
+ * you walk down — parent to child to leaf — which is how every catalogue of
+ * this shape is browsed, and what the category detail page already supports
+ * (it fetches every descendant and renders them tier-grouped).
+ *
+ * ## 🛑 Parts cannot be matched on `categoryType`
+ *
+ * Brands, franchises and bundles each carry a discriminator. Parts deliberately
+ * DO NOT — `gen-category-parts.mjs` omits `categoryType` because 92 files read
+ * it and a new value opts a row out of every path that works. So a part is
+ * identified by its ANCESTRY: a leaf whose chain passes through one of the four
+ * `*-parts` nodes. That is a fact about where it lives, not a flag that can
+ * drift from it.
+ *
+ * ## Why the tabs partition ONE payload
+ *
+ * The listing already fetches `?flat=true` once. Deriving all five tabs from
+ * that single cached response costs no extra request — a per-tab query would
+ * turn one fetch into five for the same data.
+ *
+ * @tag domain:categories
+ * @tag layer:constants
+ * @tag pattern:shared-literal
+ * @tag sideEffects:none
+ */
+/** The tier-2 nodes every part leaf hangs beneath. */
+export const PART_PARENT_IDS = [
+    "category-original-parts",
+    "category-metal-parts",
+    "category-burst-parts",
+    "category-x-parts",
+];
+/**
+ * 🛑 No "All" tab. It was the default and it was the problem — it is what
+ * rendered 1,185 undifferentiated rows. Every tab here answers a question
+ * ("which parts do you have?"); "all" answers none of them.
+ */
+export const CATEGORY_TABS = [
+    { key: "categories", label: "Categories" },
+    { key: "brands", label: "Brands" },
+    { key: "franchises", label: "Franchises" },
+    { key: "parts", label: "Parts" },
+    { key: "bundles", label: "Bundles" },
+];
+export const DEFAULT_CATEGORY_TAB = "categories";
+const typeOf = (c) => String(c.categoryType ?? "");
+/** A leaf whose ancestry passes through a `*-parts` node. */
+export function isPartCategory(c) {
+    if (typeOf(c))
+        return false; // brand / bundle / franchise / sublisting
+    return (c.parentIds ?? []).some((p) => PART_PARENT_IDS.includes(String(p)));
+}
+/**
+ * Does this row belong on the given tab?
+ *
+ * 🛑 The Categories tab is ROOTS ONLY (`tier === 0`). Brands, franchises and
+ * bundles are tier-0 too but carry a discriminator, so the type check has to
+ * come first or they would appear under Categories as well.
+ */
+export function matchesCategoryTab(c, tab) {
+    const type = typeOf(c);
+    switch (tab) {
+        case "brands":
+            return type === "brand";
+        case "franchises":
+            return type === "franchise";
+        case "bundles":
+            return type === "bundle";
+        case "parts":
+            return isPartCategory(c);
+        case "categories":
+            /*
+             * A plain, top-level category. Parts are excluded by the type check
+             * being empty AND tier 0 — no part leaf is tier 0 — but a reader should
+             * not have to derive that, so the root test carries the meaning.
+             */
+            return type === "" && Number(c.tier ?? -1) === 0;
+        default:
+            return false;
+    }
+}

package/dist/features/categories/hooks/useCategories.d.ts

@@ -20,6 +20,20 @@ export interface CategoriesFilteredParams {
     sort?: string;
     page?: number;
     pageSize?: number;
+    /**
+     * Tab partition, applied BEFORE pagination.
+     *
+     * 🛑 Before, not after — the hook paginates internally, so filtering the
+     * returned page would show a short grid and a page count for a different,
+     * larger set. It is a predicate rather than another flag because the Parts
+     * tab cannot be expressed as one: a part carries no `categoryType` and is
+     * identified by its ancestry (`category-tabs.ts`).
+     *
+     * Not part of the react-query key, deliberately — the FETCH is the same
+     * unfiltered `?flat=true` for every tab, so keying on it would mint five
+     * cache entries for one response.
+     */
+    predicate?: (c: CategoryItem) => boolean;
 }
 /** API-driven for structured filters; text search + pagination done in hook (Firestore substring limitation). */
 export declare function useCategoriesFiltered(params?: CategoriesFilteredParams): {

package/dist/features/categories/hooks/useCategories.js

@@ -45,6 +45,8 @@ export function useCategoriesFiltered(params = {}) {
             items = items.filter((c) => c.name.toLowerCase().includes(lq) || (c.description ?? "").toLowerCase().includes(lq));
         if (params.isBrand === false)
             items = items.filter((c) => !c.isBrand);
+        if (params.predicate)
+            items = items.filter(params.predicate);
         if (minProductCount !== undefined)
             items = items.filter((c) => (c.productCount ?? 0) >= minProductCount);
         if (maxProductCount !== undefined)

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

@@ -303,6 +303,21 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      * Replaces the old `brandsRepository.findActive()` call site.
      */
     findActiveBrands(): Promise<CategoryDocument[]>;
+    /**
+     * The FRANCHISE rows a visitor may browse — what a product is FROM, where a
+     * brand is who made it.
+     *
+     * 🛑 `isActive == true` is the whole guard against a dead facet. Seven of the
+     * eight seeded franchises have no stock yet and are seeded INACTIVE on
+     * purpose: their pages resolve (so `/franchise/marvel` is not a 404) but they
+     * are kept out of the grid, because a card that opens an empty shop is worse
+     * than no card — the rule `_helpers/brand-rows.ts` states as trap 3.
+     *
+     * Same query shape as `findActiveBrands`, so it rides the SAME
+     * (categoryType, isActive, order) composite index rather than needing a new
+     * one.
+     */
+    findActiveFranchises(): Promise<CategoryDocument[]>;
     /**
      * SB-UNI-B — derive the canonical `sublisting-{slug}` ID from a
      * human-entered category name.