@mohasinac/appkit 4.49.1 → 4.51.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.49.1",
-  "head": "bf2ce556216b8dcd3e3e5a009d83979d992a565b",
+  "version": "4.51.0",
+  "head": "8e22d42a3cf524b03f860462c5fe567bfbb621de",
   "branch": "main",
   "dirty": false,
-  "builtAt": "2026-10-14T04:52:23.154Z"
+  "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/category-images-generated.d.ts

@@ -7,12 +7,32 @@
  * a third-party URL (Root Cause #104 — that adds an upstream fetch to every
  * single render).
  *
+ * Covers BOTH complete-model leaves and PART leaves — they share one id space
+ * (`category-*`), so one map serves the category cover and, through
+ * `gen-catalogue-listings.mjs`, that leaf's product listing image too.
+ *
  * A hand-authored `display.coverImage` always wins over this map; a row absent
  * from it keeps no image rather than being given a placeholder. See
  * `withGeneratedCoverImage` in `categories-seed-data.ts`.
  *
+ * ── Replacing one of these with your own photograph ───────────────────────
+ *
+ * `CategoryForm` already edits `display.coverImage` (upload -> `/media/<id>`),
+ * so any of these can be swapped for an original at runtime.
+ *
+ * 🛑 But a RUNTIME edit does not survive `appkit-seed load` — the loader
+ * merge-writes `display`, so the generated value comes back. To replace one
+ * permanently, set `display.coverImage` in the category SOURCE (the forest or
+ * the seed row); the hand-authored value then wins here forever. That is the
+ * deliberate trade for "the seed can always rebuild the database".
+ *
+ * Deleting them entirely: remove the `media/categories/` Storage prefix, delete
+ * this file and `media-assets-seed-data.ts`, re-run the category seed. Bucket
+ * versioning and soft-delete are both OFF, so a deleted object leaves no
+ * recoverable copy and no residual billing.
+ *
  * Source and licensing for every file:
  * `docs/research/bey-corpus-2026-10/image-provenance.json`.
  */
 export declare const GENERATED_CATEGORY_IMAGES: Readonly<Record<string, string>>;
-export declare const GENERATED_CATEGORY_IMAGE_COUNT = 195;
+export declare const GENERATED_CATEGORY_IMAGE_COUNT = 504;