@mohasinac/appkit 4.43.0 → 4.44.0

package/dist/features/categories/repository/price-index.repository.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Price Index Repository — what things actually SOLD for here, per leaf.
+ *
+ * ## 🛑 Why this is its own collection and not a field on `categories`
+ *
+ * The obvious design is `categories/{leafId}.productDefaults.priceGuidance.sold`,
+ * beside the seed-owned `market` band it is shown next to. That design is a
+ * runaway-trigger hazard and it is not a theoretical one.
+ *
+ * `onCategoryWrite` is a `documentWritten` trigger on `categories`, so a job
+ * writing a price band there re-triggers it once per document. That is exactly
+ * the shape of Root Cause #92, where `onShipmentHeaderWrite` wrote back to the
+ * collection it watched and produced **1,017,548 invocations in 24 hours**
+ * against a 2M/month allowance, blocked `firebase deploy` with a billing
+ * denial, and degraded production.
+ *
+ * It is also worse than that here, because `notifyRevalidate` fires on every
+ * category write — so each nightly price write would drop that category page's
+ * ISR entry, on a project that was paused for exceeding ISR writes by 15.5×.
+ *
+ * A sibling collection removes the self-write entirely. It costs one extra
+ * read on the surface that shows the band, and buys immunity.
+ *
+ * ## Shape
+ *
+ *   priceIndex/{leafId}                 the current band
+ *   priceIndex/{leafId}/daily/{YYYYMMDD}  one point per day, for a series
+ *
+ * 🛑 NO `soldPrices: number[]` on the document. `CategoryDocument.metrics`
+ * already carries two unbounded arrays and a third is the 1 MiB trap. The
+ * samples stay in job memory and only the summary is written.
+ */
+import { BaseRepository } from "../../../providers/db-firebase";
+/** Which acquisition path a sale came through. Counts, not amounts. */
+export interface PriceIndexByPath {
+    standard?: number;
+    auction?: number;
+    offer?: number;
+}
+export interface PriceIndexDocument {
+    /** The LEAF category id. A sale rolls up to exactly one leaf. */
+    id: string;
+    currency: "INR";
+    /**
+     * Scoped by listing type WITHIN the leaf.
+     *
+     * 🛑 Load-bearing. A named-model leaf holds every listing type for that
+     * model — the bey, its stickers, its spare parts, a used one as a classified
+     * — because `listingType` and `categorySlugs` are independent axes. A ₹399
+     * sticker sheet and a ₹1,299 bey under one leaf would blend into a
+     * meaningless band, so the band is per type and the UI shows the one the
+     * seller is listing.
+     */
+    byListingType: Record<string, PriceIndexBand>;
+    /** How many days of completed sales the bands cover. */
+    windowDays: number;
+    computedAt: Date;
+}
+export interface PriceIndexBand {
+    min: number;
+    median: number;
+    max: number;
+    /**
+     * 🛑 The confidence signal, and the UI must render a small one as a sample
+     * size with NO headline number — the same discipline as `truncated`
+     * rendering "50+" rather than a false total. A median of two sales is a coin
+     * flip presented as data.
+     */
+    sampleSize: number;
+    byPath?: PriceIndexByPath;
+    lastSold?: {
+        amount: number;
+        at: Date;
+        via?: "standard" | "auction" | "offer";
+    };
+}
+/** One day's point, for a series. */
+export interface PriceIndexDailyPoint {
+    id: string;
+    /** `YYYYMMDD`, so the document id sorts chronologically on its own. */
+    date: string;
+    byListingType: Record<string, Pick<PriceIndexBand, "median" | "sampleSize">>;
+    computedAt: Date;
+}
+export declare const PRICE_INDEX_COLLECTION = "priceIndex";
+/**
+ * Below this, a band renders as a sample size and no headline figure.
+ *
+ * Exported because the renderer and the job must agree: a threshold the job
+ * applied and the UI did not would hide bands that exist, and the reverse
+ * would publish a median of one sale as a market rate.
+ */
+export declare const PRICE_INDEX_MIN_CONFIDENT_SAMPLES = 3;
+export declare class PriceIndexRepository extends BaseRepository<PriceIndexDocument> {
+    constructor();
+    getForLeaf(leafId: string): Promise<PriceIndexDocument | null>;
+    /**
+     * Write the current band for one leaf.
+     *
+     * `createWithId`/`update` rather than a blind `set`, matching every other
+     * rollup repository here — and `update` merges, so a leaf whose band for one
+     * listing type disappeared this run would keep the stale entry. Hence
+     * `byListingType` is replaced wholesale by passing the full map.
+     */
+    setForLeaf(leafId: string, data: Pick<PriceIndexDocument, "byListingType" | "windowDays">): Promise<void>;
+    /**
+     * Append today's point.
+     *
+     * Keyed on the date, so a re-run on the same day OVERWRITES rather than
+     * double-counting — the same idempotency `pageViewRollup`'s `throughDate`
+     * buys, achieved here by the document id instead of a cursor.
+     */
+    setDailyPoint(leafId: string, date: string, byListingType: PriceIndexDailyPoint["byListingType"]): Promise<void>;
+}
+export declare const priceIndexRepository: PriceIndexRepository;

