@mohasinac/appkit 4.42.18 → 4.43.0

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

@@ -22,6 +22,7 @@ import { AuctionDetailView } from "../../products/components/AuctionDetailView";
 import { ProductTabsShell } from "../../products/components/ProductTabsShell";
 import { CustomSectionTabContent } from "../../products/components/CustomSectionTabContent";
 import { AuctionBottomActions } from "./AuctionBottomActions";
+import { AuctionLiveStatusBadge } from "./AuctionLiveStatusBadge";
 import { RelatedProducts } from "../../products/components/RelatedProducts";
 import { ProductGalleryClient } from "../../products/components/ProductGalleryClient";
 import { ProductFeatureBadges } from "../../products/components/ProductFeatureBadges";
@@ -48,7 +49,7 @@ function toDescriptionHtml(raw) {
 }
 function renderAuctionInfoPanel(props) {
     const { productId, title, currentBid, currency, bidCount, isEnded, endDate, buyNowPrice, buyNowAvailable, featured, freeShipping, condition, finalSale, category, categoryName, brand, brandSlug, productFeatures, features, descriptionHtml, safeSeller, storeHref } = props;
-    return (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_LIVE_BADGE, children: "\uD83C\uDFF7\uFE0F Live Auction" }), isEnded ? (_jsx(Span, { color: "error", surface: "danger-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: "Ended" })) : (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: "Active" }))] }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title })] }), _jsxs(Div, { children: [_jsx(Text, { className: "mb-0.5", color: "muted", size: "xs", children: "Current bid" }), _jsx(LiveBidPrice, { productId: productId, currentBid: currentBid, bidCount: bidCount, currency: currency, isEnded: isEnded, priceSize: "2xl", badgeSize: "sm" }), endDate && !isEnded && (_jsxs(Text, { className: "mt-1.5", color: "muted", size: "sm", children: ["Ends in ", _jsx(Span, { weight: "medium", color: "muted", children: _jsx(CountdownDisplay, { targetDate: endDate, format: "auto", expiredLabel: "Ended" }) })] })), endDate && _jsxs(Text, { className: "mt-0.5", color: "faint", size: "xs", children: [isEnded ? "Ended" : "Ends", " ", endDate.toLocaleString()] })] }), buyNowAvailable && buyNowPrice !== null && (_jsxs(Row, { align: "center", gap: "sm", className: "border border-[var(--appkit-color-primary-200)] dark:border-[var(--appkit-color-primary-800)] bg-primary-50 dark:bg-primary-900/20", padding: "inlineSm", rounded: "lg", children: [_jsx(Span, { size: "xs", color: "muted", children: "Buy Now:" }), _jsx(Span, { size: "base", weight: "bold", className: "text-primary-700 dark:text-primary-300", children: _jsx(GatedPrice, { label: "Sign in to see the Buy Now price", children: formatCurrency(buyNowPrice, currency) }) }), _jsx(Span, { size: "xs", color: "faint", children: "\u2014 in \u201CPlace a bid\u201D" })] })), _jsx(ProductFeatureBadges, { featured: featured, freeShipping: freeShipping, condition: condition ?? undefined, finalSale: finalSale, labels: { featured: "Featured", fasterDelivery: "Faster Delivery", ratedSeller: "Rated Seller", condition: "Condition", conditionNew: "New", conditionUsed: "Used", conditionBroken: "For Parts", conditionRefurbished: "Refurbished", returnable: "Returnable", finalSale: "Final Sale", freeShipping: "Free Shipping", codAvailable: "Cash on Delivery", emiAvailable: "EMI Available", wishlistCount: (n) => `${n} wishlisted`, categoryProductCount: (n, cat) => `${n} in ${cat}` } }), (categoryName || category || brand) && (_jsxs(Row, { gap: "sm", wrap: true, children: [category && _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: categoryName || category }), !category && categoryName && _jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", children: categoryName }), brand && brandSlug && _jsx(Link, { href: String(ROUTES.PUBLIC.BRAND_DETAIL(brandSlug)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: brand }), brand && !brandSlug && _jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", children: brand })] })), productFeatures && features.length > 0 && _jsx(FeatureBadgeList, { productFeatureIds: features, features: productFeatures }), !productFeatures && features.length > 0 && (_jsxs(Div, { border: "subtle", surface: "muted", padding: "inline", rounded: "xl", children: [_jsx(Text, { className: "mb-2 tracking-wide", color: "muted", size: "xs", weight: "semibold", transform: "uppercase", children: "About this item" }), _jsx(Ul, { spacing: "comfortable", size: "sm", color: "primary", children: features.map((f, i) => _jsxs(Li, { layout: "flex-start", gap: "2", children: [_jsx(Span, { className: "mt-0.5 flex-shrink-0 text-primary-500", children: "\u2022" }), f] }, i)) })] })), descriptionHtml && _jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" }), safeSeller && (_jsx(Div, { className: `${__P.p3}`, border: "subtle", rounded: "xl", surface: "muted", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Listed by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && _jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" })] }) }))] }));
+    return (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_LIVE_BADGE, children: "\uD83C\uDFF7\uFE0F Live Auction" }), _jsx(AuctionLiveStatusBadge, { auctionEndDate: endDate, initialIsEnded: isEnded })] }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title })] }), _jsxs(Div, { children: [_jsx(Text, { className: "mb-0.5", color: "muted", size: "xs", children: "Current bid" }), _jsx(LiveBidPrice, { productId: productId, currentBid: currentBid, bidCount: bidCount, currency: currency, isEnded: isEnded, priceSize: "2xl", badgeSize: "sm" }), endDate && !isEnded && (_jsxs(Text, { className: "mt-1.5", color: "muted", size: "sm", children: ["Ends in ", _jsx(Span, { weight: "medium", color: "muted", children: _jsx(CountdownDisplay, { targetDate: endDate, format: "auto", expiredLabel: "Ended" }) })] })), endDate && _jsxs(Text, { className: "mt-0.5", color: "faint", size: "xs", children: [isEnded ? "Ended" : "Ends", " ", endDate.toLocaleString()] })] }), buyNowAvailable && buyNowPrice !== null && (_jsxs(Row, { align: "center", gap: "sm", className: "border border-[var(--appkit-color-primary-200)] dark:border-[var(--appkit-color-primary-800)] bg-primary-50 dark:bg-primary-900/20", padding: "inlineSm", rounded: "lg", children: [_jsx(Span, { size: "xs", color: "muted", children: "Buy Now:" }), _jsx(Span, { size: "base", weight: "bold", className: "text-primary-700 dark:text-primary-300", children: _jsx(GatedPrice, { label: "Sign in to see the Buy Now price", children: formatCurrency(buyNowPrice, currency) }) }), _jsx(Span, { size: "xs", color: "faint", children: "\u2014 in \u201CPlace a bid\u201D" })] })), _jsx(ProductFeatureBadges, { featured: featured, freeShipping: freeShipping, condition: condition ?? undefined, finalSale: finalSale, labels: { featured: "Featured", fasterDelivery: "Faster Delivery", ratedSeller: "Rated Seller", condition: "Condition", conditionNew: "New", conditionUsed: "Used", conditionBroken: "For Parts", conditionRefurbished: "Refurbished", returnable: "Returnable", finalSale: "Final Sale", freeShipping: "Free Shipping", codAvailable: "Cash on Delivery", emiAvailable: "EMI Available", wishlistCount: (n) => `${n} wishlisted`, categoryProductCount: (n, cat) => `${n} in ${cat}` } }), (categoryName || category || brand) && (_jsxs(Row, { gap: "sm", wrap: true, children: [category && _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: categoryName || category }), !category && categoryName && _jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", children: categoryName }), brand && brandSlug && _jsx(Link, { href: String(ROUTES.PUBLIC.BRAND_DETAIL(brandSlug)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: brand }), brand && !brandSlug && _jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", children: brand })] })), productFeatures && features.length > 0 && _jsx(FeatureBadgeList, { productFeatureIds: features, features: productFeatures }), !productFeatures && features.length > 0 && (_jsxs(Div, { border: "subtle", surface: "muted", padding: "inline", rounded: "xl", children: [_jsx(Text, { className: "mb-2 tracking-wide", color: "muted", size: "xs", weight: "semibold", transform: "uppercase", children: "About this item" }), _jsx(Ul, { spacing: "comfortable", size: "sm", color: "primary", children: features.map((f, i) => _jsxs(Li, { layout: "flex-start", gap: "2", children: [_jsx(Span, { className: "mt-0.5 flex-shrink-0 text-primary-500", children: "\u2022" }), f] }, i)) })] })), descriptionHtml && _jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" }), safeSeller && (_jsx(Div, { className: `${__P.p3}`, border: "subtle", rounded: "xl", surface: "muted", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Listed by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && _jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" })] }) }))] }));
 }
 /**
  * Store reviews for the auction's seller.

package/dist/features/auctions/components/AuctionLiveStatusBadge.d.ts

@@ -0,0 +1,20 @@
+export interface AuctionLiveStatusBadgeProps {
+    /** The auction's end timestamp — the only thing that decides this. */
+    auctionEndDate: Date | string | null;
+    /** The server's answer, used as the initial value so SSR and hydration agree. */
+    initialIsEnded: boolean;
+}
+/**
+ * Active / Ended, decided on the client.
+ *
+ * The server-rendered version of this badge sat directly above a countdown that
+ * already flipped itself to "Ended" — so a cached auction page could render
+ * `Ends in Ended` beside a green **Active** pill. The countdown was right and the
+ * badge was stale, in the same `<Stack>`.
+ *
+ * Extracted to a client component rather than passing a derived prop down,
+ * because `AuctionDetailPageView` is a Server Component and cannot hold the
+ * timer. Colours follow the status-pair rule (Root Cause #67): a theme-relative
+ * surface with its matching theme-relative ink, never a literal `text-white`.
+ */
+export declare function AuctionLiveStatusBadge({ auctionEndDate, initialIsEnded, }: AuctionLiveStatusBadgeProps): import("react").JSX.Element;

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

