@mohasinac/appkit 4.67.0 → 4.68.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.67.0",
-  "head": "a745f11c80fa634f73acc9013502f5bcc17972db",
+  "version": "4.68.0",
+  "head": "d9da5b62aa583840cb50fa07288dc03177d1d991",
   "branch": "main",
   "dirty": false,
-  "builtAt": "2026-10-26T11:54:19.893Z"
+  "builtAt": "2026-10-26T21:11:44.047Z"
 }

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 { hiddenSurfaceRoutes } 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,19 +667,14 @@ 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));
     const keep = (entry) => {
         const path = entry.url.startsWith("http")
             ? new URL(entry.url).pathname

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

@@ -1,3 +1,4 @@
+import { 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,15 @@ 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),
         // 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,26 @@ 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[];
 }

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

@@ -0,0 +1,43 @@
+/**
+ * Which public BROWSE ROUTES must not be served, given the admin flags and the
+ * measured counts.
+ *
+ * ## Why this is one function and not two copies
+ *
+ * Two places need this answer and they must never disagree:
+ *
+ *   · `buildSitemap` — decides which browse URLs are advertised.
+ *   · `toPublicSiteSettings` → `src/proxy.ts` — decides which browse 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.
+ *
+ * ## 🛑 EXACT PATHS, never prefixes
+ *
+ * `art`, `stickers`, `spares` and `standard` all detail at `/products/{slug}`,
+ * so a prefix rule would delist — or 404 — the entire standard catalogue the
+ * day `spares` emptied. An empty type contributes no detail URLs anyway, since
+ * its own fetcher returns none, so the exact-path rule loses nothing real.
+ *
+ * ## 🛑 A SHARED route survives while ANY of its types is visible
+ *
+ * `/art` spans `art` and `stickers`; `/products` spans `standard` plus several
+ * others. Without the 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 SurfaceCountSnapshot } from "./feature-flags";
+/** The snapshot shape `isListingSurfaceVisible` reads its admin flags from. */
+interface SettingsSnapshot {
+    listings?: {
+        listingTypes?: Partial<Record<string, boolean>>;
+    };
+}
+export declare function hiddenSurfaceRoutes(settings: SettingsSnapshot | null | undefined, counts: SurfaceCountSnapshot | null | undefined): string[];
+export {};

package/dist/_internal/shared/listing-types/hidden-surfaces.js

@@ -0,0 +1,57 @@
+/**
+ * Which public BROWSE ROUTES must not be served, given the admin flags and the
+ * measured counts.
+ *
+ * ## Why this is one function and not two copies
+ *
+ * Two places need this answer and they must never disagree:
+ *
+ *   · `buildSitemap` — decides which browse URLs are advertised.
+ *   · `toPublicSiteSettings` → `src/proxy.ts` — decides which browse 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.
+ *
+ * ## 🛑 EXACT PATHS, never prefixes
+ *
+ * `art`, `stickers`, `spares` and `standard` all detail at `/products/{slug}`,
+ * so a prefix rule would delist — or 404 — the entire standard catalogue the
+ * day `spares` emptied. An empty type contributes no detail URLs anyway, since
+ * its own fetcher returns none, so the exact-path rule loses nothing real.
+ *
+ * ## 🛑 A SHARED route survives while ANY of its types is visible
+ *
+ * `/art` spans `art` and `stickers`; `/products` spans `standard` plus several
+ * others. Without the 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 { ALL_LISTING_TYPES, isListingSurfaceVisible, } from "./feature-flags.js";
+import { pluginFor } from "./_registry.js";
+export function hiddenSurfaceRoutes(settings, counts) {
+    const hidden = new Set();
+    const routeOf = (type) => String(pluginFor(type).browseRoute ?? "");
+    for (const type of ALL_LISTING_TYPES) {
+        if (isListingSurfaceVisible(type, settings, counts))
+            continue;
+        const route = routeOf(type);
+        if (route)
+            hidden.add(route);
+    }
+    /*
+     * Second pass, deliberately not folded into the first: a route is only
+     * hidden once EVERY type that browses there is hidden, and the first pass
+     * cannot know that until it has seen them all.
+     */
+    for (const type of ALL_LISTING_TYPES) {
+        if (isListingSurfaceVisible(type, settings, counts))
+            hidden.delete(routeOf(type));
+    }
+    return [...hidden];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.67.0",
+  "version": "4.68.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"