package/dist/features/categories/repository/price-index.repository.js

@@ -0,0 +1,85 @@
+/**
+ * Price Index Repository — what things actually SOLD for here, per leaf.
+ *
+ * ## 🛑 Why this is its own collection and not a field on `categories`
+ *
+ * The obvious design is `categories/{leafId}.productDefaults.priceGuidance.sold`,
+ * beside the seed-owned `market` band it is shown next to. That design is a
+ * runaway-trigger hazard and it is not a theoretical one.
+ *
+ * `onCategoryWrite` is a `documentWritten` trigger on `categories`, so a job
+ * writing a price band there re-triggers it once per document. That is exactly
+ * the shape of Root Cause #92, where `onShipmentHeaderWrite` wrote back to the
+ * collection it watched and produced **1,017,548 invocations in 24 hours**
+ * against a 2M/month allowance, blocked `firebase deploy` with a billing
+ * denial, and degraded production.
+ *
+ * It is also worse than that here, because `notifyRevalidate` fires on every
+ * category write — so each nightly price write would drop that category page's
+ * ISR entry, on a project that was paused for exceeding ISR writes by 15.5×.
+ *
+ * A sibling collection removes the self-write entirely. It costs one extra
+ * read on the surface that shows the band, and buys immunity.
+ *
+ * ## Shape
+ *
+ *   priceIndex/{leafId}                 the current band
+ *   priceIndex/{leafId}/daily/{YYYYMMDD}  one point per day, for a series
+ *
+ * 🛑 NO `soldPrices: number[]` on the document. `CategoryDocument.metrics`
+ * already carries two unbounded arrays and a third is the 1 MiB trap. The
+ * samples stay in job memory and only the summary is written.
+ */
+import { BaseRepository } from "../../../providers/db-firebase";
+export const PRICE_INDEX_COLLECTION = "priceIndex";
+const DAILY_SUBCOLLECTION = "daily";
+/**
+ * Below this, a band renders as a sample size and no headline figure.
+ *
+ * Exported because the renderer and the job must agree: a threshold the job
+ * applied and the UI did not would hide bands that exist, and the reverse
+ * would publish a median of one sale as a market rate.
+ */
+export const PRICE_INDEX_MIN_CONFIDENT_SAMPLES = 3;
+export class PriceIndexRepository extends BaseRepository {
+    constructor() {
+        super(PRICE_INDEX_COLLECTION);
+    }
+    async getForLeaf(leafId) {
+        return this.findById(leafId);
+    }
+    /**
+     * Write the current band for one leaf.
+     *
+     * `createWithId`/`update` rather than a blind `set`, matching every other
+     * rollup repository here — and `update` merges, so a leaf whose band for one
+     * listing type disappeared this run would keep the stale entry. Hence
+     * `byListingType` is replaced wholesale by passing the full map.
+     */
+    async setForLeaf(leafId, data) {
+        const payload = { currency: "INR", ...data, computedAt: new Date() };
+        const existing = await this.findById(leafId);
+        if (existing) {
+            await this.update(leafId, payload);
+        }
+        else {
+            await this.createWithId(leafId, payload);
+        }
+    }
+    /**
+     * Append today's point.
+     *
+     * Keyed on the date, so a re-run on the same day OVERWRITES rather than
+     * double-counting — the same idempotency `pageViewRollup`'s `throughDate`
+     * buys, achieved here by the document id instead of a cursor.
+     */
+    async setDailyPoint(leafId, date, byListingType) {
+        await this.db
+            .collection(PRICE_INDEX_COLLECTION)
+            .doc(leafId)
+            .collection(DAILY_SUBCOLLECTION)
+            .doc(date)
+            .set({ date, byListingType, computedAt: new Date() }, { merge: true });
+    }
+}
+export const priceIndexRepository = new PriceIndexRepository();

