@mohasinac/appkit 4.42.17 → 4.43.0

package/dist/_internal/client/features/lottery/LotteryDetailView.js

@@ -3,6 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
 import { Stack, Row, Text, Heading, Badge, Section, Container, Div, Anchor, } from "../../../../ui";
 import { MediaImage } from "../../../../features/media/MediaImage";
+import { useOptionalSession } from "../../../../react/contexts/SessionContext";
 import { ROUTES } from "../../../../next/routing/route-map";
 import { LotterySlotGrid } from "./LotterySlotGrid";
 import { LotteryPullForm } from "./LotteryPullForm";
@@ -13,10 +14,30 @@ import { slotsToCollageItems } from "./slot-collage-items";
  * Shows cover + description + slot grid + pull form (if active + logged in).
  */
 export function LotteryDetailView({ event, user, currentEntry }) {
+    /*
+     * 🛑 Viewer identity is read on the CLIENT, not taken from the `user` prop.
+     *
+     * The page used to `await getServerSessionUser()` to supply that prop, which
+     * cost twice over: `cookies()` forced dynamic rendering, so the route's
+     * `revalidate = 30` was silently inert (Root Cause #94) and every visit paid a
+     * full render; and the HTML then varied per viewer, so it could never be
+     * cached or shared even once the TTL was fixed.
+     *
+     * `useOptionalSession` — not `useSession` — because library code that adjusts
+     * for the viewer must not require a provider to be mounted (Root Cause #20);
+     * absent, it fails CLOSED to the signed-out branch.
+     *
+     * The `user` prop is kept as an optional SEED so a caller that genuinely has
+     * the viewer (an authenticated dashboard mount) still renders correctly on
+     * first paint.
+     */
+    const session = useOptionalSession();
+    const isAuthResolving = session?.loading ?? false;
+    const viewer = session?.user ?? user ?? null;
     const [pulledEntry, setPulledEntry] = useState(currentEntry?.assignedPrizeSlotNumber != null ? currentEntry : null);
     const config = event.lotteryConfig;
     const prizeItems = slotsToCollageItems(config?.slots ?? []);
     const isActive = event.status === "active";
     const isEnded = event.status === "ended" || event.status === "cancelled";
-    return (_jsx(Container, { children: _jsx(Section, { children: _jsxs(Stack, { gap: "xl", children: [event.coverImageUrl || event.coverImage?.url ? (_jsx(Div, { rounded: "2xl", className: "relative overflow-hidden", style: { aspectRatio: "16/9", maxHeight: "16rem" }, children: _jsx(MediaImage, { src: event.coverImageUrl || event.coverImage?.url || "", alt: event.title, size: "hero" }) })) : (_jsx(Div, { rounded: "2xl", surface: "subtle", padding: "xl", align: "center", justify: "center", children: _jsx(Text, { size: "5xl", children: "\uD83C\uDFB0" }) })), _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { gap: "xs", align: "center", wrap: true, children: [_jsx(Badge, { variant: isActive ? "success" : isEnded ? "danger" : "warning", children: event.status }), config && (_jsxs(Badge, { variant: "info", children: [config.slots.filter((s) => s.isBooked).length, "/", config.totalSlots, " slots claimed"] }))] }), _jsx(Heading, { level: 1, size: "3xl", weight: "bold", children: event.title }), event.description ? (_jsx(Text, { color: "muted", size: "sm", children: event.description.replace(/<[^>]+>/g, "").slice(0, 200) })) : null, event.endsAt ? (_jsxs(Text, { size: "sm", color: "muted", children: ["Ends: ", new Date(event.endsAt).toLocaleDateString("en-IN", { dateStyle: "long" })] })) : null] }), prizeItems.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Prizes" }), _jsx(PrizeDrawCollage, { items: prizeItems, wonLabel: "Claimed" })] })) : null, config && config.slots.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Slots" }), _jsx(LotterySlotGrid, { slots: config.slots, totalSlots: config.totalSlots })] })) : null, isActive && config && (_jsx(Div, { padding: "md", rounded: "2xl", surface: "card", className: "border border-[var(--appkit-color-border)]", children: !user ? (_jsxs(Stack, { gap: "md", className: "text-center", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Want to Participate?" }), _jsx(Text, { color: "muted", children: "Log in to submit your lottery entry." }), _jsx(Anchor, { href: String(ROUTES.AUTH.LOGIN), tone: "brand", children: "Log In to Enter" })] })) : pulledEntry ? (_jsxs(Stack, { gap: "sm", surface: "success-surface", padding: "md", rounded: "xl", className: "border border-success/20", children: [_jsxs(Heading, { level: 2, size: "lg", weight: "bold", className: "text-success", children: ["You're Lottery #", pulledEntry.userLotteryNumber, "!"] }), _jsxs(Text, { className: "text-success", size: "sm", children: ["Assigned to Slot #", pulledEntry.assignedPrizeSlotNumber, pulledEntry.slotName ? ` — ${pulledEntry.slotName}` : "", "."] })] })) : (_jsx(LotteryPullForm, { sourceType: "event", eventId: event.id, totalSlots: config.totalSlots, maxPullsPerUser: config.maxPullsPerUser, onSuccess: (res) => setPulledEntry(res) })) })), isEnded && !pulledEntry && (_jsx(Stack, { gap: "sm", surface: "muted", padding: "md", rounded: "xl", children: _jsx(Text, { color: "muted", weight: "semibold", children: "This lottery has ended." }) }))] }) }) }));
+    return (_jsx(Container, { children: _jsx(Section, { children: _jsxs(Stack, { gap: "xl", children: [event.coverImageUrl || event.coverImage?.url ? (_jsx(Div, { rounded: "2xl", className: "relative overflow-hidden", style: { aspectRatio: "16/9", maxHeight: "16rem" }, children: _jsx(MediaImage, { src: event.coverImageUrl || event.coverImage?.url || "", alt: event.title, size: "hero" }) })) : (_jsx(Div, { rounded: "2xl", surface: "subtle", padding: "xl", align: "center", justify: "center", children: _jsx(Text, { size: "5xl", children: "\uD83C\uDFB0" }) })), _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { gap: "xs", align: "center", wrap: true, children: [_jsx(Badge, { variant: isActive ? "success" : isEnded ? "danger" : "warning", children: event.status }), config && (_jsxs(Badge, { variant: "info", children: [config.slots.filter((s) => s.isBooked).length, "/", config.totalSlots, " slots claimed"] }))] }), _jsx(Heading, { level: 1, size: "3xl", weight: "bold", children: event.title }), event.description ? (_jsx(Text, { color: "muted", size: "sm", children: event.description.replace(/<[^>]+>/g, "").slice(0, 200) })) : null, event.endsAt ? (_jsxs(Text, { size: "sm", color: "muted", children: ["Ends: ", new Date(event.endsAt).toLocaleDateString("en-IN", { dateStyle: "long" })] })) : null] }), prizeItems.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Prizes" }), _jsx(PrizeDrawCollage, { items: prizeItems, wonLabel: "Claimed" })] })) : null, config && config.slots.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Slots" }), _jsx(LotterySlotGrid, { slots: config.slots, totalSlots: config.totalSlots })] })) : null, isActive && config && (_jsx(Div, { padding: "md", rounded: "2xl", surface: "card", className: "border border-[var(--appkit-color-border)]", children: isAuthResolving ? (_jsx(Stack, { gap: "md", className: "text-center", children: _jsx(Text, { color: "muted", children: "Checking your session\u2026" }) })) : !viewer ? (_jsxs(Stack, { gap: "md", className: "text-center", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Want to Participate?" }), _jsx(Text, { color: "muted", children: "Log in to submit your lottery entry." }), _jsx(Anchor, { href: String(ROUTES.AUTH.LOGIN), tone: "brand", children: "Log In to Enter" })] })) : pulledEntry ? (_jsxs(Stack, { gap: "sm", surface: "success-surface", padding: "md", rounded: "xl", className: "border border-success/20", children: [_jsxs(Heading, { level: 2, size: "lg", weight: "bold", className: "text-success", children: ["You're Lottery #", pulledEntry.userLotteryNumber, "!"] }), _jsxs(Text, { className: "text-success", size: "sm", children: ["Assigned to Slot #", pulledEntry.assignedPrizeSlotNumber, pulledEntry.slotName ? ` — ${pulledEntry.slotName}` : "", "."] })] })) : (_jsx(LotteryPullForm, { sourceType: "event", eventId: event.id, totalSlots: config.totalSlots, maxPullsPerUser: config.maxPullsPerUser, onSuccess: (res) => setPulledEntry(res) })) })), isEnded && !pulledEntry && (_jsx(Stack, { gap: "sm", surface: "muted", padding: "md", rounded: "xl", children: _jsx(Text, { color: "muted", weight: "semibold", children: "This lottery has ended." }) }))] }) }) }));
 }

package/dist/_internal/server/features/products/list-public.d.ts

@@ -90,6 +90,30 @@ export interface PublicProductListInput {
     pageSize?: number;
     sorts?: string;
     cursor?: string | null;
+    /**
+     * How many documents the BOUNDED-WINDOW path may fetch. Defaults to
+     * `PUBLIC_PRODUCT_MAX_PAGE_SIZE` (50) — today's behaviour for every caller
+     * that omits it.
+     *
+     * 🛑 Only meaningful when the query lands on the in-memory path, which is
+     * almost always: `hidesTestData` is true for EVERY anonymous viewer, so
+     * `inMemory` is true for essentially all public browsing. On that path the
+     * fetch is pinned to `page: 1, pageSize: 50` regardless of the caller's
+     * `pageSize`, because the filter is a per-row predicate applied after the
+     * fetch and before the slice.
+     *
+     * That is correct for a browse page, which must be able to page deeply. It is
+     * wasteful for a FIXED-SIZE homepage strip: `getFeaturedProducts(12)` read 51
+     * documents to render 12, and the homepage did that four times — ~200 reads
+     * for 44 cards, on a 50K-reads/day free tier (measured 2.1M/week).
+     *
+     * Set it only where the caller genuinely wants N items and will never page:
+     * a larger value than `pageSize` is still needed as headroom, because rows are
+     * dropped by the predicate after the fetch. Too small a window silently yields
+     * fewer items than asked for — which is why this is opt-in rather than derived
+     * from `pageSize`, and why `truncated` still reports honestly below.
+     */
+    windowSize?: number;
 }
 export interface PublicProductListResult {
     items: Row[];

package/dist/_internal/server/features/products/list-public.js

@@ -607,11 +607,14 @@ export async function listPublicProducts(input, opts) {
         : hasTypeFacet
             ? FACET_FETCH_SORT
             : sorts;
+    // Clamped to the 50-doc ceiling so an opt-in can only ever make the window
+    // SMALLER — a caller cannot widen the public read budget through this door.
+    const windowSize = Math.min(Math.max(1, input.windowSize ?? PUBLIC_PRODUCT_MAX_PAGE_SIZE), PUBLIC_PRODUCT_MAX_PAGE_SIZE);
     const result = await runQuery(executor, {
         filters,
         sorts: fetchSorts,
         page: inMemory ? 1 : page,
-        pageSize: inMemory ? PUBLIC_PRODUCT_MAX_PAGE_SIZE : pageSize,
+        pageSize: inMemory ? windowSize : pageSize,
         cursor: inMemory ? null : (input.cursor ?? null),
         search: input.q,
     });
@@ -625,7 +628,12 @@ export async function listPublicProducts(input, opts) {
     let cursor = result.cursor ?? null;
     let truncated = false;
     if (inMemory) {
-        truncated = items.length >= PUBLIC_PRODUCT_MAX_PAGE_SIZE;
+        // Against `windowSize`, NOT the 50 ceiling. A caller that opted into a
+        // smaller window saturates it at that size, so comparing with 50 would
+        // report `truncated: false` for a window that was in fact full — and
+        // `truncated` is what makes `total` render as "50+" and keeps the pager
+        // offering Next instead of claiming a false last page.
+        truncated = items.length >= windowSize;
         /** OR semantics, matching the single-value `array-contains` pushdown. */
         const matchesAny = (raw, wanted) => {
             if (!Array.isArray(raw))

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

@@ -1,3 +1,4 @@
+import { notifyRevalidate } from "./revalidateNotify";
 import { normalizeError } from "../../../../errors/normalize";
 /**
  * Core: maintain DFS `position` + `subtreeSize` on every category write.
@@ -87,6 +88,10 @@ async function getMaxPosition(ctx, excludeId) {
 }
 export async function handleCategoryWrite(input, ctx) {
     const { categoryId, before, after } = input;
+    // Drop the ISR entries for this category/brand/bundle page and the listings
+    // that link it. Folded into the existing trigger rather than given its own —
+    // see the note in onProductWrite. No Firestore write here (Root Cause #92).
+    await notifyRevalidate({ collection: "categories", id: categoryId }, ctx);
     const isCreate = !before && !!after;
     const isDelete = !!before && !after;
     const isUpdate = !!before && !!after;

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

@@ -7,6 +7,7 @@ import { categoriesRepository, storeRepository, } from "../../../../repositories
 import { ProductStatusValues } from "../../../../features/products/schemas/firestore";
 import { PRODUCT_FIELDS } from "../../../../constants/field-names";
 import { isListingRowAvailable } from "../../../shared/listing-types/_registry";
+import { notifyRevalidate, productCacheFieldsChanged } from "./revalidateNotify";
 const UNAVAILABLE_PRODUCT_STATUSES = new Set([
     ProductStatusValues.ARCHIVED,
 ]);
@@ -158,6 +159,36 @@ async function dispatchProductWriteEvent(p) {
 }
 export async function handleProductWrite(input, ctx) {
     const { productId, before, after } = input;
+    /*
+     * Drop the ISR entries for every page that renders this product.
+     *
+     * Deliberately folded into THIS handler rather than given a trigger of its
+     * own. `products/{productId}` already carries two `documentWritten` triggers;
+     * a third would add a whole function's worth of invocations for one `fetch`,
+     * and Root Cause #92's collateral is the standing warning about what happens
+     * when several functions share one hot path.
+     *
+     * Gated on a real content change so a stock decrement invalidates and an
+     * `updatedAt` bump does not. Awaited — not fire-and-forget — because a Cloud
+     * Function may be frozen the moment its promise settles, and a detached fetch
+     * would be cancelled mid-flight often enough to make invalidation unreliable
+     * without ever reporting a failure.
+     */
+    if (productCacheFieldsChanged(before, after)) {
+        const doc = after ?? before;
+        await notifyRevalidate({
+            collection: "products",
+            id: productId,
+            hints: {
+                listingType: doc?.listingType,
+                categorySlugs: Array.isArray(doc?.categorySlugs)
+                    ? doc.categorySlugs
+                    : undefined,
+                brandSlug: doc?.brandSlug,
+                storeId: doc?.storeId,
+            },
+        }, ctx);
+    }
     const beforeStatus = before?.status ?? null;
     const afterStatus = after?.status ?? null;
     // `category` is @deprecated in favor of `categorySlugs[]` — the repository's

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

@@ -1,8 +1,16 @@
+import { notifyRevalidate } from "./revalidateNotify";
 import { reviewRepository, storeRepository } from "../../../../repositories";
 import { ReviewStatusValues } from "../../../../features/reviews/schemas/firestore";
 import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore";
 export async function handleReviewWrite(input, ctx) {
     const { reviewId, before: beforeData, after: afterData } = input;
+    /*
+     * A review changes the product's rating badge AND the homepage's
+     * `platform_rating` / `total_reviews` stats, so the targets are the listing
+     * pages rather than a per-review page (there isn't one). Uses the review's own
+     * id purely for log correlation. No Firestore write here (Root Cause #92).
+     */
+    await notifyRevalidate({ collection: "reviews", id: reviewId }, ctx);
     const beforeStatus = beforeData?.status ?? null;
     const afterStatus = afterData?.status ?? null;
     const wasApproved = beforeStatus === ReviewStatusValues.APPROVED;

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

@@ -10,4 +10,4 @@ export interface HandleStoreWriteInput {
     before: StoreDoc | null;
     after: StoreDoc | null;
 }
-export declare function handleStoreWrite(_input: HandleStoreWriteInput, _ctx: JobContext): Promise<void>;
+export declare function handleStoreWrite(input: HandleStoreWriteInput, ctx: JobContext): Promise<void>;

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

@@ -2,6 +2,12 @@
  * Core: stores/{id} onWrite — currently a no-op. Previous implementation
  * synced an external search index that has since been removed.
  */
-export async function handleStoreWrite(_input, _ctx) {
-    // Intentionally empty — search provider removed; Firestore queries handle search now.
+import { notifyRevalidate } from "./revalidateNotify";
+export async function handleStoreWrite(input, ctx) {
+    // The search-index sync this used to perform is gone (Firestore queries handle
+    // search now), so the only remaining side-effect is cache invalidation: drop
+    // the ISR entries for this store's page and the stores listing. Reuses the
+    // existing trigger, so this costs no additional invocations, and performs no
+    // Firestore write (Root Cause #92).
+    await notifyRevalidate({ collection: "stores", id: input.storeId }, ctx);
 }

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

@@ -0,0 +1,28 @@
+import type { JobContext } from "../runtime/types";
+import type { JsonValue } from "@mohasinac/appkit";
+/** Same shape the sibling job cores use (`ProductDoc`, `CategoryDoc`, …). */
+type Doc = Record<string, JsonValue> | null | undefined;
+/**
+ * Did anything a page renders actually change?
+ *
+ * 🛑 Compared with `JSON.stringify` per FIELD, never over the whole document.
+ * Root Cause #92's bug was a whole-object `JSON.stringify` comparison that could
+ * never report "equal" because Firestore returns map keys alphabetically while
+ * the code built them in construction order. Per-field, the values are scalars
+ * or small arrays whose order IS meaningful, so stringify is sound here.
+ *
+ * A create or a delete always counts — there is no previous/next state to diff.
+ */
+export declare function productCacheFieldsChanged(before: Doc, after: Doc): boolean;
+export interface RevalidateNotifyInput {
+    collection: string;
+    id: string;
+    hints?: {
+        listingType?: string;
+        categorySlugs?: string[];
+        brandSlug?: string;
+        storeId?: string;
+    };
+}
+export declare function notifyRevalidate(input: RevalidateNotifyInput, ctx: JobContext): Promise<void>;
+export {};

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

@@ -0,0 +1,125 @@
+import { normalizeError } from "../../../../errors/normalize";
+/**
+ * Tell the Next.js app that a document changed, so it can drop the stale ISR
+ * entries for the pages that render it.
+ *
+ * ## Why an HTTP call and not `revalidatePath()`
+ *
+ * `revalidatePath` only exists inside the Next.js runtime. The writers that
+ * matter most do NOT run there: a checkout stock decrement, auction settlement,
+ * the nightly reconcilers and every `appkit-seed` write all execute in Cloud
+ * Functions or a CLI. A Firestore trigger is the one place that observes all of
+ * them, and the only way it can reach Next's cache is over the network.
+ *
+ * ## 🛑 This does not write to Firestore — by construction
+ *
+ * Root Cause #92: a trigger that writes back to the collection it watches is how
+ * this project produced 1.02M invocations/day and knocked out production. This
+ * performs exactly one `fetch` and touches no document, so it cannot re-trigger
+ * itself. Keep it that way — if this ever needs to persist anything, it needs a
+ * different trigger path, not a write.
+ *
+ * ## Best-effort, and silent about it
+ *
+ * A failed invalidation must never fail the write side-effects it rides along
+ * with — the product is already saved; the worst case is a page that stays stale
+ * until its TTL rolls. So this swallows every error after classifying it, and
+ * logs at `warn` once per failure rather than per document.
+ */
+/** Fields whose change can alter what a public page renders. */
+const CACHE_RELEVANT_PRODUCT_FIELDS = [
+    "status",
+    "stockQuantity",
+    "isSold",
+    "price",
+    "salePrice",
+    "title",
+    "images",
+    "categorySlugs",
+    "brandSlug",
+    "brand",
+    "storeId",
+    "listingType",
+    "auctionEndDate",
+    "currentBid",
+    "buyNowPrice",
+    "isFeatured",
+    "isPromoted",
+    "featured",
+];
+/**
+ * Did anything a page renders actually change?
+ *
+ * 🛑 Compared with `JSON.stringify` per FIELD, never over the whole document.
+ * Root Cause #92's bug was a whole-object `JSON.stringify` comparison that could
+ * never report "equal" because Firestore returns map keys alphabetically while
+ * the code built them in construction order. Per-field, the values are scalars
+ * or small arrays whose order IS meaningful, so stringify is sound here.
+ *
+ * A create or a delete always counts — there is no previous/next state to diff.
+ */
+export function productCacheFieldsChanged(before, after) {
+    if (!before || !after)
+        return true;
+    for (const field of CACHE_RELEVANT_PRODUCT_FIELDS) {
+        if (JSON.stringify(before[field] ?? null) !== JSON.stringify(after[field] ?? null)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * The app origin to call.
+ *
+ * No existing job needed one, so this introduces `APP_ORIGIN`. Returning null
+ * (rather than guessing a host) makes an unconfigured deployment a no-op with a
+ * one-line warning instead of a stream of failed requests to the wrong site —
+ * and the stale page it leaves behind is bounded by the TTL.
+ */
+function appOrigin(ctx) {
+    const raw = ctx.env("APP_ORIGIN");
+    if (!raw)
+        return null;
+    return raw.replace(/\/+$/, "");
+}
+export async function notifyRevalidate(input, ctx) {
+    const origin = appOrigin(ctx);
+    const secret = ctx.env("CACHE_REVALIDATION_SECRET");
+    if (!origin || !secret) {
+        ctx.logger.warn("revalidate-notify: not configured — skipping", {
+            hasOrigin: !!origin,
+            hasSecret: !!secret,
+            collection: input.collection,
+        });
+        return;
+    }
+    try {
+        const res = await fetch(`${origin}/api/cache/revalidate`, {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-api-key": secret },
+            body: JSON.stringify({
+                collections: [input.collection],
+                id: input.id,
+                hints: input.hints ?? {},
+            }),
+            // The caller is a background trigger, not a user request — but an
+            // unbounded fetch would pin the function open until the platform kills it.
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok) {
+            ctx.logger.warn("revalidate-notify: endpoint returned non-ok", {
+                status: res.status,
+                collection: input.collection,
+                id: input.id,
+            });
+        }
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.warn("revalidate-notify: request failed", {
+            collection: input.collection,
+            id: input.id,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}

package/dist/_internal/shared/cache/revalidate-targets.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Which PAGE paths a write to a collection makes stale.
+ *
+ * ## Why this exists
+ *
+ * Detail routes used to carry very short `revalidate` windows — 30s on
+ * `auctions/[id]`, 60s on `products/[slug]` — not because anyone wanted that
+ * freshness, but because **the window was the only freshness mechanism in the
+ * app**. Measured 2026-10-09: `revalidatePath` appeared three times in the whole
+ * repository, all `revalidatePath("/")`, and `revalidateTag` zero times.
+ *
+ * Short windows × many unique paths is how you manufacture ISR writes. 95
+ * products at 60s is up to 137K regenerations/day from one route, and the
+ * project was suspended for exceeding 200K ISR writes with 3.1M — the signature
+ * being writes outnumbering reads 3:1, i.e. entries regenerating before anyone
+ * read them twice.
+ *
+ * Invalidation keyed on the WRITE is both cheaper and more correct than any
+ * clock: a product that changed is stale immediately, and one that did not never
+ * regenerates at all.
+ *
+ * ## Contract
+ *
+ * Returns **locale-less** paths. The caller is responsible for prefixing each
+ * with the locales it serves — see the revalidate route, which does that from
+ * `routing.locales`, because prerendered entries live at `/en/...`.
+ *
+ * Paths are returned on a best-effort basis: a caller that cannot supply hints
+ * still gets the always-stale list, which is the part that matters for a
+ * listing. Over-revalidating is cheap (it marks an entry stale; it does not
+ * render). Under-revalidating is the failure that shows a buyer a sold-out
+ * listing as in stock, so when in doubt this returns MORE paths, not fewer.
+ */
+/** What the caller knows about the written document, when it knows anything. */
+export interface RevalidateHints {
+    /** `standard` | `auction` | `pre-order` | … — picks the right detail route. */
+    listingType?: string;
+    /** Full ancestor chain; every category page listing this product goes stale. */
+    categorySlugs?: string[];
+    brandSlug?: string;
+    storeId?: string;
+}
+/**
+ * Page paths made stale by a write to `collection`.
+ *
+ * `id` and `hints` are optional; omitting them yields only the always-stale
+ * listing pages, which is the correct answer for a bulk or unknown write.
+ */
+export declare function revalidateTargetsFor(collection: string, id?: string, hints?: RevalidateHints): string[];

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

@@ -0,0 +1,157 @@
+/**
+ * Which PAGE paths a write to a collection makes stale.
+ *
+ * ## Why this exists
+ *
+ * Detail routes used to carry very short `revalidate` windows — 30s on
+ * `auctions/[id]`, 60s on `products/[slug]` — not because anyone wanted that
+ * freshness, but because **the window was the only freshness mechanism in the
+ * app**. Measured 2026-10-09: `revalidatePath` appeared three times in the whole
+ * repository, all `revalidatePath("/")`, and `revalidateTag` zero times.
+ *
+ * Short windows × many unique paths is how you manufacture ISR writes. 95
+ * products at 60s is up to 137K regenerations/day from one route, and the
+ * project was suspended for exceeding 200K ISR writes with 3.1M — the signature
+ * being writes outnumbering reads 3:1, i.e. entries regenerating before anyone
+ * read them twice.
+ *
+ * Invalidation keyed on the WRITE is both cheaper and more correct than any
+ * clock: a product that changed is stale immediately, and one that did not never
+ * regenerates at all.
+ *
+ * ## Contract
+ *
+ * Returns **locale-less** paths. The caller is responsible for prefixing each
+ * with the locales it serves — see the revalidate route, which does that from
+ * `routing.locales`, because prerendered entries live at `/en/...`.
+ *
+ * Paths are returned on a best-effort basis: a caller that cannot supply hints
+ * still gets the always-stale list, which is the part that matters for a
+ * listing. Over-revalidating is cheap (it marks an entry stale; it does not
+ * render). Under-revalidating is the failure that shows a buyer a sold-out
+ * listing as in stock, so when in doubt this returns MORE paths, not fewer.
+ */
+/** 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}`,
+};
+/**
+ * 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.
+ */
+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";
+    return undefined;
+}
+function productTargets(id, hints) {
+    const out = ["/", "/products"];
+    if (!id)
+        return 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 !== "/products")
+            out.push(browse);
+    }
+    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.
+         */
+        for (const build of Object.values(PRODUCT_DETAIL_BY_TYPE))
+            out.push(build(id));
+    }
+    // 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
+    // leaf and every parent up to the root.
+    for (const slug of hints?.categorySlugs ?? [])
+        out.push(`/categories/${slug}`);
+    if (hints?.brandSlug)
+        out.push(`/brands/${hints.brandSlug}`);
+    if (hints?.storeId)
+        out.push(`/stores/${hints.storeId}`);
+    return out;
+}
+/**
+ * Page paths made stale by a write to `collection`.
+ *
+ * `id` and `hints` are optional; omitting them yields only the always-stale
+ * listing pages, which is the correct answer for a bulk or unknown write.
+ */
+export function revalidateTargetsFor(collection, id, hints) {
+    let paths;
+    switch (collection) {
+        case "products":
+            paths = productTargets(id, hints);
+            break;
+        case "categories":
+            // Brands and pricing bundles are `categories` rows discriminated by
+            // `categoryType`, so all three detail shapes are marked.
+            paths = ["/", "/categories"];
+            if (id)
+                paths.push(`/categories/${id}`, `/brands/${id}`, `/bundles/${id}`);
+            break;
+        case "blogPosts":
+            paths = ["/", "/blog"];
+            if (id)
+                paths.push(`/blog/${id}`);
+            break;
+        case "events":
+            paths = ["/", "/events"];
+            if (id)
+                paths.push(`/events/${id}`);
+            break;
+        case "reviews":
+            // A new review changes the product's rating and the homepage stat.
+            paths = ["/", "/reviews"];
+            break;
+        case "stores":
+            paths = ["/", "/stores"];
+            if (id)
+                paths.push(`/stores/${id}`);
+            break;
+        case "carouselSlides":
+        case "homepageSections":
+        case "siteSettings":
+            paths = ["/"];
+            break;
+        case "faqs":
+            paths = ["/", "/faqs"];
+            break;
+        default:
+            paths = [];
+    }
+    return Array.from(new Set(paths));
+}

package/dist/features/auctions/components/AuctionBottomActions.js

@@ -6,6 +6,7 @@ import { useCanSeePrices } from "../../../react/hooks/useCanSeePrices";
 import { formatCurrency } from "../../../utils/number.formatter";
 import { ACTION_ID, ACTION_META } from "../../products/constants/action-defs";
 import { useCountdown } from "../../../react";
+import { useIsAuctionEnded } from "../hooks/useIsAuctionEnded";
 import { Modal } from "../../../ui";
 import { isBuyNowAvailable } from "../../../_internal/shared/features/auctions/config";
 import { PlaceBidFormClient, } from "./PlaceBidFormClient";
@@ -38,7 +39,15 @@ function formatCountdownLabel(remaining) {
  * button can report an error or route to `/checkout?lane=auction`.
  */
 export function AuctionBottomActions(props) {
-    const { currentBid, currency, bidCount, isEnded, auctionEndDate, buyNowPrice } = props;
+    const { currentBid, currency, bidCount, isEnded: ssrIsEnded, auctionEndDate, buyNowPrice } = props;
+    /*
+     * Derived client-side — see `useIsAuctionEnded`. This bar is a FIXED, always-
+     * visible row on mobile, so a stale "Place bid" here is the most prominent
+     * wrong affordance on the page. `useCountdown` below already knew the truth
+     * (it returns null past the target) but only fed a label; the bar's actions
+     * were gated on the frozen server boolean.
+     */
+    const isEnded = useIsAuctionEnded(auctionEndDate, ssrIsEnded);
     const [open, setOpen] = useState(false);
     const remaining = useCountdown(auctionEndDate ?? undefined);
     const { canSeePrices } = useCanSeePrices();