@mohasinac/appkit 4.66.0 → 4.68.0

package/dist/_internal/server/jobs/core/surfaceCountsRollup.js

@@ -0,0 +1,128 @@
+/**
+ * Recompute `surfaceCounts/global` — "does each public browse surface have
+ * anything in it?"
+ *
+ * ## 🛑 It asks `listPublicProducts`, not Firestore
+ *
+ * The temptation is a `count()` aggregation per listing type. That would be
+ * cheaper and it would be WRONG, because "available" is not expressible as a
+ * Firestore predicate: it is a negation (`NOT (sold OR ended OR closed OR
+ * depleted)`) evaluated per row, which is exactly why `listPublicProducts`
+ * runs one bounded query per unavailable-clause and filters in memory.
+ *
+ * A bespoke count would therefore answer a DIFFERENT question from the page it
+ * governs, and the failure mode is the bad one: hiding `/spares` while
+ * `/spares` would have rendered rows. Routing through the one function every
+ * browse page already uses makes that disagreement impossible by construction
+ * — the same argument CLAUDE.md makes for never calling
+ * `productRepository.list()` directly from a listing view.
+ *
+ * ## Cost
+ *
+ * `pageSize: 1` — we need existence, not a figure. Ten listing types plus one
+ * review query, each bounded, and only from a job or a boundary-crossing
+ * trigger. Never from a request path: the public reader gets the single
+ * pre-computed document via `/api/site-settings`.
+ *
+ * ## 🛑 A failed probe writes NOTHING for that type
+ *
+ * `listPublicProducts` returns `null` on failure. Recording that as `0` would
+ * hide a surface because a query timed out, so a failed probe leaves the key
+ * ABSENT — which every reader treats as "show" (Root Cause #72). Partial
+ * results are written: a surface we did measure is still worth recording.
+ *
+ * @tag domain:products
+ * @tag layer:job
+ * @tag access:server-only
+ * @tag sideEffects:firestore-read,firestore-write
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { listPublicProducts } from "../../features/products/list-public.js";
+import { SURFACE_COUNTS_COLLECTION, SURFACE_COUNTS_DOC_ID, } from "../../../../features/products/schemas/surface-counts.js";
+import { ALL_LISTING_TYPES } from "../../../shared/listing-types/feature-flags.js";
+import { REVIEW_COLLECTION, reviewQueryHelpers, } from "../../../../features/reviews/schemas/firestore.js";
+/**
+ * Probe one listing type. Returns `undefined` — not 0 — when the query failed.
+ *
+ * `total` is a FLOOR once `truncated` is set, which does not matter here: we
+ * only compare against zero, and a floor of N > 0 is still decisively
+ * non-empty.
+ */
+async function probeListingType(type) {
+    try {
+        const res = await listPublicProducts({ listingTypes: [type], pageSize: 1 });
+        if (!res)
+            return undefined;
+        return res.total;
+    }
+    catch (err) {
+        void normalizeError(err);
+        return undefined;
+    }
+}
+export async function computeSurfaceCounts(ctx, only) {
+    const types = only ?? ALL_LISTING_TYPES;
+    const listingTypes = {};
+    const surfaces = {};
+    const failed = [];
+    // Parallel: ten bounded queries with no interdependence. Sequential would
+    // be ten round-trips for no benefit.
+    const probes = await Promise.all(types.map((t) => probeListingType(t)));
+    types.forEach((t, i) => {
+        const n = probes[i];
+        if (n === undefined)
+            failed.push(t);
+        else
+            listingTypes[t] = n;
+    });
+    // `/reviews` has no listing-type flag, so emptiness is its only signal.
+    // A plain `count()` IS correct here: a review has no availability notion —
+    // it is approved and public, or it is not in the collection's public view.
+    if (!only) {
+        try {
+            // `reviewQueryHelpers.approved()` rather than a hand-written
+            // `["isApproved", "==", true]` — which is what this first read, and the
+            // field does not exist. Approval is `status == "approved"`, and a filter
+            // on an absent field matches NOTHING, so the hand-written version would
+            // have reported every site as having zero reviews and hidden /reviews
+            // permanently. The helper is the shipped spelling.
+            const [field, op, value] = reviewQueryHelpers.approved();
+            const snap = await ctx.db
+                .collection(REVIEW_COLLECTION)
+                .where(field, op, value)
+                .limit(1)
+                .get();
+            surfaces.reviews = snap.size;
+        }
+        catch (err) {
+            void normalizeError(err);
+            failed.push("reviews");
+        }
+    }
+    return { listingTypes, surfaces, failed };
+}
+/**
+ * Recompute and persist.
+ *
+ * `only` narrows to the types a single product write could have moved, so the
+ * trigger path costs one query instead of eleven. A narrowed run MERGES — it
+ * must never clear the keys it did not measure.
+ */
+export async function runSurfaceCountsRollup(ctx, only) {
+    const result = await computeSurfaceCounts(ctx, only);
+    const payload = { updatedAt: new Date() };
+    // Dot-path merge for a narrowed run: `{ listingTypes: {...} }` with
+    // `merge: true` would still replace the whole map on some drivers, and we
+    // must not drop a key this run did not probe.
+    for (const [k, v] of Object.entries(result.listingTypes)) {
+        payload[`listingTypes.${k}`] = v;
+    }
+    for (const [k, v] of Object.entries(result.surfaces)) {
+        payload[`surfaces.${k}`] = v;
+    }
+    await ctx.db
+        .collection(SURFACE_COUNTS_COLLECTION)
+        .doc(SURFACE_COUNTS_DOC_ID)
+        .set(payload, { merge: true });
+    return result;
+}

