@mohasinac/appkit 4.66.0 → 4.67.0

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

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

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

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

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

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

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

@@ -117,4 +117,21 @@ export interface PublicSiteSettings {
     disabledRoutes: string[];
     /** Derived, not a stored field — the resolved marker → wordmark → text chain. */
     effectiveWatermark?: MediaVideoWatermark;
+    /**
+     * Which public browse surfaces currently have something in them. Derived
+     * from the `surfaceCounts/global` document, not a `siteSettings` field —
+     * carried here because this payload is already the channel the navbar,
+     * footer and sidebar read their visibility rules from, so adding a second
+     * client fetch for one more rule would be a request per page load.
+     *
+     * 🛑 OMITTED ENTIRELY when the counts document has not been written yet,
+     * and every reader must treat that as "show everything". A present-but-empty
+     * object would be indistinguishable from "measured, and all zero" — which is
+     * the shape that hides the whole catalogue. `isListingSurfaceVisible`
+     * encodes the rule; do not re-derive it at a call site.
+     */
+    surfaceCounts?: {
+        listingTypes?: Record<string, number>;
+        surfaces?: Record<string, number>;
+    };
 }

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

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

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

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

package/dist/client.d.ts

@@ -422,6 +422,8 @@ export { useListingTypeFlags } from "./react/hooks/useListingTypeFlags";
 export type { ListingTypeFlags, ListingTypeFlagsShape, } from "./react/hooks/useListingTypeFlags";
 export { useBrowsePageFlags } from "./react/hooks/useBrowsePageFlags";
 export type { BrowsePageFlags, BrowsePageFlagsShape, } from "./react/hooks/useBrowsePageFlags";
+export { useListingSurfaceVisibility } from "./react/hooks/useListingSurfaceVisibility";
+export type { ListingSurfaceVisibility } from "./react/hooks/useListingSurfaceVisibility";
 export { useActionDispatch } from "./react/hooks/use-action-dispatch";
 export type { DispatchAction, UseActionDispatchOptions } from "./react/hooks/use-action-dispatch";
 export { usePanelStore } from "./stores/panel-store";
@@ -535,8 +537,8 @@ export type { TrackArgs as TrackHistoryArgs } from "./features/history/hooks/use
 export { WISHLIST_MAX, HISTORY_MAX, CART_MAX_ITEMS, } from "./constants/limits";
 export { normalizeListingType, isAuctionListing, isPreOrderListing, isStandardListing, isPrizeDrawListing, isClassifiedListing, isDigitalCodeListing, isLiveListing, isArtListing, isStickersListing, } from "./features/products/utils/listing-type";
 export { isFinalSale, acceptsChangeOfMindReturns, } from "./features/products/constants/final-sale";
-export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, isListingType, isBrowsePageEnabled, enabledBrowsePages, ALL_BROWSE_PAGES, isBrowsePageKey, } from "./_internal/shared/listing-types/feature-flags";
-export type { BrowsePageKey } from "./_internal/shared/listing-types/feature-flags";
+export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, isListingType, isBrowsePageEnabled, enabledBrowsePages, ALL_BROWSE_PAGES, isBrowsePageKey, isListingSurfaceVisible, isCountedSurfaceVisible, visibleListingTypes, } from "./_internal/shared/listing-types/feature-flags";
+export type { BrowsePageKey, SurfaceCountSnapshot, } from "./_internal/shared/listing-types/feature-flags";
 export { ADVANCED_LISTING_TYPE_CAPABILITY, ADVANCED_LISTING_TYPES, BASIC_LISTING_TYPES, LISTING_TYPE_TIER, hasAdvancedListingTypes, isAdvancedListingType, isListingTypeAllowedFor, listingTypesAllowedFor, } from "./_internal/shared/listing-types/tiers";
 export type { ListingTypeAccessContext, ListingTypeTier, } from "./_internal/shared/listing-types/tiers";
 export { actionTracker, setActionTrackerSink, resetActionTrackerSink, type ActionEvent, type ActionTrackerSink, } from "./_internal/shared/listing-types/action-tracker";

package/dist/client.js

@@ -448,6 +448,11 @@ export { useListingTypeFlags } from "./react/hooks/useListingTypeFlags.js";
 // [CLIENT-ONLY] useBrowsePageFlags: read listings.browsePages from
 // siteSettings; drop nav/sidebar/footer links into a closed browse section.
 export { useBrowsePageFlags } from "./react/hooks/useBrowsePageFlags.js";
