@mohasinac/appkit 4.43.0 → 4.44.0

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

@@ -0,0 +1,170 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The seller form's category description-template picker — C2c.
+ *
+ * Fills `SellerProductShell`'s `renderTemplateSelector` slot, which existed
+ * with zero consumers until C2b widened it (Root Cause #8's shape: a slot
+ * shell rendered with no render props shows a layout skeleton and no content).
+ *
+ * ## What it is for
+ *
+ * Our sellers write every description from scratch because no
+ * category→description mechanism has ever existed. The competitor crawl shows
+ * the model: worldhobbyshop reuses TWO bodies across 1,195 listings — a
+ * pre-owned disclosure and a new-in-box spec block — and tcgindia generates
+ * five templated FAQs per product. The bodies live on the CATEGORY, so fixing
+ * the copy fixes every future listing at once.
+ *
+ * ## 🛑 The clobber rule is the whole design
+ *
+ * `isDescriptionDirty` arrives from the shell: non-empty after trim AND not
+ * byte-identical to a body applied this session. When it is false the picker
+ * may fill silently — the seller is looking at either an empty box or our own
+ * text. When it is TRUE it must not overwrite; it offers **Replace
+ * description** instead, which is destructive and therefore carries a
+ * `confirmation` on its ActionDef (Rule #7), not a `window.confirm`.
+ *
+ * ## 🛑 "No template" must never blank the field
+ *
+ * A category with no body at any ancestor renders "No template yet" and leaves
+ * whatever is in the box alone. Blanking a field to signal absence is how a
+ * seller loses work to a feature that was trying to help.
+ */
+import React from "react";
+import { useQuery } from "@tanstack/react-query";
+import { Button, Div, Row, Stack, Text } from "../../../ui";
+import { apiClient } from "../../../http";
+import { CATEGORY_ENDPOINTS } from "../../../constants/api-endpoints";
+import { ACTIONS } from "../../../_internal/shared/actions/action-registry";
+import { interpolate } from "../../../_internal/shared/templating/placeholders";
+const PANEL_CLASS = "rounded-lg border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-3)] py-[var(--appkit-space-3)]";
+/**
+ * Which body a condition wants.
+ *
+ * 🛑 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, which is why `CategoryTemplateVariant` has
+ * five members against the form's six conditions.
+ *
+ * `refurbished` maps to `pre_owned` rather than `default`: it has been owned
+ * and worked on, so the disclosure applies. Mapping it to `default` would hand
+ * a refurbished item a brand-new-item body, which is the one wrong answer
+ * available here.
+ */
+export function variantForCondition(condition) {
+    switch (condition) {
+        case "new":
+            return "new_in_box";
+        case "like_new":
+        case "good":
+        case "fair":
+        case "used":
+        case "refurbished":
+            return "pre_owned";
+        default:
+            return "default";
+    }
+}
+function unwrap(res) {
+    const body = res?.data ?? res;
+    return body && typeof body === "object" && "template" in body ? body : null;
+}
+/** "2 of 9 slots could not be filled: {{year}}, {{type}}" */
+function unresolvedNote(unresolved, total) {
+    if (unresolved.length === 0)
+        return null;
+    const named = unresolved.map((n) => `{{${n}}}`).join(", ");
+    return `${unresolved.length} of ${total} slots could not be filled: ${named}`;
+}
+/** "adds 2 specification rows · sets condition to Used" */
+function describeDefaults(defaults) {
+    const parts = [];
+    const specs = defaults.specifications?.length ?? 0;
+    if (specs > 0)
+        parts.push(`${specs} specification row${specs === 1 ? "" : "s"}`);
+    const box = defaults.inTheBox?.length ?? 0;
+    if (box > 0)
+        parts.push(`a "what's in the box" list of ${box}`);
+    const kw = defaults.seoKeywords?.length ?? 0;
+    if (kw > 0)
+        parts.push(`${kw} SEO keyword${kw === 1 ? "" : "s"}`);
+    const faqs = defaults.faqTemplates?.length ?? 0;
+    if (faqs > 0)
+        parts.push(`${faqs} listing FAQ${faqs === 1 ? "" : "s"}`);
+    return parts;
+}
+export function CategoryTemplatePicker({ categoryId, condition, context, isDescriptionDirty, onApply, }) {
+    const variant = variantForCondition(condition);
+    /*
+     * Keyed on (category, variant) — the same pair the endpoint's edge cache is
+     * keyed on, so switching back to a condition the seller already looked at
+     * costs nothing at all. Fired on change, never per keystroke: `condition` is
+     * a select and `categoryId` comes from a picker.
+     */
+    const query = useQuery({
+        queryKey: ["category-description-template", categoryId, variant],
+        enabled: categoryId.length > 0,
+        staleTime: 60 * 60 * 1000,
+        queryFn: async () => unwrap(await apiClient.get(CATEGORY_ENDPOINTS.DESCRIPTION_TEMPLATE(categoryId, variant))),
+    });
+    const data = query.data ?? null;
+    const template = data?.template ?? null;
+    /*
+     * Interpolated here rather than on apply, so the unresolved-slot note is
+     * accurate BEFORE the seller commits. A note that appears only after the
+     * text lands is a report on something they can no longer choose about.
+     */
+    const filled = React.useMemo(() => (template ? interpolate(template.body, context) : null), [template, context]);
+    /*
+     * Auto-fill when the seller owns nothing. Deliberately an effect rather than
+     * a render-time write: the body has to reach the draft, which is the
+     * shell's state.
+     *
+     * 🛑 Guarded on `isDescriptionDirty` reading FALSE, which covers all three
+     * silent cases the plan specifies — never touched, cleared, or still showing
+     * a body we applied. The seller who typed one character gets the button
+     * instead.
+     *
+     * `filled.text` is in the dependency list, so changing the category or the
+     * condition refreshes a body we own. That is the "Updated for Burst Dual
+     * Layer" case, and it is the reason this is not a one-shot.
+     */
+    const applied = data && template && filled;
+    React.useEffect(() => {
+        if (!applied || isDescriptionDirty)
+            return;
+        onApply({
+            description: filled.text,
+            appliedTemplateId: template.id,
+            appliedTemplateBody: filled.text,
+        });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [applied, isDescriptionDirty, filled?.text, template?.id]);
+    if (categoryId.length === 0)
+        return null;
+    if (query.isLoading) {
+        return (_jsx(Div, { className: PANEL_CLASS, children: _jsx(Text, { size: "xs", color: "muted", children: "Looking for a description template for this category\u2026" }) }));
+    }
+    /*
+     * 🛑 A failed fetch says so, and does NOT fall through to "No template yet".
+     * Those are different facts, and conflating them is Root Cause #72's rule
+     * one level out: absence must never be reported as a measured zero.
+     */
+    if (query.isError) {
+        return (_jsx(Div, { className: PANEL_CLASS, children: _jsx(Text, { size: "xs", color: "muted", children: "Could not load the category's description template. Your description is untouched \u2014 write your own, or try again in a moment." }) }));
+    }
+    if (!data || !template || !filled) {
+        return (_jsx(Div, { className: PANEL_CLASS, children: _jsx(Text, { size: "xs", color: "muted", children: "No description template for this category yet \u2014 write your own, and an admin can add one so the next listing starts from it." }) }));
+    }
+    const note = unresolvedNote(filled.unresolved, template.placeholders?.length ?? filled.unresolved.length);
+    const extras = describeDefaults(data.defaults);
+    const source = data.inheritedFromName
+        ? `Inherited from ${data.inheritedFromName}`
+        : "From this category";
+    return (_jsx(Div, { className: PANEL_CLASS, children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Row, { gap: "sm", align: "center", justify: "between", wrap: true, children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "sm", weight: "semibold", children: template.label }), _jsxs(Text, { size: "xs", color: "muted", children: [source, isDescriptionDirty ? "" : " · applied"] })] }), isDescriptionDirty ? (_jsx(Button, { action: ACTIONS.STORE["replace-description"], size: "sm", onClick: () => onApply({
+                                description: filled.text,
+                                appliedTemplateId: template.id,
+                                appliedTemplateBody: filled.text,
+                            }) })) : null] }), note ? (_jsx(Text, { size: "xs", color: "muted", children: note })) : null, extras.length > 0 ? (_jsxs(Text, { size: "xs", color: "muted", children: ["This category also supplies ", extras.join(", "), " when you save."] })) : null, isDescriptionDirty ? (_jsx(Text, { size: "xs", color: "muted", children: "Your own description is kept \u2014 nothing was overwritten." })) : null] }) }));
+}