package/dist/_internal/server/jobs/handlers/countersReconcile.js

@@ -1,2 +1,55 @@
+import { normalizeError } from "../../../../errors/normalize.js";
 import { runCountersReconcile } from "../core/countersReconcile.js";
-export const countersReconcileHandler = runCountersReconcile;
+import { runSurfaceCountsRollup } from "../core/surfaceCountsRollup.js";
+/*
+ * 🛑 The surface-count rollup rides THIS job rather than taking a Scheduler
+ * slot of its own.
+ *
+ * Two reasons, and the second is the one that matters:
+ *
+ * 1. Cost — every registered Scheduler job is billed (~$0.10/mo beyond the
+ *    free 3), and the Firebase budget table in CLAUDE.md says to fold new
+ *    periodic work into an existing cadence when it is a natural fit.
+ * 2. Semantics — `countersReconcile` IS the nightly healer for incrementally
+ *    maintained counters. `surfaceCounts` is incrementally maintained by
+ *    `onProductWrite` under exactly the same "non-fatal, the nightly job will
+ *    heal it" contract. Putting the healer somewhere else would mean two jobs
+ *    owning one guarantee.
+ *
+ * Sequential, not `Promise.all`: both walk products, and running them together
+ * doubles the peak read rate for no wall-clock benefit on a 540s budget.
+ *
+ * 🛑 Its failure must not fail the reconcile. The counters this job exists for
+ * are the ones two Sieve SORTS order by; a surface count is a display decision
+ * that degrades to "unknown", i.e. to showing the surface. Never let the
+ * cosmetic half take down the load-bearing half.
+ */
+export const countersReconcileHandler = async (ctx) => {
+    const result = await runCountersReconcile(ctx);
+    try {
+        const surfaces = await runSurfaceCountsRollup(ctx);
+        /*
+         * Serialised to `"type=n"` pairs rather than logged as the maps
+         * themselves: the logger's value type is `JsonValue`, and a
+         * `Partial<Record<K, number>>` is not assignable to it (an optional
+         * property can be `undefined`, which is not JSON). Flattening is also the
+         * more readable log line.
+         */
+        ctx.logger.info("Surface counts rolled up", {
+            listingTypes: Object.entries(surfaces.listingTypes)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(" "),
+            surfaces: Object.entries(surfaces.surfaces)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(" "),
+            // Named rather than counted — a surface left unmeasured stays visible,
+            // and an operator needs to know WHICH, not how many.
+            failed: surfaces.failed.join(",") || "none",
+        });
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.error("Surface-count rollup failed (non-fatal)", err);
+    }
+    return result;
+};

