@mohasinac/appkit 4.50.0 → 4.52.0

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;
@@ -10,6 +10,18 @@ export interface CategoryDisplay {
     coverImage?: string;
     color?: string;
     showInMenu?: boolean;
+    /**
+     * Member images for a collage, most important first — what a BUNDLE actually
+     * looks like, which is its contents rather than one tile.
+     *
+     * 🛑 Derived at SEED time from the members' own `mainImage`, not fetched. A
+     * card cannot resolve `bundleProductIds` into images without one query per
+     * bundle per render, and a grid of five bundles would then be five extra
+     * reads for decoration. `<ImageMosaic>` renders nothing below `MOSAIC_MIN`
+     * (3), so a short list degrades to the cover image rather than a broken
+     * collage.
+     */
+    mosaicImages?: string[];
 }
 export interface CategoryMetrics {
     productCount: number;

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),
@@ -238,6 +247,34 @@ function bundleCategorySlugsFor(productIds) {
     }
     return out;
 }
+/**
+ * Attach a bundle's member images so its card can render a collage.
+ *
+ * 🛑 A bundle IS its contents, so a single placeholder tile is the least
+ * informative thing a bundle card can show. Resolved here, at seed time, from
+ * the members' own `mainImage` — a card cannot do it at render time without one
+ * query per bundle, and a grid of five would be five reads for decoration.
+ *
+ * `<ImageMosaic>` renders nothing below `MOSAIC_MIN` (3), so a bundle with one
+ * or two resolvable members quietly falls back to its cover image rather than
+ * showing a broken collage. A member id that resolves to no product is dropped
+ * rather than defaulted — a wrong photo is worse than one fewer tile.
+ */
+function withBundleMosaic(row) {
+    const ids = row.bundleProductIds ?? [];
+    // `row.display` must already exist — `CategoryDocumentDisplay` requires
+    // `showInFooter`, so spreading onto `{}` would drop a required field. Every
+    // bundle row declares one; a row without is left untouched rather than
+    // half-built.
+    if (ids.length === 0 || !row.display)
+        return row;
+    const images = ids
+        .map((id) => productsStandardSeedData.find((p) => p.id === id)?.mainImage)
+        .filter((src) => typeof src === "string" && src.length > 0);
+    if (images.length === 0)
+        return row;
+    return { ...row, display: { ...row.display, mosaicImages: images } };
+}
 const bundleRows = [
     {
         id: "bundle-original-collectors-set",
@@ -504,7 +541,8 @@ const allCategoryRows = [
     ...rawCategories.map((c) => ({ ancestors: [], ...c, createdByType: "admin" })),
     ...sublistingRows.map((s) => ({ ancestors: [], ...s, createdByType: "admin" })),
     ...brandRows.map((b) => ({ ancestors: [], ...b, createdByType: "admin" })),
-    ...bundleRows.map((b) => ({ ancestors: [], ...b })),
+    ...franchiseRows.map((f) => ({ ancestors: [], ...f, createdByType: "admin" })),
+    ...bundleRows.map((b) => ({ ancestors: [], ...withBundleMosaic(b) })),
 ]
     .map(withGeneratedContent)
     .map(withGeneratedCoverImage)
@@ -610,6 +648,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.52.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,