@mohasinac/appkit 4.66.0 → 4.68.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.66.0",
-  "head": "e06ffbfe125e5c77504aa8a6a1a3c2e553244321",
+  "version": "4.68.0",
+  "head": "d9da5b62aa583840cb50fa07288dc03177d1d991",
   "branch": "main",
   "dirty": false,
-  "builtAt": "2026-10-25T21:20:19.588Z"
+  "builtAt": "2026-10-26T21:11:44.047Z"
 }

package/dist/_internal/client/features/maintenance/index.d.ts

@@ -5,5 +5,6 @@ export type { ServerErrorDetailViewProps } from "./views/ServerErrorDetailView";
 export { MaintenanceDashboardView } from "./views/MaintenanceDashboardView";
 export type { MaintenanceDashboardViewProps } from "./views/MaintenanceDashboardView";
 export { AnalysisRunnerView } from "./views/AnalysisRunnerView";
+export { CacheInvalidationPanel } from "./views/CacheInvalidationPanel";
 export { CloudLogsListView } from "./views/CloudLogsListView";
 export type { CloudLogsListViewProps } from "./views/CloudLogsListView";

package/dist/_internal/client/features/maintenance/index.js

@@ -2,4 +2,5 @@ export { ServerErrorsListView } from "./views/ServerErrorsListView.js";
 export { ServerErrorDetailView } from "./views/ServerErrorDetailView.js";
 export { MaintenanceDashboardView } from "./views/MaintenanceDashboardView.js";
 export { AnalysisRunnerView } from "./views/AnalysisRunnerView.js";
+export { CacheInvalidationPanel } from "./views/CacheInvalidationPanel.js";
 export { CloudLogsListView } from "./views/CloudLogsListView.js";

package/dist/_internal/client/features/maintenance/views/CacheInvalidationPanel.d.ts

@@ -0,0 +1,33 @@
+import * as React from "react";
+/**
+ * "Invalidate all cached pages" — the manual door into ISR invalidation.
+ *
+ * ## Why a human needs this at all
+ *
+ * The Firestore triggers (`onProductWrite`, `onCategoryWrite`, `onReviewWrite`,
+ * `onStoreWrite`) invalidate on their own, so the common case needs no button.
+ * What they cannot see is a change that did not pass through them: an
+ * `appkit-seed load`, a console edit, a bulk script, or a trigger that failed
+ * its one best-effort `fetch`. Before this the only recovery was a redeploy or
+ * waiting out a TTL — and most detail routes have no TTL at all (they are
+ * absent from `prerender-manifest.json`, i.e. cached indefinitely), so "wait"
+ * was not actually an option.
+ *
+ * ## 🛑 Confirmed, and the confirmation is about COST, not damage
+ *
+ * Nothing is deleted and no document is written — this marks entries stale.
+ * The risk is the re-render: this project was suspended with HTTP 402 for 3.1M
+ * ISR writes against a 200K allowance. The dialog comes from
+ * `ACTIONS.ADMIN["invalidate-cache"].confirmation`, so Rule #7 owns the copy
+ * and there is no `window.confirm` here.
+ *
+ * ## The result is rendered, not toasted
+ *
+ * `revalidatePath` does not report whether an entry existed, so the only
+ * honest feedback is *which paths were marked*. A green toast saying "done"
+ * would read identically whether seven paths were marked or zero — and
+ * "marked nothing, silently" is the documented failure mode of this whole
+ * subsystem (the locale-prefix trap in `revalidate-page-targets.ts`). Showing
+ * the list means a wrong prefix is visible rather than inferred.
+ */
+export declare function CacheInvalidationPanel(): React.JSX.Element;

package/dist/_internal/client/features/maintenance/views/CacheInvalidationPanel.js