@@ -0,0 +1,21 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Span } from "../../../ui";
+import { useIsAuctionEnded } from "../hooks/useIsAuctionEnded";
+/**
+ * Active / Ended, decided on the client.
+ *
+ * The server-rendered version of this badge sat directly above a countdown that
+ * already flipped itself to "Ended" — so a cached auction page could render
+ * `Ends in Ended` beside a green **Active** pill. The countdown was right and the
+ * badge was stale, in the same `<Stack>`.
+ *
+ * Extracted to a client component rather than passing a derived prop down,
+ * because `AuctionDetailPageView` is a Server Component and cannot hold the
+ * timer. Colours follow the status-pair rule (Root Cause #67): a theme-relative
+ * surface with its matching theme-relative ink, never a literal `text-white`.
+ */
+export function AuctionLiveStatusBadge({ auctionEndDate, initialIsEnded, }) {
+    const isEnded = useIsAuctionEnded(auctionEndDate, initialIsEnded);
+    return isEnded ? (_jsx(Span, { color: "error", surface: "danger-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: "Ended" })) : (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: "Active" }));
+}

package/dist/features/auctions/components/PlaceBidFormClient.d.ts

@@ -45,7 +45,7 @@ export interface PlaceBidFormClientProps {
     onPlaceBid: (input: PlaceBidInput) => Promise<BidActionEnvelope<unknown>>;
     onBuyNow?: () => Promise<BidActionEnvelope<BuyNowSuccess>>;
 }
-export declare function PlaceBidFormClient({ productId, currentBid: ssrCurrentBid, startingBid, tiers, minBidIncrementOverride, currency, isEnded, auctionEndDate, buyNowPrice, bidCount: ssrBidCount, tags, onPlaceBid, onBuyNow, }: PlaceBidFormClientProps): React.JSX.Element;
+export declare function PlaceBidFormClient({ productId, currentBid: ssrCurrentBid, startingBid, tiers, minBidIncrementOverride, currency, isEnded: ssrIsEnded, auctionEndDate, buyNowPrice, bidCount: ssrBidCount, tags, onPlaceBid, onBuyNow, }: PlaceBidFormClientProps): React.JSX.Element;
 /**
  * `PlaceBidModalButton` — opens a modal that hosts the same PlaceBidFormClient.
  *

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

@@ -13,6 +13,7 @@ import { FieldInput } from "../../../ui/forms/FieldInput";
 import { applyZodIssues } from "../../../ui/forms/apply-zod-issues";
 import { placeBidSchema } from "../schemas/bid-input";
 import { useLiveAuctionBid } from "../hooks/useLiveAuctionBid";
+import { useIsAuctionEnded } from "../hooks/useIsAuctionEnded";
 import { AUCTION_BUYOUT_WINDOW_MINUTES } from "../../../_internal/shared/checkout/lanes";
 import { BID_PRESET_MULTIPLIERS, isBuyNowAvailable, resolveMinBid, resolveMinBidIncrement, } from "../../../_internal/shared/features/auctions/config";
 import { normalizeError } from "../../../errors/normalize";
@@ -36,7 +37,20 @@ const __P = {
 /** Feature-specific last resort. Authored copy, never derived from an error. */
 const BID_FALLBACK = "Failed to place bid. Please try again.";
 const BUY_NOW_FALLBACK = "Buy Now failed. Please try again.";
-export function PlaceBidFormClient({ productId, currentBid: ssrCurrentBid, startingBid, tiers, minBidIncrementOverride, currency, isEnded, auctionEndDate, buyNowPrice, bidCount: ssrBidCount, tags = [], onPlaceBid, onBuyNow, }) {
+export function PlaceBidFormClient({ productId, currentBid: ssrCurrentBid, startingBid, tiers, minBidIncrementOverride, currency, isEnded: ssrIsEnded, auctionEndDate, buyNowPrice, bidCount: ssrBidCount, tags = [], onPlaceBid, onBuyNow, }) {
+    /*
+     * 🛑 Derived here, not trusted from the server.
+     *
+     * `isEnded` arrives baked into cached HTML. On a page cached while the auction
+     * was live it says "still open" indefinitely, so every gate below it — the
+     * amount field, the presets, the submit button, Buy Now — stayed enabled on a
+     * closed lot. The server prop is the INITIAL value only; `auctionEndDate` was
+     * already being passed in and used for display, and it is the real answer.
+     *
+     * The bid itself was never at risk: `placeBid` re-reads the product and
+     * rejects on an expired `auctionEndDate`. This fixes the affordance.
+     */
+    const isEnded = useIsAuctionEnded(auctionEndDate, ssrIsEnded);
     const router = useRouter();
     // Declared with the other hooks, never inside the early return below — a
     // conditional hook is a render-order violation, and this component early-
@@ -277,5 +291,9 @@ export function PlaceBidFormClient({ productId, currentBid: ssrCurrentBid, start
 export function PlaceBidModalButton(props) {
     const { triggerLabel = "Place a bid", triggerClassName = "", ...formProps } = props;
     const [open, setOpen] = useState(false);
-    return (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "primary", size: "md", className: triggerClassName, disabled: props.isEnded, onClick: () => setOpen(true), children: props.isEnded ? "Auction Ended" : triggerLabel }), _jsx(Modal, { isOpen: open, onClose: () => setOpen(false), size: "md", title: "Place your bid", children: _jsx(PlaceBidFormClient, { ...formProps }) })] }));
+    // Same reason as inside the form: this trigger is THE affordance a buyer sees
+    // on a cached auction page, so it must decide for itself rather than trust a
+    // boolean that was true whenever the HTML happened to be generated.
+    const isEnded = useIsAuctionEnded(props.auctionEndDate, props.isEnded);
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "primary", size: "md", className: triggerClassName, disabled: isEnded, onClick: () => setOpen(true), children: isEnded ? "Auction Ended" : triggerLabel }), _jsx(Modal, { isOpen: open, onClose: () => setOpen(false), size: "md", title: "Place your bid", children: _jsx(PlaceBidFormClient, { ...formProps }) })] }));
 }