+// [CLIENT-ONLY] useListingSurfaceVisibility: the admin flag MINUS the surfaces
+// measured as empty. For BROWSING links only — authoring surfaces (the seller
+// type dropdown) must keep using useListingTypeFlags, or the first listing of
+// an emptied type becomes impossible to create.
+export { useListingSurfaceVisibility } from "./react/hooks/useListingSurfaceVisibility.js";
 // Action dispatch hook + panel store
 export { useActionDispatch } from "./react/hooks/use-action-dispatch.js";
 export { usePanelStore } from "./stores/panel-store.js";
@@ -542,7 +547,11 @@ export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabl
 // Browse-section gates. Client-safe and genuinely needed here: the nav,
 // sidebar, mobile sheet and footer all filter on them, and a link into a
 // closed section is a 404 on every page of the site.
-isBrowsePageEnabled, enabledBrowsePages, ALL_BROWSE_PAGES, isBrowsePageKey, } from "./_internal/shared/listing-types/feature-flags.js";
+isBrowsePageEnabled, enabledBrowsePages, ALL_BROWSE_PAGES, isBrowsePageKey, 
+// Auto-hide: a surface measured as having nothing in it. Client-safe and
+// needed here for the same reason as the browse-section gates above — the
+// nav, sidebar, mobile sheet and footer all filter on them.
+isListingSurfaceVisible, isCountedSurfaceVisible, visibleListingTypes, } from "./_internal/shared/listing-types/feature-flags.js";
 // Basic/advanced listing-type split. Client-safe: the nav filter and any
 // seller-facing picker need the same rule the server enforces, and deriving it
 // twice is how the ten hand-written copies of the union happened.

package/dist/constants/api-endpoints.d.ts

