@mohasinac/appkit 4.43.0 → 4.44.0

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/CategoryDetailPageView.js

@@ -21,6 +21,16 @@ const __O = {
     hidden: "overflow-hidden",
     xAuto: "overflow-x-auto",
 };
+/**
+ * Read and display bounds for this page. Every one of these replaced an
+ * unbounded read — see the comments at each use site for what each one cost.
+ */
+/** Tiles rendered in "Related Categories". A sample, not an index. */
+const RELATED_CATEGORY_LIMIT = 24;
+/** Documents read to fill those tiles. Headroom for the non-listing filter. */
+const RELATED_CATEGORY_FETCH = 60;
+/** Descendant slugs the Stores tab will match on → at most 4 chunked queries. */
+const STORE_CATEGORY_SLUG_MAX = 120;
 export async function CategoryDetailPageView({ slug }) {
     // The category IS this page's subject — a read failure must surface rather
     // than render an anonymous, empty category page. `undefined` still means
@@ -75,8 +85,18 @@ export async function CategoryDetailPageView({ slug }) {
         // Related categories — every other category sharing this category's root
         // (siblings + cousins across the tree, up to the tier-0/1/2 depth the
         // catalog actually uses), not just direct children.
+        //
+        // 🛑 BOUNDED. This read is a display grid, and it used to be an unbounded
+        // `.get()` over the whole root subtree — ~9% of a 50K/day Firestore budget
+        // for one page render once the forest reaches ~330 nodes, and it rendered
+        // every one of those as a tile. The section is a SAMPLE of nearby
+        // categories; the tier-grouped children grid above it is the real index.
+        // Fetch headroom is larger than the display cap because the filter below
+        // drops this category plus every brand/bundle/sublisting row.
+        // `buildTree` still passes no limit — a truncated node list there would
+        // silently drop whole branches.
         category?.rootId
-            ? safeRead(() => categoriesRepository.getCategoriesByRootId(category.rootId), {
+            ? safeRead(() => categoriesRepository.getCategoriesByRootId(category.rootId, { limit: RELATED_CATEGORY_FETCH }), {
                 route: "/categories/[slug]",
                 key: "category.rootSiblings",
                 fallback: [],
@@ -98,7 +118,9 @@ export async function CategoryDetailPageView({ slug }) {
             fallback: null,
         }),
     ]);
-    const relatedCategories = rootSiblingCategories.filter((c) => c.id !== category?.id && (!c.categoryType || c.categoryType === "category"));
+    const relatedCategories = rootSiblingCategories
+        .filter((c) => c.id !== category?.id && (!c.categoryType || c.categoryType === "category"))
+        .slice(0, RELATED_CATEGORY_LIMIT);
     // Stores tab — stores whose storeCategory is this category or ANY descendant.
     //
     // `storeCategory` is a single slug with no ancestor chain (unlike a product's
@@ -108,14 +130,25 @@ export async function CategoryDetailPageView({ slug }) {
     // an unbounded N+1. Both are fixed by pipe-joining the slugs into OR-groups:
     // the enhanced Sieve adapter turns a same-field OR into a Firestore `in`,
     // which caps at 30 values, hence the chunking.
-    const storeCategorySlugs = [
-        slug,
-        ...(await safeRead(() => categoriesRepository.getDescendantIds(category?.id ?? ""), {
-            route: "/categories/[slug]",
-            key: "category.descendantIds",
-            fallback: [],
-        })),
-    ].filter(Boolean);
+    //
+    // 🛑 The descendant ids are REUSED from `childCategories` above, not fetched
+    // again. `getDescendantIds` is literally `getDescendants().map(d => d.id)`,
+    // so calling it here ran the identical paginated subtree query a second time
+    // and threw the documents away — on a ~330-node root that is ~330 wasted
+    // reads per page view, and the two answers could disagree if one read failed
+    // while the other succeeded.
+    //
+    // 🛑 And the fan-out is CAPPED, nearest-first. One `listStores` query per 30
+    // slugs is 11 queries at ~330 nodes and 51 at ~1,500; sorting by tier takes
+    // the closest descendants, which is what someone browsing a root cares
+    // about. `storeCount` was already a floor (each chunk caps at pageSize 50),
+    // so this tightens a floor rather than making an exact number wrong.
+    const descendantIdsByProximity = [...childCategories]
+        .sort((a, b) => (a.tier ?? 0) - (b.tier ?? 0))
+        .map((c) => c.id);
+    const storeCategorySlugs = [slug, ...descendantIdsByProximity]
+        .filter(Boolean)
+        .slice(0, STORE_CATEGORY_SLUG_MAX);
     const SLUG_CHUNK = 30;
     const slugChunks = [];
     for (let i = 0; i < storeCategorySlugs.length; i += SLUG_CHUNK) {

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

@@ -0,0 +1,65 @@
+/**
+ * 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 type { CategoryTemplateVariant } from "../schemas/category-content";
+/** What the picker may apply to the draft. Deliberately narrow. */
+export interface CategoryTemplateApply {
+    description?: string;
+    appliedTemplateId?: string;
+    appliedTemplateBody?: string;
+}
+export interface CategoryTemplatePickerProps {
+    /** The leaf the seller has chosen. Empty until they pick one. */
+    categoryId: string;
+    /** The raw `condition` enum from the draft — mapped to a variant below. */
+    condition: string;
+    /** Resolved `{{slot}}` values, supplied by the shell. */
+    context: Record<string, string>;
+    /** True when the seller has authored text we must not overwrite. */
+    isDescriptionDirty: boolean;
+    onApply: (partial: CategoryTemplateApply) => void;
+}
+/**
+ * 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 declare function variantForCondition(condition: string): CategoryTemplateVariant;
+export declare function CategoryTemplatePicker({ categoryId, condition, context, isDescriptionDirty, onApply, }: CategoryTemplatePickerProps): React.JSX.Element | null;