@mohasinac/appkit 4.50.0 → 4.51.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.50.0",
-  "head": "cc3acd12565598821ab36a76ec2fe0c286ca8299",
+  "version": "4.51.0",
+  "head": "8e22d42a3cf524b03f860462c5fe567bfbb621de",
   "branch": "main",
   "dirty": false,
-  "builtAt": "2026-10-14T06:47:51.500Z"
+  "builtAt": "2026-10-14T12:00:13.325Z"
 }

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/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/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.

package/dist/features/categories/repository/categories.repository.js

@@ -1022,6 +1022,29 @@ export class CategoriesRepository extends BaseRepository {
             .get();
         return snap.docs.map((d) => this.mapDoc(d));
     }
+    /**
+     * 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.
+     */
+    async findActiveFranchises() {
+        const snap = await this.db
+            .collection(this.collection)
+            .where(CATEGORY_FIELDS.CATEGORY_TYPE, "==", "franchise")
+            .where(CATEGORY_FIELDS.IS_ACTIVE, "==", true)
+            .orderBy(CATEGORY_FIELDS.ORDER, "asc")
+            .get();
+        return snap.docs.map((d) => this.mapDoc(d));
+    }
     /*
      * 🛑 `incrementViewCount` DELETED 2026-10-10 — zero callers since
      * 2026-08-31, when it was removed from the category-detail render path (a

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

@@ -1,4 +1,4 @@
-export type CategoryType = "category" | "sublisting" | "brand" | "bundle";
+export type CategoryType = "category" | "sublisting" | "brand" | "bundle" | "franchise";
 export interface CategorySeo {
     title?: string;
     description?: string;

package/dist/features/collections/schemas/index.d.ts

@@ -33,9 +33,9 @@ export declare const collectionItemSchema: z.ZodObject<{
     brandSlug?: string | undefined;
     productCount?: number | undefined;
     description?: string | undefined;
+    franchiseSlug?: string | undefined;
     subtitle?: string | undefined;
     bannerImage?: string | undefined;
-    franchiseSlug?: string | undefined;
     manualProductIds?: string[] | undefined;
 }, {
     title: string;
@@ -46,10 +46,10 @@ export declare const collectionItemSchema: z.ZodObject<{
     productCount?: number | undefined;
     active?: boolean | undefined;
     description?: string | undefined;
+    franchiseSlug?: string | undefined;
     subtitle?: string | undefined;
     sortOrder?: number | undefined;
     bannerImage?: string | undefined;
-    franchiseSlug?: string | undefined;
     manualProductIds?: string[] | undefined;
 }>;
 export declare const collectionListItemSchema: z.ZodObject<{

package/dist/features/pre-orders/schemas/index.d.ts

@@ -66,8 +66,8 @@ export declare const preorderItemSchema: z.ZodObject<{
         youtubeId?: string | undefined;
         duration?: number | undefined;
     }[] | undefined;
-    images?: string[] | undefined;
     franchise?: string | undefined;
+    images?: string[] | undefined;
     preorderShipDate?: string | undefined;
 }, {
     id: string;
@@ -87,8 +87,8 @@ export declare const preorderItemSchema: z.ZodObject<{
         youtubeId?: string | undefined;
         duration?: number | undefined;
     }[] | undefined;
+    franchise?: string | undefined;
     images?: string[] | undefined;
     isFeatured?: boolean | undefined;
-    franchise?: string | undefined;
     preorderShipDate?: string | undefined;
 }>;

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

@@ -398,6 +398,10 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        franchiseSlug: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         sublistingCategoryId: {
             canFilter: boolean;
             canSort: boolean;

package/dist/features/products/repository/products.repository.js

@@ -1519,6 +1519,11 @@ ProductRepository.SIEVE_FIELDS = {
     "physicalLocation.shelf": { canFilter: true, canSort: false },
     "physicalLocation.bin": { canFilter: true, canSort: false },
     brandSlug: { canFilter: true, canSort: false },
+    /* 🛑 Must be declared here or the clause is SILENTLY DROPPED — sieve.ts
+     * sets `throwExceptions: false`, so an unallowlisted field does not raise,
+     * it just vanishes and the franchise page returns the whole catalogue
+     * (Root Cause #62). */
+    franchiseSlug: { canFilter: true, canSort: false },
     sublistingCategoryId: { canFilter: true, canSort: false },
     createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     updatedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },

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