package/dist/features/auctions/hooks/useIsAuctionEnded.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Has this auction ended, decided on the CLIENT from its end timestamp.
+ *
+ * ## Why this exists
+ *
+ * `AuctionDetailPageView` computed `const isEnded = endDate < new Date()` on the
+ * SERVER and froze the answer into eleven places — the status badge, the Buy-Now
+ * chip, the SSE `enabled` flag, the Place-Bid button, the mobile bid card and
+ * the bottom action bar. That is correct only for as long as the rendered HTML
+ * is fresh.
+ *
+ * The page is cached. At `revalidate = 30` the window was small enough to hide
+ * the problem; it is not small enough to be *correct*, and raising the TTL (so
+ * that 95 auction pages stop regenerating up to 2,880 times a day each, which is
+ * what produced 3.1M ISR writes) makes it plainly visible: a page cached while
+ * the auction was live renders a green **Active** badge and an enabled "Place a
+ * bid" button on a lot that closed hours ago.
+ *
+ * The timestamp needed to know better was already being passed down — it was
+ * used for display only.
+ *
+ * ## What this does NOT change
+ *
+ * Server-side enforcement is independent and already correct: `placeBid` and
+ * `buyNowAuction` both re-read the product and reject on `endDate < now`, and
+ * `assertAuctionActive()` is a third copy. A stale page could never actually
+ * place a bid — the defect was always a misleading affordance, never a bad
+ * write. That is what makes this safe to adopt incrementally: every component
+ * converted is an improvement, and an unconverted one is no worse than today.
+ *
+ * ## Behaviour
+ *
+ * - Starts from `initial` (the server's answer) so the first paint is unchanged
+ *   and hydration does not mismatch.
+ * - Re-checks on mount, which is where a cached page corrects itself.
+ * - Schedules ONE timer for the exact moment of expiry rather than ticking every
+ *   second — a bid button does not need per-second resolution, and an interval
+ *   on every auction card would be a needless wakeup. Long waits are clamped to
+ *   the setTimeout 32-bit ceiling and re-armed.
+ */
+export declare function useIsAuctionEnded(auctionEndDate: Date | string | null | undefined, initial?: boolean): boolean;

package/dist/features/auctions/hooks/useIsAuctionEnded.js

@@ -0,0 +1,76 @@
+"use client";
+import { useEffect, useState } from "react";
+/**
+ * Has this auction ended, decided on the CLIENT from its end timestamp.
+ *
+ * ## Why this exists
+ *
+ * `AuctionDetailPageView` computed `const isEnded = endDate < new Date()` on the
+ * SERVER and froze the answer into eleven places — the status badge, the Buy-Now
+ * chip, the SSE `enabled` flag, the Place-Bid button, the mobile bid card and
+ * the bottom action bar. That is correct only for as long as the rendered HTML
+ * is fresh.
+ *
+ * The page is cached. At `revalidate = 30` the window was small enough to hide
+ * the problem; it is not small enough to be *correct*, and raising the TTL (so
+ * that 95 auction pages stop regenerating up to 2,880 times a day each, which is
+ * what produced 3.1M ISR writes) makes it plainly visible: a page cached while
+ * the auction was live renders a green **Active** badge and an enabled "Place a
+ * bid" button on a lot that closed hours ago.
+ *
+ * The timestamp needed to know better was already being passed down — it was
+ * used for display only.
+ *
+ * ## What this does NOT change
+ *
+ * Server-side enforcement is independent and already correct: `placeBid` and
+ * `buyNowAuction` both re-read the product and reject on `endDate < now`, and
+ * `assertAuctionActive()` is a third copy. A stale page could never actually
+ * place a bid — the defect was always a misleading affordance, never a bad
+ * write. That is what makes this safe to adopt incrementally: every component
+ * converted is an improvement, and an unconverted one is no worse than today.
+ *
+ * ## Behaviour
+ *
+ * - Starts from `initial` (the server's answer) so the first paint is unchanged
+ *   and hydration does not mismatch.
+ * - Re-checks on mount, which is where a cached page corrects itself.
+ * - Schedules ONE timer for the exact moment of expiry rather than ticking every
+ *   second — a bid button does not need per-second resolution, and an interval
+ *   on every auction card would be a needless wakeup. Long waits are clamped to
+ *   the setTimeout 32-bit ceiling and re-armed.
+ */
+export function useIsAuctionEnded(auctionEndDate, initial = false) {
+    const endMs = toMs(auctionEndDate);
+    const [ended, setEnded] = useState(initial);
+    useEffect(() => {
+        if (endMs === null) {
+            // No end date — the server's answer is the only one available.
+            setEnded(initial);
+            return;
+        }
+        let timer;
+        const evaluate = () => {
+            const remaining = endMs - Date.now();
+            if (remaining <= 0) {
+                setEnded(true);
+                return;
+            }
+            setEnded(false);
+            // setTimeout overflows past ~24.8 days and fires immediately; re-arm.
+            timer = setTimeout(evaluate, Math.min(remaining, 2147483000));
+        };
+        evaluate();
+        return () => {
+            if (timer)
+                clearTimeout(timer);
+        };
+    }, [endMs, initial]);
+    return ended;
+}
+function toMs(value) {
+    if (!value)
+        return null;
+    const ms = value instanceof Date ? value.getTime() : new Date(value).getTime();
+    return Number.isFinite(ms) ? ms : null;
+}

package/dist/features/blog/api/route.js

@@ -72,7 +72,22 @@ export async function GET(request) {
             posts: result.items,
             meta,
         };
-        return NextResponse.json({ success: true, data: body });
+        const response = NextResponse.json({ success: true, data: body });
+        /*
+         * The only public listing API that set NO Cache-Control — `/api/products`,
+         * `/api/stores`, `/api/events` and `/api/reviews` all do, and CLAUDE.md
+         * Rule #6.5 requires it of every public GET (20 of 378 routes complied).
+         *
+         * It mattered little while anonymous browsing never reached this route (the
+         * dynamic `/blog` page rendered server-side and seeded the client), but it
+         * is on the critical path the moment a filtered view misses the page cache.
+         * Window matched to its siblings deliberately — a blog post is no more
+         * volatile than a product.
+         *
+         * Errors below stay uncached: a 500 must not be pinned at the edge.
+         */
+        response.headers.set("Cache-Control", "public, max-age=60, s-maxage=120, stale-while-revalidate=60");
+        return response;
     }
     catch (error) {
         void normalizeError(error);

package/dist/features/categories/actions/category-actions.d.ts

@@ -9,8 +9,8 @@ export declare function listCategories(params?: {
     page?: number;
     pageSize?: number;
 }): Promise<FirebaseSieveResult<CategoryDocument>>;
-export declare function listTopLevelCategories(limit?: number): Promise<CategoryDocument[]>;
-export declare function listBrandCategories(limit?: number): Promise<CategoryDocument[]>;
+export declare const listTopLevelCategories: (limit?: number) => Promise<CategoryDocument[]>;
+export declare const listBrandCategories: (limit?: number) => Promise<CategoryDocument[]>;
 export declare function getCategoryById(id: string): Promise<CategoryDocument | null>;
 export declare function getCategoryBySlug(slug: string): Promise<CategoryDocument | null>;
 export declare function getCategoryChildren(parentId: string): Promise<CategoryDocument[]>;

package/dist/features/categories/actions/category-actions.js

@@ -1,3 +1,4 @@
+import { cache } from "react";
 import { serverLogger } from "../../../monitoring";
 import { categoriesRepository } from "../repository/categories.repository";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility";
@@ -39,19 +40,30 @@ export async function listCategories(params) {
     };
     return categoriesRepository.list(sieve);
 }