@@ -0,0 +1,96 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Button, Div, Heading, Span, Text } from "@mohasinac/appkit/client";
+import { normalizeError } from "../../../../../errors/normalize.js";
+import { toUserMessage } from "../../../../../errors/error-display-map.js";
+import { ADMIN_ENDPOINTS } from "../../../../../constants/api-endpoints.js";
+import { ACTIONS } from "../../../../shared/actions/action-registry.js";
+/**
+ * "Invalidate all cached pages" — the manual door into ISR invalidation.
+ *
+ * ## Why a human needs this at all
+ *
+ * The Firestore triggers (`onProductWrite`, `onCategoryWrite`, `onReviewWrite`,
+ * `onStoreWrite`) invalidate on their own, so the common case needs no button.
+ * What they cannot see is a change that did not pass through them: an
+ * `appkit-seed load`, a console edit, a bulk script, or a trigger that failed
+ * its one best-effort `fetch`. Before this the only recovery was a redeploy or
+ * waiting out a TTL — and most detail routes have no TTL at all (they are
+ * absent from `prerender-manifest.json`, i.e. cached indefinitely), so "wait"
+ * was not actually an option.
+ *
+ * ## 🛑 Confirmed, and the confirmation is about COST, not damage
+ *
+ * Nothing is deleted and no document is written — this marks entries stale.
+ * The risk is the re-render: this project was suspended with HTTP 402 for 3.1M
+ * ISR writes against a 200K allowance. The dialog comes from
+ * `ACTIONS.ADMIN["invalidate-cache"].confirmation`, so Rule #7 owns the copy
+ * and there is no `window.confirm` here.
+ *
+ * ## The result is rendered, not toasted
+ *
+ * `revalidatePath` does not report whether an entry existed, so the only
+ * honest feedback is *which paths were marked*. A green toast saying "done"
+ * would read identically whether seven paths were marked or zero — and
+ * "marked nothing, silently" is the documented failure mode of this whole
+ * subsystem (the locale-prefix trap in `revalidate-page-targets.ts`). Showing
+ * the list means a wrong prefix is visible rather than inferred.
+ */
+export function CacheInvalidationPanel() {
+    const [running, setRunning] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const [result, setResult] = React.useState(null);
+    async function invalidateAll() {
+        setRunning(true);
+        setError(null);
+        setResult(null);
+        try {
+            const res = await fetch(ADMIN_ENDPOINTS.CACHE_REVALIDATE, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                // No `collections` key — the server reads that as "every known
+                // collection", which is what this button means.
+                body: JSON.stringify({}),
+            });
+            const body = (await res.json());
+            if (!res.ok || !body.ok) {
+                /*
+                 * 🛑 `toUserMessage`, never `?? body.error`. The server's own message
+                 * is server text; piping it into the UI is how a Node MODULE_NOT_FOUND
+                 * with a full require stack was once rendered inside a buyer-facing
+                 * modal (Rule #9 §6, Root Cause #86).
+                 */
+                setError(toUserMessage("code" in body ? String(body.code) : undefined, undefined, {
+                    fallback: `Cache invalidation failed (HTTP ${res.status}).`,
+                }));
+                return;
+            }
+            setResult(body.data);
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            setError(toUserMessage(e.code, undefined, {
+                fallback: "Could not reach the cache endpoint. Check the server logs for detail.",
+            }));
+        }
+        finally {
+            setRunning(false);
+        }
+    }
+    return (_jsxs(Div, { style: {
+            padding: "1rem 1.25rem",
+            border: "1px solid var(--appkit-color-border)",
+            borderRadius: 8,
+            background: "var(--appkit-color-surface)",
+            marginBottom: "1.5rem",
+        }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600 }, children: "Page cache" }), _jsx(Text, { as: "p", style: { color: "var(--appkit-color-text-muted)", margin: "0.35rem 0 0.9rem" }, children: "Writes made through the app invalidate their own pages automatically. Use this after a change the triggers could not see \u2014 a seed load, a direct Firestore edit, or a bulk script." }), _jsx(Button, { action: ACTIONS.ADMIN["invalidate-cache"], isLoading: running, disabled: running, onClick: invalidateAll }), error ? (_jsx(Text, { as: "p", role: "alert", style: { color: "var(--appkit-color-error)", marginTop: "0.75rem" }, children: error })) : null, result ? (_jsxs(Div, { style: { marginTop: "0.9rem" }, children: [_jsxs(Text, { as: "p", style: { margin: 0 }, children: ["Marked ", _jsx(Span, { weight: "bold", children: result.pagesRevalidated.length }), " page", result.pagesRevalidated.length === 1 ? "" : "s", " stale across", " ", _jsx(Span, { weight: "bold", children: result.collections.length }), " collection", result.collections.length === 1 ? "" : "s", "."] }), _jsx(Text, { as: "p", size: "xs", style: { color: "var(--appkit-color-text-muted)", margin: "0.3rem 0 0" }, children: "They re-render on their next visit; nothing was deleted." }), _jsx(Div, { style: {
+                            marginTop: "0.5rem",
+                            maxHeight: 180,
+                            overflowY: "auto",
+                            fontFamily: "monospace",
+                            fontSize: "0.75rem",
+                            lineHeight: 1.6,
+                            color: "var(--appkit-color-text-muted)",
+                        }, children: result.pagesRevalidated.map((p) => (_jsx(Div, { children: p }, p))) })] })) : null] }));
+}

