@mohasinac/appkit 4.53.0 → 4.53.1

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

@@ -0,0 +1,61 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useQuery } from "@tanstack/react-query";
+import { PricesOnly, Stack, Text } from "../../../ui/index.js";
+import { apiClient } from "../../../http/index.js";
+import { CATEGORY_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+function unwrap(res) {
+    const body = res?.data ?? res;
+    return body && typeof body === "object" && "guidance" in body ? body : null;
+}
+/**
+ * The seller-facing price hint `description-template/route.ts`'s own
+ * docstring names as "C1's job, from a surface that knows who is asking" —
+ * renders the inherited competitor-derived market band beside the price
+ * field, on the SELLER'S own tax basis (the `/price-guidance` endpoint does
+ * that conversion server-side; this component only formats what it returns).
+ *
+ * Mounted via `ProductForm`'s `renderPriceGuidance` slot rather than fetched
+ * unconditionally inside the form — `ProductForm` has no data-fetching of its
+ * own (every app-specific concern is a render-prop), and this component is
+ * seller/admin-only, not something the form itself should assume a caller
+ * wants.
+ *
+ * 🛑 NEVER mount this on a public page (category/brand detail). A
+ * competitor-derived market band is exactly the "a neighbouring surface
+ * publishes the range" leak the guest price gate exists to close (CLAUDE.md
+ * § "Guest price gating"), even though the figure is advisory rather than a
+ * real listing price — which is also why `/price-guidance` itself is
+ * seller/admin/moderator-gated, not a public, edge-cached endpoint like its
+ * `description-template` sibling.
+ */
+export function PriceGuidanceHint({ categoryId, currency = "INR", className = "", }) {
+    const query = useQuery({
+        queryKey: ["category-price-guidance", categoryId],
+        enabled: categoryId.length > 0,
+        staleTime: 60 * 60 * 1000,
+        queryFn: async () => unwrap(await apiClient.get(CATEGORY_ENDPOINTS.PRICE_GUIDANCE(categoryId))),
+    });
+    const guidance = query.data?.guidance;
+    const basisNote = query.data?.basisNote;
+    if (!guidance?.market)
+        return null;
+    const { median, p25, p75 } = guidance.market;
+    const fmt = (n) => formatCurrency(n, currency);
+    // p25/p75 are independently optional (see CategoryPriceGuidance's own
+    // docstring) — a range renders only when BOTH are present, never a
+    // half-range that would misreport the band's shape.
+    const range = p25 !== undefined && p75 !== undefined ? ` (${fmt(p25)}–${fmt(p75)})` : "";
+    /*
+     * `<PricesOnly>` rather than `<GatedPrice>`: this is advisory guidance
+     * BESIDE the seller's own price input, not a listing's primary price, so a
+     * viewer who may not see prices should get nothing here — a "Sign in to see
+     * price" prompt inside a seller form would be nonsense. In practice it
+     * never renders for a guest anyway, because the data source
+     * (`/api/categories/[id]/price-guidance`) is seller/admin/moderator-gated
+     * and 403s before there is a number to format; the wrapper makes that
+     * guarantee visible at the render site instead of implied by the route.
+     */
+    return (_jsx(PricesOnly, { children: _jsxs(Stack, { gap: "xs", className: className, children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Market median:", " ", _jsx(Text, { as: "span", weight: "medium", color: "primary", children: fmt(median) }), range, basisNote?.suffix ? ` ${basisNote.suffix}` : ""] }), basisNote?.note && _jsx(Text, { size: "xs", color: "faint", children: basisNote.note })] }) }));
+}

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

@@ -0,0 +1,27 @@
+import React from "react";
+export interface SubcategoryCardItem {
+    id: string;
+    name: string;
+    href: string;
+    /** Rollup listing count. Omitted when zero — a card reading "0" invites a dead click. */
+    count?: number;
+    /** A real picture, when the row resolved one. */
+    imageUrl?: string;
+    /** An emoji, when that is all the row has. Never passed to an `<img>`. */
+    emoji?: string;
+    /** Direct children's names — searched, never rendered. */
+    childNames?: readonly string[];
+    /**
+     * Depth in the forest: 0 is a root, 1 its child, and so on.
+     *
+     * Rendered as a small "L0 / L1 / L2" marker so a row of ancestors reads as a
+     * LADDER rather than as five unrelated cards. Omitted on the subcategory row
+     * itself, where every card is the same depth by construction and the marker
+     * would be noise repeated N times.
+     */
+    level?: number;
+}
+export declare function SubcategoryCardRow({ items, label, }: {
+    items: readonly SubcategoryCardItem[];
+    label?: string;
+}): React.JSX.Element | null;

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

@@ -0,0 +1,98 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: the Subcategories row was a pill per child in an `<OverflowRow>`, which
+ *      collapses to a searchable dropdown when it does not fit. A pill carries
+ *      only a name and a count, so on a tree this wide every child looked the
+ *      same and the row read as a wall of words.
+ * WHAT: small cards in the shared `<HorizontalScroller>`, with a filter box
+ *       that matches ONE LEVEL DEEPER than the cards themselves.
+ *
+ * EXPORTS: SubcategoryCardRow, SubcategoryCardItem
+ *
+ * ## 🛑 The filter matches grandchildren, and that is the point
+ *
+ * Searching "Dranzer" on Spinning Tops should surface *Beyblade Original* —
+ * the card you must click to get there — not nothing. So each card carries its
+ * own direct children's names (`childNames`) and the match runs over the card
+ * name PLUS that list. One level only: the full subtree of a root is ~1,200
+ * nodes, and matching all of it would surface a card because of a name six
+ * levels down that the visitor will never see on the next page either.
+ *
+ * `childNames` is built from data the page has ALREADY fetched
+ * (`getDescendants` is one array-contains query over `parentIds`), so the
+ * filter costs no request — it is pure in-browser narrowing of a list that is
+ * already in memory.
+ *
+ * ## 🛑 Why this does not reintroduce the bug `OverflowRow` was built for
+ *
+ * CLAUDE.md records a bare `overflow-x-auto` row as an anti-pattern, measured:
+ * "4 of 12 subcategories past the right edge with no scrollbar and no arrow".
+ * The discoverability problem is real and this row answers it twice over —
+ * `<HorizontalScroller showArrows>` renders real scroll affordances, and the
+ * filter box makes an off-screen card reachable by typing rather than by
+ * scrolling to it. What is given up is the collapse-to-dropdown behaviour,
+ * which was the fallback for exactly that problem.
+ *
+ * @tag domain:categories
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag sideEffects:none
+ */
+import { useMemo, useState } from "react";
+import { Div, HorizontalScroller, Row, Span, Stack, Text } from "../../../ui/index.js";
+import { FieldInput } from "../../../ui/forms/index.js";
+import { MediaImage } from "../../media/MediaImage.js";
+import { TextLink } from "../../../ui/components/TextLink.js";
+/**
+ * The filter appears once this many NAMES are searchable — cards plus the
+ * grandchildren they match on.
+ *
+ * 🛑 Counting cards alone was wrong, and wrong in the case that prompted this
+ * row. Spinning Tops shows FIVE cards, so a `cards >= 6` rule hid the filter
+ * on exactly the page the request came from — while that page actually has 26
+ * searchable names (5 cards + 21 grandchildren), which is precisely where
+ * typing beats scanning.
+ *
+ * The number of cards is not what the filter searches, so it is not what
+ * should decide whether the filter exists.
+ */
+const FILTER_MIN_NAMES = 12;
+/** Case- and whitespace-insensitive contains. */
+function matches(item, needle) {
+    if (item.name.toLowerCase().includes(needle))
+        return true;
+    /*
+     * 🛑 `?? []`, not a non-null assertion. A card whose children were never
+     * resolved must still match on its OWN name — otherwise a transient fetch
+     * failure upstream silently removes it from every search, which looks like
+     * the category does not exist rather than like a degraded read.
+     */
+    return (item.childNames ?? []).some((n) => n.toLowerCase().includes(needle));
+}
+export function SubcategoryCardRow({ items, label = "Subcategories", }) {
+    const [query, setQuery] = useState("");
+    const needle = query.trim().toLowerCase();
+    const filtered = useMemo(() => (needle ? items.filter((i) => matches(i, needle)) : items), [items, needle]);
+    const searchableNames = useMemo(() => items.reduce((n, i) => n + 1 + (i.childNames?.length ?? 0), 0), [items]);
+    if (items.length === 0)
+        return null;
+    const showFilter = searchableNames >= FILTER_MIN_NAMES;
+    return (_jsxs(Stack, { gap: "xs", children: [_jsxs(Row, { justify: "between", align: "center", gap: "md", wrap: true, children: [_jsx(Text, { size: "xs", color: "muted", weight: "medium", children: label }), showFilter && (_jsx(Div, { className: "w-full sm:w-64", children: _jsx(FieldInput, { name: "subcategory-filter", type: "search", value: query, onChange: setQuery, placeholder: "Filter subcategories\u2026", "aria-label": "Filter subcategories" }) }))] }), filtered.length === 0 ? (
+            /*
+             * A real empty state rather than a blank strip. The row is otherwise
+             * indistinguishable from "this category has no subcategories", which
+             * is a different and much more alarming thing to tell someone.
+             */
+            _jsxs(Text, { size: "sm", color: "muted", children: ["No subcategory matches \u201C", query.trim(), "\u201D."] })) : (_jsx(HorizontalScroller, { showArrows: true, showScrollbar: false, gap: 12, minItemWidth: 150, items: filtered, keyExtractor: (item) => item.id, renderItem: (item) => (_jsx(TextLink, { href: item.href, className: "group block h-full no-underline", "aria-label": item.count !== undefined
+                        ? `${item.name}, ${item.count} listings`
+                        : item.name, children: _jsxs(Stack, { gap: "xs", surface: "card", rounded: "lg", border: "subtle", padding: "sm", className: "h-full transition-colors hover:bg-surface-hover", children: [_jsx(Div, { surface: "muted", rounded: "md", className: `relative aspect-square w-full overflow-hidden flex-shrink-0`, children: item.imageUrl ? (_jsx(MediaImage, { src: item.imageUrl, alt: "", size: "thumbnail", className: "transition-transform duration-300 group-hover:scale-105" })) : (
+                                /*
+                                 * The emoji is the FALLBACK, never an overlay — same rule
+                                 * as `CategoryCard` and `resolveTaxonomyVisual`: an emoji
+                                 * is what you show when there is no picture, not something
+                                 * you paint on top of one.
+                                 */
+                                _jsx(Row, { align: "center", justify: "center", textSize: "2xl", className: "absolute inset-0", children: item.emoji ?? "" })) }), item.level !== undefined && (_jsx(Span, { size: "xs", color: "muted", weight: "medium", children: item.level === 0 ? "L0 · root" : `L${item.level}` })), _jsx(Text, { size: "xs", weight: "medium", className: "line-clamp-2", children: item.name }), item.count !== undefined && (_jsx(Span, { size: "xs", color: "muted", children: item.count.toLocaleString() }))] }) })) }))] }));
+}

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

@@ -10,29 +10,36 @@
  * this shape is browsed, and what the category detail page already supports
  * (it fetches every descendant and renders them tier-grouped).
  *
- * ## 🛑 Parts cannot be matched on `categoryType`
+ * ## 🛑 There is no Parts tab, and that is deliberate
  *
- * Brands, franchises and bundles each carry a discriminator. Parts deliberately
- * DO NOT — `gen-category-parts.mjs` omits `categoryType` because 92 files read
- * it and a new value opts a row out of every path that works. So a part is
- * identified by its ANCESTRY: a leaf whose chain passes through one of the four
- * `*-parts` nodes. That is a fact about where it lives, not a flag that can
- * drift from it.
+ * It was removed 2026-10-20. Parts have a better home than a flat tab over
+ * 752 leaves: `/parts/[classification]/[code]` is a purpose-built part
+ * catalogue with composition data, and the `spares` listing type sells loose
+ * parts. A fifth tab listing every part leaf duplicated the worse half of
+ * both.
+ *
+ * The part leaves themselves are untouched and still reachable by drilling
+ * down from their `*-parts` node, which is also why no `categoryType` was
+ * involved: a part is identified by ANCESTRY, never by a discriminator
+ * (`gen-category-parts.mjs` omits `categoryType` because 92 files read it and
+ * a new value opts a row out of every path that works).
+ *
+ * 🛑 Do not confuse this with the product-detail **Parts composition tab**
+ * ("What it is made of"), gated by `LISTING_TYPE_HAS_COMPOSITION`. That is a
+ * different feature on a different surface and is unaffected.
  *
  * ## Why the tabs partition ONE payload
  *
- * The listing already fetches `?flat=true` once. Deriving all five tabs from
+ * The listing already fetches `?flat=true` once. Deriving all four tabs from
  * that single cached response costs no extra request — a per-tab query would
- * turn one fetch into five for the same data.
+ * turn one fetch into four for the same data.
  *
  * @tag domain:categories
  * @tag layer:constants
  * @tag pattern:shared-literal
  * @tag sideEffects:none
  */
-/** The tier-2 nodes every part leaf hangs beneath. */
-export declare const PART_PARENT_IDS: readonly string[];
-export type CategoryTabKey = "categories" | "brands" | "franchises" | "parts" | "bundles";
+export type CategoryTabKey = "categories" | "brands" | "franchises" | "bundles";
 export interface CategoryTabDef {
     key: CategoryTabKey;
     label: string;
@@ -40,7 +47,7 @@ export interface CategoryTabDef {
 /**
  * 🛑 No "All" tab. It was the default and it was the problem — it is what
  * rendered 1,185 undifferentiated rows. Every tab here answers a question
- * ("which parts do you have?"); "all" answers none of them.
+ * ("which brands do you carry?"); "all" answers none of them.
  */
 export declare const CATEGORY_TABS: readonly CategoryTabDef[];
 export declare const DEFAULT_CATEGORY_TAB: CategoryTabKey;
@@ -48,19 +55,7 @@ export declare const DEFAULT_CATEGORY_TAB: CategoryTabKey;
 interface TabbableCategory {
     categoryType?: string | null;
     tier?: number | null;
-    parentIds?: readonly string[] | null;
-    isLeaf?: boolean | null;
 }
-/**
- * A LEAF whose ancestry passes through a `*-parts` node.
- *
- * 🛑 `isLeaf` is required, not incidental. Without it the tab also matches the
- * 20 classification NODES — "Attack Rings", "Weight Disks" — because their own
- * `parentIds` include a `*-parts` node too, giving 772 entries that mix groups
- * with the parts inside them. A part is a leaf by itself; the classification is
- * a branch you reach by drilling down.
- */
-export declare function isPartCategory(c: TabbableCategory): boolean;
 /**
  * Does this row belong on the given tab?
  *

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

@@ -10,63 +10,48 @@
  * this shape is browsed, and what the category detail page already supports
  * (it fetches every descendant and renders them tier-grouped).
  *
- * ## 🛑 Parts cannot be matched on `categoryType`
+ * ## 🛑 There is no Parts tab, and that is deliberate
  *
- * Brands, franchises and bundles each carry a discriminator. Parts deliberately
- * DO NOT — `gen-category-parts.mjs` omits `categoryType` because 92 files read
- * it and a new value opts a row out of every path that works. So a part is
- * identified by its ANCESTRY: a leaf whose chain passes through one of the four
- * `*-parts` nodes. That is a fact about where it lives, not a flag that can
- * drift from it.
+ * It was removed 2026-10-20. Parts have a better home than a flat tab over
+ * 752 leaves: `/parts/[classification]/[code]` is a purpose-built part
+ * catalogue with composition data, and the `spares` listing type sells loose
+ * parts. A fifth tab listing every part leaf duplicated the worse half of
+ * both.
+ *
+ * The part leaves themselves are untouched and still reachable by drilling
+ * down from their `*-parts` node, which is also why no `categoryType` was
+ * involved: a part is identified by ANCESTRY, never by a discriminator
+ * (`gen-category-parts.mjs` omits `categoryType` because 92 files read it and
+ * a new value opts a row out of every path that works).
+ *
+ * 🛑 Do not confuse this with the product-detail **Parts composition tab**
+ * ("What it is made of"), gated by `LISTING_TYPE_HAS_COMPOSITION`. That is a
+ * different feature on a different surface and is unaffected.
  *
  * ## Why the tabs partition ONE payload
  *
- * The listing already fetches `?flat=true` once. Deriving all five tabs from
+ * The listing already fetches `?flat=true` once. Deriving all four tabs from
  * that single cached response costs no extra request — a per-tab query would
- * turn one fetch into five for the same data.
+ * turn one fetch into four for the same data.
  *
  * @tag domain:categories
  * @tag layer:constants
  * @tag pattern:shared-literal
  * @tag sideEffects:none
  */
-/** The tier-2 nodes every part leaf hangs beneath. */
-export const PART_PARENT_IDS = [
-    "category-original-parts",
-    "category-metal-parts",
-    "category-burst-parts",
-    "category-x-parts",
-];
 /**
  * 🛑 No "All" tab. It was the default and it was the problem — it is what
  * rendered 1,185 undifferentiated rows. Every tab here answers a question
- * ("which parts do you have?"); "all" answers none of them.
+ * ("which brands do you carry?"); "all" answers none of them.
  */
 export const CATEGORY_TABS = [
     { key: "categories", label: "Categories" },
     { key: "brands", label: "Brands" },
     { key: "franchises", label: "Franchises" },
-    { key: "parts", label: "Parts" },
     { key: "bundles", label: "Bundles" },
 ];
 export const DEFAULT_CATEGORY_TAB = "categories";
 const typeOf = (c) => String(c.categoryType ?? "");
-/**
- * A LEAF whose ancestry passes through a `*-parts` node.
- *
- * 🛑 `isLeaf` is required, not incidental. Without it the tab also matches the
- * 20 classification NODES — "Attack Rings", "Weight Disks" — because their own
- * `parentIds` include a `*-parts` node too, giving 772 entries that mix groups
- * with the parts inside them. A part is a leaf by itself; the classification is
- * a branch you reach by drilling down.
- */
-export function isPartCategory(c) {
-    if (typeOf(c))
-        return false; // brand / bundle / franchise / sublisting
-    if (c.isLeaf !== true)
-        return false;
-    return (c.parentIds ?? []).some((p) => PART_PARENT_IDS.includes(String(p)));
-}
 /**
  * Does this row belong on the given tab?
  *
@@ -83,13 +68,11 @@ export function matchesCategoryTab(c, tab) {
             return type === "franchise";
         case "bundles":
             return type === "bundle";
-        case "parts":
-            return isPartCategory(c);
         case "categories":
             /*
-             * A plain, top-level category. Parts are excluded by the type check
-             * being empty AND tier 0 — no part leaf is tier 0 — but a reader should
-             * not have to derive that, so the root test carries the meaning.
+             * A plain, top-level category. Part and model leaves are excluded by the
+             * tier test — no leaf is tier 0 — but a reader should not have to derive
+             * that, so the root test carries the meaning.
              */
             return type === "" && Number(c.tier ?? -1) === 0;
         default:

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

@@ -32,6 +32,18 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      * indistinguishable from a count of nothing (Root Cause #72).
      */
     liveTotalsFor(ids: readonly string[]): Promise<Map<string, number>>;
+    /**
+     * `db.getAll`, not N `findById` calls — same reasoning as `liveTotalsFor`
+     * just above. Built for the site-wide search index's local-resolution
+     * path: the client resolves candidate category ids from the public
+     * artifact at zero reads, and this is the one query the server still
+     * needs to turn those ids into real documents.
+     *
+     * A missing id is simply ABSENT from the returned array, never null —
+     * the caller filters, so there is nothing to distinguish a deleted
+     * category from one that never existed, and nothing needs to.
+     */
+    getManyByIds(ids: readonly string[]): Promise<CategoryDocument[]>;
     getCategoryBySlug(slug: string): Promise<CategoryDocument | null>;
     getRootCategories(): Promise<CategoryDocument[]>;
     getLeafCategories(): Promise<CategoryDocument[]>;

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

@@ -128,6 +128,26 @@ export class CategoriesRepository extends BaseRepository {
         const { total } = await getLiveCategoryCounts(this.db, ids);
         return total;
     }
+    /**
+     * `db.getAll`, not N `findById` calls — same reasoning as `liveTotalsFor`
+     * just above. Built for the site-wide search index's local-resolution
+     * path: the client resolves candidate category ids from the public
+     * artifact at zero reads, and this is the one query the server still
+     * needs to turn those ids into real documents.
+     *
+     * A missing id is simply ABSENT from the returned array, never null —
+     * the caller filters, so there is nothing to distinguish a deleted
+     * category from one that never existed, and nothing needs to.
+     */
+    async getManyByIds(ids) {
+        if (ids.length === 0)
+            return [];
+        const refs = ids.map((id) => this.getCollection().doc(id));
+        const snaps = await this.db.getAll(...refs);
+        return snaps
+            .filter((s) => s.exists)
+            .map((s) => this.mapDoc(s));
+    }
     async getCategoryBySlug(slug) {
         try {
             const snapshot = await this.db

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

@@ -126,6 +126,27 @@ export interface CategoryDocument extends BaseDocument {
     brandCountry?: string;
     /** Brand founding year — categoryType==="brand". */
     brandFounded?: number;
+    /**
+     * The Hasbro / international-market name for this generation or wave, where
+     * it genuinely differs from the Takara-Tomy one. Two real pairs exist and
+     * they are separate waves, not one renaming: TT **God** ships as Hasbro
+     * **Evolution**, and TT **Cho-Z** ships as Hasbro **Turbo**.
+     *
+     * 🛑 RENDERED — "Also known as" on the category detail page. That is the
+     * whole difference from `aliases` below, which feeds `searchTxt` and is
+     * rendered nowhere. A buyer who only knows the Hasbro season name needs to
+     * SEE the correspondence, not merely be found by it.
+     *
+     * Left unset wherever a divergence is not confirmed. An honest gap beats a
+     * guessed pairing — same precedent as the 25 of 220 models with no cover and
+     * the deliberately partial `FRANCHISE_BY_CATEGORY_ROOT`.
+     */
+    hasbroName?: string;
+    /**
+     * Cover for the Hasbro-named variant, shown beside the primary cover when
+     * both exist. Same `/media/<slug>` form as `display.coverImage`.
+     */
+    hasbroCoverImage?: string;
     /**
      * Short bullet points — "why shop this category/brand." Category and
      * brand detail pages only; renders nothing when absent/empty.
@@ -255,7 +276,7 @@ export declare const MIN_ITEMS_FOR_FEATURED: 8;
 export declare const MAX_FEATURED_CATEGORIES: 4;
 export declare const DEFAULT_CATEGORY_DATA: Partial<CategoryDocument>;
 export declare const CATEGORIES_PUBLIC_FIELDS: readonly ["id", "name", "slug", "description", "rootId", "parentIds", "childrenIds", "tier", "path", "order", "position", "subtreeSize", "isLeaf", "metrics.totalProductCount", "metrics.totalAuctionCount", "metrics.totalItemCount", "isFeatured", "featuredPriority", "isBrand", "seo", "display", "isActive", "ancestors", "highlights", "faqs", "contentBody", "descriptionTemplates", "productDefaults", "aliases"];
-export declare const CATEGORIES_UPDATABLE_FIELDS: readonly ["name", "slug", "description", "order", "isFeatured", "featuredPriority", "isBrand", "seo", "display", "isActive", "isSearchable", "highlights", "faqs", "contentBody", "descriptionTemplates", "productDefaults", "aliases"];
+export declare const CATEGORIES_UPDATABLE_FIELDS: readonly ["name", "slug", "description", "order", "isFeatured", "featuredPriority", "isBrand", "seo", "display", "isActive", "isSearchable", "highlights", "faqs", "contentBody", "descriptionTemplates", "productDefaults", "aliases", "hasbroName", "hasbroCoverImage"];
 export type CategoryCreateInput = Omit<CategoryDocument, "id" | "createdAt" | "updatedAt" | "metrics" | "isLeaf" | "ancestors"> & {
     parentIds?: string[];
     parentId?: string | null;

package/dist/features/categories/schemas/firestore.js

@@ -123,6 +123,16 @@ export const CATEGORIES_UPDATABLE_FIELDS = [
     "descriptionTemplates",
     "productDefaults",
     "aliases",
+    /*
+     * The regional-naming pair. Updatable for the same reason the five above
+     * are: without it `CategoryUpdateInput` cannot express the field and the
+     * admin editor would save a 200 and write nothing. Wave names are editorial
+     * and get corrected — the one case this plan would not set (Burst Ultimate ↔
+     * QuadStrike) is exactly the kind a human may later confirm and want to fill
+     * in without a reseed.
+     */
+    "hasbroName",
+    "hasbroCoverImage",
 ];
 export const categoryQueryHelpers = {
     bySlug: (slug) => ["slug", "==", slug],

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

@@ -769,6 +769,8 @@ export declare const categoryFirestoreSchema: z.ZodObject<{
     brandWebsite: z.ZodOptional<z.ZodString>;
     brandCountry: z.ZodOptional<z.ZodString>;
     brandFounded: z.ZodOptional<z.ZodNumber>;
+    hasbroName: z.ZodOptional<z.ZodString>;
+    hasbroCoverImage: z.ZodOptional<z.ZodString>;
     highlights: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     faqs: z.ZodOptional<z.ZodArray<z.ZodObject<{
         question: z.ZodString;
@@ -1363,6 +1365,8 @@ export declare const categoryFirestoreSchema: z.ZodObject<{
     brandWebsite?: string | undefined;
     brandCountry?: string | undefined;
     brandFounded?: number | undefined;
+    hasbroName?: string | undefined;
+    hasbroCoverImage?: string | undefined;
     highlights?: string[] | undefined;
     contentBody?: string | undefined;
     descriptionTemplates?: {
@@ -1534,6 +1538,8 @@ export declare const categoryFirestoreSchema: z.ZodObject<{
     brandWebsite?: string | undefined;
     brandCountry?: string | undefined;
     brandFounded?: number | undefined;
+    hasbroName?: string | undefined;
+    hasbroCoverImage?: string | undefined;
     highlights?: string[] | undefined;
     contentBody?: string | undefined;
     descriptionTemplates?: {

package/dist/features/categories/schemas/index.js

@@ -167,6 +167,8 @@ export const categoryFirestoreSchema = z.object({
     brandWebsite: z.string().optional(),
     brandCountry: z.string().optional(),
     brandFounded: z.number().int().optional(),
+    hasbroName: z.string().optional(),
+    hasbroCoverImage: z.string().optional(),
     highlights: z.array(z.string()).optional(),
     faqs: z.array(z.object({ question: z.string(), answer: z.string() })).optional(),
     aliases: z.array(z.string()).optional(),

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

@@ -49,6 +49,14 @@ export interface CategoryItem {
     brandCountry?: string;
     /** Brand founded year — only set when categoryType==="brand". */
     brandFounded?: number;
+    /**
+     * Hasbro / international-market name for this generation or wave (TT "God" →
+     * Hasbro "Evolution"; TT "Cho-Z" → Hasbro "Turbo"). Rendered as "Also known
+     * as" — unlike `aliases`, which only feeds search.
+     */
+    hasbroName?: string;
+    /** Cover for the Hasbro-named variant, shown beside the primary cover. */
+    hasbroCoverImage?: string;
     /** Short bullet points — "why shop this category/brand." */
     highlights?: string[];
     /** A handful of Q&A pairs shown on the category/brand detail page. */

package/dist/features/categories/utils/taxonomy-visual.d.ts

@@ -14,8 +14,21 @@ export interface TaxonomyVisual {
 /**
  * Resolve the leading visual for a taxonomy row.
  *
- * Precedence: `display.icon` (as image when it is a URL, else as emoji) →
- * `display.coverImage`. Returns an empty object when the row has neither, so
- * the caller can fall back to an initial rather than reserving a blank box.
+ * Precedence: an `icon` that is a URL → `coverImage` → an `icon` that is an
+ * EMOJI. Returns an empty object when the row has none, so the caller can fall
+ * back to an initial rather than reserving a blank box.
+ *
+ * 🛑 The emoji ranks LAST, and that ordering changed 2026-10-20. It used to be
+ * "icon, whatever it holds, then cover", which meant a row carrying both a
+ * real photograph and a decorative emoji rendered the emoji — the twelve
+ * forest roots are exactly that shape. `brand-rows.ts` trap 2 already names
+ * this as the defect rather than the intent: the brand seed leaves `icon`
+ * unset *precisely because* an emoji there would beat a real logo. Honouring
+ * that reading everywhere is what lets a root keep its emoji for menus while
+ * its page shows the photograph.
+ *
+ * An icon that is a URL still wins — that is `BrandsSection`'s long-standing
+ * convention, where `icon` holds the brand logo and is the more specific
+ * choice than a generic cover.
  */
 export declare function resolveTaxonomyVisual(row: TaxonomyVisualSource | null | undefined): TaxonomyVisual;

package/dist/features/categories/utils/taxonomy-visual.js

@@ -7,10 +7,12 @@
  *      either prints a raw URL as visible text, or hands an emoji to an
  *      `<img src>` that then 404s into a broken-image glyph.
  *
- *      On top of that, `icon` BEATS `coverImage` — `brand-rows.ts` trap 2
- *      records why: the brand seed deliberately leaves `icon` unset precisely
- *      because an emoji left there would win over a real logo. A renderer that
- *      checks `coverImage` first silently inverts that rule.
+ *      On top of that there is an ORDERING question between the two, and
+ *      `brand-rows.ts` trap 2 settles it: the brand seed leaves `icon` unset
+ *      *precisely because* an emoji there would win over a real logo. So an
+ *      emoji must rank BELOW a real cover (it is decoration), while an icon
+ *      that is a URL ranks above one (it is the more specific asset). That is
+ *      the precedence implemented below, corrected 2026-10-20.
  *
  *      Two decisions, both easy to get wrong, previously made at each call
  *      site. This is the one place that makes them.
@@ -42,17 +44,31 @@ function looksLikeUrl(value) {
 /**
  * Resolve the leading visual for a taxonomy row.
  *
- * Precedence: `display.icon` (as image when it is a URL, else as emoji) →
- * `display.coverImage`. Returns an empty object when the row has neither, so
- * the caller can fall back to an initial rather than reserving a blank box.
+ * Precedence: an `icon` that is a URL → `coverImage` → an `icon` that is an
+ * EMOJI. Returns an empty object when the row has none, so the caller can fall
+ * back to an initial rather than reserving a blank box.
+ *
+ * 🛑 The emoji ranks LAST, and that ordering changed 2026-10-20. It used to be
+ * "icon, whatever it holds, then cover", which meant a row carrying both a
+ * real photograph and a decorative emoji rendered the emoji — the twelve
+ * forest roots are exactly that shape. `brand-rows.ts` trap 2 already names
+ * this as the defect rather than the intent: the brand seed leaves `icon`
+ * unset *precisely because* an emoji there would beat a real logo. Honouring
+ * that reading everywhere is what lets a root keep its emoji for menus while
+ * its page shows the photograph.
+ *
+ * An icon that is a URL still wins — that is `BrandsSection`'s long-standing
+ * convention, where `icon` holds the brand logo and is the more specific
+ * choice than a generic cover.
  */
 export function resolveTaxonomyVisual(row) {
     const icon = row?.display?.icon?.trim();
-    if (icon) {
-        return looksLikeUrl(icon) ? { imageUrl: icon } : { emoji: icon };
-    }
+    if (icon && looksLikeUrl(icon))
+        return { imageUrl: icon };
     const cover = row?.display?.coverImage?.trim();
     if (cover && looksLikeUrl(cover))
         return { imageUrl: cover };
+    if (icon)
+        return { emoji: icon };
     return {};
 }