-export async function listTopLevelCategories(limit = 12) {
-    const all = await categoriesRepository.getCategoriesByTier(0);
+/*
+ * Both of these fetched the ENTIRE matching set and `.slice()`d it to 12, on
+ * every homepage render. The bound is now pushed into Firestore (with headroom
+ * for the post-fetch filters), and both are `cache()`-wrapped so a second reader
+ * in the same request tree — the nav, a footer, a sibling section — costs
+ * nothing. Measured 2026-10-09 against a 50K-reads/day free tier.
+ *
+ * The in-memory `isActive !== false` filter is gone: both queries already
+ * require `isActive == true`, and a Firestore equality excludes documents
+ * lacking the field, so it could never match anything the query had not already
+ * admitted. `hidePublicTestData` stays — that one is a real post-filter, which
+ * is why the repository fetches with headroom rather than exactly `limit`.
+ */
+export const listTopLevelCategories = cache(async (limit = 12) => {
+    const all = await categoriesRepository.getCategoriesByTier(0, limit);
     return hidePublicTestData(all)
-        .filter((c) => c.isActive !== false)
         .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
         .slice(0, limit);
-}
-export async function listBrandCategories(limit = 12) {
-    const brands = await categoriesRepository.getBrandCategories();
-    return hidePublicTestData(brands)
-        .filter((c) => c.isActive !== false)
-        .slice(0, limit);
-}
+});
+export const listBrandCategories = cache(async (limit = 12) => {
+    // Over-fetch a small margin so `hidePublicTestData` cannot under-fill the row.
+    const brands = await categoriesRepository.getBrandCategories(limit + 8);
+    return hidePublicTestData(brands).slice(0, limit);
+});
 export async function getCategoryById(id) {
     return categoriesRepository.findById(id);
 }

