@mohasinac/appkit 4.42.18 → 4.44.0

package/dist/features/catalogue/components/CatalogueItemEditorView.js

@@ -38,8 +38,12 @@ import { useMediaUpload } from "../../media";
 import { MediaUploadList } from "../../media/upload/MediaUploadList";
 import { createCatalogueItemSchema } from "../schemas/validation";
 /** PUBLIC endpoints — this is a buyer surface; the admin ones would 403. */
-async function loadOptionsFrom(endpoint, query, page) {
-    const params = new URLSearchParams({ page: String(page), pageSize: "25" });
+async function loadOptionsFrom(endpoint, query, page, 
+/** Extra query params. Passed as an object rather than baked into
+ *  `endpoint`, because this builds its own `?` and a pre-existing query
+ *  string would produce `...?listingOnly=true?page=1`. */
+extra) {
+    const params = new URLSearchParams({ page: String(page), pageSize: "25", ...extra });
     if (query)
         params.set("q", query);
     const res = await apiClient.get(`${endpoint}?${params.toString()}`);
@@ -49,7 +53,14 @@ async function loadOptionsFrom(endpoint, query, page) {
         hasMore: data.hasMore ?? false,
     };
 }
-const loadCategoryOptions = (q, p) => loadOptionsFrom(CATEGORY_ENDPOINTS.LIST, q, p);
+/*
+ * 🛑 `listingOnly=true` is load-bearing. Without it this picker offered brand
+ * and bundle rows as categories — measured against production: "Takara-Tomy",
+ * "Original Collector's Set", "Metal Fusion Duo". They share the `categories`
+ * collection and a plain listing category omits `categoryType`, so the test
+ * cannot be a query clause; the route applies it in memory.
+ */
+const loadCategoryOptions = (q, p) => loadOptionsFrom(CATEGORY_ENDPOINTS.LIST, q, p, { listingOnly: "true" });
 const loadBrandOptions = (q, p) => loadOptionsFrom(BRAND_ENDPOINTS.LIST, q, p);
 export function CatalogueItemEditorView({ item, onSaved }) {
     const isCreate = !item;

package/dist/features/categories/actions/category-actions.d.ts

@@ -9,8 +9,8 @@ export declare function listCategories(params?: {
     page?: number;
     pageSize?: number;
 }): Promise<FirebaseSieveResult<CategoryDocument>>;
-export declare function listTopLevelCategories(limit?: number): Promise<CategoryDocument[]>;
-export declare function listBrandCategories(limit?: number): Promise<CategoryDocument[]>;
+export declare const listTopLevelCategories: (limit?: number) => Promise<CategoryDocument[]>;
+export declare const listBrandCategories: (limit?: number) => Promise<CategoryDocument[]>;
 export declare function getCategoryById(id: string): Promise<CategoryDocument | null>;
 export declare function getCategoryBySlug(slug: string): Promise<CategoryDocument | null>;
 export declare function getCategoryChildren(parentId: string): Promise<CategoryDocument[]>;

package/dist/features/categories/actions/category-actions.js

@@ -1,3 +1,4 @@
+import { cache } from "react";
 import { serverLogger } from "../../../monitoring";
 import { categoriesRepository } from "../repository/categories.repository";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility";
@@ -39,19 +40,30 @@ export async function listCategories(params) {
     };
     return categoriesRepository.list(sieve);
 }
-export async function listTopLevelCategories(limit = 12) {
-    const all = await categoriesRepository.getCategoriesByTier(0);
+/*
+ * Both of these fetched the ENTIRE matching set and `.slice()`d it to 12, on
+ * every homepage render. The bound is now pushed into Firestore (with headroom
+ * for the post-fetch filters), and both are `cache()`-wrapped so a second reader
+ * in the same request tree — the nav, a footer, a sibling section — costs
+ * nothing. Measured 2026-10-09 against a 50K-reads/day free tier.
+ *
+ * The in-memory `isActive !== false` filter is gone: both queries already
+ * require `isActive == true`, and a Firestore equality excludes documents
+ * lacking the field, so it could never match anything the query had not already
+ * admitted. `hidePublicTestData` stays — that one is a real post-filter, which
+ * is why the repository fetches with headroom rather than exactly `limit`.
+ */
+export const listTopLevelCategories = cache(async (limit = 12) => {
+    const all = await categoriesRepository.getCategoriesByTier(0, limit);
     return hidePublicTestData(all)
-        .filter((c) => c.isActive !== false)
         .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
         .slice(0, limit);
-}
-export async function listBrandCategories(limit = 12) {
-    const brands = await categoriesRepository.getBrandCategories();
-    return hidePublicTestData(brands)
-        .filter((c) => c.isActive !== false)
-        .slice(0, limit);
-}
+});
+export const listBrandCategories = cache(async (limit = 12) => {
+    // Over-fetch a small margin so `hidePublicTestData` cannot under-fill the row.
+    const brands = await categoriesRepository.getBrandCategories(limit + 8);
+    return hidePublicTestData(brands).slice(0, limit);
+});
 export async function getCategoryById(id) {
     return categoriesRepository.findById(id);
 }

package/dist/features/categories/api/[id]/description-template/route.d.ts

@@ -0,0 +1,45 @@
+/**
+ * feat-categories — GET /api/categories/[id]/description-template
+ *
+ * The ONE read the seller form makes when a category or condition changes.
+ *
+ * ```ts
+ * // app/api/categories/[id]/description-template/route.ts
+ * export { categoryDescriptionTemplateGET as GET } from "@mohasinac/appkit";
+ * ```
+ *
+ * ## Why an endpoint rather than letting the client walk the tree
+ *
+ * A description template lives on the category and INHERITS: a named-model
+ * leaf like `category-dragoon-g` carries no body of its own, and the right one
+ * is on the `category-original-engine-gear` line above it. Resolving that on
+ * the client would be one request per ancestor, on every category change, from
+ * a form — up to five round trips to answer one question.
+ *
+ * Here it is **two reads worst case and zero on a cache hit**: the leaf, then
+ * one bounded `getAll` over at most four ancestors, behind a one-hour edge
+ * cache. The response depends only on `(id, variant)` and category content
+ * changes when an admin edits it, so an hour of staleness costs a seller
+ * nothing and saves a function invocation per keystroke-free form open.
+ *
+ * ## 🛑 NO MONEY IN THIS PAYLOAD
+ *
+ * `Cache-Control: public` means a CDN holds this and anyone can fetch it, so
+ * `priceGuidance` is deliberately stripped even though it sits in the same
+ * `productDefaults` object. The band is competitor-derived market data, not a
+ * listing price — but prices are withheld from signed-out visitors precisely
+ * because hiding one number is pointless if a neighbouring surface publishes
+ * the range, and a publicly-cached endpoint is exactly such a surface. The
+ * seller's price hint is C1's job, from a surface that knows who is asking.
+ *
+ * `taxCodeId` is stripped for a different reason: nothing on the client reads
+ * it. The rate is resolved server-side by `deriveTaxonomy`, which is the whole
+ * point of the reference being server-resolved (C2a) — a client that knew the
+ * code could not do anything correct with it.
+ */
+import { NextResponse } from "next/server.js";
+export declare function GET(request: Request, context: {
+    params: Promise<{
+        id: string;
+    }>;
+}): Promise<NextResponse>;

package/dist/features/categories/api/[id]/description-template/route.js

@@ -0,0 +1,252 @@
+/**
+ * feat-categories — GET /api/categories/[id]/description-template
+ *
+ * The ONE read the seller form makes when a category or condition changes.
+ *
+ * ```ts
+ * // app/api/categories/[id]/description-template/route.ts
+ * export { categoryDescriptionTemplateGET as GET } from "@mohasinac/appkit";
+ * ```
+ *
+ * ## Why an endpoint rather than letting the client walk the tree
+ *
+ * A description template lives on the category and INHERITS: a named-model
+ * leaf like `category-dragoon-g` carries no body of its own, and the right one
+ * is on the `category-original-engine-gear` line above it. Resolving that on
+ * the client would be one request per ancestor, on every category change, from
+ * a form — up to five round trips to answer one question.
+ *
+ * Here it is **two reads worst case and zero on a cache hit**: the leaf, then
+ * one bounded `getAll` over at most four ancestors, behind a one-hour edge
+ * cache. The response depends only on `(id, variant)` and category content
+ * changes when an admin edits it, so an hour of staleness costs a seller
+ * nothing and saves a function invocation per keystroke-free form open.
+ *
+ * ## 🛑 NO MONEY IN THIS PAYLOAD
+ *
+ * `Cache-Control: public` means a CDN holds this and anyone can fetch it, so
+ * `priceGuidance` is deliberately stripped even though it sits in the same
+ * `productDefaults` object. The band is competitor-derived market data, not a
+ * listing price — but prices are withheld from signed-out visitors precisely
+ * because hiding one number is pointless if a neighbouring surface publishes
+ * the range, and a publicly-cached endpoint is exactly such a surface. The
+ * seller's price hint is C1's job, from a surface that knows who is asking.
+ *
+ * `taxCodeId` is stripped for a different reason: nothing on the client reads
+ * it. The rate is resolved server-side by `deriveTaxonomy`, which is the whole
+ * point of the reference being server-resolved (C2a) — a client that knew the
+ * code could not do anything correct with it.
+ */
+import { NextResponse } from "next/server.js";
+import { normalizeError } from "../../../../../errors/normalize";
+import { serverLogger } from "../../../../../monitoring";
+/*
+ * The repository directly, which is the established shape for an appkit API
+ * route (blog/[slug], products/[id] and seller/products all do the same). The
+ * `getProviders()` contract exposes only the generic `IRepository`, so the
+ * bounded `findByIds` ancestor walk this route needs is not reachable through
+ * it — and the alternative is four sequential reads on a route the seller form
+ * hits on every category change.
+ */
+import { categoriesRepository } from "../../../repository/categories.repository";
+import { usedPlaceholders } from "../../../../../_internal/shared/templating/placeholders";
+/**
+ * The variants a caller may ask for.
+ *
+ * 🛑 Validated against the union rather than passed through. An unrecognised
+ * variant must fall back to `default` and not reach a `templates.find()` that
+ * would answer `null` — because `null` here means "this category has no
+ * template", which the picker renders as "No template yet". A typo'd variant
+ * would therefore look like missing content rather than a bad request, and
+ * nobody would ever find it.
+ */
+const VARIANTS = [
+    "default",
+    "new_in_box",
+    "new_in_packet",
+    "pre_owned",
+    "replica",
+];
+/** At most four ancestors on a five-tier tree, so the walk is bounded by shape. */
+const MAX_ANCESTORS = 8;
+function toPublicDefaults(d) {
+    if (!d)
+        return {};
+    /*
+     * An explicit allow-list, not a spread-and-delete. Root Cause #70: a
+     * deny-list keyed on a TypeScript interface is structurally blind to fields
+     * the interface does not declare, and this object gains fields over time.
+     */
+    const out = {};
+    if (d.specifications?.length)
+        out.specifications = d.specifications;
+    if (d.inTheBox?.length)
+        out.inTheBox = d.inTheBox;
+    if (d.defaultCondition)
+        out.defaultCondition = d.defaultCondition;
+    if (d.defaultAuthenticity)
+        out.defaultAuthenticity = d.defaultAuthenticity;
+    if (d.seoKeywords?.length)
+        out.seoKeywords = d.seoKeywords;
+    if (d.faqTemplates?.length)
+        out.faqTemplates = d.faqTemplates;
+    return out;
+}
+function pickTemplate(doc, variant) {
+    const all = doc?.descriptionTemplates;
+    if (!all?.length)
+        return null;
+    /*
+     * The asked-for variant, else the category's `default`, else nothing. NOT
+     * "the first template in the array": a category offering a reproduction
+     * body and a new-in-box body has no natural first, and answering with
+     * whichever the author happened to list first would silently hand a
+     * brand-new listing the reproduction disclosure.
+     */
+    return (all.find((t) => t.variant === variant) ??
+        all.find((t) => t.variant === "default") ??
+        null);
+}
+/**
+ * The `productDefaults` fields the picker can inherit, resolved INDIVIDUALLY.
+ *
+ * 🛑 PER FIELD, not per object, and the first version of this route got it
+ * wrong in exactly the way C2a's `applyCategoryDefaults` was written to avoid.
+ *
+ * A named-model leaf DOES carry a `productDefaults` object — its
+ * `defaultFeatures` (blader, battle type, spin) — while the spec rows and the
+ * in-the-box list live on the tier-3 line above it. Stopping at "the leaf has
+ * an object, so stop looking" therefore returned the blader and silently
+ * dropped the specs, so the picker could never say "this will add 2
+ * specification rows". Caught by a test asserting the picker still gets what
+ * it needs, which the money-stripping assertion sitting beside it would
+ * otherwise have made look fine.
+ */
+const INHERITABLE_DEFAULT_KEYS = [
+    "specifications",
+    "inTheBox",
+    "defaultCondition",
+    "defaultAuthenticity",
+    "seoKeywords",
+    "faqTemplates",
+];
+const isEmptyValue = (v) => v == null || (Array.isArray(v) && v.length === 0);
+/** Fill only the keys still missing, from `src`. Returns what is still absent. */
+function mergeDefaults(into, src) {
+    if (src) {
+        for (const k of INHERITABLE_DEFAULT_KEYS) {
+            if (isEmptyValue(into[k]) && !isEmptyValue(src[k])) {
+                into[k] = src[k];
+            }
+        }
+    }
+    return INHERITABLE_DEFAULT_KEYS.filter((k) => isEmptyValue(into[k]));
+}
+/**
+ * Walk the ancestors nearest-first for whatever the leaf did not supply.
+ *
+ * Extracted because `audit-code-quality` flagged the inline version at
+ * brace-depth 6, and it was right — "for each ancestor, if we still need a
+ * template, if this one has it" is three questions in one block, and the
+ * nesting is what hides the ordering guarantee below.
+ */
+async function resolveInherited(parentIds, variant, seed) {
+    const out = { ...seed };
+    if (parentIds.length === 0)
+        return out;
+    // `parentIds` is root-first/nearest-last, so reverse it. ONE `getAll`: four
+    // sequential reads would be four round trips on a route the seller form hits
+    // on every category change.
+    const nearestFirst = [...parentIds].reverse();
+    const ancestors = await categoriesRepository.findByIds(nearestFirst);
+    /*
+     * 🛑 Re-indexed into the ASKED-FOR order rather than trusted.
+     *
+     * `findByIds` dedupes and drops ids that no longer exist, so its result is
+     * in request order but may be SHORTER — and "nearest ancestor wins" is the
+     * whole semantics here. Walking `nearestFirst` instead of the result means a
+     * missing ancestor cannot silently promote a more distant one to first
+     * place, which would hand a leaf the ROOT's generic body while reporting
+     * that it came from the line.
+     */
+    const byId = new Map(ancestors.map((a) => [a.id, a]));
+    for (const pid of nearestFirst) {
+        const d = byId.get(pid);
+        if (!d)
+            continue;
+        const found = out.template ? null : pickTemplate(d, variant);
+        if (found) {
+            out.template = found;
+            out.inheritedFrom = pid;
+            out.inheritedFromName = d.name ?? null;
+        }
+        // PER FIELD — see INHERITABLE_DEFAULT_KEYS. Stop only once the template is
+        // settled AND no inheritable default is still missing.
+        const stillMissing = mergeDefaults(out.defaults, d.productDefaults);
+        if (out.template && stillMissing.length === 0)
+            break;
+    }
+    return out;
+}
+export async function GET(request, context) {
+    try {
+        const { id } = await context.params;
+        const raw = new URL(request.url).searchParams.get("variant") ?? "default";
+        const variant = VARIANTS.includes(raw)
+            ? raw
+            : "default";
+        const leafDoc = await categoriesRepository.findById(id);
+        if (!leafDoc) {
+            return NextResponse.json({ success: false, error: "Category not found" }, { status: 404 });
+        }
+        const leaf = leafDoc;
+        const parentIds = (leaf.parentIds ?? []).slice(0, MAX_ANCESTORS);
+        /*
+         * The leaf's own defaults are COPIED into the accumulator rather than
+         * referenced, so the per-field merge below cannot mutate the document the
+         * repository cached.
+         */
+        const { template, inheritedFrom, inheritedFromName, defaults } = await resolveInherited(parentIds, variant, {
+            template: pickTemplate(leaf, variant),
+            inheritedFrom: null,
+            inheritedFromName: null,
+            defaults: { ...(leaf.productDefaults ?? {}) },
+        });
+        /*
+         * 🛑 `placeholders` is RE-DERIVED here and not trusted from the stored
+         * template.
+         *
+         * The field's own contract says absent means "re-parse", never "no slots",
+         * and the seeded bodies deliberately leave it unset so there is one
+         * implementation rather than a hand-written list that drifts the first time
+         * a body is edited. The picker needs the real list to report "2 of 9 slots
+         * could not be filled", and a stale list is how a literal `{{series}}`
+         * reaches a published description.
+         */
+        const placeholders = template ? usedPlaceholders(template.body) : [];
+        return NextResponse.json({
+            success: true,
+            data: {
+                template: template
+                    ? { ...template, placeholders }
+                    : null,
+                /** Null when the template came from the category itself. */
+                inheritedFrom,
+                inheritedFromName,
+                defaults: toPublicDefaults(defaults),
+            },
+        }, {
+            headers: {
+                // One hour at the edge. The response is a pure function of
+                // (id, variant) over admin-authored content; an hour of staleness
+                // costs a seller nothing and removes an invocation per form open.
+                "Cache-Control": "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400",
+            },
+        });
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.error("description-template read failed", { message: e.message });
+        return NextResponse.json({ success: false, error: "Could not load the category template" }, { status: 500 });
+    }
+}

package/dist/features/categories/api/route.js

@@ -17,6 +17,10 @@ import { z } from "zod";
 import { mediaUrlSchema } from "../../../validation/schemas";
 import { getProviders } from "../../../contracts";
 import { createRouteHandler } from "../../../next";
+import { toCategoryListItem } from "../../../_internal/server/features/categories/adapters";
+import { isListingCategory } from "../constants/listing-categories";
+import { planSearchTxt } from "../../../utils/search-txt-query";
+import { matchesAllSearchTerms } from "../../../utils/search-txt";
 import { normalizeError } from "../../../errors/normalize";
 const CACHE_CONTROL_PUBLIC = "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400";
 function buildTreeFromFlat(items, rootId) {
@@ -77,10 +81,65 @@ export async function GET(request) {
         const rawFilters = param(url, "filters");
         const tier = numParam(url, "tier");
         const pageSizeParam = numParam(url, "pageSize");
+        /*
+         * 🛑 `?page=` MEANS "give me a paged flat list", and reading it fixes two
+         * live bugs rather than adding a feature.
+         *
+         * (a) `useAdminListingData` ALWAYS sends `page` and `pageSize`, so
+         *     `/admin/categories` has been requesting `?flat=true&page=N` while
+         *     this handler ignored `page` entirely — the pager advanced the URL
+         *     and returned page 1's rows every time. It also returned a bare
+         *     array with no `total`, so `extractCategoryTotal` fell back to
+         *     `mappedRows.length`, making `totalPages` 1 and disabling Next. The
+         *     list showed 50 of 58 categories with no way to reach the rest.
+         *
+         * (b) `loadOptionsFrom` (the catalogue editor's category and brand
+         *     pickers) sends ONLY `page`/`pageSize`/`q` — none of which `isFiltered`
+         *     tested — so it fell through to TREE mode and then read `.items` off
+         *     a bare array of nested nodes. `data.items ?? []` meant both pickers
+         *     were permanently empty. Same shape as the `useCategoryTree` bug:
+         *     `isFiltered` did not include the params real callers send.
+         */
+        const pageParam = numParam(url, "page");
+        const isPaged = pageParam !== null && pageParam > 0;
+        /*
+         * `?listingOnly=true` drops brand / bundle / sublisting rows.
+         *
+         * Applied in memory because the test cannot be a query clause — a plain
+         * listing category OMITS `categoryType`, so there is no value to match
+         * and an inequality would exclude every real category. See
+         * `constants/listing-categories.ts`.
+         *
+         * Server-side rather than per-caller: three surfaces had hand-written the
+         * same Set and the fourth (`loadCategoryOptions`, the catalogue editor's
+         * category picker) shipped without one, offering "Takara-Tomy" and
+         * "Original Collector's Set" as categories.
+         */
+        const listingOnly = param(url, "listingOnly") === "true";
+        /*
+         * `q` is read now that `searchTxt` exists.
+         *
+         * `loadOptionsFrom` has always sent it and this handler never read it, so
+         * the catalogue editor's category picker returned the same unfiltered page
+         * for every term — the search box accepted typing and changed nothing.
+         * Root Cause #62's shape, and the second half of why that picker was
+         * useless (the first being that it got a nested tree, §A1c).
+         */
+        const q = (param(url, "q") ?? "").trim();
         const { db } = getProviders();
         if (!db) {
             return NextResponse.json({ success: false, error: "Database provider not registered" }, { status: 503 });
         }
+        /*
+         * 🛑 Typed as the DOCUMENT, not as `CategoryItem`.
+         *
+         * This was `getRepository<CategoryItem>`, which is a cast-by-generic: the
+         * repository returns raw Firestore documents at runtime, so every return
+         * site below was handing out `createdBy`, `createdByStoreId` and the
+         * unbounded `metrics.productIds[]`/`auctionIds[]` while tsc believed the
+         * payload was already projected. Naming the real shape is what makes the
+         * missing `toCategoryListItem` calls a compile error instead of a leak.
+         */
         const repo = db.getRepository("categories");
         // -- Single slug lookup ----------------------------------------------------
         if (slug) {
@@ -92,7 +151,7 @@ export async function GET(request) {
             if (!category) {
                 return NextResponse.json({ success: false, error: "Category not found" }, { status: 404 });
             }
-            return NextResponse.json({ success: true, data: category });
+            return NextResponse.json({ success: true, data: toCategoryListItem(category) });
         }
         // -- Build Sieve filter string from query params ----------------------------
         const parts = [];
@@ -117,6 +176,7 @@ export async function GET(request) {
         // -- Filtered flat list modes -----------------------------------------------
         // If any filter is active, or ?flat=true → return flat array
         const isFiltered = flat === "true" ||
+            isPaged ||
             parentId !== null ||
             featured === "true" ||
             isBrand === "true" ||
@@ -125,14 +185,95 @@ export async function GET(request) {
             type !== null;
         if (isFiltered) {
             const perPage = pageSizeParam !== null && pageSizeParam > 0 ? pageSizeParam : 200;
-            const result = await repo.findAll({
-                filters,
-                sort: "order",
-                order: "asc",
-                perPage,
-            });
-            const items = result.data.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
-            const res = NextResponse.json({ success: true, data: items });
+            const page = pageParam ?? 1;
+            /*
+             * 🛑 `listingOnly` and `q` both force an in-memory window, and `total`
+             * is the reason.
+             *
+             * Each removes rows AFTER the query, so the repository's own `total`
+             * would be an over-count and `hasMore` would promise a "Load more" page
+             * that renders empty. Rather than ship a number that is wrong in a
+             * direction nobody can see, fetch one bounded window, filter it, and
+             * paginate the result — so `total` is exact.
+             *
+             * Affordable because this collection is small and hard-capped at 500 by
+             * `base.ts` anyway: 58 rows today, ~330 after the taxonomy seed. Past
+             * the cap the window truncates, which is the same ceiling the sitemap
+             * builder has and is tracked as its own item — it is not made worse
+             * here.
+             *
+             * The MATCH uses `matchesAllSearchTerms` over the stored `searchTxt`,
+             * not `name.includes()`, so this route and the admin route's real
+             * push-down agree on what a term means: word prefixes, accent-folded,
+             * all terms ANDed, lineage included via `ancestors[].name`. Two
+             * different notions of "matches" across two pickers over one collection
+             * is the drift this reuse avoids.
+             */
+            const plan = planSearchTxt(q);
+            // A query that normalised to no usable token must return NOTHING.
+            // Emitting no clause returns the whole collection and calls it a result.
+            if (plan.empty) {
+                const res = isPaged
+                    ? NextResponse.json({
+                        success: true,
+                        data: { items: [], total: 0, page, perPage, totalPages: 0, hasMore: false },
+                    })
+                    : NextResponse.json({ success: true, data: [] });
+                res.headers.set("Cache-Control", CACHE_CONTROL_PUBLIC);
+                return res;
+            }
+            const terms = plan.head ? [plan.head, ...plan.rest] : [];
+            const needsWindow = listingOnly || terms.length > 0;
+            const windowed = needsWindow
+                ? await repo.findAll({ filters, sort: "order", order: "asc", perPage: 500 })
+                : null;
+            let items;
+            let total;
+            if (windowed) {
+                const kept = windowed.data
+                    .filter((d) => (listingOnly ? isListingCategory(d) : true))
+                    .filter((d) => (terms.length ? matchesAllSearchTerms(d.searchTxt, terms) : true))
+                    .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+                total = kept.length;
+                const offset = (page - 1) * perPage;
+                items = (isPaged ? kept.slice(offset, offset + perPage) : kept).map(toCategoryListItem);
+            }
+            else {
+                const result = await repo.findAll({
+                    filters,
+                    sort: "order",
+                    order: "asc",
+                    page: pageParam ?? undefined,
+                    perPage,
+                });
+                total = result.total;
+                items = result.data
+                    .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+                    .map(toCategoryListItem);
+            }
+            const totalPages = total === 0 ? 0 : Math.max(1, Math.ceil(total / perPage));
+            /*
+             * Shape switches on `?page=`, deliberately, and only there.
+             *
+             * A paged caller gets an envelope carrying `total`/`totalPages`/`hasMore`
+             * — without `total` the admin pager computes `totalPages = 1` from the
+             * row count and disables Next, which is the "50 of 58 rows" bug. A
+             * caller that sends no `page` keeps the bare array it has always had,
+             * because `useCategories` and `useTopCategories` are TYPED as
+             * `CategoryItem[]` and would throw on `.map` of an object (Root Cause
+             * #20 — a public shape change must update its call sites, and these
+             * callers never ask for paging, so the correct move is not to change
+             * their shape at all).
+             *
+             * `hasMore` exists because `loadOptionsFrom` reads it for "Load more";
+             * it used to read it off a bare array and always got `false`.
+             */
+            const res = isPaged
+                ? NextResponse.json({
+                    success: true,
+                    data: { items, total, page, perPage, totalPages, hasMore: page < totalPages },
+                })
+                : NextResponse.json({ success: true, data: items });
             res.headers.set("Cache-Control", CACHE_CONTROL_PUBLIC);
             return res;
         }
@@ -143,8 +284,12 @@ export async function GET(request) {
             order: "asc",
             perPage: 500,
         });
+        // Project BEFORE nesting — `CategoryTreeNode extends CategoryItem`, so the
+        // children carry the public shape too rather than being raw documents
+        // reachable one level down.
+        const allItems = allResult.data.map(toCategoryListItem);
         if (tree === "true" || !flat) {
-            const treeNodes = buildTreeFromFlat(allResult.data, rootId);
+            const treeNodes = buildTreeFromFlat(allItems, rootId);
             const res = NextResponse.json({ success: true, data: treeNodes });
             res.headers.set("Cache-Control", CACHE_CONTROL_PUBLIC);
             return res;
@@ -153,7 +298,7 @@ export async function GET(request) {
         // because isFiltered catches it, but kept for clarity)
         const res = NextResponse.json({
             success: true,
-            data: allResult.data.sort((a, b) => (a.order ?? 0) - (b.order ?? 0)),
+            data: allItems.sort((a, b) => (a.order ?? 0) - (b.order ?? 0)),
         });
         res.headers.set("Cache-Control", CACHE_CONTROL_PUBLIC);
         return res;

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

@@ -1,8 +1,6 @@
 import React from "react";
-import type { CategoryItem } from "../types";
 export interface CategoriesIndexListingProps {
-    initialData?: CategoryItem[];
     /** When true, filters to brands only (for the standalone /brands page) */
     brandsOnly?: boolean;
 }
-export declare function CategoriesIndexListing({ initialData: _, brandsOnly }: CategoriesIndexListingProps): React.JSX.Element;
+export declare function CategoriesIndexListing({ brandsOnly }: CategoriesIndexListingProps): React.JSX.Element;

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

@@ -63,7 +63,7 @@ const SORT_OPTIONS = [
     { value: sortBy(CATEGORY_FIELDS.NAME), label: "Name Z–A" },
     { value: sortBy("metrics.productCount", "DESC"), label: "Most Products" },
 ];
-export function CategoriesIndexListing({ initialData: _, brandsOnly = false }) {
+export function CategoriesIndexListing({ brandsOnly = false }) {
     const table = useUrlTable({ defaults: { pageSize: String(PAGE_SIZE), sort: DEFAULT_SORT } });
     const [searchInput, setSearchInput] = useState(table.get(TABLE_KEYS.QUERY) || "");
     const [filterOpen, setFilterOpen] = useState(false);

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

@@ -1,7 +1,33 @@
 import React from "react";
 type SearchParams = Record<string, string | string[]>;
 export interface CategoriesIndexPageViewProps {
+    /**
+     * @deprecated Accepted and ignored. Kept so the consumer page shim compiles
+     * either way; remove once no caller passes it.
+     */
     searchParams?: SearchParams;
 }
-export declare function CategoriesIndexPageView({ searchParams }: CategoriesIndexPageViewProps): Promise<React.JSX.Element>;
+/**
+ * The categories index.
+ *
+ * 🛑 This view deliberately performs NO Firestore read.
+ *
+ * It used to fetch `pageSize: 200` and hand the result to
+ * `CategoriesIndexListing` as `initialData` — which destructured it as
+ * `initialData: _` and threw it away, then fetched `/api/categories?flat=true`
+ * regardless. So the read was 200 documents per render, on a route that
+ * regenerated every 300s, rendering nothing. Measured 2026-10-09 while tracing
+ * 2.1M Firestore reads/week against a 50K/day free tier.
+ *
+ * Deleting it also removes this page from Root Cause #30's blast radius
+ * entirely: you cannot freeze the wrong data under a `staleTime: Infinity` key
+ * you never seeded. The long "MUST MATCH CategoriesIndexListing's DEFAULT_SORT"
+ * warning that used to live here is now moot for the same reason — there is no
+ * second parser to keep in sync.
+ *
+ * Unlike the other listing pages, making this one static costs no SEO: its grid
+ * was already client-rendered, so there was never a server-rendered grid to
+ * lose (contrast `/products`, where the grid IS in the SSR HTML and must stay).
+ */
+export declare function CategoriesIndexPageView(_props?: CategoriesIndexPageViewProps): Promise<React.JSX.Element>;
 export {};