@mohasinac/appkit 4.67.0 → 4.69.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.67.0",
-  "head": "a745f11c80fa634f73acc9013502f5bcc17972db",
+  "version": "4.69.0",
+  "head": "f8d0558f54602d80ef0200435f7a49f8848d5928",
   "branch": "main",
   "dirty": false,
-  "builtAt": "2026-10-26T11:54:19.893Z"
+  "builtAt": "2026-10-27T12:56:14.309Z"
 }

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

@@ -16,8 +16,8 @@ import { PRODUCT_FIELDS } from "../../../../constants/field-names.js";
 import { PRODUCT_DETAIL_LISTING_TYPES } from "./product-detail-types.js";
 import { safeRead } from "../../../../errors/safe-read.js";
 import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
-import { ALL_BROWSE_PAGES, ALL_LISTING_TYPES, browsePageForPath, isBrowsePageEnabled, isListingSurfaceVisible, } from "../../../shared/listing-types/feature-flags.js";
-import { pluginFor } from "../../../shared/listing-types/_registry.js";
+import { ALL_BROWSE_PAGES, browsePageForPath, isBrowsePageEnabled, } from "../../../shared/listing-types/feature-flags.js";
+import { closedSurfacePrefixes, hiddenSurfaceRoutes, isUnderClosedPrefix, } from "../../../shared/listing-types/hidden-surfaces.js";
 import { getSurfaceCounts } from "../products/surface-counts.js";
 // Product field strings — matches consumer field-names.ts
 const PRODUCT_STATUS = "status";