package/dist/features/categories/constants/listing-categories.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `categoryType` values that are NOT browsable listing categories.
+ *
+ * - `brand`     — a manufacturer/publisher row, browsed at `/brands/{slug}`
+ * - `bundle`    — a priced bundle, browsed at `/bundles/{slug}`
+ * - `sublisting`— a grading/variant axis (`"PSA 10"`, `"105RF"`), never browsed
+ */
+export declare const NON_LISTING_CATEGORY_TYPES: ReadonlySet<string>;
+/**
+ * True when a category row is a real, browsable listing category.
+ *
+ * Structural parameter on purpose: callers hold `CategoryDocument` (server) or
+ * `CategoryItem` (client) and neither should have to be imported here.
+ */
+export declare function isListingCategory(cat: {
+    categoryType?: string | null;
+}): boolean;

package/dist/features/categories/constants/listing-categories.js

@@ -0,0 +1,53 @@
+/*
+ * WHY: four surfaces need to answer "is this row a browsable listing category,
+ *      or is it a brand / bundle / sublisting sharing the collection?" — the
+ *      sitemap, the filter-facet hook, the public categories route, and the
+ *      catalogue editor's picker. Three of them had already hand-written the
+ *      same Set, which is how the fourth got shipped without one.
+ *
+ * WHAT: one Set and one predicate. No imports, so it is safe in a client
+ *       bundle (Root Cause #6) and safe in a server-only metadata path
+ *       (Root Cause #76).
+ *
+ * 🛑 THE TEST CANNOT BE A FIRESTORE CLAUSE, and that is the whole reason this
+ * exists as a predicate rather than a query filter. A plain listing category
+ * **OMITS** `categoryType` entirely — that is the convention every seeded
+ * listing category follows — so there is no value to match on and
+ * `where("categoryType", "not-in", [...])` would exclude every real category
+ * (a Firestore inequality drops documents that lack the field). It has to be
+ * applied in memory, after the fetch.
+ *
+ * Measured cost of not doing this: the `/products` category facet offered 11
+ * options of which **9 were not categories** — "Takara-Tomy", "Hasbro",
+ * "Burst Battlers Pack", "X-Series Starter Set" — and the catalogue editor's
+ * category picker offered "Original Collector's Set" and "Metal Fusion Duo".
+ * It fails silently because a short list of plausible names is
+ * indistinguishable from a correct one.
+ *
+ * @tag domain:categories
+ * @tag layer:constants
+ * @tag access:isomorphic
+ * @tag sideEffects:none
+ */
+/**
+ * `categoryType` values that are NOT browsable listing categories.
+ *
+ * - `brand`     — a manufacturer/publisher row, browsed at `/brands/{slug}`
+ * - `bundle`    — a priced bundle, browsed at `/bundles/{slug}`
+ * - `sublisting`— a grading/variant axis (`"PSA 10"`, `"105RF"`), never browsed
+ */
+export const NON_LISTING_CATEGORY_TYPES = new Set([
+    "brand",
+    "bundle",
+    "sublisting",
+]);
+/**
+ * True when a category row is a real, browsable listing category.
+ *
+ * Structural parameter on purpose: callers hold `CategoryDocument` (server) or
+ * `CategoryItem` (client) and neither should have to be imported here.
+ */
+export function isListingCategory(cat) {
+    const kind = cat.categoryType;
+    return typeof kind !== "string" || !NON_LISTING_CATEGORY_TYPES.has(kind);
+}