package/dist/features/categories/schemas/category-content.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Category-owned content — description templates and product defaults.
+ *
+ * ## Why this lives on the CATEGORY and not on a listing template
+ *
+ * `ListingTemplateDocument` is store-scoped. The ask is that the description
+ * lives with the *category*, and the crawl proves the model: worldhobbyshop
+ * reuses TWO bodies across 1,195 listings, and tcgindia generates five
+ * templated FAQs per product. Nobody writes 1,195 descriptions by hand — our
+ * sellers do, because no category→description mechanism exists anywhere in
+ * this codebase.
+ *
+ * ## Why it costs ZERO extra reads
+ *
+ * Both hot paths already hold the category document: `deriveTaxonomy` does
+ * `cats.doc(leaf).get()`, and `CategoryDetailPageView` does `getCategoryBySlug`
+ * plus seven parallel reads — already at Rule #6's ~3-round-trip ceiling. A
+ * sidecar collection would add an eighth read to the second-most-crawled page
+ * on the site.
+ *
+ * ## Why three fields rather than one blob
+ *
+ * Each has exactly one reader: `contentBody` → the category page;
+ * `descriptionTemplates` → the seller form plus the narrow template endpoint;
+ * `productDefaults` → `deriveTaxonomy`. A single `content` object would make
+ * every one of those read the other two.
+ */
+import type { ProductAuthenticity } from "../../products/schemas/firestore";
+/**
+ * Which condition a template is written for.
+ *
+ * 🛑 A KEYED SET, not one body, because worldhobbyshop demonstrably reuses
+ * **two** per category — a pre-owned body and a new-in-box body — and a single
+ * string field cannot express that. The variants are the conditions that
+ * change what the copy must SAY, not every `CONDITION_OPTIONS` value: a
+ * "pre-owned" and a "used" listing want the same disclosure paragraph.
+ */
+export type CategoryTemplateVariant = "default" | "new_in_box" | "new_in_packet" | "pre_owned" | "replica";
+export interface CategoryDescriptionTemplate {
+    id: string;
+    /** What the picker shows, e.g. "Pre-owned — condition as pictured". */
+    label: string;
+    variant: CategoryTemplateVariant;
+    /** `{{placeholder}}` slots; HTML permitted, rendered via RichTextRenderer. */
+    body: string;
+    /**
+     * Slot names found in `body`, derived at write time as a convenience.
+     *
+     * 🛑 ABSENT means "re-parse", never "this body has no slots". A reader that
+     * treats `undefined` as an empty list will skip interpolation entirely on
+     * every template written before this field existed — and the failure is a
+     * published description containing a literal `{{series}}`, which is the most
+     * visible way this feature can break. Use `extractPlaceholders(body)` when
+     * it is absent.
+     */
+    placeholders?: string[];
+    /**
+     * An admin has published a real listing from this template.
+     *
+     * Exists because of raikages, the crawl's counter-example: 114-char bodies
+     * lifted from the Beyblade Wiki, one of which ships with the literal UI
+     * string "Add to Wishlist Add to Wishlist" welded into the product body. An
+     * unreviewed template is how that happens, so the flag records review rather
+     * than assuming it.
+     */
+    isTested?: boolean;
+    version?: number;
+}
+/** A spec row as the product page renders it. */
+export interface CategorySpecification {
+    name: string;
+    value: string;
+    unit?: string;
+}
+/**
+ * What a category hands down to a product filed under it.
+ *
+ * Three behaviours, and the distinction matters more than the field list:
+ *
+ *   WRITTEN      tax, specifications, inTheBox, features — written server-side
+ *                by `deriveTaxonomy` when the product omits them.
+ *   FILL-BLANK   seo* — fills only an empty field, never overwrites.
+ *   ADVISORY     priceGuidance — NEVER written to `price`. It renders as a hint
+ *                beside the price input and nothing else.
+ */
+export interface CategoryProductDefaults {
+    /**
+     * Points at a `taxCodes` row. `deriveTaxonomy` resolves it and writes
+     * `gstRate`/`hsnCode` onto the product; the order item then snapshots from
+     * the product. That layering is what stops a tax-code edit retroactively
+     * re-rating an invoice already issued.
+     */
+    taxCodeId?: string;
+    specifications?: CategorySpecification[];
+    /**
+     * Feature ids merged onto the product, never replacing what it already has.
+     * (The old `defaultTags` name went with `ProductDocument.tags`.)
+     */
+    defaultFeatures?: string[];
+    defaultCondition?: string;
+    defaultAuthenticity?: ProductAuthenticity;
+    /** "What's in the box?" — becomes `ProductDocument.features[]` prose. */
+    inTheBox?: string[];
+    priceGuidance?: CategoryPriceGuidance;
+    seoTitleTemplate?: string;
+    seoDescriptionTemplate?: string;
+    /** Merged with whatever the product already has. */
+    seoKeywords?: string[];
+    weightG?: number;
+    dimensionsCm?: {
+        l: number;
+        w: number;
+        h: number;
+    };
+    shippingPaidBy?: string;
+    fragile?: boolean;
+    /**
+     * Rendered at READ time, so fixing a wrong answer fixes every listing at
+     * once. The tcgindia model — five per product, three interpolating the
+     * name — and nobody else in the crawl of fifteen does it.
+     */
+    faqTemplates?: {
+        question: string;
+        answer: string;
+    }[];
+}
+/**
+ * Two price views, never blended.
+ *
+ * 🛑 `market` and `sold` are rendered SIDE BY SIDE — "Market ₹799–₹1,499 ·
+ * Sold here ₹850–₹1,200 (7 sales)" — and the gap between them is the most
+ * useful thing we can tell a seller, given 76–93% of competitor listings never
+ * sell at their ask. Averaging the two would launder an inference into a
+ * measurement.
+ */
+export interface CategoryPriceGuidance {
+    currency: "INR";
+    /**
+     * Day-1 baseline from the competitor crawl: a TYPICAL MARKET LISTING PRICE.
+     *
+     * 🛑 NOT evidence of a transaction. A competitor's sold-out row proves the
+     * item is GONE, not that it sold at that price. Seed-owned — the rollup job
+     * must never write here, or a quiet night would erase the baseline.
+     */
+    market?: {
+        /**
+         * The one figure every measured band has. Required for exactly that
+         * reason — a band with no central value is not a band.
+         */
+        median: number;
+        /**
+         * 🛑 OPTIONAL, and that is load-bearing. The crawl recorded quartiles for
+         * parts, launchers, TCG and figures and only a MEDIAN AND A RANGE for Hot
+         * Wheels (n=7,418, ₹99–36,500). Requiring p25/p75 would have forced a
+         * range to be retyped as quartiles, which is a different statistic
+         * presented as the one the field is named after. Absent means "not
+         * measured", and the hint renders as "around ₹850" rather than a span.
+         */
+        p25?: number;
+        p75?: number;
+        /**
+         * 🛑 Also optional, for the same reason: the crawl's Beyblade-top table
+         * carries no per-leaf sample size at all, and the one place two sources
+         * disagreed (HMS: beybladeshopindia n=39 against worldhobbyshop n=2) is
+         * recorded precisely because an n=2 median is a coin flip presented as
+         * data. Absent must render as absent — never as a confident figure, and
+         * never as a number somebody filled in to satisfy the type.
+         */
+        sampleSize?: number;
+        asOf: Date;
+        soldOutShare?: number;
+        /**
+         * Which crawl this came from, and any caveat about it — "worldhobbyshop",
+         * "raikages n=68 (the only component-level pricing anywhere)",
+         * "toycollectorsindia 1:64 POOLED across mainline and premium".
+         *
+         * Carried so the question "where did this number come from" is answerable
+         * from the data rather than from a markdown file nobody has open, and so a
+         * source-priority decision can be applied without re-deriving the bands.
+         */
+        source?: string;
+    };
+    /**
+     * OUR completed sales only, including won auctions and accepted offers.
+     *
+     * Absent until there are some — **never zeroed**. A zero would render as a
+     * real figure meaning "things sell here for ₹0", which is worse than silence.
+     */
+    sold?: {
+        min: number;
+        median: number;
+        max: number;
+        sampleSize: number;
+        windowDays: number;
+        byPath?: {
+            standard?: number;
+            auction?: number;
+            offer?: number;
+        };
+    };
+    lastSold?: {
+        amount: number;
+        at: Date;
+        via?: "standard" | "auction" | "offer";
+    };
+}