@@ -216,6 +216,19 @@ export interface ProductDocument extends BaseDocument {
     subcategory?: string;
     brand?: string;
     brandSlug?: string;
+    /**
+     * The IP this product is FROM — "Beyblade", "Pokémon". A sibling of `brand`
+     * (who MADE it), matching a `categoryType: "franchise"` row.
+     *
+     * 🛑 `franchiseSlug` is the match key here, NOT the display name — the
+     * opposite of `brand`, which `BrandDetailPageView` filters on by display name
+     * and which therefore orphans its whole catalogue on a rename (see
+     * `_helpers/brand-rows.ts`, trap 1). Franchise is new, so it gets the
+     * correct shape from the start rather than inheriting that trap; `franchise`
+     * is the denormalised label for display only.
+     */
+    franchise?: string;
+    franchiseSlug?: string;
     price: number;
     /**
      * The strike-through "was ₹X", for a listing the seller is discounting.

package/dist/index.d.ts

@@ -651,6 +651,7 @@ export { historySeedData } from "./seed/index";
 export { groupedListingsSeedData } from "./seed/index";
 export { mediaAssetsSeedData, MEDIA_ASSET_SEED_COUNT } from "./seed/index";
 export { productsCatalogueSeedData, CATALOGUE_LISTING_COUNT, } from "./seed/index";
+export { FRANCHISE_ROW_COUNT, FRANCHISE_SLUGS, FRANCHISE_BY_CATEGORY_ROOT, } from "./seed/index";
 export type { CouponDiscountType } from "./seed/index";
 export type { FirestoreIndexConfig } from "./seed/index";
 export type { HomepageSectionType } from "./seed/index";

package/dist/index.js

@@ -1375,6 +1375,9 @@ export { mediaAssetsSeedData, MEDIA_ASSET_SEED_COUNT } from "./seed/index.js";
 // Same Root Cause #18 shape as mediaAssetsSeedData above: seed-cli.mjs imports
 // the bare "@mohasinac/appkit" package, which resolves through THIS file.
 export { productsCatalogueSeedData, CATALOGUE_LISTING_COUNT, } from "./seed/index.js";
+// Franchise — the IP a product is FROM (brand is who MADE it). Re-exported
+// from the outer barrel because seed-cli.mjs imports the bare package.
+export { FRANCHISE_ROW_COUNT, FRANCHISE_SLUGS, FRANCHISE_BY_CATEGORY_ROOT, } from "./seed/index.js";
 export { NOTIFICATION_TYPE_VALUES, NOTIFICATION_RELATED_TYPE_VALUES } from "./features/admin/schemas/firestore.js";
 // [UTIL]-Pure utility â€" no framework or runtime dependency; safe to import from any environment.
 // ErrorCategory - Shared export for error category.

package/dist/next/routing/route-map.d.ts

@@ -54,6 +54,8 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly CATEGORY_DETAIL: (slug: string) => string;
         readonly BRANDS: "/brands";
         readonly BRAND_DETAIL: (slug: string) => string;
+        readonly FRANCHISE: "/franchise";
+        readonly FRANCHISE_DETAIL: (slug: string) => string;
         readonly REVIEWS: "/reviews";
         readonly REVIEW_DETAIL: (id: string) => string;
         readonly SEARCH: "/search";
@@ -468,6 +470,8 @@ export declare const ROUTES: {
         readonly CATEGORY_DETAIL: (slug: string) => string;
         readonly BRANDS: "/brands";
         readonly BRAND_DETAIL: (slug: string) => string;
+        readonly FRANCHISE: "/franchise";
+        readonly FRANCHISE_DETAIL: (slug: string) => string;
         readonly REVIEWS: "/reviews";
         readonly REVIEW_DETAIL: (id: string) => string;
         readonly SEARCH: "/search";

package/dist/next/routing/route-map.js

@@ -47,6 +47,15 @@ export const DEFAULT_ROUTE_MAP = {
         CATEGORY_DETAIL: (slug) => `/categories/${slug}`,
         BRANDS: "/brands",
         BRAND_DETAIL: (slug) => `/brands/${slug}`,
+        /*
+         * FRANCHISE — what a collectible is FROM, where a brand is who MADE it.
+         * Singular in the path because `CharacterHotspot` already ships eighteen
+         * `/franchise/<slug>` links; matching them is what turns those 404s into
+         * real pages, and changing the segment to `/franchises` would just move
+         * the breakage.
+         */
+        FRANCHISE: "/franchise",
+        FRANCHISE_DETAIL: (slug) => `/franchise/${slug}`,
         REVIEWS: "/reviews",
         REVIEW_DETAIL: (id) => `/reviews/${id}`,
         SEARCH: "/search",

package/dist/seed/_helpers/franchise-rows.d.ts

@@ -0,0 +1,43 @@
+import type { CategoryDocument } from "../../features/categories/schemas";
+export interface FranchiseSeedInput {
+    /** Without the `franchise-` prefix. Products match on this, never the name. */
+    slug: string;
+    name: string;
+    description: string;
+    /** Live only when real stock exists — see the dead-facet rule above. */
+    active: boolean;
+    featured?: boolean;
+    keywords: string[];
+    seoDescription: string;
+}
+export declare function franchiseRow(input: FranchiseSeedInput, order: number, stamps: {
+    createdBy: string;
+    createdAt: Date;
+    updatedAt: Date;
+}): Partial<CategoryDocument>;
+export declare function buildFranchiseRows(stamps: {
+    createdBy: string;
+    createdAt: Date;
+    updatedAt: Date;
+}): Partial<CategoryDocument>[];
+export declare const FRANCHISE_ROW_COUNT: number;
+/** The slugs a product's `franchiseSlug` may point at. */
+export declare const FRANCHISE_SLUGS: readonly string[];
+/**
+ * Category ROOT -> the franchise everything beneath it belongs to.
+ *
+ * Derived rather than stamped per product: a product already carries its full
+ * ancestor chain, so the root is free and cannot drift from the taxonomy the
+ * way a hand-written field would (Root Cause #42).
+ *
+ * 🛑 Deliberately PARTIAL. `category-living-collectibles` is absent because a
+ * juniper bonsai and a leucistic axolotl are not from an IP — they are living
+ * things. Mapping every root for completeness' sake would assert a franchise
+ * that does not exist, and "no franchise" is the correct answer for 4 of the
+ * 1,308 seeded products. A root with no entry yields no franchise, not a
+ * fallback.
+ */
+export declare const FRANCHISE_BY_CATEGORY_ROOT: Readonly<Record<string, {
+    slug: string;
+    name: string;
+}>>;

package/dist/seed/_helpers/franchise-rows.js

@@ -0,0 +1,181 @@
+/*
+ * WHY: a product's BRAND is who made it (Takara-Tomy); its FRANCHISE is what
+ *      it is from (Beyblade). The site had no way to express the second, while
+ *      `CharacterHotspot` shipped eighteen `/franchise/*` links to a route that
+ *      did not exist. This is that unit, modelled on brands per the explicit
+ *      instruction — "like brands make franchise its own separate unit".
+ *
+ * WHAT: one factory plus eight declarations.
+ *
+ * EXPORTS:
+ *   FRANCHISE_ROWS       — Partial<CategoryDocument>[], categoryType:"franchise"
+ *   FRANCHISE_ROW_COUNT  — asserted by the seed so a silent drop is loud
+ *
+ * ── 🛑 THE DEAD-FACET RULE, AND HOW THESE OBEY IT ─────────────────────────
+ *
+ * `brand-rows.ts` trap 3 states it exactly: *"A brand 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 rows below have no stock today,
+ * because this catalogue sells Beyblade.
+ *
+ * So they are seeded **`isActive: false`**. That is not a soft delete — the row
+ * exists, it is editable in the admin category editor, its page resolves, and
+ * `/franchise/marvel` stops being a 404. It is excluded from the grid and from
+ * search until it has something to sell, at which point one flag flips.
+ *
+ * The alternative readings were both worse: omitting them leaves eighteen links
+ * broken, and seeding them active puts seven empty shopfronts on a live grid.
+ *
+ * 🛑 `isActive` is therefore load-bearing here, not boilerplate. A future
+ * franchise row should be `false` until a product carries its `franchiseSlug`.
+ *
+ * ── Why tier-0 and outside the forest ─────────────────────────────────────
+ *
+ * Same as brands: `position` is NOT set, because these live outside the
+ * category forest's DFS numbering and a position inside it would corrupt the
+ * ranges `onCategoryWrite` shifts on insert.
+ *
+ * @tag domain:categories
+ * @tag layer:seed
+ * @tag pattern:shared-literal
+ * @tag access:server-only
+ * @tag consumers:seed/categories-seed-data.ts
+ * @tag sideEffects:none
+ */
+/* 🛑 `constants/field-names`, NOT the schema copy — there are two
+ * `CATEGORY_FIELDS` and only this one carries `CATEGORY_TYPE_VALUES`.
+ * `categories-seed-data.ts` imports this one; matching it is what keeps the
+ * discriminator a single spelling. Same reasoning as `brand-rows.ts`. */
+import { CATEGORY_FIELDS } from "../../constants/field-names.js";
+import { seedPhoto } from "./media.js";
+export function franchiseRow(input, order, stamps) {
+    const id = `franchise-${input.slug}`;
+    return {
+        id,
+        slug: id,
+        name: input.name,
+        categoryType: CATEGORY_FIELDS.CATEGORY_TYPE_VALUES.FRANCHISE,
+        description: input.description,
+        rootId: id,
+        parentIds: [],
+        childrenIds: [],
+        ancestors: [],
+        tier: 0,
+        path: id,
+        isLeaf: true,
+        order,
+        /* `icon` deliberately unset — the brands grid reads `display.icon` first
+         * and an emoji there would beat a real cover image (brand-rows trap 2). */
+        display: {
+            coverImage: seedPhoto(`franchise-cover-${input.slug}-20261014`, 800, 800),
+            showInMenu: false,
+            showInFooter: false,
+        },
+        isFeatured: input.featured ?? false,
+        isActive: input.active,
+        isSearchable: input.active,
+        createdBy: stamps.createdBy,
+        createdAt: stamps.createdAt,
+        updatedAt: stamps.updatedAt,
+        seo: {
+            title: `${input.name} | LetItRip`,
+            description: input.seoDescription,
+            keywords: input.keywords,
+        },
+    };
+}
+/*
+ * The eight. Beyblade is the catalogue; the other seven are the IPs
+ * `CharacterHotspot` already links to, seeded inactive so those links resolve
+ * without advertising an empty shop.
+ */
+const INPUTS = [
+    {
+        slug: "beyblade",
+        name: "Beyblade",
+        description: "The spinning-top battling franchise — every generation from the original Spin Gear tops through Metal Fight, Burst and Beyblade X. Complete tops, loose parts, stadiums and accessories.",
+        active: true,
+        featured: true,
+        keywords: ["beyblade", "spinning tops", "burst", "metal fight", "beyblade x"],
+        seoDescription: "Shop Beyblade across every generation — tops, parts, stadiums and spares, new and pre-owned.",
+    },
+    {
+        slug: "marvel",
+        name: "Marvel",
+        description: "Figures, collectibles and merchandise from the Marvel universe.",
+        active: false,
+        keywords: ["marvel", "comics", "superhero", "figures"],
+        seoDescription: "Marvel collectibles and figures.",
+    },
+    {
+        slug: "dc-comics",
+        name: "DC Comics",
+        description: "Figures, collectibles and merchandise from the DC universe.",
+        active: false,
+        keywords: ["dc", "dc comics", "superhero", "figures"],
+        seoDescription: "DC Comics collectibles and figures.",
+    },
+    {
+        slug: "dragon-ball",
+        name: "Dragon Ball",
+        description: "Figures and collectibles from the Dragon Ball series.",
+        active: false,
+        keywords: ["dragon ball", "anime", "figures", "shonen"],
+        seoDescription: "Dragon Ball collectibles and figures.",
+    },
+    {
+        slug: "naruto",
+        name: "Naruto",
+        description: "Figures and collectibles from the Naruto series.",
+        active: false,
+        keywords: ["naruto", "anime", "figures", "shonen"],
+        seoDescription: "Naruto collectibles and figures.",
+    },
+    {
+        slug: "bleach",
+        name: "Bleach",
+        description: "Figures and collectibles from the Bleach series.",
+        active: false,
+        keywords: ["bleach", "anime", "figures", "shonen"],
+        seoDescription: "Bleach collectibles and figures.",
+    },
+    {
+        slug: "one-piece",
+        name: "One Piece",
+        description: "Figures and collectibles from the One Piece series.",
+        active: false,
+        keywords: ["one piece", "anime", "figures", "shonen"],
+        seoDescription: "One Piece collectibles and figures.",
+    },
+    {
+        slug: "one-punch-man",
+        name: "One Punch Man",
+        description: "Figures and collectibles from the One Punch Man series.",
+        active: false,
+        keywords: ["one punch man", "anime", "figures"],
+        seoDescription: "One Punch Man collectibles and figures.",
+    },
+];
+export function buildFranchiseRows(stamps) {
+    return INPUTS.map((input, i) => franchiseRow(input, i + 1, stamps));
+}
+export const FRANCHISE_ROW_COUNT = INPUTS.length;
+/** The slugs a product's `franchiseSlug` may point at. */
+export const FRANCHISE_SLUGS = INPUTS.map((i) => `franchise-${i.slug}`);
+/**
+ * Category ROOT -> the franchise everything beneath it belongs to.
+ *
+ * Derived rather than stamped per product: a product already carries its full
+ * ancestor chain, so the root is free and cannot drift from the taxonomy the
+ * way a hand-written field would (Root Cause #42).
+ *
+ * 🛑 Deliberately PARTIAL. `category-living-collectibles` is absent because a
+ * juniper bonsai and a leucistic axolotl are not from an IP — they are living
+ * things. Mapping every root for completeness' sake would assert a franchise
+ * that does not exist, and "no franchise" is the correct answer for 4 of the
+ * 1,308 seeded products. A root with no entry yields no franchise, not a
+ * fallback.
+ */
+export const FRANCHISE_BY_CATEGORY_ROOT = {
+    "category-spinning-tops": { slug: "franchise-beyblade", name: "Beyblade" },
+};

package/dist/seed/categories-seed-data.js

@@ -56,6 +56,7 @@ import { buildCategoryTree } from "./_helpers/category-tree.js";
 import { withCategorySearchTxt } from "./_helpers/search-txt-wrappers.js";
 import { CATEGORY_FOREST } from "./_helpers/category-forest.js";
 import { BRAND_ROW_COUNT, buildBrandRows } from "./_helpers/brand-rows.js";
+import { FRANCHISE_ROW_COUNT, buildFranchiseRows } from "./_helpers/franchise-rows.js";
 import { MODEL_LEAF_COUNT } from "./_helpers/category-models.js";
 import { PART_LEAF_COUNT } from "./_helpers/category-parts.js";
 import { MARKET_BAND_LEAF_IDS } from "./_helpers/category-content.js";
@@ -195,6 +196,14 @@ const brandRows = buildBrandRows({
     createdAt: daysAgo(300),
     updatedAt: daysAgo(30),
 });
+// FRANCHISE rows — what a product is FROM, where a brand is who MADE it.
+// Same tier-0, outside-the-forest shape as brands. Seven of the eight are
+// seeded INACTIVE on purpose; see the dead-facet rule in _helpers/franchise-rows.ts.
+const franchiseRows = buildFranchiseRows({
+    createdBy: "user-admin-letitrip",
+    createdAt: daysAgo(300),
+    updatedAt: daysAgo(30),
+});
 // P-17 — 5 bundle rows (categoryType:"bundle") grouping the Beyblade-minimal
 // standard products by generation, plus one cross-generation starter pack.
 // Every bundle references real seeded product ids (products-standard-seed-data.ts),
@@ -504,6 +513,7 @@ const allCategoryRows = [
     ...rawCategories.map((c) => ({ ancestors: [], ...c, createdByType: "admin" })),
     ...sublistingRows.map((s) => ({ ancestors: [], ...s, createdByType: "admin" })),
     ...brandRows.map((b) => ({ ancestors: [], ...b, createdByType: "admin" })),
+    ...franchiseRows.map((f) => ({ ancestors: [], ...f, createdByType: "admin" })),
     ...bundleRows.map((b) => ({ ancestors: [], ...b })),
 ]
     .map(withGeneratedContent)
@@ -610,6 +620,9 @@ if (tier4Rows !== expectedTier4) {
 if (brandRows.length !== BRAND_ROW_COUNT) {
     throw new Error(`category seed: ${brandRows.length} brand rows built, expected ${BRAND_ROW_COUNT}`);
 }
+if (franchiseRows.length !== FRANCHISE_ROW_COUNT) {
+    throw new Error(`category seed: ${franchiseRows.length} franchise rows built, expected ${FRANCHISE_ROW_COUNT}`);
+}
 {
     /*
      * A price band keyed on a leaf that does not exist is dead weight that READS

package/dist/seed/index.d.ts

@@ -79,6 +79,7 @@ export { groupedListingsSeedData } from "./grouped-listings-seed-data";
 export { mediaAssetsSeedData, MEDIA_ASSET_SEED_COUNT, } from "./media-assets-seed-data";
 export { productsCatalogueSeedData, CATALOGUE_LISTING_COUNT, } from "./products-catalogue-seed-data";
 export { GENERATED_PART_COLOURS, GENERATED_PART_COLOUR_COUNT, } from "./_helpers/part-colours-generated";
+export { FRANCHISE_ROW_COUNT, FRANCHISE_SLUGS, FRANCHISE_BY_CATEGORY_ROOT, } from "./_helpers/franchise-rows";
 export { scammersSeedData } from "./scammers-seed-data";
 export { supportTicketsSeedData } from "./support-tickets-seed-data";
 export { testerChecklistSeedData, testerResponsesSeedData, } from "../features/tester/seed-data";

package/dist/seed/index.js

@@ -78,6 +78,7 @@ export { groupedListingsSeedData } from "./grouped-listings-seed-data.js";
 export { mediaAssetsSeedData, MEDIA_ASSET_SEED_COUNT, } from "./media-assets-seed-data.js";
 export { productsCatalogueSeedData, CATALOGUE_LISTING_COUNT, } from "./products-catalogue-seed-data.js";
 export { GENERATED_PART_COLOURS, GENERATED_PART_COLOUR_COUNT, } from "./_helpers/part-colours-generated.js";
+export { FRANCHISE_ROW_COUNT, FRANCHISE_SLUGS, FRANCHISE_BY_CATEGORY_ROOT, } from "./_helpers/franchise-rows.js";
 export { scammersSeedData } from "./scammers-seed-data.js";
 export { supportTicketsSeedData } from "./support-tickets-seed-data.js";
 // Tester checklist/response seed data lives in ../features/tester/seed-data (isolated from

package/dist/server.d.ts

@@ -509,6 +509,7 @@ export { getPreOrderForDetail, getProductFeaturesForPreOrder } from "./_internal
 export { getStoreForDetail, listStoreProductsInitial, listStoreAuctionsInitial, listStorePreOrdersInitial, listSitemapStores } from "./_internal/server/features/stores/index";
 export { toStoreDetail, toStoreListItem, PUBLIC_STORE_FIELDS, PRIVATE_STORE_FIELDS, type ToStoreDetailOptions, type ToStoreListItemOptions, type StoreProjectionSource, } from "./_internal/server/features/stores/adapters";
 export { getBrandForDetail } from "./_internal/server/features/brands/index";
+export { getFranchiseForDetail, listActiveFranchises, renderFranchiseOg, } from "./_internal/server/features/franchises/index";
 export { getBlogPostForDetail } from "./_internal/server/features/blog/index";
 export { getEventForDetail } from "./_internal/server/features/events/index";
 export { getSublistingCategoryForDetail } from "./_internal/server/features/sublisting-categories/index";

package/dist/server.js

@@ -1387,6 +1387,7 @@ export { getStoreForDetail, listStoreProductsInitial, listStoreAuctionsInitial,
 // may reach a client component or an HTTP response. See adapters.ts header.
 export { toStoreDetail, toStoreListItem, PUBLIC_STORE_FIELDS, PRIVATE_STORE_FIELDS, } from "./_internal/server/features/stores/adapters.js";
 export { getBrandForDetail } from "./_internal/server/features/brands/index.js";
+export { getFranchiseForDetail, listActiveFranchises, renderFranchiseOg, } from "./_internal/server/features/franchises/index.js";
 export { getBlogPostForDetail } from "./_internal/server/features/blog/index.js";
 export { getEventForDetail } from "./_internal/server/features/events/index.js";
 export { getSublistingCategoryForDetail } from "./_internal/server/features/sublisting-categories/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.50.0",
+  "version": "4.51.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/scripts/seed-cli.mjs

@@ -195,6 +195,7 @@ const {
   productsPrizeDrawsSeedData, productsClassifiedsSeedData, productsDigitalCodesSeedData, productsLiveItemsSeedData,
   productsArtSeedData, productsStickersSeedData,
   productsCatalogueSeedData,
+  FRANCHISE_BY_CATEGORY_ROOT,
   ordersSeedData, reviewsSeedData, cartsSeedData, bidsSeedData,
   couponsSeedData, couponUsageSeedData,
   eventsSeedData, eventEntriesSeedData, payoutsSeedData, offersSeedData,
@@ -369,6 +370,35 @@ const COLLECTION_MAP = {
  * signal, so a silent 5% here would hide exactly what it is meant to surface —
  * and a wrong rate on a real invoice is worse than a failed load.
  */
+/**
+ * Stamp `franchise` / `franchiseSlug` from the product's category ROOT.
+ *
+ * 🛑 Its OWN pass, deliberately NOT folded into `withDerivedCategoryFields`.
+ * That function early-returns on `gstRate && hsnCode && authenticity`, which
+ * every one of the 1,237 generated catalogue rows already satisfies — so a
+ * franchise derived in there would be silently skipped for 95% of the
+ * catalogue. That is the exact bug its own comment records happening when
+ * `authenticity` was added beside `gstRate`; adding a third field to the same
+ * condition is how it happens a third time.
+ *
+ * A root with no mapping yields NO franchise (living collectibles are not an
+ * IP) — see `FRANCHISE_BY_CATEGORY_ROOT`.
+ */
+function withFranchise(products) {
+  let stamped = 0;
+  const out = products.map((p) => {
+    if (p.franchiseSlug) return p;
+    const chain = Array.isArray(p.categorySlugs) ? p.categorySlugs : [];
+    const root = chain.length > 0 ? String(chain[chain.length - 1]) : null;
+    const f = root ? FRANCHISE_BY_CATEGORY_ROOT[root] : null;
+    if (!f) return p;
+    stamped++;
+    return { ...p, franchise: f.name, franchiseSlug: f.slug };
+  });
+  console.log(`  • franchise stamped on ${stamped}/${products.length} products`);
+  return out;
+}
+
 function withDerivedCategoryFields(products) {
   const catById = new Map((categoriesSeedData || []).map((c) => [String(c.id), c]));
   const taxById = new Map((taxCodesSeedData || []).map((t) => [String(t.id), t]));
@@ -461,7 +491,7 @@ const SEED_DATA_MAP = {
   // standalone brands collection/seed exists anymore.
   categories: categoriesSeedData,
   stores: storesSeedData,
-  products: withDerivedCategoryFields([
+  products: withFranchise(withDerivedCategoryFields([
     ...(productsStandardSeedData || []), ...(productsAuctionsSeedData || []), ...(productsPreordersSeedData || []),
     ...(productsPrizeDrawsSeedData || []), ...(productsClassifiedsSeedData || []), ...(productsDigitalCodesSeedData || []), ...(productsLiveItemsSeedData || []),
     // art + stickers were written, exported from the seed barrel, and then never
@@ -474,7 +504,7 @@ const SEED_DATA_MAP = {
     // reproducible after a full wipe; without it the collection drops from
     // 1,039 to 71 the moment someone purges it.
     ...(productsCatalogueSeedData || []),
-  ]),
+  ])),
   orders: ordersSeedData,
   reviews: reviewsSeedData,
   bids: bidsSeedData,