package/dist/_internal/client/features/maintenance/views/MaintenanceDashboardView.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Anchor, Div, Heading, Li, Nav, Section, Span, Text, Ul } from "@mohasinac/appkit/client";
+import { CacheInvalidationPanel } from "./CacheInvalidationPanel.js";
 const card = {
     padding: "1rem 1.25rem",
     border: "1px solid var(--appkit-color-border)",
@@ -7,7 +8,7 @@ const card = {
     background: "var(--appkit-color-surface)",
 };
 export function MaintenanceDashboardView({ counts, basePath, }) {
-    return (_jsxs(Div, { style: { padding: "1.5rem", maxWidth: "1200px", margin: "0 auto" }, children: [_jsx(Heading, { level: 1, style: { fontSize: "1.5rem", fontWeight: 600 }, children: "Maintenance" }), _jsx(Text, { as: "p", style: { color: "var(--appkit-color-text-muted)", marginBottom: "1.25rem" }, children: "Errors and failures across the platform \u2014 server, client, and Cloud Functions." }), _jsxs(Div, { style: { display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(170px, 1fr))", gap: "0.75rem", marginBottom: "1.5rem" }, children: [_jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Last 24 hours" }), _jsx(Div, { style: { fontSize: "1.75rem", fontWeight: 700 }, children: counts.last24h })] }), _jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Last 7 days" }), _jsx(Div, { style: { fontSize: "1.75rem", fontWeight: 700 }, children: counts.last7d })] }), _jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Last 30 days" }), _jsx(Div, { style: { fontSize: "1.75rem", fontWeight: 700 }, children: counts.last30d })] }), _jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Server (Vercel)" }), _jsx(Div, { style: { fontSize: "1.5rem", fontWeight: 700 }, children: counts.bySource.vercel })] }), _jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Client" }), _jsx(Div, { style: { fontSize: "1.5rem", fontWeight: 700 }, children: counts.bySource.client })] }), _jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Cloud Functions" }), _jsx(Div, { style: { fontSize: "1.5rem", fontWeight: 700 }, children: counts.bySource.function })] })] }), _jsxs(Section, { style: { marginBottom: "1.5rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600 }, children: "Top codes (30d)" }), _jsx(Ul, { style: { listStyle: "none", padding: 0 }, children: counts.topCodes.length === 0 ? _jsx(Li, { style: { color: "var(--appkit-color-text-muted)" }, children: "No errors recorded." }) :
+    return (_jsxs(Div, { style: { padding: "1.5rem", maxWidth: "1200px", margin: "0 auto" }, children: [_jsx(Heading, { level: 1, style: { fontSize: "1.5rem", fontWeight: 600 }, children: "Maintenance" }), _jsx(Text, { as: "p", style: { color: "var(--appkit-color-text-muted)", marginBottom: "1.25rem" }, children: "Errors and failures across the platform \u2014 server, client, and Cloud Functions." }), _jsxs(Div, { style: { display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(170px, 1fr))", gap: "0.75rem", marginBottom: "1.5rem" }, children: [_jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Last 24 hours" }), _jsx(Div, { style: { fontSize: "1.75rem", fontWeight: 700 }, children: counts.last24h })] }), _jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Last 7 days" }), _jsx(Div, { style: { fontSize: "1.75rem", fontWeight: 700 }, children: counts.last7d })] }), _jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Last 30 days" }), _jsx(Div, { style: { fontSize: "1.75rem", fontWeight: 700 }, children: counts.last30d })] }), _jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Server (Vercel)" }), _jsx(Div, { style: { fontSize: "1.5rem", fontWeight: 700 }, children: counts.bySource.vercel })] }), _jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Client" }), _jsx(Div, { style: { fontSize: "1.5rem", fontWeight: 700 }, children: counts.bySource.client })] }), _jsxs(Div, { style: card, children: [_jsx(Div, { style: { fontSize: "0.78rem", color: "var(--appkit-color-text-muted)" }, children: "Cloud Functions" }), _jsx(Div, { style: { fontSize: "1.5rem", fontWeight: 700 }, children: counts.bySource.function })] })] }), _jsx(CacheInvalidationPanel, {}), _jsxs(Section, { style: { marginBottom: "1.5rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600 }, children: "Top codes (30d)" }), _jsx(Ul, { style: { listStyle: "none", padding: 0 }, children: counts.topCodes.length === 0 ? _jsx(Li, { style: { color: "var(--appkit-color-text-muted)" }, children: "No errors recorded." }) :
                             counts.topCodes.map((c) => (_jsxs(Li, { style: { display: "flex", justifyContent: "space-between", padding: "0.25rem 0", borderBottom: "1px solid var(--appkit-color-border-subtle)" }, children: [_jsx(Span, { style: { fontFamily: "monospace" }, children: c.code }), _jsx(Span, { children: c.count })] }, c.code))) })] }), _jsxs(Section, { style: { marginBottom: "1.5rem" }, children: [_jsx(Heading, { level: 2, style: { fontSize: "1rem", fontWeight: 600 }, children: "Top routes (30d)" }), _jsx(Ul, { style: { listStyle: "none", padding: 0 }, children: counts.topRoutes.length === 0 ? _jsx(Li, { style: { color: "var(--appkit-color-text-muted)" }, children: "No errors recorded." }) :
                             counts.topRoutes.map((r) => (_jsxs(Li, { style: { display: "flex", justifyContent: "space-between", padding: "0.25rem 0", borderBottom: "1px solid var(--appkit-color-border-subtle)" }, children: [_jsxs(Span, { style: { fontFamily: "monospace" }, children: ["[", r.source, "] ", r.route] }), _jsx(Span, { children: r.count })] }, `${r.source}:${r.route}`))) })] }), _jsxs(Nav, { "aria-label": "Maintenance sections", style: { display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(200px, 1fr))", gap: "0.5rem" }, children: [_jsxs(Anchor, { href: `${basePath}/server-errors`, tone: "default", underline: "none", style: { ...card }, children: [_jsx(Span, { weight: "bold", children: "Server errors" }), _jsx(Div, { style: { color: "var(--appkit-color-text-muted)", fontSize: "0.85rem" }, children: "Vercel function failures" })] }), _jsxs(Anchor, { href: `${basePath}/client-errors`, tone: "default", underline: "none", style: { ...card }, children: [_jsx(Span, { weight: "bold", children: "Client errors" }), _jsx(Div, { style: { color: "var(--appkit-color-text-muted)", fontSize: "0.85rem" }, children: "window.onerror + unhandledrejection + boundaries" })] }), _jsxs(Anchor, { href: `${basePath}/function-errors`, tone: "default", underline: "none", style: { ...card }, children: [_jsx(Span, { weight: "bold", children: "Function errors" }), _jsx(Div, { style: { color: "var(--appkit-color-text-muted)", fontSize: "0.85rem" }, children: "Cloud Functions handler exceptions" })] }), _jsxs(Anchor, { href: `${basePath}/cloud-logs`, tone: "default", underline: "none", style: { ...card }, children: [_jsx(Span, { weight: "bold", children: "Cloud Logging" }), _jsx(Div, { style: { color: "var(--appkit-color-text-muted)", fontSize: "0.85rem" }, children: "Live stream from Cloud Logging API" })] }), _jsxs(Anchor, { href: `${basePath}/payment-rollbacks`, tone: "default", underline: "none", style: { ...card }, children: [_jsx(Span, { weight: "bold", children: "Payment rollbacks" }), _jsx(Div, { style: { color: "var(--appkit-color-text-muted)", fontSize: "0.85rem" }, children: "PhonePe refund + upstream-unavailable rows" })] }), _jsxs(Anchor, { href: `${basePath}/analysis`, tone: "default", underline: "none", style: { ...card }, children: [_jsx(Span, { weight: "bold", children: "Analysis" }), _jsx(Div, { style: { color: "var(--appkit-color-text-muted)", fontSize: "0.85rem" }, children: "Run the maintenance analyzer + recommendations" })] })] })] }));
 }

package/dist/_internal/server/features/products/surface-counts.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Read `surfaceCounts/global` — one document, for the public settings payload
+ * and the server-side page guards.
+ *
+ * 🛑 FAILS OPEN, AND "OPEN" HERE MEANS `undefined`, NOT `{}`.
+ *
+ * Every failure path — missing document, unreadable document, malformed
+ * payload — returns `undefined`, which `isListingSurfaceVisible` reads as
+ * "unknown, show it". Returning an empty object instead would read as
+ * "measured, everything is empty" and would 404 every browse page on the site
+ * the first time Firestore hiccuped.
+ *
+ * This is the same failure posture as `guardBrowsePage`'s settings read ("a
+ * Firestore blip must not 404 the catalogue") and `getLiveCategoryCounts`
+ * ("a missing document is `undefined`, never 0").
+ *
+ * @tag domain:products
+ * @tag layer:server-feature
+ * @tag access:server-only
+ * @tag sideEffects:firestore-read
+ */
+export interface PublicSurfaceCounts {
+    listingTypes?: Record<string, number>;
+    surfaces?: Record<string, number>;
+}
+export declare function getSurfaceCounts(): Promise<PublicSurfaceCounts | undefined>;

package/dist/_internal/server/features/products/surface-counts.js

@@ -0,0 +1,60 @@
+/**
+ * Read `surfaceCounts/global` — one document, for the public settings payload
+ * and the server-side page guards.
+ *
+ * 🛑 FAILS OPEN, AND "OPEN" HERE MEANS `undefined`, NOT `{}`.
+ *
+ * Every failure path — missing document, unreadable document, malformed
+ * payload — returns `undefined`, which `isListingSurfaceVisible` reads as
+ * "unknown, show it". Returning an empty object instead would read as
+ * "measured, everything is empty" and would 404 every browse page on the site
+ * the first time Firestore hiccuped.
+ *
+ * This is the same failure posture as `guardBrowsePage`'s settings read ("a
+ * Firestore blip must not 404 the catalogue") and `getLiveCategoryCounts`
+ * ("a missing document is `undefined`, never 0").
+ *
+ * @tag domain:products
+ * @tag layer:server-feature
+ * @tag access:server-only
+ * @tag sideEffects:firestore-read
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { SURFACE_COUNTS_COLLECTION, SURFACE_COUNTS_DOC_ID, } from "../../../../features/products/schemas/surface-counts.js";
+/** Keep only numeric entries — a malformed value must not read as a zero. */
+function sanitize(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+        if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+            out[k] = v;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+export async function getSurfaceCounts() {
+    try {
+        const db = getAdminDb();
+        const snap = await db
+            .collection(SURFACE_COUNTS_COLLECTION)
+            .doc(SURFACE_COUNTS_DOC_ID)
+            .get();
+        if (!snap.exists)
+            return undefined;
+        const data = snap.data() ?? {};
+        const listingTypes = sanitize(data.listingTypes);
+        const surfaces = sanitize(data.surfaces);
+        // Both empty -> `undefined`, not `{}`. A document that exists but holds
+        // nothing usable is not a measurement.
+        if (!listingTypes && !surfaces)
+            return undefined;
+        return { listingTypes, surfaces };
+    }
+    catch (err) {
+        void normalizeError(err);
+        serverLogger.warn("surfaceCounts read failed — surfaces will all render visible");
+        return undefined;
+    }
+}

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

@@ -17,6 +17,8 @@ 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, 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";
 const PRODUCT_STATUS_PUBLISHED = "published";
@@ -648,12 +650,39 @@ export async function buildSitemap({ baseUrl }) {
         fallback: null,
     });
     const closed = new Set(ALL_BROWSE_PAGES.filter((p) => !isBrowsePageEnabled(p, settings)));
+    /*
+     * The same treatment for a listing-type surface that is switched off or
+     * measured as holding nothing — `/auctions`, `/art`, `/spares`, …
+     *
+     * 🛑 BROWSE ROUTES ONLY, matched on the exact path. Detail URLs are NOT
+     * dropped here and that is deliberate: art, stickers, spares and standard
+     * all detail at `/products/{slug}`, so a path test cannot tell them apart,
+     * and a prefix rule would silently delist the entire standard catalogue the
+     * day `spares` emptied. An empty type contributes no detail URLs anyway —
+     * its fetcher returns none — so the exact-path rule loses nothing real.
+     *
+     * 🛑 Fails OPEN twice: `settings` is already `safeRead`-wrapped above, and
+     * `getSurfaceCounts` returns `undefined` on any failure, which
+     * `isListingSurfaceVisible` reads as visible. An unmeasured surface stays in
+     * the sitemap rather than being withdrawn by a job that has not run.
+     */
+    const counts = await getSurfaceCounts();
+    /*
+     * 🛑 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.
+     */
+    const hiddenSurfacePaths = new Set(hiddenSurfaceRoutes(settings, counts));
     const keep = (entry) => {
-        if (closed.size === 0)
-            return true;
         const path = entry.url.startsWith("http")
             ? new URL(entry.url).pathname
             : entry.url;
+        if (hiddenSurfacePaths.has(path.replace(/\/+$/, "") || "/"))
+            return false;
+        if (closed.size === 0)
+            return true;
         const page = browsePageForPath(path);
         return page === null || !closed.has(page);
     };

package/dist/_internal/server/features/site-settings/adapters.d.ts

@@ -47,5 +47,21 @@ export interface ToPublicSiteSettingsOptions {
      * (`src/lib/watermark/resolve-effective-watermark.ts`), not in appkit.
      */
     effectiveWatermark?: MediaVideoWatermark;
+    /**
+     * The `surfaceCounts/global` document, when one exists.
+     *
+     * Injected rather than read here for the same reason as the watermark: this
+     * adapter is a pure projection over a document it is handed, and giving it
+     * a Firestore read of its own would make every caller pay for it.
+     *
+     * 🛑 Pass `undefined` when the document is missing OR the read failed. Those
+     * two must not be distinguished here and must never become `{}`: an absent
+     * key means "unknown, show it", and an empty object measured as all-zero
+     * would hide every browse surface on the site.
+     */
+    surfaceCounts?: {
+        listingTypes?: Record<string, number>;
+        surfaces?: Record<string, number>;
+    };
 }
 export declare function toPublicSiteSettings(doc: SiteSettingsDocument, opts?: ToPublicSiteSettingsOptions): PublicSiteSettings;

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,
@@ -186,6 +187,26 @@ export function toPublicSiteSettings(doc, opts) {
         // and leave the next person wondering whether the projection ran at all.
         disabledRoutes: doc.disabledRoutes ?? [],
         effectiveWatermark: opts?.effectiveWatermark,
+        /*
+         * 🛑 Passed through as-is, INCLUDING `undefined` — the exact opposite of
+         * the `disabledRoutes` line three above, and the contrast is deliberate.
+         *
+         * There, defaulting to `[]` is right because the proxy fails open and an
+         * absent list and an empty list already mean the same thing. Here they
+         * mean OPPOSITE things: absent is "never measured, show everything",
+         * `{}` is "measured, and every surface is empty". Defaulting this one
+         * 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/core/onProductWrite.js

@@ -8,7 +8,9 @@ import { storeRepository } from "../../../../features/stores/repository/store.re
 import { ProductStatusValues } from "../../../../features/products/schemas/firestore.js";
 import { PRODUCT_FIELDS } from "../../../../constants/field-names.js";
 import { isListingRowAvailable } from "../../../shared/listing-types/_registry.js";
+import { isListingType } from "../../../shared/listing-types/feature-flags.js";
 import { notifyRevalidate, productCacheFieldsChanged } from "./revalidateNotify.js";
+import { runSurfaceCountsRollup } from "./surfaceCountsRollup.js";
 const UNAVAILABLE_PRODUCT_STATUSES = new Set([
     ProductStatusValues.ARCHIVED,
 ]);
@@ -301,4 +303,35 @@ export async function handleProductWrite(input, ctx) {
         // reports how many rows it had to correct.
         ctx.logger.error("Counter update failed (non-fatal — countersReconcile will heal it tonight)", err, { productId });
     }
+    /*
+     * Refresh the site-wide "is this surface empty" counters.
+     *
+     * 🛑 Gated on `wasCounted !== isCounted`, reusing the availability-boundary
+     * signals computed just above rather than deriving a second opinion. Those
+     * two booleans already mean "did this row enter or leave the set a public
+     * browse page would show", which is exactly and only when a surface can
+     * cross zero. A stock decrement from 9 to 8 recomputes nothing.
+     *
+     * 🛑 Scoped to the AFFECTED types, never all ten. A product can change
+     * `listingType`, which empties the old surface and fills the new one, so
+     * both are probed — and `only` makes `runSurfaceCountsRollup` merge rather
+     * than replace, so the eight types this write cannot have touched keep
+     * their measured values instead of being dropped to unknown.
+     *
+     * Non-fatal, same contract as the counters above: the nightly rollup is the
+     * healer, and an unwritten counter degrades to "unknown", which every
+     * reader shows rather than hides.
+     */
+    if (wasCounted !== isCounted) {
+        const touched = Array.from(new Set([before?.listingType, after?.listingType].filter((t) => typeof t === "string" && isListingType(t))));
+        if (touched.length > 0) {
+            try {
+                await runSurfaceCountsRollup(ctx, touched);
+            }
+            catch (err) {
+                void normalizeError(err);
+                ctx.logger.error("Surface-count refresh failed (non-fatal — the nightly rollup will heal it)", err, { productId, touched });
+            }
+        }
+    }
 }

package/dist/_internal/server/jobs/core/surfaceCountsRollup.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 type { ListingType } from "../../../../features/products/types/index";
+import type { JobContext } from "../runtime/types";
+export interface SurfaceCountsResult {
+    listingTypes: Partial<Record<ListingType, number>>;
+    surfaces: Partial<Record<string, number>>;
+    /** Types whose probe failed — recorded so a silent partial is visible. */
+    failed: string[];
+}
+export declare function computeSurfaceCounts(ctx: Pick<JobContext, "db">, only?: readonly ListingType[]): Promise<SurfaceCountsResult>;
+/**
+ * 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 declare function runSurfaceCountsRollup(ctx: Pick<JobContext, "db">, only?: readonly ListingType[]): Promise<SurfaceCountsResult>;