package/dist/features/categories/hooks/useCategoryTree.js

@@ -2,6 +2,7 @@
 import { useQuery } from "@tanstack/react-query";
 import { apiClient } from "../../../http";
 import { CATEGORY_ENDPOINTS } from "../../../constants/api-endpoints";
+import { isListingCategory } from "../constants/listing-categories";
 /**
  * Returns all categories flattened in DFS tree order:
  * parent → its children → their children, etc.
@@ -11,11 +12,36 @@ export function useCategoryTree(opts) {
     const { data, isLoading } = useQuery({
         queryKey: ["categories", "tree"],
         queryFn: async () => {
-            const res = await apiClient.get(`${CATEGORY_ENDPOINTS.LIST}?pageSize=300&sort=tier,order,name`);
+            /*
+             * 🛑 `flat=true` is load-bearing, not a preference.
+             *
+             * `/api/categories` computes `isFiltered` from flat/parentId/featured/
+             * isBrand/showOnHomepage/tier/type. `pageSize` and `sort` are NOT in
+             * that set — so a request carrying only those falls through to TREE
+             * mode, which returns a NESTED payload with only roots at the top
+             * level. `flattenTree` below then builds its adjacency map from roots
+             * alone and `dfs(null)` emits tier-0 only.
+             *
+             * Measured against production data before this fix: the category
+             * facet on /products, /auctions, /pre-orders and /prize-draws showed
+             * **11 options instead of 47** — and 9 of those 11 were not categories
+             * at all. It listed "Takara-Tomy", "Hasbro", "Burst Battlers Pack" and
+             * "X-Series Starter Set", because brand and bundle rows live in the
+             * same collection with empty `parentIds`, so tree mode surfaced them
+             * as roots.
+             *
+             * It failed silently because a short list of plausible-looking names
+             * is indistinguishable from a correct one.
+             *
+             * `sort` was also dropped: BOTH branches hardcode `sort: "order"`, and
+             * this hook re-orders by DFS anyway, so passing it implied a control
+             * that never existed.
+             */
+            const res = await apiClient.get(`${CATEGORY_ENDPOINTS.LIST}?flat=true&pageSize=500`);
             const items = Array.isArray(res)
                 ? res
                 : res.items ?? res.data ?? [];