package/dist/features/categories/components/CategoriesIndexListing.d.ts

@@ -1,8 +1,6 @@
 import React from "react";
-import type { CategoryItem } from "../types";
 export interface CategoriesIndexListingProps {
-    initialData?: CategoryItem[];
     /** When true, filters to brands only (for the standalone /brands page) */
     brandsOnly?: boolean;
 }
-export declare function CategoriesIndexListing({ initialData: _, brandsOnly }: CategoriesIndexListingProps): React.JSX.Element;
+export declare function CategoriesIndexListing({ brandsOnly }: CategoriesIndexListingProps): React.JSX.Element;

package/dist/features/categories/components/CategoriesIndexListing.js

@@ -63,7 +63,7 @@ const SORT_OPTIONS = [
     { value: sortBy(CATEGORY_FIELDS.NAME), label: "Name Z–A" },
     { value: sortBy("metrics.productCount", "DESC"), label: "Most Products" },
 ];
-export function CategoriesIndexListing({ initialData: _, brandsOnly = false }) {
+export function CategoriesIndexListing({ brandsOnly = false }) {
     const table = useUrlTable({ defaults: { pageSize: String(PAGE_SIZE), sort: DEFAULT_SORT } });
     const [searchInput, setSearchInput] = useState(table.get(TABLE_KEYS.QUERY) || "");
     const [filterOpen, setFilterOpen] = useState(false);

package/dist/features/categories/components/CategoriesIndexPageView.d.ts

@@ -1,7 +1,33 @@
 import React from "react";
 type SearchParams = Record<string, string | string[]>;
 export interface CategoriesIndexPageViewProps {
+    /**
+     * @deprecated Accepted and ignored. Kept so the consumer page shim compiles
+     * either way; remove once no caller passes it.
+     */
     searchParams?: SearchParams;
 }
-export declare function CategoriesIndexPageView({ searchParams }: CategoriesIndexPageViewProps): Promise<React.JSX.Element>;
+/**
+ * The categories index.
+ *
+ * 🛑 This view deliberately performs NO Firestore read.
+ *
+ * It used to fetch `pageSize: 200` and hand the result to
+ * `CategoriesIndexListing` as `initialData` — which destructured it as
+ * `initialData: _` and threw it away, then fetched `/api/categories?flat=true`
+ * regardless. So the read was 200 documents per render, on a route that
+ * regenerated every 300s, rendering nothing. Measured 2026-10-09 while tracing
+ * 2.1M Firestore reads/week against a 50K/day free tier.
+ *
+ * Deleting it also removes this page from Root Cause #30's blast radius
+ * entirely: you cannot freeze the wrong data under a `staleTime: Infinity` key
+ * you never seeded. The long "MUST MATCH CategoriesIndexListing's DEFAULT_SORT"
+ * warning that used to live here is now moot for the same reason — there is no
+ * second parser to keep in sync.
+ *
+ * Unlike the other listing pages, making this one static costs no SEO: its grid
+ * was already client-rendered, so there was never a server-rendered grid to
+ * lose (contrast `/products`, where the grid IS in the SSR HTML and must stay).
+ */
+export declare function CategoriesIndexPageView(_props?: CategoriesIndexPageViewProps): Promise<React.JSX.Element>;
 export {};

package/dist/features/categories/components/CategoriesIndexPageView.js

@@ -1,13 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { sieveFilter, SIEVE_OP } from "@mohasinac/appkit";
-import { sortBy } from "../../../constants/sort";
-import { CATEGORY_FIELDS } from "../../../constants/field-names";
-import { categoriesRepository } from "../../../repositories";
 import { Container, Heading, Main, Section } from "../../../ui";
 import { AdSlot } from "../../homepage/components/AdSlot";
 import { CategoriesIndexListing } from "./CategoriesIndexListing";
-import { safeRead } from "../../../errors/safe-read";
-import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility";
 function sp(params, key) {
     const v = params[key];
     return Array.isArray(v) ? v[0] ?? "" : v ?? "";
@@ -39,32 +34,28 @@ function buildCategoryFilters(params) {
     }
     return parts.join(",");
 }
-export async function CategoriesIndexPageView({ searchParams = {} }) {
-    /*
-     * 🛑 MUST MATCH CategoriesIndexListing's DEFAULT_SORT.
-     *
-     * This defaulted to "name" while the client listing defaulted to the same,
-     * and both were wrong: the roots fell off page 1. Now both default to tier
-     * ascending — and they have to agree, because this view hands its result to
-     * the listing as initialData and every public listing hook sets
-     * `staleTime: Infinity` when given it. A disagreement here is not a
-     * transient wrong first paint; it is frozen for that query key
-     * (Root Cause #30).
-     */
-    const sort = sp(searchParams, "sort") || sortBy(CATEGORY_FIELDS.TIER, "ASC");
-    const page = Number(sp(searchParams, "page")) || 1;
-    const filters = buildCategoryFilters(searchParams);
-    const result = await safeRead(() => categoriesRepository.list({
-        page,
-        pageSize: 200,
-        sorts: sort,
-        ...(filters ? { filters } : {}),
-    }), { route: "/categories", key: "categories.list", fallback: null });
-    /*
-     * This one page carries THREE entity kinds — categories, brands and bundles
-     * are all `CategoryDocument` rows discriminated by `categoryType` — so a
-     * single unfiltered read published sandbox fixtures of all three.
-     */
-    const initialData = hidePublicTestData((result?.items ?? []));
-    return (_jsx(Main, { children: _jsx(Section, { padding: "y-2xl", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 1, className: "mb-8", color: "primary", size: "3xl", weight: "semibold", children: "Categories" }), _jsx(AdSlot, { id: "listing-sidebar-top", className: "mb-6" }), _jsx(CategoriesIndexListing, { initialData: initialData }), _jsx(AdSlot, { id: "listing-sidebar-bottom", className: "mt-8" })] }) }) }));
+/**
+ * The categories index.
+ *
+ * 🛑 This view deliberately performs NO Firestore read.
+ *
+ * It used to fetch `pageSize: 200` and hand the result to
+ * `CategoriesIndexListing` as `initialData` — which destructured it as
+ * `initialData: _` and threw it away, then fetched `/api/categories?flat=true`
+ * regardless. So the read was 200 documents per render, on a route that
+ * regenerated every 300s, rendering nothing. Measured 2026-10-09 while tracing
+ * 2.1M Firestore reads/week against a 50K/day free tier.
+ *
+ * Deleting it also removes this page from Root Cause #30's blast radius
+ * entirely: you cannot freeze the wrong data under a `staleTime: Infinity` key
+ * you never seeded. The long "MUST MATCH CategoriesIndexListing's DEFAULT_SORT"
+ * warning that used to live here is now moot for the same reason — there is no
+ * second parser to keep in sync.
+ *
+ * Unlike the other listing pages, making this one static costs no SEO: its grid
+ * was already client-rendered, so there was never a server-rendered grid to
+ * lose (contrast `/products`, where the grid IS in the SSR HTML and must stay).
+ */
+export async function CategoriesIndexPageView(_props = {}) {
+    return (_jsx(Main, { children: _jsx(Section, { padding: "y-2xl", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 1, className: "mb-8", color: "primary", size: "3xl", weight: "semibold", children: "Categories" }), _jsx(AdSlot, { id: "listing-sidebar-top", className: "mb-6" }), _jsx(CategoriesIndexListing, {}), _jsx(AdSlot, { id: "listing-sidebar-bottom", className: "mt-8" })] }) }) }));
 }

