@mohasinac/appkit 4.63.4 → 4.64.0

package/dist/_internal/server/features/seo/sitemap.js

@@ -9,8 +9,11 @@ import { CATEGORIES_COLLECTION, CATEGORY_FIELDS } from "../../../../features/cat
 import { isListingCategory } from "../../../../features/categories/constants/listing-categories.js";
 import { STORE_COLLECTION, STORE_FIELDS } from "../../../../features/stores/schemas/firestore.js";
 import { SCAMMER_COLLECTION } from "../../../../features/scams/schemas/firestore.js";
+import { BEYS_COLLECTION } from "../../../../features/beys/schemas/firestore.js";
+import { PART_GLOSSARY_COLLECTION, ALL_PART_SLOTS } from "../../../../features/parts/schemas/firestore.js";
 import { serverLogger } from "../../../../monitoring/server-logger.js";
 import { PRODUCT_FIELDS } from "../../../../constants/field-names.js";
+import { PRODUCT_DETAIL_LISTING_TYPES } from "./product-detail-types.js";
 // Product field strings — matches consumer field-names.ts
 const PRODUCT_STATUS = "status";
 const PRODUCT_STATUS_PUBLISHED = "published";
@@ -137,10 +140,25 @@ function staticPages(baseUrl) {
         page(String(ROUTES.PUBLIC.PRE_ORDERS), "daily", 0.7),
         page(String(ROUTES.PUBLIC.BUNDLES), "weekly", 0.6),
         page(String(ROUTES.PUBLIC.PRIZE_DRAWS), "daily", 0.7),
-        page(String(ROUTES.PUBLIC.CLASSIFIED), "daily", 0.6),
-        page(String(ROUTES.PUBLIC.DIGITAL_CODES), "daily", 0.6),
-        page(String(ROUTES.PUBLIC.LIVE), "hourly", 0.7),
+        /*
+         * 🛑 `/classified`, `/digital-codes` and `/live` are NOT listed, and must
+         * not be re-added. All three index pages were reduced to redirect stubs
+         * that export `robots: { index: false, follow: false }` and immediately
+         * `redirect()` to `/products?listingType=…`. Submitting a URL that
+         * declares itself noindex is a direct contradiction — we ask Google to
+         * crawl it and then tell it not to keep it. Their DETAIL pages are still
+         * submitted by `fetchClassifiedUrls`/`fetchDigitalCodeUrls`/`fetchLiveUrls`
+         * below; it is only the dead index that goes.
+         */
         page(String(ROUTES.PUBLIC.ART), "weekly", 0.6),
+        /*
+         * Hubs that exist, are linked, and were never submitted.
+         * `/franchise` is the index for a whole `categoryType`; `/parts` is the
+         * Beyblade parts gallery — both are real pages with real content and both
+         * were absent from the sitemap entirely (measured 2026-10-24).
+         */
+        page(String(ROUTES.PUBLIC.FRANCHISE), "weekly", 0.6),
+        page(String(ROUTES.PUBLIC.PARTS), "weekly", 0.6),
         /*
          * `daily`, matching the other one-of-a-kind types rather than `/art`'s
          * weekly: most spares are quantity 1, so the page turns over as fast as
@@ -161,16 +179,13 @@ function staticPages(baseUrl) {
         page(String(ROUTES.PUBLIC.SCAM_FAQS), "weekly", 0.7),
     ];
 }
-// "art" and "stickers" listing types render at the same PRODUCT_DETAIL route
-// as "standard" (see route-map.ts's ART comment) — no dedicated detail page.
-const PRODUCT_DETAIL_LISTING_TYPES = ["standard", "art", "stickers"];
 async function fetchProductUrls(baseUrl) {
     try {
         const db = getAdminDb();
         const snap = await db
             .collection(PRODUCT_COLLECTION)
             .where(PRODUCT_STATUS, "==", PRODUCT_STATUS_PUBLISHED)
-            .where("listingType", "in", PRODUCT_DETAIL_LISTING_TYPES)
+            .where("listingType", "in", [...PRODUCT_DETAIL_LISTING_TYPES])
             .select(PRODUCT_SLUG, PRODUCT_UPDATED_AT, TEST_DATA_FIELD)
             .limit(5000)
             .get();
@@ -322,36 +337,38 @@ async function fetchCategoryTypeUrls(baseUrl, categoryType, buildUrl, label) {
         return sitemapSectionFailed(label, err);
     }
 }
-/**
- * Plain listing categories — the /categories/{slug} pages.
- *
- * These CANNOT be selected by an equality on `categoryType`, because a plain
- * listing category omits the field entirely rather than storing "category".
- * `.where(CATEGORY_TYPE, "==", <anything>)` therefore excludes every one of
- * them, and a Firestore `!=` would be worse still — it silently drops documents
- * that lack the field, which is exactly the set we want.
- *
- * So: select on `isActive` alone (the one predicate that IS stored on every
- * row) and reject the three discriminated kinds in memory. `categoryType` must
- * stay in the `.select()` list or it comes back undefined and nothing is
- * rejected.
- */
+/** A rollup of zero, or no rollup at all, means nothing to show. */
+function hasStock(metrics) {
+    return (metrics?.totalProductCount ?? 0) + (metrics?.totalAuctionCount ?? 0) > 0;
+}
 async function fetchCategoryUrls(baseUrl) {
     try {
         const db = getAdminDb();
         const docs = await readAllDocs(db
             .collection(CATEGORIES_COLLECTION)
             .where(CATEGORY_FIELDS.IS_ACTIVE, "==", true)
-            .select(CATEGORY_FIELDS.SLUG, CATEGORY_FIELDS.UPDATED_AT, CATEGORY_FIELDS.CATEGORY_TYPE, TEST_DATA_FIELD), "category");
-        return docs
+            .select(CATEGORY_FIELDS.SLUG, CATEGORY_FIELDS.UPDATED_AT, CATEGORY_FIELDS.CATEGORY_TYPE, CATEGORY_FIELDS.TIER, CATEGORY_FIELDS.METRICS, TEST_DATA_FIELD), "category");
+        let uncounted = 0;
+        const kept = docs
             .filter((doc) => {
             const data = doc.data();
             if (isTestDoc(data))
                 return false;
-            return isListingCategory({
+            if (!isListingCategory({
                 categoryType: data[CATEGORY_FIELDS.CATEGORY_TYPE],
-            });
-        })
+            })) {
+                return false;
+            }
+            const metrics = data[CATEGORY_FIELDS.METRICS];
+            if (metrics?.totalProductCount === undefined && metrics?.totalAuctionCount === undefined) {
+                uncounted++;
+            }
+            return data[CATEGORY_FIELDS.TIER] === 0 || hasStock(metrics);
+        });
+        if (uncounted > 0) {
+            serverLogger.warn(`sitemap: ${uncounted} active categories have no rollup counter and were judged empty`, { section: "category", uncounted });
+        }
+        return kept
             .map((doc) => {
             const data = doc.data();
             const slug = data[CATEGORY_FIELDS.SLUG] ?? doc.id;
@@ -370,6 +387,19 @@ async function fetchCategoryUrls(baseUrl) {
 }
 const fetchBrandUrls = (baseUrl) => fetchCategoryTypeUrls(baseUrl, "brand", (slug) => ROUTES.PUBLIC.BRAND_DETAIL(slug), "brand");
 const fetchBundleUrls = (baseUrl) => fetchCategoryTypeUrls(baseUrl, "bundle", (slug) => ROUTES.PUBLIC.BUNDLE_DETAIL(slug), "bundle");
+/**
+ * `/franchise/{slug}` — what a product is FROM, where a brand is who made it.
+ *
+ * `"franchise"` has been a real `CategoryType` with a real detail route since
+ * 2026-10-14, and this call simply did not exist: **zero** franchise URLs were
+ * ever submitted (measured 2026-10-24). `fetchCategoryTypeUrls` already filters
+ * on `isActive`, which is the behaviour wanted here rather than an accident —
+ * 7 of the 8 franchises are deliberately inactive because an unstocked facet
+ * "renders as a card in the grid that opens an empty page", so only the stocked
+ * one is advertised while the rest still resolve for the `/franchise/*` links
+ * `CharacterHotspot` ships.
+ */
+const fetchFranchiseUrls = (baseUrl) => fetchCategoryTypeUrls(baseUrl, "franchise", (slug) => ROUTES.PUBLIC.FRANCHISE_DETAIL(slug), "franchise");
 /**
  * `groupedListings` documents. `listSitemapGroupedListings` has existed since
  * the feature was built, but there was no public page for it to point at until
@@ -478,11 +508,71 @@ async function fetchScammerUrls(baseUrl) {
         return sitemapSectionFailed("scammer", err);
     }
 }
+/**
+ * `/beys/{slug}` — 1,988 model reference pages, and `/parts/{slot}/{code}` —
+ * 2,488 part pages. Both carry real measured data (type, system, weight, spin,
+ * release code, WBO legality, which models use a part) and both had **zero**
+ * sitemap URLs, while 4,658 empty category pages were submitted. The index was
+ * precisely inverted.
+ *
+ * They are submitted together with their prerendering (`static-params.ts`), not
+ * before it: a page whose `<title>` still streams into `<body>` is not ready to
+ * be advertised.
+ */
+async function fetchBeyUrls(baseUrl) {
+    try {
+        const docs = await readAllDocs(getAdminDb().collection(BEYS_COLLECTION).select(PRODUCT_UPDATED_AT, TEST_DATA_FIELD), "bey");
+        return docs
+            .filter((doc) => !isTestDoc(doc.data()))
+            .map((doc) => ({
+            url: `${baseUrl}${ROUTES.PUBLIC.BEY_DETAIL(doc.id)}`,
+            lastModified: doc.data()[PRODUCT_UPDATED_AT]?.toDate?.() ??
+                new Date(),
+            changeFrequency: "monthly",
+            priority: 0.4,
+        }));
+    }
+    catch (err) {
+        void normalizeError(err);
+        return sitemapSectionFailed("bey", err);
+    }
+}
+async function fetchPartUrls(baseUrl) {
+    try {
+        const docs = await readAllDocs(getAdminDb().collection(PART_GLOSSARY_COLLECTION).select(PRODUCT_UPDATED_AT, TEST_DATA_FIELD), "part");
+        const slots = new Set(ALL_PART_SLOTS);
+        return docs
+            .filter((doc) => !isTestDoc(doc.data()))
+            .map((doc) => {
+            // Document id is `{slot}--{tail}`, and the route segment IS the slot.
+            const sep = doc.id.indexOf("--");
+            if (sep === -1)
+                return null;
+            const classification = doc.id.slice(0, sep);
+            const code = doc.id.slice(sep + 2);
+            if (!code || !slots.has(classification))
+                return null;
+            return {
+                url: `${baseUrl}${ROUTES.PUBLIC.PART_DETAIL(classification, code)}`,
+                lastModified: doc.data()[PRODUCT_UPDATED_AT]?.toDate?.() ??
+                    new Date(),
+                changeFrequency: "monthly",
+                priority: 0.4,
+            };
+        })
+            .filter((row) => row !== null);
+    }
+    catch (err) {
+        void normalizeError(err);
+        return sitemapSectionFailed("part", err);
+    }
+}
 export async function buildSitemap({ baseUrl }) {
-    const [productUrls, categoryUrls, brandUrls, bundleUrls, groupedListingUrls, eventUrls, blogUrls, auctionUrls, preOrderUrls, prizeDrawUrls, classifiedUrls, digitalCodeUrls, liveUrls, storeUrls, scammerUrls,] = await Promise.all([
+    const [productUrls, categoryUrls, brandUrls, franchiseUrls, bundleUrls, groupedListingUrls, eventUrls, blogUrls, auctionUrls, preOrderUrls, prizeDrawUrls, classifiedUrls, digitalCodeUrls, liveUrls, storeUrls, scammerUrls, beyUrls, partUrls,] = await Promise.all([
         fetchProductUrls(baseUrl),
         fetchCategoryUrls(baseUrl),
         fetchBrandUrls(baseUrl),
+        fetchFranchiseUrls(baseUrl),
         fetchBundleUrls(baseUrl),
         fetchGroupedListingUrls(baseUrl),
         fetchEventUrls(baseUrl),
@@ -495,6 +585,8 @@ export async function buildSitemap({ baseUrl }) {
         fetchLiveUrls(baseUrl),
         fetchStoreUrls(baseUrl),
         fetchScammerUrls(baseUrl),
+        fetchBeyUrls(baseUrl),
+        fetchPartUrls(baseUrl),
     ]);
     const staticUrls = staticPages(baseUrl);
     // Per-section count digest. A section that drops to zero is otherwise
@@ -509,6 +601,7 @@ export async function buildSitemap({ baseUrl }) {
         static: staticUrls.length,
         category: categoryUrls.length,
         brand: brandUrls.length,
+        franchise: franchiseUrls.length,
         bundle: bundleUrls.length,
         group: groupedListingUrls.length,
         blog: blogUrls.length,
@@ -522,6 +615,8 @@ export async function buildSitemap({ baseUrl }) {
         event: eventUrls.length,
         store: storeUrls.length,
         scammer: scammerUrls.length,
+        bey: beyUrls.length,
+        part: partUrls.length,
     };
     const empty = Object.entries(sections)
         .filter(([, n]) => n === 0)
@@ -537,6 +632,7 @@ export async function buildSitemap({ baseUrl }) {
         ...staticUrls,
         ...categoryUrls,
         ...brandUrls,
+        ...franchiseUrls,
         ...bundleUrls,
         ...groupedListingUrls,
         ...blogUrls,
@@ -550,5 +646,7 @@ export async function buildSitemap({ baseUrl }) {
         ...eventUrls,
         ...storeUrls,
         ...scammerUrls,
+        ...beyUrls,
+        ...partUrls,
     ];
 }

package/dist/_internal/server/features/seo/static-params.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Slug enumerators for `generateStaticParams`.
+ *
+ * ## Why this exists
+ *
+ * Measured against production 2026-10-24: on EVERY dynamic route
+ * (`/products/[slug]`, `/brands/[slug]`, `/categories/[slug]`, `/blog/[slug]`,
+ * `/beys/[slug]`, `/parts/[c]/[code]`) the `<head>` ended at byte 8,180 with
+ * **no `<title>`, no `og:title` and no `description`** — the real `<title>` sat
+ * at byte 563,190, inside `<body>`. Google Search Console reported **12 indexed
+ * pages against 249 not indexed** on a 4,773-URL sitemap.
+ *
+ * The cause is that Next STREAMS metadata whenever a route is dynamic, and
+ * `.next/prerender-manifest.json` confirms no content detail route is in either
+ * the static or the ISR list — because only three files in the whole app export
+ * `generateStaticParams` (`[locale]/layout.tsx`, `parts/[classification]`,
+ * `collectibles/[city]`). Giving a route this function moves its metadata into
+ * `<head>` at build time and removes the streaming question entirely.
+ *
+ * `next.config.js`'s `htmlLimitedBots` is the belt for crawlers that cannot
+ * render; this is the braces.
+ *
+ * ## Why in appkit rather than inline in each `page.tsx`
+ *
+ * Four routes need the same bounded slug query. CLAUDE.md § SSR Architecture
+ * lists "a `page.tsx` with non-trivial Firestore querying" as a red flag and
+ * caps consumer shims at ~30 lines, and four hand-rolled copies would be past
+ * the Duplication Framework's Rule of Three before the first one shipped — the
+ * shape Root Cause #59 and #75 both describe.
+ *
+ * ## Three properties that are load-bearing
+ *
+ * 1. 🛑 **Every function FAILS OPEN, returning `[]`.** `generateStaticParams`
+ *    runs at BUILD time, where a Firestore credential problem is a plausible
+ *    environment failure rather than a code fault. Returning `[]` means "no
+ *    page is prerendered", which is exactly today's behaviour — so a build
+ *    degrades to the status quo instead of failing. Throwing here would turn a
+ *    transient admin-SDK hiccup into a failed deploy.
+ * 2. 🛑 **`dynamicParams` stays at its default of `true`.** A slug absent from
+ *    the returned list still renders on demand, so a product created after the
+ *    last build is reachable immediately and is never a 404. Nothing here needs
+ *    to be exhaustive to be correct — it is a prerender hint, not an allow-list.
+ * 3. **Test fixtures are excluded in memory, never by a Firestore inequality.**
+ *    `where("isTestData", "!=", true)` excludes every document that LACKS the
+ *    field — i.e. all real content — so such a query returns only test data.
+ *    Same trap as `sitemap.ts` and CLAUDE.md § Tester QA Program. The field must
+ *    therefore appear in each `.select(...)` list or nothing is filtered.
+ */
+/**
+ * `/products/[slug]`.
+ *
+ * Scoped to the listing types whose plugin `detailRoute` actually RESOLVES to
+ * this route — `standard`, `art`, `stickers` and `spares` all return
+ * `ROUTES.PUBLIC.PRODUCT_DETAIL`. Every other type owns a dedicated route and
+ * the page `permanentRedirect`s away from here, so prerendering one would bake
+ * a redirect into the build output.
+ *
+ * 🛑 Imported rather than re-declared, because this list and `sitemap.ts`'s
+ * drifting apart is how `spares` ended up renderable at `/products/{slug}` and
+ * absent from the sitemap (measured 2026-10-24: 14 product URLs submitted
+ * against 15 that resolve).
+ */
+export declare function productDetailSlugs(): Promise<string[]>;
+/**
+ * `/brands/[slug]` — `categoryType: "brand"` rows. Brands are categories
+ * discriminated by that field, not a separate collection.
+ */
+export declare function brandDetailSlugs(): Promise<string[]>;
+/**
+ * `/franchise/[slug]`.
+ *
+ * 🛑 Only 1 of the 8 seeded franchises is `isActive` (measured 2026-10-24) —
+ * the other seven are deliberately inactive because a facet with no stock
+ * "renders as a card in the grid that opens an empty page" (`brand-rows.ts`
+ * trap 3). Their detail pages still RESOLVE, they are just not prerendered and
+ * not advertised, which is the correct treatment for a page that exists only so
+ * `CharacterHotspot`'s seventeen `/franchise/*` links land somewhere honest.
+ */
+export declare function franchiseDetailSlugs(): Promise<string[]>;
+/** `/blog/[slug]` — published posts only; drafts must not be prerendered. */
+export declare function blogPostSlugs(): Promise<string[]>;
+/**
+ * `/beys/[slug]` — 1,988 model reference pages.
+ *
+ * These carry real data (type, system, weight, spin, release code, parts) and
+ * were invisible to search: zero in the sitemap, and no `<title>` in `<head>`
+ * because the route is dynamic. The id IS the slug here, so the shared
+ * `slugsFrom` projection applies unchanged.
+ */
+export declare function beyDetailSlugs(): Promise<string[]>;
+/**
+ * `/parts/[classification]/[code]` — 2,488 part reference pages.
+ *
+ * Two params, so this cannot use `slugsFrom`: the document id is
+ * `{slot}--{tail}` and the route splits it across both segments. The URL
+ * segment IS the slot (`partSlotFromSegment` is an identity lookup against
+ * `ALL_PART_SLOTS`), so the split is the whole derivation.
+ *
+ * 🛑 Ids carrying no `--`, or an unrecognised slot, are SKIPPED rather than
+ * guessed at — a prerendered param that does not resolve is a build-time 404
+ * baked into the output. The count of skips is logged so a generator change
+ * that breaks the id shape is visible rather than silently halving the set.
+ */
+export declare function partDetailParams(): Promise<{
+    classification: string;
+    code: string;
+}[]>;

package/dist/_internal/server/features/seo/static-params.js

@@ -0,0 +1,228 @@
+/**
+ * Slug enumerators for `generateStaticParams`.
+ *
+ * ## Why this exists
+ *
+ * Measured against production 2026-10-24: on EVERY dynamic route
+ * (`/products/[slug]`, `/brands/[slug]`, `/categories/[slug]`, `/blog/[slug]`,
+ * `/beys/[slug]`, `/parts/[c]/[code]`) the `<head>` ended at byte 8,180 with
+ * **no `<title>`, no `og:title` and no `description`** — the real `<title>` sat
+ * at byte 563,190, inside `<body>`. Google Search Console reported **12 indexed
+ * pages against 249 not indexed** on a 4,773-URL sitemap.
+ *
+ * The cause is that Next STREAMS metadata whenever a route is dynamic, and
+ * `.next/prerender-manifest.json` confirms no content detail route is in either
+ * the static or the ISR list — because only three files in the whole app export
+ * `generateStaticParams` (`[locale]/layout.tsx`, `parts/[classification]`,
+ * `collectibles/[city]`). Giving a route this function moves its metadata into
+ * `<head>` at build time and removes the streaming question entirely.
+ *
+ * `next.config.js`'s `htmlLimitedBots` is the belt for crawlers that cannot
+ * render; this is the braces.
+ *
+ * ## Why in appkit rather than inline in each `page.tsx`
+ *
+ * Four routes need the same bounded slug query. CLAUDE.md § SSR Architecture
+ * lists "a `page.tsx` with non-trivial Firestore querying" as a red flag and
+ * caps consumer shims at ~30 lines, and four hand-rolled copies would be past
+ * the Duplication Framework's Rule of Three before the first one shipped — the
+ * shape Root Cause #59 and #75 both describe.
+ *
+ * ## Three properties that are load-bearing
+ *
+ * 1. 🛑 **Every function FAILS OPEN, returning `[]`.** `generateStaticParams`
+ *    runs at BUILD time, where a Firestore credential problem is a plausible
+ *    environment failure rather than a code fault. Returning `[]` means "no
+ *    page is prerendered", which is exactly today's behaviour — so a build
+ *    degrades to the status quo instead of failing. Throwing here would turn a
+ *    transient admin-SDK hiccup into a failed deploy.
+ * 2. 🛑 **`dynamicParams` stays at its default of `true`.** A slug absent from
+ *    the returned list still renders on demand, so a product created after the
+ *    last build is reachable immediately and is never a 404. Nothing here needs
+ *    to be exhaustive to be correct — it is a prerender hint, not an allow-list.
+ * 3. **Test fixtures are excluded in memory, never by a Firestore inequality.**
+ *    `where("isTestData", "!=", true)` excludes every document that LACKS the
+ *    field — i.e. all real content — so such a query returns only test data.
+ *    Same trap as `sitemap.ts` and CLAUDE.md § Tester QA Program. The field must
+ *    therefore appear in each `.select(...)` list or nothing is filtered.
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore.js";
+import { BLOG_POSTS_COLLECTION, BLOG_POST_FIELDS } from "../../../../features/blog/schemas/firestore.js";
+import { CATEGORIES_COLLECTION, CATEGORY_FIELDS } from "../../../../features/categories/schemas/firestore.js";
+import { BEYS_COLLECTION } from "../../../../features/beys/schemas/firestore.js";
+import { PART_GLOSSARY_COLLECTION, ALL_PART_SLOTS } from "../../../../features/parts/schemas/firestore.js";
+import { PRODUCT_FIELDS } from "../../../../constants/field-names.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { PRODUCT_DETAIL_LISTING_TYPES } from "./product-detail-types.js";
+const PRODUCT_STATUS = "status";
+const PRODUCT_STATUS_PUBLISHED = "published";
+const SLUG = "slug";
+const TEST_DATA_FIELD = PRODUCT_FIELDS.IS_TEST_DATA;
+/**
+ * A prerender budget, not a correctness bound — see property 2 above.
+ *
+ * Sized to clear today's real counts with room: 15 products, 28 brands, 22
+ * posts, 1 active franchise, **1,988 beys and 2,488 parts** (measured
+ * 2026-10-24). The two reference corpora are what set this number.
+ *
+ * 🛑 Hitting the budget TRUNCATES silently in SEO terms — the remainder still
+ * render on demand and still work, they just go back to streaming their
+ * metadata. Both call sites therefore log when they saturate it, because
+ * "some pages quietly stopped being prerendered" is exactly the kind of
+ * regression that reads as normal.
+ *
+ * 🛑 Prerendering ~4,500 extra pages has a real build cost, and a cold build
+ * on this repo already peaks near 8,100 MB against Hobby's 8,192 MB ceiling.
+ * Measure before and after with
+ * `node scripts/probe-build-docker.mjs --peak --memory 7g --cpus 2 --runs 3`
+ * rather than assuming it fits.
+ */
+const MAX_PRERENDER = 5000;
+const isTestDoc = (data) => data.isTestData === true;
+/**
+ * Shared shape: project the slug field only, drop test fixtures, de-duplicate,
+ * and never throw.
+ *
+ * `.select()` matters for cost — Rule #6's Firestore budget is per document
+ * read, and projecting one field keeps a 2,000-row enumeration cheap.
+ */
+async function slugsFrom(label, build) {
+    try {
+        const snap = await build(getAdminDb()).select(SLUG, TEST_DATA_FIELD).limit(MAX_PRERENDER).get();
+        const slugs = snap.docs
+            .filter((doc) => !isTestDoc(doc.data()))
+            .map((doc) => doc.data()[SLUG] ?? doc.id)
+            .filter((slug) => Boolean(slug));
+        // A duplicate param crashes the build with "duplicate slug" rather than
+        // being ignored, and `slug` is denormalised alongside the doc id on several
+        // of these collections, so two rows CAN carry the same value.
+        const unique = [...new Set(slugs)];
+        if (snap.size >= MAX_PRERENDER) {
+            serverLogger.warn(`generateStaticParams: "${label}" hit the ${MAX_PRERENDER}-document prerender budget; the remainder render on demand`, { section: label });
+        }
+        return unique;
+    }
+    catch (err) {
+        void normalizeError(err);
+        // Fail OPEN — see property 1. Logged at error so a section silently
+        // dropping to zero is greppable, matching sitemap.ts's convention.
+        serverLogger.error(`generateStaticParams: "${label}" failed and prerendered 0 pages`, {
+            section: label,
+            error: err,
+        });
+        return [];
+    }
+}
+/**
+ * `/products/[slug]`.
+ *
+ * Scoped to the listing types whose plugin `detailRoute` actually RESOLVES to
+ * this route — `standard`, `art`, `stickers` and `spares` all return
+ * `ROUTES.PUBLIC.PRODUCT_DETAIL`. Every other type owns a dedicated route and
+ * the page `permanentRedirect`s away from here, so prerendering one would bake
+ * a redirect into the build output.
+ *
+ * 🛑 Imported rather than re-declared, because this list and `sitemap.ts`'s
+ * drifting apart is how `spares` ended up renderable at `/products/{slug}` and
+ * absent from the sitemap (measured 2026-10-24: 14 product URLs submitted
+ * against 15 that resolve).
+ */
+export function productDetailSlugs() {
+    return slugsFrom("product", (db) => db
+        .collection(PRODUCT_COLLECTION)
+        .where(PRODUCT_STATUS, "==", PRODUCT_STATUS_PUBLISHED)
+        .where("listingType", "in", [...PRODUCT_DETAIL_LISTING_TYPES]));
+}
+/**
+ * `/brands/[slug]` — `categoryType: "brand"` rows. Brands are categories
+ * discriminated by that field, not a separate collection.
+ */
+export function brandDetailSlugs() {
+    return slugsFrom("brand", (db) => db
+        .collection(CATEGORIES_COLLECTION)
+        .where(CATEGORY_FIELDS.CATEGORY_TYPE, "==", "brand")
+        .where(CATEGORY_FIELDS.IS_ACTIVE, "==", true));
+}
+/**
+ * `/franchise/[slug]`.
+ *
+ * 🛑 Only 1 of the 8 seeded franchises is `isActive` (measured 2026-10-24) —
+ * the other seven are deliberately inactive because a facet with no stock
+ * "renders as a card in the grid that opens an empty page" (`brand-rows.ts`
+ * trap 3). Their detail pages still RESOLVE, they are just not prerendered and
+ * not advertised, which is the correct treatment for a page that exists only so
+ * `CharacterHotspot`'s seventeen `/franchise/*` links land somewhere honest.
+ */
+export function franchiseDetailSlugs() {
+    return slugsFrom("franchise", (db) => db
+        .collection(CATEGORIES_COLLECTION)
+        .where(CATEGORY_FIELDS.CATEGORY_TYPE, "==", "franchise")
+        .where(CATEGORY_FIELDS.IS_ACTIVE, "==", true));
+}
+/** `/blog/[slug]` — published posts only; drafts must not be prerendered. */
+export function blogPostSlugs() {
+    return slugsFrom("blog", (db) => db.collection(BLOG_POSTS_COLLECTION).where(BLOG_POST_FIELDS.STATUS, "==", "published"));
+}
+/**
+ * `/beys/[slug]` — 1,988 model reference pages.
+ *
+ * These carry real data (type, system, weight, spin, release code, parts) and
+ * were invisible to search: zero in the sitemap, and no `<title>` in `<head>`
+ * because the route is dynamic. The id IS the slug here, so the shared
+ * `slugsFrom` projection applies unchanged.
+ */
+export function beyDetailSlugs() {
+    return slugsFrom("bey", (db) => db.collection(BEYS_COLLECTION));
+}
+/**
+ * `/parts/[classification]/[code]` — 2,488 part reference pages.
+ *
+ * Two params, so this cannot use `slugsFrom`: the document id is
+ * `{slot}--{tail}` and the route splits it across both segments. The URL
+ * segment IS the slot (`partSlotFromSegment` is an identity lookup against
+ * `ALL_PART_SLOTS`), so the split is the whole derivation.
+ *
+ * 🛑 Ids carrying no `--`, or an unrecognised slot, are SKIPPED rather than
+ * guessed at — a prerendered param that does not resolve is a build-time 404
+ * baked into the output. The count of skips is logged so a generator change
+ * that breaks the id shape is visible rather than silently halving the set.
+ */
+export async function partDetailParams() {
+    try {
+        const snap = await getAdminDb()
+            .collection(PART_GLOSSARY_COLLECTION)
+            .select()
+            .limit(MAX_PRERENDER)
+            .get();
+        const slots = new Set(ALL_PART_SLOTS);
+        let skipped = 0;
+        const params = [];
+        for (const doc of snap.docs) {
+            const sep = doc.id.indexOf("--");
+            const classification = sep === -1 ? "" : doc.id.slice(0, sep);
+            const code = sep === -1 ? "" : doc.id.slice(sep + 2);
+            if (!code || !slots.has(classification)) {
+                skipped++;
+                continue;
+            }
+            params.push({ classification, code });
+        }
+        if (skipped > 0) {
+            serverLogger.warn(`generateStaticParams: "part" skipped ${skipped} glossary id(s) that are not {slot}--{tail}`, { section: "part", skipped });
+        }
+        if (snap.size >= MAX_PRERENDER) {
+            serverLogger.warn(`generateStaticParams: "part" hit the ${MAX_PRERENDER}-document prerender budget; the remainder render on demand`, { section: "part" });
+        }
+        return params;
+    }
+    catch (err) {
+        void normalizeError(err);
+        serverLogger.error('generateStaticParams: "part" failed and prerendered 0 pages', {
+            section: "part",
+            error: err,
+        });
+        return [];
+    }
+}

package/dist/_internal/server/features/seo/taxonomy-links.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Server-side link lists for the taxonomy hub pages.
+ *
+ * Feeds `<TaxonomyLinkIndex>`, which renders them as real `<a href>`s in the
+ * server HTML. See that component for why: measured 2026-10-24, `/categories`,
+ * `/brands` and `/parts` each emitted ZERO outbound entity links because all
+ * three filter client-side, so a crawler landing on a hub had nothing to
+ * follow and the franchise detail pages were reachable by no link at all.
+ *
+ * 🛑 Every function FAILS OPEN with `[]`. These pages are statically rendered;
+ * a Firestore hiccup at build time must degrade to "no index section" rather
+ * than fail the build or 500 the page. An empty list makes
+ * `<TaxonomyLinkIndex>` render nothing at all, which is the correct fallback —
+ * the interactive grid above it is unaffected either way.
+ *
+ * 🛑 A read here does NOT make the hub dynamic. Only `searchParams`,
+ * `cookies()` and `headers()` do (Root Cause #94); a Server Component awaiting
+ * Firestore stays static and simply bakes the result in at build/ISR time.
+ */
+export interface TaxonomyLink {
+    href: string;
+    label: string;
+}
+/** Every active brand — 28 of them, and none was linked from `/brands`. */
+export declare function brandLinks(): Promise<TaxonomyLink[]>;
+/**
+ * Active franchises only.
+ *
+ * 7 of the 8 are deliberately `isActive: false` because an unstocked facet
+ * "renders as a card in the grid that opens an empty page" (`brand-rows.ts`
+ * trap 3), so this list is short on purpose. Linking the inactive ones would
+ * re-create exactly the empty-page problem the rest of this work removes.
+ */
+export declare function franchiseLinks(): Promise<TaxonomyLink[]>;
+/**
+ * The tier-0 category roots — the six real entry points a visitor drills down
+ * from, not the 4,698-row forest.
+ *
+ * `CategoryDetailPageView` already renders a root as a tier-grouped index of
+ * its descendants, so a root is where a crawl of the taxonomy should start.
+ * Listing every leaf here would put the 4,658 empty pages back in front of
+ * Google by another route, which is the thing being undone.
+ */
+export declare function categoryRootLinks(): Promise<TaxonomyLink[]>;