@@ -667,25 +667,39 @@ export async function buildSitemap({ baseUrl }) {
      * the sitemap rather than being withdrawn by a job that has not run.
      */
     const counts = await getSurfaceCounts();
-    const hiddenSurfacePaths = new Set(ALL_LISTING_TYPES.filter((t) => !isListingSurfaceVisible(t, settings, counts))
-        .map((t) => String(pluginFor(t).browseRoute ?? ""))
-        .filter(Boolean));
     /*
-     * A route shared by several types survives while ANY of them is visible —
-     * `/art` spans art and stickers. Without this, hiding stickers alone would
-     * delist a page art still fills.
+     * 🛑 ONE definition, shared with the edge gate. These two loops used to live
+     * here and are now `hiddenSurfaceRoutes` — because `toPublicSiteSettings`
+     * needs the same answer to tell `src/proxy.ts` which browse routes to 404,
+     * and a sitemap that advertises a URL the edge 404s is a crawl error on a
+     * page we asked Google to fetch.
      */
-    for (const t of ALL_LISTING_TYPES) {
-        if (isListingSurfaceVisible(t, settings, counts)) {
-            hiddenSurfacePaths.delete(String(pluginFor(t).browseRoute ?? ""));
-        }
-    }
+    const hiddenSurfacePaths = new Set(hiddenSurfaceRoutes(settings, counts));
+    /*
+     * 🛑 `disabledRoutes` WAS NEVER APPLIED HERE, and it showed. Measured against
+     * the production sitemap on 2026-10-27, with `disabledRoutes: ["/blog",
+     * "/reviews"]` live and both paths already 404ing at the edge, the sitemap
+     * advertised **17 `/blog` URLs and one `/reviews` URL**.
+     *
+     * That is 18 crawl errors on pages we explicitly asked Google to fetch — the
+     * precise failure the `closed` filter below exists to prevent, on the one
+     * axis it did not cover. The browse-page half was handled because
+     * `browsePageForPath` is prefix-aware; the hand-disabled half had no reader.
+     *
+     * `closedSurfacePrefixes` is the SAME function `toPublicSiteSettings` feeds
+     * to `src/proxy.ts`, so the list of URLs this withholds and the list the edge
+     * 404s are now derived once and cannot drift (the whole reason
+     * `hiddenSurfaceRoutes` was extracted in the first place).
+     */
+    const closedPrefixes = closedSurfacePrefixes(settings);
     const keep = (entry) => {
         const path = entry.url.startsWith("http")
             ? new URL(entry.url).pathname
             : entry.url;
         if (hiddenSurfacePaths.has(path.replace(/\/+$/, "") || "/"))
             return false;
+        if (isUnderClosedPrefix(path, closedPrefixes))
+            return false;
         if (closed.size === 0)
             return true;
         const page = browsePageForPath(path);

package/dist/_internal/server/features/site-settings/adapters.js

@@ -1,3 +1,4 @@
+import { closedSurfacePrefixes, hiddenSurfaceRoutes, } from "../../../shared/listing-types/hidden-surfaces.js";
 /**
  * Document fields with a proven `useSiteSettings()` reader. Every entry below
  * was traced to a call site; anything without one belongs in the private list,
@@ -197,6 +198,32 @@ export function toPublicSiteSettings(doc, opts) {
          * would take the entire catalogue off the navbar.
          */
         surfaceCounts: opts?.surfaceCounts,
+        /*
+         * Derived from the two fields above it — the admin flags on `doc` and the
+         * measured counts in `opts`. Computed here rather than in the proxy because
+         * the proxy runs on the EDGE: `hiddenSurfaceRoutes` reaches the listing-type
+         * registry, and pulling that into the middleware bundle to re-derive an
+         * answer the server already holds would be the wrong trade. The edge gets a
+         * list of strings to match, exactly like `disabledRoutes`.
+         */
+        hiddenSurfacePaths: hiddenSurfaceRoutes(doc, opts?.surfaceCounts),
+        /*
+         * The PREFIX half of the same answer — closed browse pages, plus the
+         * `disabledRoutes` the line above already carries.
+         *
+         * 🛑 A SEPARATE FIELD rather than more entries in `hiddenSurfacePaths`,
+         * because the proxy applies the two with different match rules and merging
+         * them would force one rule on both. Exact-only is load-bearing for the
+         * listing-type list (`art`/`spares`/`standard` share `/products/{slug}`);
+         * prefix is load-bearing here, because closing `/categories` while serving
+         * all 4,698 `/categories/{slug}` pages is what production was doing.
+         *
+         * Overlaps `disabledRoutes` on purpose. The proxy unions both into one
+         * prefix set, so a duplicate is free — and deriving the whole prefix list
+         * in ONE place is what stops the sitemap and the edge disagreeing, which
+         * is the only reason `hiddenSurfaceRoutes` was extracted.
+         */
+        hiddenSurfacePrefixes: closedSurfacePrefixes(doc),
         // D9 — undefined reads as OFF, never a default-true `??`.
         chat: { enabled: doc.chat?.enabled === true },
         /*

package/dist/_internal/server/functions/firestore.d.ts

@@ -18,6 +18,23 @@ export declare const onPrizeDrawPaymentConfirmed: import("./types").DocumentTrig
 export declare const prizeDrawSoldOutReveal: import("./types").DocumentTriggerFunctionDefinition<import("../jobs/core/prizeDrawSoldOutReveal").PrizeDrawStockSnapshot, import("../jobs/core/prizeDrawSoldOutReveal").PrizeDrawStockSnapshot>;
 export declare const onReviewWrite: import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>;
 export declare const onCategoryWrite: import("./types").DocumentTriggerFunctionDefinition<import("../jobs").CategoryDoc, import("../jobs").CategoryDoc>;
+/**
+ * 🛑 The ONE trigger that invalidates the whole page cache.
+ *
+ * `documentWritten` and not `documentUpdated`: a settings document that is
+ * CREATED on first access (`getSingleton` writes defaults when it is missing)
+ * changes the site exactly as much as an edit does.
+ *
+ * `siteSettings` is a singleton, so the `{settingsId}` wildcard matches one
+ * document in practice — it is a wildcard because a trigger path must be, and
+ * the handler reads the id from it rather than hardcoding `"global"`.
+ *
+ * See the handler for why this carries no field-level diff while
+ * `onProductWrite` must, and for the measurement that prompted it: a listing
+ * type switched off in Firestore while its browse page kept serving a cached
+ * 200 because nothing marked it stale.
+ */
+export declare const onSiteSettingsWrite: import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>;
 export declare const onStoreWrite: import("./types").DocumentTriggerFunctionDefinition<import("../jobs").StoreDoc, import("../jobs").StoreDoc>;
 export declare const onSupportTicketCreate: import("./types").DocumentTriggerFunctionDefinition<null, Record<string, import("../../..").JsonValue>>;
 export declare const onSupportTicketUpdate: import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>;
@@ -54,7 +71,7 @@ export declare const FIRESTORE_TRIGGER_FUNCTIONS: readonly [import("./types").Do
     [x: string]: import("../../..").JsonValue;
 }, {
     [x: string]: import("../../..").JsonValue;
-}>, import("./types").DocumentTriggerFunctionDefinition<import("../jobs/core/onPrizeDrawPaymentConfirmed").PrizeDrawOrderSnapshot, import("../jobs/core/onPrizeDrawPaymentConfirmed").PrizeDrawOrderSnapshot>, import("./types").DocumentTriggerFunctionDefinition<import("../jobs/core/prizeDrawSoldOutReveal").PrizeDrawStockSnapshot, import("../jobs/core/prizeDrawSoldOutReveal").PrizeDrawStockSnapshot>, import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<import("../jobs").CategoryDoc, import("../jobs").CategoryDoc>, import("./types").DocumentTriggerFunctionDefinition<import("../jobs").StoreDoc, import("../jobs").StoreDoc>, import("./types").DocumentTriggerFunctionDefinition<null, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<null, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<{
+}>, import("./types").DocumentTriggerFunctionDefinition<import("../jobs/core/onPrizeDrawPaymentConfirmed").PrizeDrawOrderSnapshot, import("../jobs/core/onPrizeDrawPaymentConfirmed").PrizeDrawOrderSnapshot>, import("./types").DocumentTriggerFunctionDefinition<import("../jobs/core/prizeDrawSoldOutReveal").PrizeDrawStockSnapshot, import("../jobs/core/prizeDrawSoldOutReveal").PrizeDrawStockSnapshot>, import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<import("../jobs").CategoryDoc, import("../jobs").CategoryDoc>, import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<import("../jobs").StoreDoc, import("../jobs").StoreDoc>, import("./types").DocumentTriggerFunctionDefinition<null, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<null, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<Record<string, import("../../..").JsonValue>, Record<string, import("../../..").JsonValue>>, import("./types").DocumentTriggerFunctionDefinition<{
     [x: string]: import("../../..").JsonValue;
 }, {
     [x: string]: import("../../..").JsonValue;

package/dist/_internal/server/functions/firestore.js

@@ -6,7 +6,7 @@
  * The path patterns mirror the original `functions/src/index.ts` declarations
  * to preserve identical deploy behavior.
  */
-import { onCategoryWriteHandler, onOrderCreateHandler, onOrderStatusChangeHandler, onProductStockChangeHandler, onProductWriteHandler, onReviewWriteHandler, onScamReportCreateHandler, onScamReportUpdateHandler, onStoreWriteHandler, onSupportTicketCreateHandler, onSupportTicketUpdateHandler, onUserBanChangeHandler, onShipmentItemWriteHandler, onShipmentLotWriteHandler, onShipmentHeaderWriteHandler, onShipmentDeletedHandler, onCatalogueSubmittedForApprovalHandler, onJobCreatedHandler, onPrizeDrawPaymentConfirmedHandler, prizeDrawSoldOutRevealHandler, } from "../jobs/handlers/index.js";
+import { onCategoryWriteHandler, onOrderCreateHandler, onOrderStatusChangeHandler, onProductStockChangeHandler, onProductWriteHandler, onReviewWriteHandler, onScamReportCreateHandler, onScamReportUpdateHandler, onSiteSettingsWriteHandler, onStoreWriteHandler, onSupportTicketCreateHandler, onSupportTicketUpdateHandler, onUserBanChangeHandler, onShipmentItemWriteHandler, onShipmentLotWriteHandler, onShipmentHeaderWriteHandler, onShipmentDeletedHandler, onCatalogueSubmittedForApprovalHandler, onJobCreatedHandler, onPrizeDrawPaymentConfirmedHandler, prizeDrawSoldOutRevealHandler, } from "../jobs/handlers/index.js";
 import { defineFunction } from "./define.js";
 const REGION = "asia-south1";
 export const onOrderCreate = defineFunction({
@@ -65,6 +65,29 @@ export const onCategoryWrite = defineFunction({
     handler: onCategoryWriteHandler,
     options: { region: REGION },
 });
+/**
+ * 🛑 The ONE trigger that invalidates the whole page cache.
+ *
+ * `documentWritten` and not `documentUpdated`: a settings document that is
+ * CREATED on first access (`getSingleton` writes defaults when it is missing)
+ * changes the site exactly as much as an edit does.
+ *
+ * `siteSettings` is a singleton, so the `{settingsId}` wildcard matches one
+ * document in practice — it is a wildcard because a trigger path must be, and
+ * the handler reads the id from it rather than hardcoding `"global"`.
+ *
+ * See the handler for why this carries no field-level diff while
+ * `onProductWrite` must, and for the measurement that prompted it: a listing
+ * type switched off in Firestore while its browse page kept serving a cached
+ * 200 because nothing marked it stale.
+ */
+export const onSiteSettingsWrite = defineFunction({
+    name: "onSiteSettingsWrite",
+    description: "Invalidate the whole page cache when site settings change.",
+    trigger: { kind: "documentWritten", pathPattern: "siteSettings/{settingsId}" },
+    handler: onSiteSettingsWriteHandler,
+    options: { region: REGION },
+});
 export const onStoreWrite = defineFunction({
     name: "onStoreWrite",
     description: "Side-effects on store writes (status mirror, owner uid index).",
@@ -165,6 +188,7 @@ export const FIRESTORE_TRIGGER_FUNCTIONS = [
     prizeDrawSoldOutReveal,
     onReviewWrite,
     onCategoryWrite,
+    onSiteSettingsWrite,
     onStoreWrite,
     onSupportTicketCreate,
     onSupportTicketUpdate,

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/features/site-settings/types.d.ts

@@ -134,4 +134,50 @@ export interface PublicSiteSettings {
         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[];
+    /**
+     * Closed routes that take their DESCENDANTS with them — closed browse pages
+     * (`/categories`, `/brands`, `/franchise`, `/stores`, `/sellers`) plus
+     * `disabledRoutes`. Derived by `closedSurfacePrefixes`, not stored.
+     *
+     * 🛑 SEPARATE FROM `hiddenSurfacePaths` because the two carry different
+     * MATCH RULES, and each rule is load-bearing in opposite directions. Exact
+     * matching is required above (`art`/`stickers`/`spares`/`standard` all detail
+     * at `/products/{slug}`, so a prefix rule would 404 the whole standard
+     * catalogue the day `spares` emptied). Prefix matching is required here: all
+     * four browse pages had been closed since 2026-10-24 and production still
+     * served `/categories/category-beyblade-x` and `/stores/store-beyblade-arena`
+     * as real, indexable 200s. A closed section whose 4,698 detail pages stay
+     * open is not closed.
+     *
+     * Overlaps `disabledRoutes` deliberately — the proxy unions both into one
+     * prefix set, and deriving the full list once is what stops the sitemap and
+     * the edge disagreeing about which URLs exist.
+     *
+     * 🛑 Always emitted, defaulted to `[]`, for the same reason as the two lists
+     * above it: the proxy fails OPEN, so "nothing closed" and "the field never
+     * arrived" are otherwise indistinguishable on the wire.
+     */
+    hiddenSurfacePrefixes: string[];
 }

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

@@ -65,6 +65,18 @@ export declare function isBrowsePageEnabled(page: BrowsePageKey, settings: Featu
 export declare function enabledBrowsePages(settings: FeatureFlagSnapshot | null | undefined): BrowsePageKey[];
 /** Narrow an untrusted string — a route param, a form value — to the union. */
 export declare function isBrowsePageKey(value: unknown): value is BrowsePageKey;
+/**
+ * The path prefixes a given section owns — the inverse of `browsePageForPath`.
+ *
+ * 🛑 Exported so `closedSurfacePrefixes` can build the edge-gate list from the
+ * SAME table `browsePageForPath` matches against. It is one key to five paths
+ * (`stores` owns both `/stores` and `/sellers`), so a caller that re-derived
+ * "the path for a key" from `ROUTES` would get four entries and leave
+ * `/sellers` served — the exact half-closed door the `BrowsePageKey` docstring
+ * above exists to forbid. Root Cause #61: every hand-written second copy of an
+ * enumeration in this codebase has drifted at least once.
+ */
+export declare function browsePagePrefixes(page: BrowsePageKey): string[];
 /**
  * Which browse section a link points into, or `null` for a link that is not in
  * one. Used to drop nav, sidebar, mobile-sheet and footer entries for a closed

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

@@ -66,6 +66,20 @@ const BROWSE_PAGE_PREFIXES = [
     [String(ROUTES.PUBLIC.STORES), "stores"],
     [String(ROUTES.PUBLIC.SELLERS), "stores"],
 ];
+/**
+ * The path prefixes a given section owns — the inverse of `browsePageForPath`.
+ *
+ * 🛑 Exported so `closedSurfacePrefixes` can build the edge-gate list from the
+ * SAME table `browsePageForPath` matches against. It is one key to five paths
+ * (`stores` owns both `/stores` and `/sellers`), so a caller that re-derived
+ * "the path for a key" from `ROUTES` would get four entries and leave
+ * `/sellers` served — the exact half-closed door the `BrowsePageKey` docstring
+ * above exists to forbid. Root Cause #61: every hand-written second copy of an
+ * enumeration in this codebase has drifted at least once.
+ */
+export function browsePagePrefixes(page) {
+    return BROWSE_PAGE_PREFIXES.filter(([, key]) => key === page).map(([prefix]) => prefix);
+}
 /**
  * Which browse section a link points into, or `null` for a link that is not in
  * one. Used to drop nav, sidebar, mobile-sheet and footer entries for a closed

package/dist/_internal/shared/listing-types/hidden-surfaces.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Which public routes must not be served, given the admin flags and the
+ * measured counts.
+ *
+ * ## Why this is one module and not copies at each reader
+ *
+ * Two places need these answers and they must never disagree:
+ *
+ *   · `buildSitemap` — decides which URLs are advertised.
+ *   · `toPublicSiteSettings` → `src/proxy.ts` — decides which URLs 404.
+ *
+ * A disagreement is not cosmetic: the sitemap advertising a URL the edge 404s
+ * is a crawl error on a page we told Google to fetch, and the reverse serves a
+ * surface we have decided is closed. They were two hand-written copies of the
+ * same two loops when this was extracted — and the disagreement showed up
+ * anyway on the one axis only one of them read (see `closedSurfacePrefixes`).
+ *
+ * ## 🛑 TWO FUNCTIONS, because the MATCH RULE differs — and each rule is
+ * load-bearing in the opposite direction
+ *
+ * | | rule | why the other rule would break it |
+ * |---|---|---|
+ * | `hiddenSurfaceRoutes` — listing-type browse pages | **exact path** | `art`, `stickers`, `spares` and `standard` all detail at `/products/{slug}`, so a prefix rule would 404 the whole standard catalogue the day `spares` emptied |
+ * | `closedSurfacePrefixes` — browse sections, bundles, `disabledRoutes` | **prefix** | `/categories/{slug}` is owned by `categories` alone, and exact-only matching left all 4,698 of them serving a real 200 while `/categories` said 404 |
+ *
+ * Do not merge them. Picking either rule for both is a live defect one way or
+ * the other, and both directions have now been observed in production.
+ *
+ * ## 🛑 A SHARED route survives while ANY of its types is visible
+ *
+ * `/art` spans `art` and `stickers`; `/products` spans `standard` plus several
+ * others. Without `hiddenSurfaceRoutes`' second pass, hiding `stickers` alone
+ * would close a page `art` still fills — and hiding `spares` alone would close
+ * `/products`.
+ *
+ * @tag domain:products
+ * @tag layer:shared
+ * @tag access:isomorphic
+ * @tag sideEffects:none
+ */
+import { type BrowsePageKey, type SurfaceCountSnapshot } from "./feature-flags";
+/** The snapshot shape `isListingSurfaceVisible` reads its admin flags from. */
+interface SettingsSnapshot {
+    listings?: {
+        listingTypes?: Partial<Record<string, boolean>>;
+        browsePages?: Partial<Record<BrowsePageKey, boolean>>;
+        categoryTypes?: Partial<Record<string, boolean>>;
+        closedPaths?: string[];
+    };
+    disabledRoutes?: string[];
+}
+export declare function hiddenSurfaceRoutes(settings: SettingsSnapshot | null | undefined, counts: SurfaceCountSnapshot | null | undefined): string[];
+/**
+ * Closed routes that must take their DESCENDANTS with them.
+ *
+ * ## Why this is a second function and not more entries in the first
+ *
+ * `hiddenSurfaceRoutes` above is exact-path-only, and its docstring explains
+ * why it has to be: `art`, `stickers`, `spares` and `standard` all detail at
+ * `/products/{slug}`, so a prefix rule there would 404 the whole standard
+ * catalogue the day `spares` emptied.
+ *
+ * A closed BROWSE PAGE has the opposite property. `/categories/{slug}` belongs
+ * to `categories` and to nothing else — no open surface details underneath it
+ * — so there is no shared-route hazard, and exact-only matching leaves the
+ * interesting half of the section served.
+ *
+ * 🛑 THIS WAS MEASURED OPEN IN PRODUCTION, 2026-10-27. All four browse pages
+ * had been `false` in `listings.browsePages` since 2026-10-24 and:
+ *
+ * ```
+ * /categories                     200   body = "404 — Page not found"
+ * /categories/category-beyblade-x 200   a real, fully-rendered category page
+ * /stores/store-beyblade-arena    200   a real, fully-rendered store page
+ * ```
+ *
+ * The index was a SOFT 404 (`guardBrowsePage` throws `notFound()` after the
+ * shell has streamed, which cannot set the status — see the site-wide soft-404
+ * note) and the 4,698 detail pages were never guarded at all. So "the section
+ * is closed" meant "the front door says 404 while every room stays open and
+ * indexable".
+ *
+ * ## `disabledRoutes` is folded in here, not left to the proxy
+ *
+ * The proxy already prefix-matches `disabledRoutes`, so including it changes
+ * nothing at the edge. It is here because the SITEMAP needs the same list and
+ * did not have it: measured the same day, the sitemap advertised 17 `/blog`
+ * URLs and one `/reviews` URL, every one of which the edge already 404s. That
+ * is a crawl error on a page we asked Google to fetch — Root Cause #81's
+ * host/sitemap disagreement in miniature, and the precise reason
+ * `hiddenSurfaceRoutes` was extracted into one definition in the first place.
+ *
+ * One list, two readers, no way for them to disagree:
+ *   · `toPublicSiteSettings` → `src/proxy.ts` — which paths 404.
+ *   · `buildSitemap`                          — which paths are advertised.
+ *
+ * Fails OPEN on a missing settings document: every `isBrowsePageEnabled` call
+ * returns `true` and the list is empty, so a transient Firestore error cannot
+ * withdraw the catalogue (Root Cause #72).
+ */
+export declare function closedSurfacePrefixes(settings: SettingsSnapshot | null | undefined): string[];
+/**
+ * Does `path` sit on or under one of `prefixes`?
+ *
+ * 🛑 A `/`-delimited boundary, never a bare `startsWith`. `/store` is the
+ * SELLER DASHBOARD and `/stores` is the public directory, so a substring test
+ * would 404 a signed-in seller's own dashboard the moment an admin closed the
+ * public storefronts — a different surface, a different audience, one
+ * character apart. Same rule, same reason, as `browsePageForPath`.
+ */
+export declare function isUnderClosedPrefix(path: string, prefixes: readonly string[]): boolean;
+export {};