package/dist/features/categories/schemas/category-content.js

@@ -0,0 +1,28 @@
+/**
+ * Category-owned content — description templates and product defaults.
+ *
+ * ## Why this lives on the CATEGORY and not on a listing template
+ *
+ * `ListingTemplateDocument` is store-scoped. The ask is that the description
+ * lives with the *category*, and the crawl proves the model: worldhobbyshop
+ * reuses TWO bodies across 1,195 listings, and tcgindia generates five
+ * templated FAQs per product. Nobody writes 1,195 descriptions by hand — our
+ * sellers do, because no category→description mechanism exists anywhere in
+ * this codebase.
+ *
+ * ## Why it costs ZERO extra reads
+ *
+ * Both hot paths already hold the category document: `deriveTaxonomy` does
+ * `cats.doc(leaf).get()`, and `CategoryDetailPageView` does `getCategoryBySlug`
+ * plus seven parallel reads — already at Rule #6's ~3-round-trip ceiling. A
+ * sidecar collection would add an eighth read to the second-most-crawled page
+ * on the site.
+ *
+ * ## Why three fields rather than one blob
+ *
+ * Each has exactly one reader: `contentBody` → the category page;
+ * `descriptionTemplates` → the seller form plus the narrow template endpoint;
+ * `productDefaults` → `deriveTaxonomy`. A single `content` object would make
+ * every one of those read the other two.
+ */
+export {};

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