@@ -264,6 +264,7 @@ export declare const ADMIN_ENDPOINTS: {
     readonly CHECKOUT_BYPASS: "/api/admin/checkout-bypass";
     readonly MAINTENANCE_ANALYSIS: "/api/admin/maintenance/analysis";
     readonly MAINTENANCE_CLOUD_LOGS: "/api/admin/maintenance/cloud-logs";
+    readonly CACHE_REVALIDATE: "/api/admin/cache/revalidate";
     readonly MEDIA_LIST: "/api/admin/media";
 };
 export declare const AUCTION_ENDPOINTS: {
@@ -898,6 +899,7 @@ export declare const API_ENDPOINTS: {
         readonly CHECKOUT_BYPASS: "/api/admin/checkout-bypass";
         readonly MAINTENANCE_ANALYSIS: "/api/admin/maintenance/analysis";
         readonly MAINTENANCE_CLOUD_LOGS: "/api/admin/maintenance/cloud-logs";
+        readonly CACHE_REVALIDATE: "/api/admin/cache/revalidate";
         readonly MEDIA_LIST: "/api/admin/media";
     };
     readonly AUCTIONS: {
@@ -1497,6 +1499,7 @@ export declare const API_ROUTES: {
         readonly CHECKOUT_BYPASS: "/api/admin/checkout-bypass";
         readonly MAINTENANCE_ANALYSIS: "/api/admin/maintenance/analysis";
         readonly MAINTENANCE_CLOUD_LOGS: "/api/admin/maintenance/cloud-logs";
+        readonly CACHE_REVALIDATE: "/api/admin/cache/revalidate";
         readonly MEDIA_LIST: "/api/admin/media";
     };
     readonly AUCTIONS: {

package/dist/constants/api-endpoints.js

@@ -313,6 +313,17 @@ export const ADMIN_ENDPOINTS = {
     CHECKOUT_BYPASS: "/api/admin/checkout-bypass",
     MAINTENANCE_ANALYSIS: "/api/admin/maintenance/analysis",
     MAINTENANCE_CLOUD_LOGS: "/api/admin/maintenance/cloud-logs",
+    /*
+     * Admin-session-gated cache invalidation.
+     *
+     * 🛑 Deliberately NOT `/api/cache/revalidate`, which authenticates on an
+     * `x-api-key` matching `CACHE_REVALIDATION_SECRET`. That secret belongs to
+     * the Firestore triggers and the seed CLI; shipping it to a browser so a
+     * button could call that endpoint would put a server secret in client code.
+     * This one carries no secret and is gated on the admin session like every
+     * other `/api/admin/*` route.
+     */
+    CACHE_REVALIDATE: "/api/admin/cache/revalidate",
     MEDIA_LIST: "/api/admin/media",
 };
 // ---------------------------------------------------------------------------

package/dist/features/products/schemas/surface-counts.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Site-wide "does this browse surface have anything in it" counters.
+ *
+ * ## Why a sibling singleton and not a field on `siteSettings`
+ *
+ * `siteSettings` is admin-authored CONFIG and is in the tester's PRESERVE tier.
+ * This is DERIVED measurement, rewritten by a job. Mixing the two means a
+ * reconciler writing into the document that holds live API credentials, and it
+ * means a reseed or a settings restore silently reverting a count. Same split
+ * `categoryCounts` already makes against `categories`, and for the same
+ * Root Cause #92 reason: nothing triggers on this collection, so writing it
+ * can never re-enter the trigger that produced it.
+ *
+ * ## 🛑 ABSENT MEANS UNKNOWN, NEVER ZERO
+ *
+ * This is the single rule the whole file exists to enforce, and getting it
+ * backwards hides the entire catalogue.
+ *
+ * A key missing from either map means "not measured yet" — a fresh install, a
+ * failed job, a type added since the last run. Every reader must treat that as
+ * **visible**, exactly as `getLiveCategoryCounts` returns `undefined` rather
+ * than 0 so its callers fall back to `metrics`. Root Cause #72 is this
+ * project's record of the opposite choice: a "hide it when it's empty" rule
+ * whose count map did not cover an option, so "unknown" read as "zero" and the
+ * section vanished.
+ *
+ * `Partial` is therefore load-bearing typing, not convenience — an explicit
+ * zero and an absent key MUST stay distinguishable.
+ *
+ * ## 🛑 These are AVAILABLE rows, which is a time-dependent question
+ *
+ * The counts come from `listPublicProducts`, the one function every public
+ * browse page already queries through — so a surface can never be hidden while
+ * its own page would have rendered rows, which is the correctness property
+ * that matters here and the reason this is not a bespoke `count()` query.
+ *
+ * It inherits that function's time-dependence: an auction becomes unavailable
+ * by the clock with no product write, so a type whose last row just ended stays
+ * "non-empty" until the next recompute. Erring toward VISIBLE is the right
+ * direction for this feature — showing an empty list is a cosmetic problem,
+ * hiding a live one is a lost sale.
+ *
+ * @tag domain:products
+ * @tag layer:schema
+ * @tag access:isomorphic
+ */
+import type { ListingType } from "../types/index";
+export declare const SURFACE_COUNTS_COLLECTION = "surfaceCounts";
+/** Singleton — these are site-wide totals, so there is exactly one row. */
+export declare const SURFACE_COUNTS_DOC_ID = "global";
+/**
+ * Public browse surfaces that are NOT a listing type and so have no
+ * `listings.listingTypes` flag to hang off.
+ *
+ * Deliberately just `reviews` today. A key here must have a real consumer —
+ * `/stores` and `/categories` already have their own `browsePages` flag and
+ * adding them here would be a second mechanism deciding one thing.
+ */
+export type CountedSurfaceKey = "reviews";
+export interface SurfaceCountsDocument {
+    id: string;
+    /**
+     * Available listings per type. Absent key = UNKNOWN = show.
+     *
+     * A map rather than scalar fields: the listing-type union has grown twice
+     * (nine → ten with `spares`), and a map needs no schema change for the next.
+     */
+    listingTypes: Partial<Record<ListingType, number>>;
+    /** Non-listing-type surfaces. Absent key = UNKNOWN = show. */
+    surfaces: Partial<Record<CountedSurfaceKey, number>>;
+    /**
+     * When the figures were taken. Read by the admin panel so an operator can
+     * tell "measured as empty an hour ago" from "never measured".
+     */
+    updatedAt: Date;
+}
+/**
+ * Is this surface known to be empty?
+ *
+ * Returns `false` for an unmeasured surface — the caller must not be able to
+ * express "hide it" without a measurement that says so.
+ */
+export declare function isKnownEmpty(count: number | undefined): boolean;

package/dist/features/products/schemas/surface-counts.js

@@ -0,0 +1,58 @@
+/**
+ * Site-wide "does this browse surface have anything in it" counters.
+ *
+ * ## Why a sibling singleton and not a field on `siteSettings`
+ *
+ * `siteSettings` is admin-authored CONFIG and is in the tester's PRESERVE tier.
+ * This is DERIVED measurement, rewritten by a job. Mixing the two means a
+ * reconciler writing into the document that holds live API credentials, and it
+ * means a reseed or a settings restore silently reverting a count. Same split
+ * `categoryCounts` already makes against `categories`, and for the same
+ * Root Cause #92 reason: nothing triggers on this collection, so writing it
+ * can never re-enter the trigger that produced it.
+ *
+ * ## 🛑 ABSENT MEANS UNKNOWN, NEVER ZERO
+ *
+ * This is the single rule the whole file exists to enforce, and getting it
+ * backwards hides the entire catalogue.
+ *
+ * A key missing from either map means "not measured yet" — a fresh install, a
+ * failed job, a type added since the last run. Every reader must treat that as
+ * **visible**, exactly as `getLiveCategoryCounts` returns `undefined` rather
+ * than 0 so its callers fall back to `metrics`. Root Cause #72 is this
+ * project's record of the opposite choice: a "hide it when it's empty" rule
+ * whose count map did not cover an option, so "unknown" read as "zero" and the
+ * section vanished.
+ *
+ * `Partial` is therefore load-bearing typing, not convenience — an explicit
+ * zero and an absent key MUST stay distinguishable.
+ *
+ * ## 🛑 These are AVAILABLE rows, which is a time-dependent question
+ *
+ * The counts come from `listPublicProducts`, the one function every public
+ * browse page already queries through — so a surface can never be hidden while
+ * its own page would have rendered rows, which is the correctness property
+ * that matters here and the reason this is not a bespoke `count()` query.
+ *
+ * It inherits that function's time-dependence: an auction becomes unavailable
+ * by the clock with no product write, so a type whose last row just ended stays
+ * "non-empty" until the next recompute. Erring toward VISIBLE is the right
+ * direction for this feature — showing an empty list is a cosmetic problem,
+ * hiding a live one is a lost sale.
+ *
+ * @tag domain:products
+ * @tag layer:schema
+ * @tag access:isomorphic
+ */
+export const SURFACE_COUNTS_COLLECTION = "surfaceCounts";
+/** Singleton — these are site-wide totals, so there is exactly one row. */
+export const SURFACE_COUNTS_DOC_ID = "global";
+/**
+ * Is this surface known to be empty?
+ *
+ * Returns `false` for an unmeasured surface — the caller must not be able to
+ * express "hide it" without a measurement that says so.
+ */
+export function isKnownEmpty(count) {
+    return count === 0;
+}

package/dist/index.d.ts

@@ -2190,8 +2190,8 @@ export { getProductSortOptions } from "./features/products/components/ProductFil
 export { getProductTableColumns } from "./features/products/columns/productTableColumns";
 export { normalizeListingType, isAuctionListing, isPreOrderListing, isStandardListing, isPrizeDrawListing, isClassifiedListing, isDigitalCodeListing, isLiveListing, isArtListing, isStickersListing, } from "./features/products/index";
 export { isFinalSale, acceptsChangeOfMindReturns, } from "./features/products/constants/final-sale";
-export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, isListingType, isBrowsePageEnabled, enabledBrowsePages, ALL_BROWSE_PAGES, isBrowsePageKey, } from "./_internal/shared/listing-types/feature-flags";
-export type { BrowsePageKey } from "./_internal/shared/listing-types/feature-flags";
+export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, isListingType, isBrowsePageEnabled, enabledBrowsePages, ALL_BROWSE_PAGES, isBrowsePageKey, isListingSurfaceVisible, isCountedSurfaceVisible, visibleListingTypes, } from "./_internal/shared/listing-types/feature-flags";
+export type { BrowsePageKey, SurfaceCountSnapshot, } from "./_internal/shared/listing-types/feature-flags";
 export { ADVANCED_LISTING_TYPE_CAPABILITY, ADVANCED_LISTING_TYPES, BASIC_LISTING_TYPES, LISTING_TYPE_TIER, assertListingTypeAllowed, hasAdvancedListingTypes, isAdvancedListingType, isListingTypeAllowedFor, listingTypesAllowedFor, } from "./_internal/shared/listing-types/tiers";
 export type { ListingTypeAccessContext, ListingTypeTier, } from "./_internal/shared/listing-types/tiers";
 export { actionTracker, setActionTrackerSink, resetActionTrackerSink, type ActionEvent, type ActionTrackerSink, } from "./_internal/shared/listing-types/action-tracker";

package/dist/index.js

@@ -4083,7 +4083,9 @@ export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabl
 // file's ALL_LISTING_TYPES note: `server-entry.ts` re-exports index, so a
 // Server Component already reaches these from the bare specifier and a
 // second path would leak an `_internal/` symbol through a third barrel.
-isBrowsePageEnabled, enabledBrowsePages, ALL_BROWSE_PAGES, isBrowsePageKey, } from "./_internal/shared/listing-types/feature-flags.js";
+isBrowsePageEnabled, enabledBrowsePages, ALL_BROWSE_PAGES, isBrowsePageKey, 
+// Auto-hide gates — same barrel choice as the browse-section ones above.
+isListingSurfaceVisible, isCountedSurfaceVisible, visibleListingTypes, } from "./_internal/shared/listing-types/feature-flags.js";
 // Basic/advanced listing-type split — which types a store may create.
 // Pure (no firebase-admin in its import chain), so it is safe in index.ts.
 export { ADVANCED_LISTING_TYPE_CAPABILITY, ADVANCED_LISTING_TYPES, BASIC_LISTING_TYPES, LISTING_TYPE_TIER, assertListingTypeAllowed, hasAdvancedListingTypes, isAdvancedListingType, isListingTypeAllowedFor, listingTypesAllowedFor, } from "./_internal/shared/listing-types/tiers.js";