package/dist/_internal/server/jobs/handlers/index.d.ts

@@ -45,6 +45,7 @@ export { weeklyPayoutEligibilityHandler } from "./weeklyPayoutEligibility";
 export { onCategoryWriteHandler } from "./onCategoryWrite";
 export { onProductWriteHandler } from "./onProductWrite";
 export { onStoreWriteHandler } from "./onStoreWrite";
+export { onSiteSettingsWriteHandler } from "./onSiteSettingsWrite";
 export { adminAnalyticsHandler, type AdminAnalyticsResult } from "./adminAnalytics";
 export { countersReconcileNowHandler, type CountersReconcileNowResult, } from "./countersReconcileNow";
 export { storeAnalyticsHandler, type StoreAnalyticsInput, type StoreAnalyticsResult, } from "./storeAnalytics";

package/dist/_internal/server/jobs/handlers/index.js

@@ -45,6 +45,7 @@ export { weeklyPayoutEligibilityHandler } from "./weeklyPayoutEligibility.js";
 export { onCategoryWriteHandler } from "./onCategoryWrite.js";
 export { onProductWriteHandler } from "./onProductWrite.js";
 export { onStoreWriteHandler } from "./onStoreWrite.js";
+export { onSiteSettingsWriteHandler } from "./onSiteSettingsWrite.js";
 export { adminAnalyticsHandler } from "./adminAnalytics.js";
 export { countersReconcileNowHandler, } from "./countersReconcileNow.js";
 export { storeAnalyticsHandler, } from "./storeAnalytics.js";

package/dist/_internal/server/jobs/handlers/onSiteSettingsWrite.d.ts

@@ -0,0 +1,53 @@
+import type { FirestoreTriggerHandler } from "../runtime/types";
+import type { JsonValue } from "@mohasinac/appkit";
+/**
+ * A site-settings write invalidates the whole page cache.
+ *
+ * ## Why this trigger had to exist
+ *
+ * `siteSettings/global` decides the navbar, the footer, the theme tokens, the
+ * guest price gate, every listing-type kill switch and `hiddenSurfacePaths` —
+ * i.e. something on every page of the site. Nothing observed writes to it.
+ *
+ * Measured against production 2026-10-27, which is what prompted this: with
+ * `listings.listingTypes.auction` set to `false` in Firestore, `/auctions` kept
+ * answering **200** from the CDN with `Age` climbing past its own 60-second
+ * `revalidate` window, because no writer ever marked the page stale. The flag
+ * was correct and invisible. `revalidateTargetsFor("siteSettings")` returned
+ * `["/"]` — the homepage alone — so even the one caller that existed could not
+ * have fixed it.
+ *
+ * ## 🛑 Performs NO Firestore write, by construction
+ *
+ * Root Cause #92 is this project's record of a trigger writing back to the
+ * collection it watched, producing 1.02M invocations/day and taking production
+ * down. `notifyRevalidate` performs exactly one `fetch` and touches no
+ * document, so this cannot re-trigger itself. If it ever needs to persist
+ * anything, it needs a different trigger path — not a write.
+ *
+ * ## 🛑 No field-level diff, deliberately — and that is the opposite of
+ * `onProductWrite`
+ *
+ * `onProductWrite` guards on `productCacheFieldsChanged` because products are
+ * written at MACHINE rate: every checkout stock decrement and every bid fires
+ * it, so an unguarded full invalidation there is the ISR-write amplification
+ * that got this project suspended with HTTP 402 (Root Cause #104).
+ *
+ * `siteSettings` is the opposite case. It is written by `PUT /api/admin/site`
+ * and two operator scripts and by nothing else — every scheduled job that names
+ * it only READS it (measured 2026-10-27). So this fires when a human saves
+ * settings, which is rare enough that a diff would add a maintained field list
+ * to protect against nothing. A settings save that changed only `updatedAt` is
+ * not worth a list that goes stale the next time a group is added.
+ *
+ * 🛑 If a job is ever given a reason to WRITE `siteSettings`, this guard has to
+ * come back before that ships — the amplification shape returns the moment the
+ * write rate stops being human.
+ *
+ * ## Best-effort
+ *
+ * `notifyRevalidate` swallows and logs every failure. A missed invalidation
+ * leaves a stale page until its TTL rolls; failing here would achieve nothing
+ * because the settings document is already saved.
+ */
+export declare const onSiteSettingsWriteHandler: FirestoreTriggerHandler<Record<string, JsonValue>, Record<string, JsonValue>>;