@@ -6,6 +6,8 @@
  */
 import type { CategoryAncestor, CategoryMetrics, CategoryDisplay } from "../types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { CategoryDescriptionTemplate, CategoryProductDefaults } from "./category-content";
+export type { CategoryDescriptionTemplate, CategoryProductDefaults, CategoryPriceGuidance, CategorySpecification, CategoryTemplateVariant, } from "./category-content";
 export type { CategoryAncestor, CategoryMetrics };
 /**
  * How a bundle resolves its member products.
@@ -82,9 +84,9 @@ export interface CategoryDocument extends BaseDocument {
     name: string;
     slug: string;
     description?: string;
-    /** Tester sandbox flag — set on shared admin-seeded test categories/brands/bundles; swept by testerSandboxCleanup. */
+    /** Test-data flag — set on shared admin-seeded test categories/brands/bundles; swept by testDataCleanup. */
     isTestData?: boolean;
-    /** When isTestData, the cutoff after which testerSandboxCleanup deletes this doc. */
+    /** When isTestData, the cutoff after which testDataCleanup deletes this doc. */
     testDataExpiresAt?: Date;
     rootId: string;
     parentIds: string[];
@@ -135,6 +137,38 @@ export interface CategoryDocument extends BaseDocument {
         question: string;
         answer: string;
     }[];
+    /**
+     * Alternate names this category is searched by — indexed into `searchTxt`
+     * and rendered nowhere.
+     *
+     * B5. A named-model leaf is the case that needs it: *Lost Longinus* is sold
+     * in the west as *Lost Luinor L2* and its product code is *B-66*, and a
+     * buyer types whichever one they learned first. `name` can only hold one of
+     * the three.
+     *
+     * 🛑 Watch the 600-token ceiling in `buildSearchTxt`, which truncates
+     * SILENTLY. A category's own tokens (name, slug, description, path, every
+     * ancestor name) come first in the array, so an unbounded alias list would
+     * evict the lineage tokens that are the whole reason ancestors are indexed.
+     * The generator caps a model leaf at the Hasbro name plus the product code.
+     */
+    aliases?: string[];
+    /**
+     * 400–900 chars of keyword-rich HTML with sibling/parent cross-links,
+     * rendered via `<RichTextRenderer>`.
+     *
+     * 🛑 DISTINCT from `description`, which is a <=230-char blurb that also
+     * feeds `seo.description` and every card. Conflating them would put a
+     * 900-char body in a card and a 230-char stub on the page.
+     *
+     * 36 of worldhobbyshop's 46 categories carry one and it is their actual
+     * ranking mechanism; no Shopify competitor in the crawl has any.
+     */
+    contentBody?: string;
+    /** Condition-keyed description bodies. A SET, because WHS reuses two per category. */
+    descriptionTemplates?: CategoryDescriptionTemplate[];
+    /** What this category hands down to a product filed under it. */
+    productDefaults?: CategoryProductDefaults;
     /**
      * "special" — admin-curated bundle; writes reverse `partOfBundleIds`
      * pointers on member products and shows the "Bundled" badge on cards.
@@ -194,6 +228,19 @@ export interface CategoryDocument extends BaseDocument {
     isActive: boolean;
     isSearchable: boolean;
     showOnHomepage?: boolean;
+    /**
+     * Prefix-expanded search tokens, derived on every write by
+     * `CategoriesRepository.buildSearchTxtFor` → `buildCategorySearchTxt`.
+     *
+     * 🛑 Distinct from `isSearchable`, which is an admin visibility flag. This is
+     * the index that makes a category findable AT ALL: before it existed,
+     * `CATEGORY_SEARCH_SCAN_LIMIT` was capped at 100 by `SIEVE_DEFAULTS.maxPageSize`
+     * — so raising that number did nothing — and a tier-4 model like
+     * "Lost Longinus" was unfindable in every picker.
+     *
+     * Never fed any PII: no `createdBy` (a raw uid) and no `createdByStoreName`.
+     */
+    searchTxt?: string[];
     createdBy: string;
     /** Whether this category was created by admin or a store owner. */
     createdByType?: "admin" | "store";