-            return flattenTree(items);
+            return flattenTree(items.filter(isListingCategory));
         },
         enabled: opts?.enabled ?? true,
         staleTime: 5 * 60 * 1000, // 5 min

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

@@ -1,10 +1,14 @@
 import { BaseRepository, type FirebaseSieveFields, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
 import { type CategoryCreateInput, type CategoryDocument, type CategoryMoveInput, type CategoryTreeNode } from "../schemas";
-import type { FirestoreDocument } from "@mohasinac/appkit";
+import type { FirestoreDocument, JsonValue } from "@mohasinac/appkit";
 export declare class CategoriesRepository extends BaseRepository<CategoryDocument> {
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
     constructor();
-    list(model: SieveModel): Promise<FirebaseSieveResult<CategoryDocument>>;
+    /** Derived on every write path via `applyWriteHooks`. */
+    protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;
+    list(model: SieveModel, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<CategoryDocument>>;
     createWithHierarchy(input: CategoryCreateInput): Promise<CategoryDocument>;
     getCategoryBySlug(slug: string): Promise<CategoryDocument | null>;
     getRootCategories(): Promise<CategoryDocument[]>;
@@ -20,16 +24,64 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      * caller still slices to its own limit.
      */
     getCategoriesByTier(tier: number, limit?: number): Promise<CategoryDocument[]>;
-    getCategoriesByRootId(rootId: string): Promise<CategoryDocument[]>;
-    getChildren(parentId: string): Promise<CategoryDocument[]>;
     /**
-     * IDs of every descendant category at any depth (not just direct
-     * children) — `parentIds` stores the full ancestor chain, so a single
-     * array-contains query on that field already returns the whole subtree
-     * with no recursion needed. Used to expand a parent category's product
-     * listing/count to include products filed under any of its children.
+     * Every category sharing a root, tier-then-order.
+     *
+     * 🛑 `limit` is for DISPLAY callers only, and it is a real truncation.
+     * `buildTree(rootId)` must pass nothing: a tree built from a truncated node
+     * list silently drops whole branches, which is the exact failure
+     * `getDescendants`'s docstring was rewritten to avoid. A display grid of
+     * sibling categories, by contrast, renders ~20 tiles and has no reason to
+     * read 1,500 documents to do it.
+     *
+     * Paginated rather than one unbounded `.get()`: the previous form read the
+     * whole root subtree into memory on every category page render, which at the
+     * ~330-node forest this plan seeds is ~9% of a 50K/day Firestore budget for
+     * ONE page view.
+     */
+    /**
+     * Several categories by id, in ONE round trip, in the order asked for.
+     *
+     * The ancestor-walk primitive. A five-tier tree means a leaf has up to four
+     * ancestors, and resolving an inherited description template or an inherited
+     * `productDefaults` means reading them nearest-first until the answer is
+     * found — which as four sequential `findById` calls is four round trips, on
+     * a route the seller form hits on every category change. Rule #6 budgets
+     * about three for a whole request.
+     *
+     * 🛑 Order is PRESERVED and missing ids are DROPPED, not nulled. Callers
+     * walk the result looking for the first document that declares a thing, so
+     * "nearest first" has to survive the round trip — Firestore's `getAll`
+     * already answers in argument order, and this keeps that guarantee explicit
+     * rather than incidental. A caller needing to know WHICH id was missing
+     * should compare lengths; none does, because an ancestor that no longer
+     * exists is a data problem for the reconcile job, not a reason to fail a
+     * form.
+     *
+     * Bounded at 30 to match `array-contains-any`'s cap, so this cannot become
+     * the unbounded read that `getCategoriesByRootId` had to be rewritten to
+     * avoid being.
      */
-    getDescendantIds(categoryId: string): Promise<string[]>;
+    findByIds(ids: string[]): Promise<CategoryDocument[]>;
+    getCategoriesByRootId(rootId: string, opts?: {
+        limit?: number;
+    }): Promise<CategoryDocument[]>;
+    /**
+     * Categories whose `productDefaults.taxCodeId` points at `taxCodeId`.
+     *
+     * 🛑 Exists so DELETE on a tax code can REFUSE while it is referenced.
+     * `taxCodeId` is a plain string with no referential integrity, and a
+     * dangling reference does not error — `findResolvable` answers `null`,
+     * whose correct handling is "leave the product's gstRate alone", so every
+     * subsequent listing under that category silently derives NO TAX. It does
+     * not fail; it under-charges, until someone reads an invoice.
+     *
+     * One equality on a dot-path — served by the automatic index, no composite
+     * to declare. Bounded at 200: the answer is used to NAME referrers in a 409
+     * message, and the first five are what the admin reads.
+     */
+    findByTaxCodeId(taxCodeId: string): Promise<CategoryDocument[]>;
+    getChildren(parentId: string): Promise<CategoryDocument[]>;
     /**
      * Every descendant DOCUMENT at any depth.
      *
@@ -169,7 +221,6 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      * SB-UNI-B — derive the canonical `sublisting-{slug}` ID from a
      * human-entered category name.
      */
-    incrementViewCount(categoryId: string): Promise<void>;
     generateSublistingId(name: string): string;
 }
 export declare const categoriesRepository: CategoriesRepository;

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

@@ -1,15 +1,45 @@
 import { normalizeError } from "../../../errors/normalize";
 import { increment, arrayUnion, arrayRemove, } from "../../../contracts/field-ops";
 import { DatabaseError } from "../../../errors";
-import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
+import { BaseRepository, prepareForFirestore, parseSieveDateValue, applySieveToFirestore, } from "../../../providers/db-firebase";
+import { buildCategorySearchTxt } from "../../../utils/search-txt-builders";
+import { planSearchTxt, refineSearchTxt, emptySearchResult, } from "../../../utils/search-txt-query";
 import { PRODUCT_FIELDS } from "../../../constants/field-names";
 import { CATEGORY_FIELDS, CATEGORIES_COLLECTION, MIN_ITEMS_FOR_FEATURED, buildCategoryTree, calculateCategoryFields, canBeFeatured, createCategoryId, isValidCategoryMove, } from "../schemas";
 export class CategoriesRepository extends BaseRepository {
     constructor() {
         super(CATEGORIES_COLLECTION);
     }
-    async list(model) {
-        return this.sieveQuery(model, CategoriesRepository.SIEVE_FIELDS);
+    /** Derived on every write path via `applyWriteHooks`. */
+    buildSearchTxtFor(data) {
+        return buildCategorySearchTxt(data);
+    }
+    async list(model, opts) {
+        /*
+         * `q` is a searchTxt pushdown, NOT a Sieve filter.
+         *
+         * `plan.head` becomes one `array-contains` on the longest term and
+         * `plan.rest` is AND-refined in memory — the same two-part shape the other
+         * ten migrated collections use. Going through `planSearchTxt` rather than
+         * hand-rolling it is what buys the `empty` guard: a query that normalises
+         * to no usable token (`"!!!"`, `"—"`) must return NOTHING, because
+         * emitting no clause at all returns the whole collection and calls it a
+         * search result. That is the live bug `products` still has (A2).
+         */
+        const plan = planSearchTxt(opts?.search);
+        if (plan.empty)
+            return emptySearchResult();
+        if (!plan.head) {
+            return this.sieveQuery(model, CategoriesRepository.SIEVE_FIELDS);
+        }
+        const baseQuery = this.getCollection().where(CATEGORY_FIELDS.SEARCH_TXT, "array-contains", plan.head);
+        const result = await applySieveToFirestore({
+            baseQuery,
+            model,
+            fields: CategoriesRepository.SIEVE_FIELDS,
+            mapDoc: (snap) => this.mapDoc(snap),
+        });
+        return refineSearchTxt(result, plan.rest);
     }
     async createWithHierarchy(input) {
         try {
@@ -141,21 +171,139 @@ export class CategoriesRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve categories by tier: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
-    async getCategoriesByRootId(rootId) {
+    /**
+     * Every category sharing a root, tier-then-order.
+     *
+     * 🛑 `limit` is for DISPLAY callers only, and it is a real truncation.
+     * `buildTree(rootId)` must pass nothing: a tree built from a truncated node
+     * list silently drops whole branches, which is the exact failure
+     * `getDescendants`'s docstring was rewritten to avoid. A display grid of
+     * sibling categories, by contrast, renders ~20 tiles and has no reason to
+     * read 1,500 documents to do it.
+     *
+     * Paginated rather than one unbounded `.get()`: the previous form read the
+     * whole root subtree into memory on every category page render, which at the
+     * ~330-node forest this plan seeds is ~9% of a 50K/day Firestore budget for
+     * ONE page view.
+     */
+    /**
+     * Several categories by id, in ONE round trip, in the order asked for.
+     *
+     * The ancestor-walk primitive. A five-tier tree means a leaf has up to four
+     * ancestors, and resolving an inherited description template or an inherited
+     * `productDefaults` means reading them nearest-first until the answer is
+     * found — which as four sequential `findById` calls is four round trips, on
+     * a route the seller form hits on every category change. Rule #6 budgets
+     * about three for a whole request.
+     *
+     * 🛑 Order is PRESERVED and missing ids are DROPPED, not nulled. Callers
+     * walk the result looking for the first document that declares a thing, so
+     * "nearest first" has to survive the round trip — Firestore's `getAll`
+     * already answers in argument order, and this keeps that guarantee explicit
+     * rather than incidental. A caller needing to know WHICH id was missing
+     * should compare lengths; none does, because an ancestor that no longer
+     * exists is a data problem for the reconcile job, not a reason to fail a
+     * form.
+     *
+     * Bounded at 30 to match `array-contains-any`'s cap, so this cannot become
+     * the unbounded read that `getCategoriesByRootId` had to be rewritten to
+     * avoid being.
+     */
+    async findByIds(ids) {
+        const unique = Array.from(new Set(ids.filter(Boolean))).slice(0, 30);
+        if (unique.length === 0)
+            return [];
         try {
-            const snapshot = await this.db
-                .collection(this.collection)
-                .where(CATEGORY_FIELDS.ROOT_ID, "==", rootId)
-                .orderBy(CATEGORY_FIELDS.TIER, "asc")
-                .orderBy(CATEGORY_FIELDS.ORDER, "asc")
-                .get();
-            return snapshot.docs.map((doc) => this.mapDoc(doc));
+            const refs = unique.map((id) => this.db.collection(this.collection).doc(id));
+            const snaps = await this.db.getAll(...refs);
+            return snaps
+                .filter((s) => s.exists)
+                .map((s) => this.mapDoc(s));
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            /*
+             * 🛑 The raw `.message` is NOT interpolated into the thrown error — only
+             * the normalised `kind` and a count.
+             *
+             * Several older methods in this file do interpolate it, and
+             * `audit-raw-error-text` flagged this one for trying. The reasoning is
+             * Root Cause #86's: a thrown value's message is written for a developer,
+             * and this one reaches a user through the route's 500 branch — which is
+             * how a Node `MODULE_NOT_FOUND` with a full require stack ended up
+             * rendered inside the "Place your bid" modal.
+             *
+             * The ids are counted rather than listed. A category id is not
+             * sensitive, but 30 of them in one line is noise against Hobby's ~4 KB/s
+             * log budget.
+             *
+             * (`normalizeError` has to be the FIRST statement, not merely nearby:
+             * `audit-catch-normalize` looks within a few lines of the catch, and the
+             * first draft put this comment above the call and tripped it.)
+             */
+            throw new DatabaseError(`Failed to read categories by id (${unique.length} requested): ${e.kind}`);
+        }
+    }
+    async getCategoriesByRootId(rootId, opts) {
+        try {
+            const cap = opts?.limit;
+            const pageSize = cap ? Math.min(cap, 300) : 300;
+            const out = [];
+            let cursor = null;
+            for (;;) {
+                let q = this.db
+                    .collection(this.collection)
+                    .where(CATEGORY_FIELDS.ROOT_ID, "==", rootId)
+                    .orderBy(CATEGORY_FIELDS.TIER, "asc")
+                    .orderBy(CATEGORY_FIELDS.ORDER, "asc")
+                    .limit(pageSize);
+                if (cursor)
+                    q = q.startAfter(cursor);
+                const page = await q.get();
+                if (page.empty)
+                    break;
+                for (const doc of page.docs)
+                    out.push(this.mapDoc(doc));
+                if (cap && out.length >= cap)
+                    return out.slice(0, cap);
+                if (page.size < pageSize)
+                    break;
+                cursor = page.docs[page.docs.length - 1];
+            }
+            return out;
         }
         catch (error) {
             void normalizeError(error);
             throw new DatabaseError(`Failed to retrieve categories by rootId: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
+    /**
+     * Categories whose `productDefaults.taxCodeId` points at `taxCodeId`.
+     *
+     * 🛑 Exists so DELETE on a tax code can REFUSE while it is referenced.
+     * `taxCodeId` is a plain string with no referential integrity, and a
+     * dangling reference does not error — `findResolvable` answers `null`,
+     * whose correct handling is "leave the product's gstRate alone", so every
+     * subsequent listing under that category silently derives NO TAX. It does
+     * not fail; it under-charges, until someone reads an invoice.
+     *
+     * One equality on a dot-path — served by the automatic index, no composite
+     * to declare. Bounded at 200: the answer is used to NAME referrers in a 409
+     * message, and the first five are what the admin reads.
+     */
+    async findByTaxCodeId(taxCodeId) {
+        try {
+            const snap = await this.getCollection()
+                .where(CATEGORY_FIELDS.PRODUCT_DEFAULTS_TAX_CODE_ID, "==", taxCodeId)
+                .limit(200)
+                .get();
+            return snap.docs.map((d) => this.mapDoc(d));
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to find categories by tax code: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    }
     async getChildren(parentId) {
         try {
             const snapshot = await this.db
@@ -173,17 +321,16 @@ export class CategoriesRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve children categories: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
-    /**
-     * IDs of every descendant category at any depth (not just direct
-     * children) — `parentIds` stores the full ancestor chain, so a single
-     * array-contains query on that field already returns the whole subtree
-     * with no recursion needed. Used to expand a parent category's product
-     * listing/count to include products filed under any of its children.
+    /*
+     * 🛑 `getDescendantIds` was DELETED (2026-10-10). It was
+     * `getDescendants(id).then(d => d.map(x => x.id))`, and its only caller —
+     * CategoryDetailPageView — already held the documents from its own
+     * `getDescendants` call in the same render. So it re-ran the identical
+     * paginated subtree query and discarded everything but the ids: ~330 wasted
+     * reads per page view at the forest size this plan seeds, and two answers
+     * that could disagree whenever one read failed and the other did not.
+     * Call `getDescendants` and `.map(d => d.id)` at the one site that needs it.
      */
-    async getDescendantIds(categoryId) {
-        const docs = await this.getDescendants(categoryId);
-        return docs.map((d) => d.id);
-    }
     /**
      * Every descendant DOCUMENT at any depth.
      *
@@ -696,24 +843,19 @@ export class CategoriesRepository extends BaseRepository {
             .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
+     * Firestore write per render, and a second counter racing `pageViews`).
+     *
+     * Measured: `viewCount` is absent from all 58 category documents. Deleting
+     * the writer nobody calls is what stops the dead field reading as live. See
+     * the products repository for the same removal.
+     */
     /**
      * SB-UNI-B — derive the canonical `sublisting-{slug}` ID from a
      * human-entered category name.
      */
-    async incrementViewCount(categoryId) {
-        try {
-            await this.db
-                .collection(this.collection)
-                .doc(categoryId)
-                .update({ [CATEGORY_FIELDS.VIEW_COUNT]: increment(1) });
-            // Fire-and-forget analytics: a lost view increment changes nothing that
-            // renders, so it must never break the category read path it rides along
-            // with — the count is approximate by design.
-        }
-        catch (_err) {
-            void normalizeError(_err);
-        }
-    }
     generateSublistingId(name) {
         const base = name
             .toLowerCase()
@@ -730,6 +872,7 @@ CategoriesRepository.SIEVE_FIELDS = {
     isActive: { canFilter: true, canSort: false },
     isFeatured: { canFilter: true, canSort: false },
     isBrand: { canFilter: true, canSort: false },
+    searchTxt: { canFilter: true, canSort: false },
     categoryType: { canFilter: true, canSort: false },
     isSearchable: { canFilter: true, canSort: false },
     parentId: { canFilter: true, canSort: false, path: "parentIds" },