package/dist/features/categories/repository/categories.repository.d.ts

@@ -9,7 +9,17 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
     getCategoryBySlug(slug: string): Promise<CategoryDocument | null>;
     getRootCategories(): Promise<CategoryDocument[]>;
     getLeafCategories(): Promise<CategoryDocument[]>;
-    getCategoriesByTier(tier: number): Promise<CategoryDocument[]>;
+    /**
+     * @param limit 0 = unbounded (the historical behaviour). When > 0 the bound is
+     *   pushed into Firestore instead of slicing after the read.
+     *
+     * 🛑 The limit is applied with HEADROOM, not exactly, because `!isBrand` is a
+     * post-fetch filter: brand rows live in this same collection (they are
+     * `CategoryDocument`s discriminated by `isBrand`), so a bare `.limit(n)` could
+     * return n brand rows, filter all of them out, and yield an empty tier. The
+     * caller still slices to its own limit.
+     */
+    getCategoriesByTier(tier: number, limit?: number): Promise<CategoryDocument[]>;
     getCategoriesByRootId(rootId: string): Promise<CategoryDocument[]>;
     getChildren(parentId: string): Promise<CategoryDocument[]>;
     /**

package/dist/features/categories/repository/categories.repository.js

@@ -112,14 +112,26 @@ export class CategoriesRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve leaf categories: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
-    async getCategoriesByTier(tier) {
+    /**
+     * @param limit 0 = unbounded (the historical behaviour). When > 0 the bound is
+     *   pushed into Firestore instead of slicing after the read.
+     *
+     * 🛑 The limit is applied with HEADROOM, not exactly, because `!isBrand` is a
+     * post-fetch filter: brand rows live in this same collection (they are
+     * `CategoryDocument`s discriminated by `isBrand`), so a bare `.limit(n)` could
+     * return n brand rows, filter all of them out, and yield an empty tier. The
+     * caller still slices to its own limit.
+     */
+    async getCategoriesByTier(tier, limit = 0) {
         try {
-            const snapshot = await this.db
+            let query = this.db
                 .collection(this.collection)
                 .where(CATEGORY_FIELDS.TIER, "==", tier)
                 .where(CATEGORY_FIELDS.IS_ACTIVE, "==", true)
-                .orderBy(CATEGORY_FIELDS.ORDER, "asc")
-                .get();
+                .orderBy(CATEGORY_FIELDS.ORDER, "asc");
+            if (limit > 0)
+                query = query.limit(limit * 4);
+            const snapshot = await query.get();
             return snapshot.docs
                 .map((doc) => this.mapDoc(doc))
                 .filter((category) => !category.isBrand);
@@ -230,12 +242,18 @@ export class CategoriesRepository extends BaseRepository {
     }
     async getBrandCategories(limit = 0) {
         try {
-            const snapshot = await this.db
+            // The limit is pushed into Firestore rather than sliced after the read.
+            // It used to fetch EVERY brand and `.slice()` — so `limit` reduced what
+            // the caller saw but not what was billed. Exact here (no post-filter to
+            // under-fill), unlike `getCategoriesByTier` above.
+            let query = this.db
                 .collection(this.collection)
                 .where("isBrand", "==", true)
                 .where(CATEGORY_FIELDS.IS_ACTIVE, "==", true)
-                .orderBy(CATEGORY_FIELDS.ORDER, "asc")
-                .get();
+                .orderBy(CATEGORY_FIELDS.ORDER, "asc");
+            if (limit > 0)
+                query = query.limit(limit);
+            const snapshot = await query.get();
             const brands = snapshot.docs.map((doc) => this.mapDoc(doc));
             return limit > 0 ? brands.slice(0, limit) : brands;
         }

package/dist/features/faq/utils/getHomepageFaqsCached.d.ts

@@ -0,0 +1,20 @@
+/**
+ * React.cache deduplication — one Firestore read per RSC request tree.
+ *
+ * 🛑 `getHomepageFAQs()` was called TWICE on every homepage render, from two
+ * modules that could not see each other: `src/app/[locale]/page.tsx` builds the
+ * FAQ JSON-LD from it, and `MarketplaceHomepageView` renders the FAQ section
+ * from it. Two call sites, no shared wrapper, so two real queries — and the
+ * markup and the visible content had no structural guarantee of agreeing, which
+ * is a requirement Google actually enforces.
+ *
+ * Caching the NARROWEST shared call rather than either caller is the pattern
+ * CLAUDE.md § React.cache discipline prescribes, and it is a straight copy of
+ * `getSiteSettingsGlobal` (features/admin/utils/) — which exists for exactly the
+ * same reason and is the precedent this follows.
+ *
+ * Takes no arguments on purpose: `React.cache` memoises per argument list, so a
+ * parameterised version would give each distinct call its own entry and dedupe
+ * nothing.
+ */
+export declare const getHomepageFaqsCached: () => Promise<import("..").FAQDocument[]>;

package/dist/features/faq/utils/getHomepageFaqsCached.js

@@ -0,0 +1,22 @@
+import { cache } from "react";
+import { faqsRepository } from "../repository/faqs.repository";
+/**
+ * React.cache deduplication — one Firestore read per RSC request tree.
+ *
+ * 🛑 `getHomepageFAQs()` was called TWICE on every homepage render, from two
+ * modules that could not see each other: `src/app/[locale]/page.tsx` builds the
+ * FAQ JSON-LD from it, and `MarketplaceHomepageView` renders the FAQ section
+ * from it. Two call sites, no shared wrapper, so two real queries — and the
+ * markup and the visible content had no structural guarantee of agreeing, which
+ * is a requirement Google actually enforces.
+ *
+ * Caching the NARROWEST shared call rather than either caller is the pattern
+ * CLAUDE.md § React.cache discipline prescribes, and it is a straight copy of
+ * `getSiteSettingsGlobal` (features/admin/utils/) — which exists for exactly the
+ * same reason and is the precedent this follows.
+ *
+ * Takes no arguments on purpose: `React.cache` memoises per argument list, so a
+ * parameterised version would give each distinct call its own entry and dedupe
+ * nothing.
+ */
+export const getHomepageFaqsCached = cache(() => faqsRepository.getHomepageFAQs());