package/dist/_internal/server/jobs/handlers/onSiteSettingsWrite.js

@@ -0,0 +1,63 @@
+import { notifyRevalidate } from "../core/revalidateNotify.js";
+/**
+ * A site-settings write invalidates the whole page cache.
+ *
+ * ## Why this trigger had to exist
+ *
+ * `siteSettings/global` decides the navbar, the footer, the theme tokens, the
+ * guest price gate, every listing-type kill switch and `hiddenSurfacePaths` —
+ * i.e. something on every page of the site. Nothing observed writes to it.
+ *
+ * Measured against production 2026-10-27, which is what prompted this: with
+ * `listings.listingTypes.auction` set to `false` in Firestore, `/auctions` kept
+ * answering **200** from the CDN with `Age` climbing past its own 60-second
+ * `revalidate` window, because no writer ever marked the page stale. The flag
+ * was correct and invisible. `revalidateTargetsFor("siteSettings")` returned
+ * `["/"]` — the homepage alone — so even the one caller that existed could not
+ * have fixed it.
+ *
+ * ## 🛑 Performs NO Firestore write, by construction
+ *
+ * Root Cause #92 is this project's record of a trigger writing back to the
+ * collection it watched, producing 1.02M invocations/day and taking production
+ * down. `notifyRevalidate` performs exactly one `fetch` and touches no
+ * document, so this cannot re-trigger itself. If it ever needs to persist
+ * anything, it needs a different trigger path — not a write.
+ *
+ * ## 🛑 No field-level diff, deliberately — and that is the opposite of
+ * `onProductWrite`
+ *
+ * `onProductWrite` guards on `productCacheFieldsChanged` because products are
+ * written at MACHINE rate: every checkout stock decrement and every bid fires
+ * it, so an unguarded full invalidation there is the ISR-write amplification
+ * that got this project suspended with HTTP 402 (Root Cause #104).
+ *
+ * `siteSettings` is the opposite case. It is written by `PUT /api/admin/site`
+ * and two operator scripts and by nothing else — every scheduled job that names
+ * it only READS it (measured 2026-10-27). So this fires when a human saves
+ * settings, which is rare enough that a diff would add a maintained field list
+ * to protect against nothing. A settings save that changed only `updatedAt` is
+ * not worth a list that goes stale the next time a group is added.
+ *
+ * 🛑 If a job is ever given a reason to WRITE `siteSettings`, this guard has to
+ * come back before that ships — the amplification shape returns the moment the
+ * write rate stops being human.
+ *
+ * ## Best-effort
+ *
+ * `notifyRevalidate` swallows and logs every failure. A missed invalidation
+ * leaves a stale page until its TTL rolls; failing here would achieve nothing
+ * because the settings document is already saved.
+ */
+export const onSiteSettingsWriteHandler = async (event, ctx) => {
+    await notifyRevalidate({
+        collection: "siteSettings",
+        /*
+         * The singleton id, from the path params rather than hardcoded "global".
+         * The trigger pattern is `siteSettings/{settingsId}` and a second
+         * document in that collection would otherwise invalidate under the wrong
+         * id — and the endpoint logs this value.
+         */
+        id: event.params.settingsId,
+    }, ctx);
+};

package/dist/_internal/shared/actions/action-registry.js

@@ -1895,6 +1895,34 @@ export const ACTIONS = {
             kind: "primary",
             permissions: ["admin"],
         },