@@ -204,12 +251,12 @@ export interface CategoryDocument extends BaseDocument {
     ancestors: CategoryAncestor[];
 }
 export declare const CATEGORIES_COLLECTION: "categories";
-export declare const CATEGORIES_INDEXED_FIELDS: readonly ["slug", "rootId", "tier", "parentIds", "isLeaf", "isFeatured", "featuredPriority", "isBrand", "categoryType", "isActive", "isSearchable", "showOnHomepage", "createdBy", "createdByType", "createdByStoreId", "createdAt"];
+export declare const CATEGORIES_INDEXED_FIELDS: readonly ["slug", "rootId", "tier", "parentIds", "isLeaf", "isFeatured", "featuredPriority", "isBrand", "categoryType", "isActive", "isSearchable", "showOnHomepage", "searchTxt", "createdBy", "createdByType", "createdByStoreId", "createdAt"];
 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"];
-export declare const CATEGORIES_UPDATABLE_FIELDS: readonly ["name", "slug", "description", "order", "isFeatured", "featuredPriority", "isBrand", "seo", "display", "isActive", "isSearchable"];
+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 type CategoryCreateInput = Omit<CategoryDocument, "id" | "createdAt" | "updatedAt" | "metrics" | "isLeaf" | "ancestors"> & {
     parentIds?: string[];
     parentId?: string | null;
@@ -285,6 +332,11 @@ export declare const CATEGORY_FIELDS: {
     readonly VIEW_COUNT: "viewCount";
     readonly IS_ACTIVE: "isActive";
     readonly IS_SEARCHABLE: "isSearchable";
+    readonly SEARCH_TXT: "searchTxt";
+    readonly CONTENT_BODY: "contentBody";
+    readonly DESCRIPTION_TEMPLATES: "descriptionTemplates";
+    readonly PRODUCT_DEFAULTS: "productDefaults";
+    readonly PRODUCT_DEFAULTS_TAX_CODE_ID: "productDefaults.taxCodeId";
     readonly CATEGORY_TYPE: "categoryType";
     readonly CREATED_BY: "createdBy";
     readonly CREATED_AT: "createdAt";
@@ -293,5 +345,22 @@ export declare const CATEGORY_FIELDS: {
 };
 /**
  * Build a category tree from a flat list of CategoryDocument objects.
+ *
+ * 🛑 ONE INDEXING PASS, then recursion — not a `.filter()` per node.
+ * This used to scan the whole array once per category to find its children,
+ * which is O(n²): 2,209 comparisons at today's 47 nodes, ~109,000 at the ~330
+ * this plan seeds, and **2.25 million** at 1,500. It runs inside
+ * `categoriesRepository.buildTree()`, i.e. on a request path. Grouping by
+ * parent id first makes it O(n log n) (the sorts) and the output is
+ * byte-identical: same roots, same child order, same depths.
+ *
+ * 🛑 The `seen` set is not defensive padding. A root is picked by
+ * `tier === 0`, and nothing stops a corrupt row from being tier 0 *and* a
+ * descendant of its own child (`parentIds` is a denormalised chain that four
+ * different write paths maintain). The old code would recurse forever on that,
+ * and a hung SSR render is worse than a failed one — it holds a function open
+ * for its whole timeout and reports nothing. A revisited node is dropped from
+ * the second position it appears in rather than throwing: a malformed edge
+ * should cost one tile, not the category page.
  */
 export declare function buildCategoryTree(categories: CategoryDocument[], rootId?: string): CategoryTreeNode[];