+        "invalidate-cache": {
+            // `retry` — the icon registry has no `refresh`/`reload`/`sync` key, and
+            // inventing one means a new glyph in a catalogued set. `retry` is the
+            // registered "do this again" mark and reads correctly for a re-render.
+            iconKey: "retry",
+            id: "admin.invalidate-cache",
+            label: "Invalidate all cached pages",
+            ariaLabel: "Mark every cached public page stale",
+            description: "Mark every cached public page stale so the next visitor gets a freshly rendered one. Use after a bulk data change the Firestore triggers could not see — a seed load, a direct Firestore edit, or a catalogue purge.",
+            kind: "secondary",
+            permissions: ["admin"],
+            /*
+             * 🛑 A confirmation on a NON-destructive action, because the cost is
+             * real and invisible at the click.
+             *
+             * This marks entries stale; it renders nothing and destroys nothing. But
+             * every marked entry regenerates on its next request, and this project
+             * was SUSPENDED (HTTP 402) for exceeding 200K ISR writes with 3.1M —
+             * writes outnumbering reads 3:1. Rule #6's whole cache posture exists to
+             * keep that from recurring, so a button that re-renders the public site
+             * on demand must not be reachable by a stray click.
+             */
+            confirmation: {
+                title: "Invalidate every cached page?",
+                body: "Every public page is marked stale and re-renders on its next visit. Nothing is deleted and no data changes, but the re-render costs function invocations against the plan quota — so use it after a bulk change, not as a routine refresh.",
+                confirmLabel: "Invalidate all",
+            },
+        },
         "update-pricing": {
             iconKey: "save",
             id: "admin.update-pricing",

package/dist/_internal/shared/cache/revalidate-targets.js

@@ -33,67 +33,86 @@
  */
 /** What the caller knows about the written document, when it knows anything. */
 import { ROUTES } from "../../../next/routing/route-map.js";
-/** Detail route per listing type. Mirrors `ListingTypePlugin.detailRoute`. */
-const PRODUCT_DETAIL_BY_TYPE = {
-    standard: (id) => `/products/${id}`,
-    art: (id) => `/products/${id}`,
-    stickers: (id) => `/products/${id}`,
-    auction: (id) => `/auctions/${id}`,
-    "pre-order": (id) => `/pre-orders/${id}`,
-    "prize-draw": (id) => `/prize-draws/${id}`,
-    classified: (id) => `/classified/${id}`,
-    "digital-code": (id) => `/digital-codes/${id}`,
-    live: (id) => `/live/${id}`,
-};
+import { LISTING_TYPE_REGISTRY } from "../listing-types/_registry.js";
+/*
+ * 🛑 DERIVED from `LISTING_TYPE_REGISTRY`, never hand-written.
+ *
+ * This file carried its own nine-entry `PRODUCT_DETAIL_BY_TYPE` literal and its
+ * own `listingTypeFromId` prefix ladder, and both had already drifted by the
+ * time the union reached ten — exactly the tenth-enumeration failure Root Cause
+ * #61 is about. Measured 2026-10-26, while invalidating after a catalogue purge
+ * that deleted 7 `spares` and 2 `stickers`:
+ *
+ *   - **`spares` was absent from both.** A `spare-…` id fell through to the
+ *     "unknown type" branch, which marks every OTHER type's detail route and
+ *     therefore never marks `/products/spare-…` — the one page that existed.
+ *   - **`/art`, `/stickers` and `/spares` were never marked at all.** The browse
+ *     path was derived by stripping the last segment off the detail route, and
+ *     all three types detail at `/products/{slug}`, so the strip yielded
+ *     `/products` and the `!== ROUTES.PUBLIC.PRODUCTS` test discarded it. Their
+ *     dedicated browse pages are in `MAIN_NAV_ITEMS` and went stale on a clock.
+ *
+ * `browseRoute` and `slugPrefix` are required plugin fields, so a type cannot
+ * join the union without answering both — which is the property the literal
+ * could never have.
+ */
+const PLUGINS = Object.values(LISTING_TYPE_REGISTRY);
 /**
  * Infer the listing type from the id prefix when no hint was supplied.
  *
- * The slug prefix system (CLAUDE.md § Slug Prefix System) makes this reliable
- * for seeded and generated ids — `auction-…`, `preorder-…`, `prizedraw-…` — and
- * it is only a fallback: the Firestore trigger reads the document and passes
- * `listingType` explicitly.
+ * Calls the shipped `slugPrefix` on each plugin rather than re-deriving the
+ * prefix map — the same decision `audit-seed-listing-type`'s R3 makes, and the
+ * reason that audit caught five `stickers-` ids against a registered
+ * `sticker-` prefix. Returns `undefined` rather than `detectListingTypeFromSlug`'s
+ * `"standard"` default: here, "no prefix matched" must widen to every detail
+ * route, not silently narrow to one.
  */
 function listingTypeFromId(id) {
-    if (id.startsWith("auction-"))
-        return "auction";
-    if (id.startsWith("preorder-"))
-        return "pre-order";
-    if (id.startsWith("prizedraw-"))
-        return "prize-draw";
-    if (id.startsWith("classified-"))
-        return "classified";
-    if (id.startsWith("digitalcode-"))
-        return "digital-code";
-    if (id.startsWith("live-"))
-        return "live";
-    if (id.startsWith("art-"))
-        return "art";
-    if (id.startsWith("sticker-"))
-        return "stickers";
-    if (id.startsWith("product-"))
-        return "standard";
+    for (const p of PLUGINS) {
+        if (p.slugPrefix && id.startsWith(p.slugPrefix))
+            return p.listingType;
+    }
     return undefined;
 }
 function productTargets(id, hints) {
     const out = [ROUTES.HOME, ROUTES.PUBLIC.PRODUCTS];
-    if (!id)
-        return out;
+    if (!id) {
+        /*
+         * Bulk / unknown write — a seed load, a purge, or the admin "invalidate
+         * everything" button. `/products` alone is not "every listing page": five
+         * types are deliberately OUT of the general catalogue
+         * (`inGeneralCatalogue: false`) and are reachable only at their own browse
+         * route, so a bulk invalidation that marks `/products` leaves `/auctions`,
+         * `/pre-orders`, `/prize-draws`, `/art`, `/stickers` and `/spares` serving
+         * rows that no longer exist.
+         */
+        for (const p of PLUGINS)
+            if (p.browseRoute)
+                out.push(String(p.browseRoute));
+        return Array.from(new Set(out));
+    }
     const type = hints?.listingType ?? listingTypeFromId(id);
-    if (type && PRODUCT_DETAIL_BY_TYPE[type]) {
-        out.push(PRODUCT_DETAIL_BY_TYPE[type](id));
-        // The type's own browse page, when it has one distinct from /products.
-        const browse = PRODUCT_DETAIL_BY_TYPE[type](id).replace(/\/[^/]+$/, "");
-        if (browse && browse !== ROUTES.PUBLIC.PRODUCTS)
-            out.push(browse);
+    const plugin = type ? LISTING_TYPE_REGISTRY[type] : undefined;
+    if (plugin) {
+        out.push(String(plugin.detailRoute(id)));
+        // The type's own browse page. Read off the plugin, NOT derived by stripping
+        // the detail route's last segment: art/stickers/spares all detail at
+        // `/products/{slug}`, so stripping yields `/products` and loses `/art`,
+        // `/stickers` and `/spares` entirely.
+        if (plugin.browseRoute)
+            out.push(String(plugin.browseRoute));
     }
     else {
         /*
-         * Unknown type: revalidate EVERY detail route for this id rather than
-         * guessing one. At most nine entries marked stale, none of which renders
-         * until requested — strictly cheaper than leaving the real one live.
+         * Unknown type: revalidate EVERY detail and browse route for this id rather
+         * than guessing one. A couple of dozen entries marked stale, none of which
+         * renders until requested — strictly cheaper than leaving the real one live.
          */
-        for (const build of Object.values(PRODUCT_DETAIL_BY_TYPE))
-            out.push(build(id));
+        for (const p of PLUGINS) {
+            out.push(String(p.detailRoute(id)));
+            if (p.browseRoute)
+                out.push(String(p.browseRoute));
+        }
     }
     // A product's price/stock/status is rendered on every taxonomy page that
     // lists it. `categorySlugs` is the full ancestor chain, so this covers the

package/dist/_internal/shared/features/site-settings/types.d.ts

@@ -117,4 +117,43 @@ export interface PublicSiteSettings {
     disabledRoutes: string[];
     /** Derived, not a stored field — the resolved marker → wordmark → text chain. */
     effectiveWatermark?: MediaVideoWatermark;
+    /**
+     * Which public browse surfaces currently have something in them. Derived
+     * from the `surfaceCounts/global` document, not a `siteSettings` field —
+     * carried here because this payload is already the channel the navbar,
+     * footer and sidebar read their visibility rules from, so adding a second
+     * client fetch for one more rule would be a request per page load.
+     *
+     * 🛑 OMITTED ENTIRELY when the counts document has not been written yet,
+     * and every reader must treat that as "show everything". A present-but-empty
+     * object would be indistinguishable from "measured, and all zero" — which is
+     * the shape that hides the whole catalogue. `isListingSurfaceVisible`
+     * encodes the rule; do not re-derive it at a call site.
+     */
+    surfaceCounts?: {
+        listingTypes?: Record<string, number>;
+        surfaces?: Record<string, number>;
+    };
+    /**
+     * Browse routes that must answer 404 — derived from `listings.listingTypes`
+     * and `surfaceCounts` by `hiddenSurfaceRoutes`, not a stored field.
+     *
+     * 🛑 THIS EXISTS BECAUSE A PAGE-LEVEL `notFound()` CANNOT SET THE STATUS.
+     * Every one of these pages already calls `guardListingSurface`, and measured
+     * against production on 2026-10-27 all seven rendered the "404 — Page not
+     * found" body with HTTP **200**: the layout shell has already streamed by the
+     * time the guard throws, so the status is no longer mutable. `/reviews` was
+     * the one real 404 on the site, and only because it was in `disabledRoutes`
+     * and therefore caught at the edge.
+     *
+     * So the edge is the only place that can answer correctly, and `src/proxy.ts`
+     * consumes this exactly as it consumes `disabledRoutes` — same rewrite, same
+     * cached fetch, no extra request. The page guards stay as defence in depth
+     * (they are what hides the content if this payload never arrives).
+     *
+     * 🛑 Always emitted, defaulted to `[]`, for the reason spelled out on
+     * `disabledRoutes`: the proxy fails OPEN, so "nothing hidden" and "the field
+     * never arrived" are otherwise indistinguishable on the wire.
+     */
+    hiddenSurfacePaths: string[];
 }

package/dist/_internal/shared/listing-types/feature-flags.d.ts

@@ -97,5 +97,50 @@ export declare const ALL_LISTING_TYPES: ListingType[];
 export declare function isListingType(value: unknown): value is ListingType;
 /** Pull the full list of enabled listing types in canonical iteration order. */
 export declare function enabledListingTypes(settings: FeatureFlagSnapshot | null | undefined): ListingType[];
+/**
+ * The measured counts, as the public site-settings payload carries them.
+ *
+ * Structurally typed rather than importing `SurfaceCountsDocument` so this
+ * module stays a pure constants file with no feature import — the same reason
+ * it imports only `ROUTES`.
+ */
+export interface SurfaceCountSnapshot {
+    listingTypes?: Partial<Record<ListingType, number>>;
+    surfaces?: Partial<Record<string, number>>;
+}
+/**
+ * Should this listing type's public surface be shown at all?
+ *
+ * 🛑 THE PRECEDENCE, and why it is not just `count > 0`:
+ *
+ * | admin flag | measured count | result | because |
+ * |---|---|---|---|
+ * | `false`    | anything   | **hidden** | "we do not sell live animals" is a standing catalogue decision, not a statement about today's stock. An admin who closed a type must not see it reopen because someone listed one. |
+ * | `true`     | `0`        | **hidden** | auto-hide: the thing this function exists for. |
+ * | `true`     | `> 0`      | shown | |
+ * | `true`     | **absent** | **shown** | 🛑 unknown is NOT zero. A fresh install, a failed job, or a type added since the last recompute must render exactly as it does today, never as hidden. Root Cause #72. |
+ *
+ * The flag therefore stays the authority and the count only ever SUBTRACTS
+ * from what the flag already permits. Two mechanisms, one direction — which is
+ * what stops them becoming two switches that disagree.
+ */
+export declare function isListingSurfaceVisible(type: ListingType, settings: FeatureFlagSnapshot | null | undefined, counts: SurfaceCountSnapshot | null | undefined): boolean;
+/**
+ * The same question for a surface with no listing-type flag behind it
+ * (`/reviews` today).
+ *
+ * No admin-flag half: these have no switch to consult, so emptiness is the
+ * only input. Absent still means shown.
+ */
+export declare function isCountedSurfaceVisible(surface: string, counts: SurfaceCountSnapshot | null | undefined): boolean;
+/**
+ * Visible listing types — the flag list, minus the ones measured empty.
+ *
+ * This is what nav, footer and the sitemap filter on. `enabledListingTypes`
+ * above is deliberately left alone: it answers "what does this marketplace
+ * sell", which `/api/products`' post-filter and the seller forms still need
+ * even for a type with zero rows today.
+ */
+export declare function visibleListingTypes(settings: FeatureFlagSnapshot | null | undefined, counts: SurfaceCountSnapshot | null | undefined): ListingType[];
 export declare function enabledCategoryTypes(settings: FeatureFlagSnapshot | null | undefined): CategoryType[];
 export {};

package/dist/_internal/shared/listing-types/feature-flags.js

@@ -140,6 +140,57 @@ export function isListingType(value) {
 export function enabledListingTypes(settings) {
     return ALL_LISTING_TYPES.filter((t) => isListingTypeEnabled(t, settings));
 }
+/**
+ * Should this listing type's public surface be shown at all?
+ *
+ * 🛑 THE PRECEDENCE, and why it is not just `count > 0`:
+ *
+ * | admin flag | measured count | result | because |
+ * |---|---|---|---|
+ * | `false`    | anything   | **hidden** | "we do not sell live animals" is a standing catalogue decision, not a statement about today's stock. An admin who closed a type must not see it reopen because someone listed one. |
+ * | `true`     | `0`        | **hidden** | auto-hide: the thing this function exists for. |
+ * | `true`     | `> 0`      | shown | |
+ * | `true`     | **absent** | **shown** | 🛑 unknown is NOT zero. A fresh install, a failed job, or a type added since the last recompute must render exactly as it does today, never as hidden. Root Cause #72. |
+ *
+ * The flag therefore stays the authority and the count only ever SUBTRACTS
+ * from what the flag already permits. Two mechanisms, one direction — which is
+ * what stops them becoming two switches that disagree.
+ */
+export function isListingSurfaceVisible(type, settings, counts) {
+    if (!isListingTypeEnabled(type, settings))
+        return false;
+    const n = counts?.listingTypes?.[type];
+    // `undefined` -> true. Written as an explicit test rather than `(n ?? 1) > 0`
+    // so the unknown case is readable, and so nobody "simplifies" it into a
+    // falsy check that folds 0 and undefined together — which is the bug.
+    if (n === undefined)
+        return true;
+    return n > 0;
+}
+/**
+ * The same question for a surface with no listing-type flag behind it
+ * (`/reviews` today).
+ *
+ * No admin-flag half: these have no switch to consult, so emptiness is the
+ * only input. Absent still means shown.
+ */
+export function isCountedSurfaceVisible(surface, counts) {
+    const n = counts?.surfaces?.[surface];
+    if (n === undefined)
+        return true;
+    return n > 0;
+}
+/**
+ * Visible listing types — the flag list, minus the ones measured empty.
+ *
+ * This is what nav, footer and the sitemap filter on. `enabledListingTypes`
+ * above is deliberately left alone: it answers "what does this marketplace
+ * sell", which `/api/products`' post-filter and the seller forms still need
+ * even for a type with zero rows today.
+ */
+export function visibleListingTypes(settings, counts) {
+    return ALL_LISTING_TYPES.filter((t) => isListingSurfaceVisible(t, settings, counts));
+}
 export function enabledCategoryTypes(settings) {
     const all = ["category", "sublisting", "brand", "bundle"];
     return all.filter((t) => isCategoryTypeEnabled(t, settings));