@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/features/jobs/schemas/firestore.d.ts

@@ -23,6 +23,20 @@ export declare const JobStatusValues: {
     readonly PROCESSING: "processing";
     readonly DONE: "done";
     readonly FAILED: "failed";
+    /**
+     * Phase 8 — attempts exhausted. The dead-letter state.
+     *
+     * 🛑 `failed` and `dead` are DIFFERENT facts and conflating them is what
+     * made a failed job terminal with no signal. `failed` now means "this
+     * attempt failed, and a retry is scheduled or the failure was permanent";
+     * `dead` means "we have stopped trying" and is the only one that opens a
+     * case.
+     *
+     * A reader that treats every non-`done` as hopeless loses that distinction —
+     * which is why the retention sweep excludes `dead` while an open case
+     * references it: the row is the evidence.
+     */
+    readonly DEAD: "dead";
 };
 export type JobStatus = (typeof JobStatusValues)[keyof typeof JobStatusValues];
 export interface JobResult {
@@ -52,7 +66,55 @@ export interface JobDocument extends BaseDocument {
     error?: string;
     startedAt?: Date;
     finishedAt?: Date;
+    /**
+     * 1-based. Absent means 1 — every job written before this field is a first
+     * attempt, which is both true and what every reader should assume.
+     */
+    attempt?: number;
+    /** Defaults to `JOB_MAX_ATTEMPTS`; a jobType may lower it. */
+    maxAttempts?: number;
+    /**
+     * When a retry becomes eligible.
+     *
+     * 🛑 A retry is a **NEW DOCUMENT**, not a mutation of this one, because
+     * `onJobCreated` fires on CREATE — re-running a job by flipping its status
+     * back to `pending` would never wake the trigger, and the job would sit
+     * `pending` forever looking scheduled. So this field lives on the NEW
+     * document and a sweep is what moves it from scheduled to running.
+     */
+    nextAttemptAt?: Date;
+    /**
+     * The document this is a retry OF — present on every attempt after the
+     * first, and absent on the original.
+     *
+     * 🛑 Points at the ORIGINAL, not at the immediately previous attempt. A
+     * flat chain means "show me every attempt of this job" is one equality
+     * query, where a linked list would need N reads to walk; and the question
+     * anyone actually asks is "did this job eventually work", which is about the
+     * original.
+     */
+    parentJobId?: string;
+    /** Why this attempt failed, kept per attempt so a pattern is visible. */
+    lastError?: string;
 }
+/**
+ * Attempts before a job is declared dead.
+ *
+ * Three, with `JOB_BACKOFF_MS` below: a transient fault usually clears in
+ * minutes, and a fourth attempt an hour later is far more likely to be the
+ * same permanent fault again than a different outcome.
+ */
+export declare const JOB_MAX_ATTEMPTS = 3;
+/**
+ * Delay before attempt 2 and attempt 3.
+ *
+ * 🛑 Indexed by `attempt - 1`, so the array length must be at least
+ * `JOB_MAX_ATTEMPTS - 1`. The last value is reused if it is shorter, rather
+ * than producing `undefined` — a `nextAttemptAt` of `Invalid Date` would make
+ * the sweep's `<= now` comparison false forever and the retry would never run,
+ * which is the silent-stall shape this whole phase exists to remove.
+ */
+export declare const JOB_BACKOFF_MS: readonly [number, number];
 export declare const JOB_FIELDS: {
     readonly JOB_TYPE: "jobType";
     readonly STATUS: "status";
@@ -63,10 +125,28 @@ export declare const JOB_FIELDS: {
     readonly FINISHED_AT: "finishedAt";
     readonly CREATED_AT: "createdAt";
     readonly UPDATED_AT: "updatedAt";
+    readonly ATTEMPT: "attempt";
+    readonly MAX_ATTEMPTS: "maxAttempts";
+    readonly NEXT_ATTEMPT_AT: "nextAttemptAt";
+    readonly PARENT_JOB_ID: "parentJobId";
     readonly STATUS_VALUES: {
         readonly PENDING: "pending";
         readonly PROCESSING: "processing";
         readonly DONE: "done";
         readonly FAILED: "failed";
+        /**
+         * Phase 8 — attempts exhausted. The dead-letter state.
+         *
+         * 🛑 `failed` and `dead` are DIFFERENT facts and conflating them is what
+         * made a failed job terminal with no signal. `failed` now means "this
+         * attempt failed, and a retry is scheduled or the failure was permanent";
+         * `dead` means "we have stopped trying" and is the only one that opens a
+         * case.
+         *
+         * A reader that treats every non-`done` as hopeless loses that distinction —
+         * which is why the retention sweep excludes `dead` while an open case
+         * references it: the row is the evidence.
+         */
+        readonly DEAD: "dead";
     };
 };

package/dist/features/jobs/schemas/firestore.js

@@ -21,7 +21,39 @@ export const JobStatusValues = {
     PROCESSING: "processing",
     DONE: "done",
     FAILED: "failed",
+    /**
+     * Phase 8 — attempts exhausted. The dead-letter state.
+     *
+     * 🛑 `failed` and `dead` are DIFFERENT facts and conflating them is what
+     * made a failed job terminal with no signal. `failed` now means "this
+     * attempt failed, and a retry is scheduled or the failure was permanent";
+     * `dead` means "we have stopped trying" and is the only one that opens a
+     * case.
+     *
+     * A reader that treats every non-`done` as hopeless loses that distinction —
+     * which is why the retention sweep excludes `dead` while an open case
+     * references it: the row is the evidence.
+     */
+    DEAD: "dead",
 };
+/**
+ * Attempts before a job is declared dead.
+ *
+ * Three, with `JOB_BACKOFF_MS` below: a transient fault usually clears in
+ * minutes, and a fourth attempt an hour later is far more likely to be the
+ * same permanent fault again than a different outcome.
+ */
+export const JOB_MAX_ATTEMPTS = 3;
+/**
+ * Delay before attempt 2 and attempt 3.
+ *
+ * 🛑 Indexed by `attempt - 1`, so the array length must be at least
+ * `JOB_MAX_ATTEMPTS - 1`. The last value is reused if it is shorter, rather
+ * than producing `undefined` — a `nextAttemptAt` of `Invalid Date` would make
+ * the sweep's `<= now` comparison false forever and the retry would never run,
+ * which is the silent-stall shape this whole phase exists to remove.
+ */
+export const JOB_BACKOFF_MS = [5 * 60 * 1000, 30 * 60 * 1000];
 export const JOB_FIELDS = {
     JOB_TYPE: "jobType",
     STATUS: "status",
@@ -32,5 +64,10 @@ export const JOB_FIELDS = {
     FINISHED_AT: "finishedAt",
     CREATED_AT: "createdAt",
     UPDATED_AT: "updatedAt",
+    // Phase 8 retry/DLQ. `NEXT_ATTEMPT_AT` is the sweep's query field.
+    ATTEMPT: "attempt",
+    MAX_ATTEMPTS: "maxAttempts",
+    NEXT_ATTEMPT_AT: "nextAttemptAt",
+    PARENT_JOB_ID: "parentJobId",
     STATUS_VALUES: JobStatusValues,
 };

package/dist/features/layout/AppLayoutShell.d.ts

@@ -94,6 +94,14 @@ export interface AppLayoutShellProps {
     userWishlistHref?: string;
     /** Href for the user settings page — auto-generates PROFILE section in sidebar. */
     userSettingsHref?: string;
+    /**
+     * Href for the user's OWN reviews list — the target of the "Reviews" stat.
+     *
+     * The stat pointed at `${profileHref}#reviews` before, an anchor the profile
+     * page does not render, so the count linked to the top of an unrelated page.
+     * Omitting this prop hides the tile rather than guessing at a route.
+     */
+    userReviewsHref?: string;
     /** Locale switcher node rendered at the bottom of the sidebar. */
     sidebarLocaleSlot?: React.ReactNode;
     /** When true, shows theme toggle button in the sidebar footer. */
@@ -148,4 +156,4 @@ export interface AppLayoutShellProps {
         };
     };
 }
-export declare function AppLayoutShell({ children, navItems, sidebarItems, sidebarSections, sidebarPrimaryActions, sidebarTitle, hiddenNavItems, user, brandName, brandShortName, siteLogoUrl, logoHref, promotionsHref, cartHref, wishlistHref, messagesHref, unreadMessageCount, userId, profileHref, loginHref, registerHref, homeHref, shopHref, footer, showFooter, searchSlot, searchSlotRenderer, titleBarNavSlot, titleBarNotificationSlot, titleBarDevSlot, titleBarPromoStripText, showThemeToggle, suppressDashboardNav, hideSidebarToggle, onLogout, adminHref, storeHref, sellerHref, userOrdersHref, userWishlistHref, userSettingsHref, sidebarLocaleSlot, showThemeToggleInSidebar, sidebarProfileLabels, eventBannerSlot, showBottomNav, contentClassName, lightBackground, darkBackground, }: AppLayoutShellProps): React.JSX.Element;
+export declare function AppLayoutShell({ children, navItems, sidebarItems, sidebarSections, sidebarPrimaryActions, sidebarTitle, hiddenNavItems, user, brandName, brandShortName, siteLogoUrl, logoHref, promotionsHref, cartHref, wishlistHref, messagesHref, unreadMessageCount, userId, profileHref, loginHref, registerHref, homeHref, shopHref, footer, showFooter, searchSlot, searchSlotRenderer, titleBarNavSlot, titleBarNotificationSlot, titleBarDevSlot, titleBarPromoStripText, showThemeToggle, suppressDashboardNav, hideSidebarToggle, onLogout, adminHref, storeHref, sellerHref, userOrdersHref, userWishlistHref, userSettingsHref, userReviewsHref, sidebarLocaleSlot, showThemeToggleInSidebar, sidebarProfileLabels, eventBannerSlot, showBottomNav, contentClassName, lightBackground, darkBackground, }: AppLayoutShellProps): React.JSX.Element;

package/dist/features/layout/AppLayoutShell.js

@@ -17,6 +17,7 @@ const ROLE_DOT_BG_CLASS = {
 import { useTheme } from "../../_internal/client/theme/index.js";
 import { useAuth } from "../../react/contexts/SessionContext.js";
 import { useVisualViewportInset } from "../../react/hooks/useVisualViewportInset.js";
+import { useListingTypeFlags } from "../../react/hooks/useListingTypeFlags.js";
 import { isBuyerUser } from "../auth/role-predicates.js";
 import { NavbarWithSettings } from "./NavbarWithSettings.js";
 import SideActionDock from "./SideActionDock.js";
@@ -135,13 +136,20 @@ function SidebarUserHeader({ user, onClose, profileHref, }) {
 function SidebarGuestHeader({ sidebarTitle, onClose, }) {
     return (_jsxs(Row, { align: "center", justify: "between", children: [_jsx(Div, { textWeight: "semibold", textSize: "sm", color: "primary", children: sidebarTitle }), _jsx("button", { type: "button", "aria-label": "Close menu", onClick: onClose, className: "rounded-full p-[var(--appkit-space-2)] hover:bg-surface-hover hover:text-zinc-900 text-[var(--appkit-color-text-muted)] dark:hover:text-zinc-100 transition-all hover:rotate-90", children: _jsx("svg", { className: "w-4 h-4 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M6 18L18 6M6 6l12 12" }) }) })] }));
 }
-function SidebarContent({ sidebarItems, sidebarSections, sidebarPrimaryActions, user, activeHref, profileHref, userOrdersHref, userWishlistHref, userSettingsHref, adminHref, storeHref, sellerHref, sidebarLocaleSlot, showThemeToggleInSidebar, sidebarProfileLabels, theme, activeThemeName, toggleTheme, onLogout, onAfterLogout, }) {
+function SidebarContent({ sidebarItems, sidebarSections, sidebarPrimaryActions, user, activeHref, profileHref, userOrdersHref, userWishlistHref, userSettingsHref, userReviewsHref, adminHref, storeHref, sellerHref, sidebarLocaleSlot, showThemeToggleInSidebar, sidebarProfileLabels, theme, activeThemeName, toggleTheme, onLogout, onAfterLogout, }) {
     const hasLegacyItems = sidebarItems.length > 0;
     const hasSections = !!(sidebarSections && sidebarSections.length > 0);
     const isAuthenticated = !!user;
     const role = user?.role ?? "user";
     const isAdminOrSeller = role === "admin" || role === "seller";
     const resolvedStoreHref = storeHref ?? sellerHref;
+    /*
+     * Defaults to ENABLED while site settings are loading, matching the hook's
+     * own contract — hiding the tile on first paint and popping it in a moment
+     * later is worse than showing it to the handful of installs that have
+     * auctions switched off.
+     */
+    const auctionsEnabled = useListingTypeFlags().isEnabled("auction");
     const labels = {
         sectionTitle: sidebarProfileLabels?.sectionTitle ?? "Profile",
         profile: sidebarProfileLabels?.profile ?? "My Profile",
@@ -177,10 +185,10 @@ function SidebarContent({ sidebarItems, sidebarSections, sidebarPrimaryActions,
                         action.variant === "outline"
                             ? "border hover:bg-surface-hover border-[var(--appkit-color-border)] text-[var(--appkit-color-text)]"
                             : "bg-primary text-white hover:bg-primary-600 dark:bg-primary dark:hover:bg-primary-600 btn-glow",
-                    ].join(" "), children: action.label }, `${action.href}-${action.label}`))) })), isAuthenticated && (_jsx(CollapsibleNavGroup, { title: labels.sectionTitle, hasActive: !!activeProfileLink, children: _jsxs(Ul, { spacing: "2xs", children: [_jsx(Li, { children: _jsx(TextLink, { href: profileHref, variant: "none", className: activeProfileLink?.href === profileHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === profileHref ? "page" : undefined, children: labels.profile }) }), userOrdersHref && (_jsx(Li, { children: _jsx(TextLink, { href: userOrdersHref, variant: "none", className: activeProfileLink?.href === userOrdersHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userOrdersHref ? "page" : undefined, children: labels.orders }) })), userWishlistHref && (_jsx(Li, { children: _jsx(TextLink, { href: userWishlistHref, variant: "none", className: activeProfileLink?.href === userWishlistHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userWishlistHref ? "page" : undefined, children: labels.wishlist }) })), userSettingsHref && (_jsx(Li, { children: _jsx(TextLink, { href: userSettingsHref, variant: "none", className: activeProfileLink?.href === userSettingsHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userSettingsHref ? "page" : undefined, children: labels.settings }) }))] }) })), isAuthenticated && user?.stats && (_jsxs(Div, { layout: "grid", gap: "2", className: "grid-cols-2", children: [user.stats.totalOrders != null && userOrdersHref && (_jsxs(TextLink, { href: userOrdersHref, variant: "none", className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.totalOrders }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Orders" })] })), user.stats.reviewsCount != null && (_jsxs(TextLink, { href: `${profileHref}#reviews`, variant: "none", className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.reviewsCount }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Reviews" })] })), user.stats.auctionsWon != null && userOrdersHref && (_jsxs(TextLink, { href: `${userOrdersHref}?orderType=auction`, variant: "none", className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.auctionsWon }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Auctions Won" })] })), user.stats.itemsSold != null && resolvedStoreHref && (_jsxs(TextLink, { href: resolvedStoreHref, variant: "none", className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.itemsSold }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Items Sold" })] }))] })), isAuthenticated && isAdminOrSeller && (adminHref || resolvedStoreHref) && (_jsx(CollapsibleNavGroup, { title: labels.dashboardSectionTitle, hasActive: !!activeDashboardLink, children: _jsxs(Ul, { spacing: "2xs", children: [adminHref && role === "admin" && (_jsx(Li, { children: _jsx(TextLink, { href: adminHref, variant: "none", className: activeDashboardLink?.href === adminHref ? navItemActiveClass : navItemClass, "aria-current": activeDashboardLink?.href === adminHref ? "page" : undefined, children: labels.adminDashboard }) })), resolvedStoreHref && isAdminOrSeller && (_jsx(Li, { children: _jsx(TextLink, { href: resolvedStoreHref, variant: "none", className: activeDashboardLink?.href === resolvedStoreHref ? navItemActiveClass : navItemClass, "aria-current": activeDashboardLink?.href === resolvedStoreHref ? "page" : undefined, children: labels.storeDashboard }) }))] }) })), normalizedSections.map((section, sectionIndex) => (_jsx(CollapsibleSidebarSection, { section: section, navItemClass: navItemClass, navItemActiveClass: navItemActiveClass, activeHref: activeHref }, `sidebar-section-${sectionIndex}`))), (sidebarLocaleSlot || showThemeToggleInSidebar || (isAuthenticated && onLogout)) && (_jsxs(Stack, { border: "default", className: "border-t border-[var(--appkit-color-border-subtle)]", padding: "t-md", gap: "3", children: [sidebarLocaleSlot, showThemeToggleInSidebar && (_jsxs("button", { type: "button", onClick: toggleTheme, className: "flex w-full items-center justify-end gap-[var(--appkit-space-3)] rounded-lg px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text-muted)] transition-colors hover:bg-primary-surface hover:text-primary-800 dark:hover:text-primary-200", children: [_jsx(Span, { "aria-hidden": "true", children: theme === "dark" ? "☀️" : "🌙" }), activeThemeName] })), isAuthenticated && onLogout && (_jsx("button", { type: "button", onClick: () => { onLogout(); onAfterLogout(); }, className: CLS_LOGOUT_BTN, children: labels.logout }))] }))] }));
+                    ].join(" "), children: action.label }, `${action.href}-${action.label}`))) })), isAuthenticated && (_jsx(CollapsibleNavGroup, { title: labels.sectionTitle, hasActive: !!activeProfileLink, children: _jsxs(Ul, { spacing: "2xs", children: [_jsx(Li, { children: _jsx(TextLink, { href: profileHref, variant: "none", className: activeProfileLink?.href === profileHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === profileHref ? "page" : undefined, children: labels.profile }) }), userOrdersHref && (_jsx(Li, { children: _jsx(TextLink, { href: userOrdersHref, variant: "none", className: activeProfileLink?.href === userOrdersHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userOrdersHref ? "page" : undefined, children: labels.orders }) })), userWishlistHref && (_jsx(Li, { children: _jsx(TextLink, { href: userWishlistHref, variant: "none", className: activeProfileLink?.href === userWishlistHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userWishlistHref ? "page" : undefined, children: labels.wishlist }) })), userSettingsHref && (_jsx(Li, { children: _jsx(TextLink, { href: userSettingsHref, variant: "none", className: activeProfileLink?.href === userSettingsHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userSettingsHref ? "page" : undefined, children: labels.settings }) }))] }) })), isAuthenticated && user?.stats && (_jsxs(Div, { layout: "grid", gap: "2", className: "grid-cols-2", children: [user.stats.totalOrders != null && userOrdersHref && (_jsxs(TextLink, { href: userOrdersHref, variant: "none", className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.totalOrders }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Orders" })] })), user.stats.reviewsCount != null && userReviewsHref && (_jsxs(TextLink, { href: userReviewsHref, variant: "none", className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.reviewsCount }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Reviews" })] })), auctionsEnabled && user.stats.auctionsWon != null && userOrdersHref && (_jsxs(TextLink, { href: `${userOrdersHref}?orderType=auction`, variant: "none", className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.auctionsWon }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Auctions Won" })] }))] })), isAuthenticated && isAdminOrSeller && (adminHref || resolvedStoreHref) && (_jsx(CollapsibleNavGroup, { title: labels.dashboardSectionTitle, hasActive: !!activeDashboardLink, children: _jsxs(Ul, { spacing: "2xs", children: [adminHref && role === "admin" && (_jsx(Li, { children: _jsx(TextLink, { href: adminHref, variant: "none", className: activeDashboardLink?.href === adminHref ? navItemActiveClass : navItemClass, "aria-current": activeDashboardLink?.href === adminHref ? "page" : undefined, children: labels.adminDashboard }) })), resolvedStoreHref && isAdminOrSeller && (_jsx(Li, { children: _jsx(TextLink, { href: resolvedStoreHref, variant: "none", className: activeDashboardLink?.href === resolvedStoreHref ? navItemActiveClass : navItemClass, "aria-current": activeDashboardLink?.href === resolvedStoreHref ? "page" : undefined, children: labels.storeDashboard }) }))] }) })), normalizedSections.map((section, sectionIndex) => (_jsx(CollapsibleSidebarSection, { section: section, navItemClass: navItemClass, navItemActiveClass: navItemActiveClass, activeHref: activeHref }, `sidebar-section-${sectionIndex}`))), (sidebarLocaleSlot || showThemeToggleInSidebar || (isAuthenticated && onLogout)) && (_jsxs(Stack, { border: "default", className: "border-t border-[var(--appkit-color-border-subtle)]", padding: "t-md", gap: "3", children: [sidebarLocaleSlot, showThemeToggleInSidebar && (_jsxs("button", { type: "button", onClick: toggleTheme, className: "flex w-full items-center justify-end gap-[var(--appkit-space-3)] rounded-lg px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text-muted)] transition-colors hover:bg-primary-surface hover:text-primary-800 dark:hover:text-primary-200", children: [_jsx(Span, { "aria-hidden": "true", children: theme === "dark" ? "☀️" : "🌙" }), activeThemeName] })), isAuthenticated && onLogout && (_jsx("button", { type: "button", onClick: () => { onLogout(); onAfterLogout(); }, className: CLS_LOGOUT_BTN, children: labels.logout }))] }))] }));
 }
 // ─── Main component ────────────────────────────────────────────────────────────
-export function AppLayoutShell({ children, navItems, sidebarItems = [], sidebarSections, sidebarPrimaryActions, sidebarTitle = "Navigation", hiddenNavItems, user, brandName, brandShortName, siteLogoUrl, logoHref, promotionsHref, cartHref, wishlistHref, messagesHref, unreadMessageCount, userId, profileHref, loginHref, registerHref, homeHref, shopHref, footer, showFooter = true, searchSlot, searchSlotRenderer, titleBarNavSlot, titleBarNotificationSlot, titleBarDevSlot, titleBarPromoStripText, showThemeToggle = false, suppressDashboardNav = false, hideSidebarToggle = false, onLogout, adminHref, storeHref, sellerHref, userOrdersHref, userWishlistHref, userSettingsHref, sidebarLocaleSlot, showThemeToggleInSidebar = false, sidebarProfileLabels, eventBannerSlot, showBottomNav = true, contentClassName, lightBackground = DEFAULT_LIGHT_BG, darkBackground = DEFAULT_DARK_BG, }) {
+export function AppLayoutShell({ children, navItems, sidebarItems = [], sidebarSections, sidebarPrimaryActions, sidebarTitle = "Navigation", hiddenNavItems, user, brandName, brandShortName, siteLogoUrl, logoHref, promotionsHref, cartHref, wishlistHref, messagesHref, unreadMessageCount, userId, profileHref, loginHref, registerHref, homeHref, shopHref, footer, showFooter = true, searchSlot, searchSlotRenderer, titleBarNavSlot, titleBarNotificationSlot, titleBarDevSlot, titleBarPromoStripText, showThemeToggle = false, suppressDashboardNav = false, hideSidebarToggle = false, onLogout, adminHref, storeHref, sellerHref, userOrdersHref, userWishlistHref, userSettingsHref, userReviewsHref, sidebarLocaleSlot, showThemeToggleInSidebar = false, sidebarProfileLabels, eventBannerSlot, showBottomNav = true, contentClassName, lightBackground = DEFAULT_LIGHT_BG, darkBackground = DEFAULT_DARK_BG, }) {
     // QueryClientProvider used to be created here so AppLayoutShell could stand
     // alone. The real cause of the 2026-06-10/11 "No QueryClient set" prod crash
     // turned out to be a peer-dep duplicate of @tanstack/query-core under
@@ -228,7 +236,7 @@ export function AppLayoutShell({ children, navItems, sidebarItems = [], sidebarS
     // by its countdown alone got no clearance). That mirror is gone: BottomChrome
     // measures the real tier and publishes --bottom-chrome-height, and the footer
     // reserves space from that. Nothing needs to guess any more.
-    const sidebarContent = (_jsx(SidebarContent, { sidebarItems: sidebarItems, sidebarSections: sidebarSections, sidebarPrimaryActions: sidebarPrimaryActions, user: user, activeHref: pathname ?? "", profileHref: profileHref, userOrdersHref: userOrdersHref, userWishlistHref: userWishlistHref, userSettingsHref: userSettingsHref, adminHref: adminHref, storeHref: storeHref, sellerHref: sellerHref, sidebarLocaleSlot: sidebarLocaleSlot, showThemeToggleInSidebar: showThemeToggleInSidebar, sidebarProfileLabels: sidebarProfileLabels, theme: theme, activeThemeName: activeTheme.name, toggleTheme: toggleTheme, onLogout: onLogout, onAfterLogout: () => setSidebarOpen(false) }));
+    const sidebarContent = (_jsx(SidebarContent, { sidebarItems: sidebarItems, sidebarSections: sidebarSections, sidebarPrimaryActions: sidebarPrimaryActions, user: user, activeHref: pathname ?? "", profileHref: profileHref, userOrdersHref: userOrdersHref, userWishlistHref: userWishlistHref, userSettingsHref: userSettingsHref, userReviewsHref: userReviewsHref, adminHref: adminHref, storeHref: storeHref, sellerHref: sellerHref, sidebarLocaleSlot: sidebarLocaleSlot, showThemeToggleInSidebar: showThemeToggleInSidebar, sidebarProfileLabels: sidebarProfileLabels, theme: theme, activeThemeName: activeTheme.name, toggleTheme: toggleTheme, onLogout: onLogout, onAfterLogout: () => setSidebarOpen(false) }));
     const normalizedLightBackground = {
         type: lightBackground.type,
         value: lightBackground.value,

package/dist/features/layout/BottomActions.js

@@ -233,7 +233,8 @@ export default function BottomActions() {
      * own reveal — bulk mode is a state the user just entered deliberately, and
      * making them scroll to act on it would be a puzzle.
      */
-    const revealed = useCtaReveal(hasContent && !isBulkMode, ctaAnchorId) || isBulkMode;
+    const { revealed: ctaRevealed } = useCtaReveal(hasContent && !isBulkMode, ctaAnchorId);
+    const revealed = ctaRevealed || isBulkMode;
     const isVisible = hasContent && revealed;
     // A panel left open after its content is withdrawn (bulk mode taking over, or
     // the page clearing it) would sit there as an empty sheet.

package/dist/features/layout/BottomNavbar.d.ts

@@ -32,12 +32,20 @@ export interface BottomNavbarUser {
         };
         zoom: number;
     } | null;
+    /**
+     * The account holder's own activity AS A BUYER, derived live by
+     * `/api/user/profile`. `undefined` on a member means the count could not be
+     * taken — render nothing, never 0.
+     *
+     * 🛑 `itemsSold` and `rating` were removed, not forgotten. `itemsSold` is a
+     * SELLER number and had no business in the account holder's own profile
+     * block (see `AppLayoutShell`); `rating` had no writer anywhere in either
+     * repo, so its `!= null` guard meant the tile could never render.
+     */
     stats?: {
         totalOrders?: number;
         auctionsWon?: number;
-        itemsSold?: number;
         reviewsCount?: number;
-        rating?: number;
     } | null;
 }
 export interface BottomNavbarProps {

package/dist/features/layout/SideActionDock.js

@@ -54,7 +54,7 @@ import { useClickOutside } from "../../react/index.js";
 import { useHandMode } from "../../_internal/client/hand-mode/index.js";
 import { useCtaReveal } from "./useCtaReveal.js";
 import { useIsDesktop } from "./useIsDesktop.js";
-import { ActionRow, Div, IconButton, Row, Span, Stack, Text, Button } from "../../ui/index.js";
+import { ActionRow, Div, ICON_SIZE, IconButton, Row, Span, Stack, Text, Button } from "../../ui/index.js";
 const PANEL_SURFACE = "bg-[color-mix(in_srgb,var(--appkit-color-bg)_94%,transparent)] backdrop-blur-md border border-[var(--appkit-color-border)]";
 const FLEX_CENTER = "flex items-center justify-center";
 const CLS_COUNT_BADGE = "bg-error-solid text-error-on-solid";
@@ -143,8 +143,40 @@ export default function SideActionDock() {
         !!infoLabel ||
         !!secondaryLabel;
     // Rule 3 — a selection is its own reveal.
-    const revealed = useCtaReveal(hasContent && !isBulkMode, ctaAnchorId) || isBulkMode;
+    const { revealed: ctaRevealed, hasAnchor, scrollToAnchor, } = useCtaReveal(hasContent && !isBulkMode, ctaAnchorId);
+    const revealed = ctaRevealed || isBulkMode;
     const isVisible = isDesktop && hasContent && revealed;
+    /*
+     * ── Rule 4 — a page with a REAL Buy button gets a way BACK to it ─────────
+     *
+     * On a detail page the dock was a second copy of the CTA you had just
+     * scrolled past, which is the one thing rule 2 says a floating control must
+     * not be: `useCtaReveal` already means "you have met the Buy button and left
+     * it", so re-offering the purchase mid-screen answers a question the user
+     * did not ask. Taking them back to the real control answers the one they
+     * did — and it keeps the purchase decision on the page's own CTA, beside
+     * the price, the variant and the stock state that qualify it.
+     *
+     * 🛑 Gated on `hasAnchor`, NOT on a route or a listing type. A bulk screen
+     * marks no anchor, so it keeps the centred dock carrying its actions — which
+     * is correct, because there was never an inline control there to return to.
+     * `ctaAnchorProps` has exactly one caller today (`ProductDetailPageView`),
+     * so this branch is opt-in by construction and ~70 admin bulk bars cannot
+     * reach it.
+     *
+     * It sits in the bottom-right cluster above `BackToTop` and shares that
+     * control's bottom-tier `calc()` verbatim, so the two stack rather than
+     * overlap — and rule 1's objection (a bottom-anchored bar reads as a browser
+     * download bar) does not apply to a single round puck in the corner that is
+     * already where the scroll affordance lives.
+     *
+     * 🛑 The RETURN for this branch is deliberately deferred to just above the
+     * main one. An early return here would sit above this component's remaining
+     * `useEffect`s, so the hook order would differ between a detail page and a
+     * bulk screen — React's "rendered fewer hooks than expected" crash, and the
+     * kind that only shows up on the page nobody opened during review.
+     */
+    const isBackToCta = isDesktop && hasAnchor && !isBulkMode;
     // Rule 1 — opposite the sidebar, which docks to the hand-mode side.
     const dockSideClass = hand === "left" ? "right-0" : "left-0";
     const panelAlignClass = hand === "left" ? "items-end" : "items-start";
@@ -216,6 +248,24 @@ export default function SideActionDock() {
     const fabLabel = isBulkMode
         ? `${bulk?.selectedCount ?? 0} selected — bulk actions`
         : (primaryAction?.label ?? infoLabel ?? "Page actions");
+    // Rule 4's deferred return — below every hook, for the reason given above.
+    if (isBackToCta) {
+        if (!ctaRevealed)
+            return null;
+        return (_jsx(Div, { className: [
+                "fixed pointer-events-auto z-[var(--appkit-z-back-to-top)]",
+                hand === "left" ? "left-4" : "right-4",
+                /*
+                 * `BackToTop`'s own expression verbatim — including its `4rem`
+                 * default for `--bottom-nav-height`, not the `0px` the dock's other
+                 * branch would imply — plus 3.5rem to clear that control's touch
+                 * box and its gap. Copying the expression rather than inventing one
+                 * is what keeps the two stacked when the tier changes height.
+                 */
+                "bottom-[calc(var(--keyboard-inset-height,0px)+var(--bottom-nav-height,4rem)+var(--bottom-chrome-height,0px)+var(--appkit-space-4)+3.5rem)]",
+                "transition-[bottom] duration-300 ease-out",
+            ].join(" "), "data-section": "back-to-cta", children: _jsxs(Button, { type: "button", variant: "primary", size: "sm", onClick: scrollToAnchor, "aria-label": `Back to ${primaryAction?.label ?? "the buy button"}`, children: [_jsx(ChevronUp, { "aria-hidden": "true", size: ICON_SIZE.sm }), `Back to ${primaryAction?.label ?? "buy"}`] }) }));
+    }
     return (_jsxs(Div, { ref: containerRef, role: "toolbar", "aria-label": isBulkMode ? "Bulk actions" : "Page actions", className: [
             "fixed z-[var(--appkit-z-overlay)] pointer-events-auto flex flex-col",
             panelAlignClass,

package/dist/features/layout/TitleBarLayout.js

@@ -23,6 +23,15 @@ const iconBtn = "flex items-center justify-center w-11 h-11 rounded-lg text-[var
  * `important: true`, so the utility would beat the unlayered rule and the badge
  * would silently stop mirroring. The vertical `-top-0.5` is hand-neutral and stays. */
 const countBadge = "appkit-hand-badge absolute -top-0.5 flex items-center justify-center w-4 h-4 rounded-full bg-error-solid text-error-on-solid text-[10px] font-bold leading-none";
+/**
+ * Applied to the GLYPH, never the link, when the icon is carrying something.
+ *
+ * On the glyph so the count badge stays put: animating the link would swing
+ * the number with it, which turns a readable badge into a moving target. The
+ * keyframes and the `prefers-reduced-motion` opt-out live in
+ * `TitleBarLayout.style.css`.
+ */
+const nudgeWhenCarrying = (count) => count > 0 ? "appkit-nav-icon--has-items" : "";
 /**
  * TitleBarLayout — generic top sticky title-bar shell.
  *
@@ -50,13 +59,13 @@ export function TitleBarLayout({ onToggleSidebar, sidebarOpen, onSearchToggle, s
     // Dedicated notification bell — rendered immediately before the wishlist
     // icon (per layout request). Falls back to invisible when no href is set;
     // the count badge mirrors the wishlist/cart pattern.
-    const notificationsEl = notificationsHref ? (_jsxs(Link, { href: notificationsHref, "aria-label": `Notifications${unreadNotificationCount > 0 ? `, ${unreadNotificationCount} unread` : ""}`, className: `relative ${iconBtn}`, children: [_jsx(Icon, { name: "notification", size: "lg" }), unreadNotificationCount > 0 && (_jsx(Span, { className: countBadge, children: unreadNotificationCount > 99 ? "99+" : unreadNotificationCount }))] })) : null;
+    const notificationsEl = notificationsHref ? (_jsxs(Link, { href: notificationsHref, "aria-label": `Notifications${unreadNotificationCount > 0 ? `, ${unreadNotificationCount} unread` : ""}`, className: `relative ${iconBtn}`, children: [_jsx(Icon, { name: "notification", size: "lg", className: nudgeWhenCarrying(unreadNotificationCount) }), unreadNotificationCount > 0 && (_jsx(Span, { className: countBadge, children: unreadNotificationCount > 99 ? "99+" : unreadNotificationCount }))] })) : null;
     // D9 — chat. Same shape as the notification bell: absent entirely when no
     // href is supplied (the consumer only passes one when
     // `siteSettings.chat.enabled === true`), never rendered-but-disabled.
-    const messagesEl = messagesHref ? (_jsxs(Link, { href: messagesHref, "aria-label": `Messages${unreadMessageCount > 0 ? `, ${unreadMessageCount} unread` : ""}`, className: `relative ${iconBtn}`, children: [_jsx(Icon, { name: "message", size: "lg" }), unreadMessageCount > 0 && (_jsx(Span, { className: countBadge, children: unreadMessageCount > 99 ? "99+" : unreadMessageCount }))] })) : null;
-    const wishlistEl = wishlistHref ? (_jsxs(Link, { href: wishlistHref, "aria-label": `Wishlist${wishlistCount > 0 ? `, ${wishlistCount} items` : ""}`, className: `relative ${iconBtn}`, "data-tour": "nav-wishlist", children: [_jsx(Icon, { name: "wishlist", size: "lg" }), wishlistCount > 0 && (_jsx(Span, { className: countBadge, children: wishlistCount > 9 ? "9+" : wishlistCount }))] })) : null;
-    const cartEl = cartHref ? (_jsxs(Link, { href: cartHref, "aria-label": `Cart${cartCount > 0 ? `, ${cartCount} items` : ""}`, className: `relative ${iconBtn}`, "data-tour": "nav-cart", children: [_jsx(Icon, { name: "cart", size: "lg" }), cartCount > 0 && (_jsx(Span, { className: countBadge, children: cartCount > 9 ? "9+" : cartCount }))] })) : null;
+    const messagesEl = messagesHref ? (_jsxs(Link, { href: messagesHref, "aria-label": `Messages${unreadMessageCount > 0 ? `, ${unreadMessageCount} unread` : ""}`, className: `relative ${iconBtn}`, children: [_jsx(Icon, { name: "message", size: "lg", className: nudgeWhenCarrying(unreadMessageCount) }), unreadMessageCount > 0 && (_jsx(Span, { className: countBadge, children: unreadMessageCount > 99 ? "99+" : unreadMessageCount }))] })) : null;
+    const wishlistEl = wishlistHref ? (_jsxs(Link, { href: wishlistHref, "aria-label": `Wishlist${wishlistCount > 0 ? `, ${wishlistCount} items` : ""}`, className: `relative ${iconBtn}`, "data-tour": "nav-wishlist", children: [_jsx(Icon, { name: "wishlist", size: "lg", className: nudgeWhenCarrying(wishlistCount) }), wishlistCount > 0 && (_jsx(Span, { className: countBadge, children: wishlistCount > 9 ? "9+" : wishlistCount }))] })) : null;
+    const cartEl = cartHref ? (_jsxs(Link, { href: cartHref, "aria-label": `Cart${cartCount > 0 ? `, ${cartCount} items` : ""}`, className: `relative ${iconBtn}`, "data-tour": "nav-cart", children: [_jsx(Icon, { name: "cart", size: "lg", className: nudgeWhenCarrying(cartCount) }), cartCount > 0 && (_jsx(Span, { className: countBadge, children: cartCount > 9 ? "9+" : cartCount }))] })) : null;
     const profileEl = profileHref ? (_jsx(Link, { href: profileHref, "aria-label": user ? `Profile — ${user.displayName ?? user.email}` : "Sign in", className: `relative ${iconBtn}`, "data-tour": "nav-profile", children: _jsx(Avatar, { src: user?.photoURL ?? undefined, name: user?.displayName ?? user?.email ?? undefined, alt: user?.displayName ?? "Profile", size: "sm" }) })) : null;
     const authButtonsEl = !user && (loginHref || registerHref) ? (
     // Mirrors with TB1 so Register (the primary CTA) keeps the outer, more

package/dist/features/layout/TitleBarLayout.style.css

@@ -0,0 +1,59 @@
+/*
+ * Title-bar icons that are carrying something.
+ *
+ * The count badge already states the fact, but it is a 16px dot in the corner
+ * of a dense bar — easy to miss on a phone, and it never changes once drawn.
+ * A small periodic nudge is what makes "you have three things in your cart"
+ * noticeable without adding a second place to read the number.
+ *
+ * 🛑 It is a PERIODIC nudge, not a loop. The movement lasts about half a
+ * second at the END of a 10s cycle and the icon is still for the other ~9.5s,
+ * so it reads as an occasional glance-catcher rather than a permanent
+ * animation sitting in the chrome of every page. A continuously-moving element
+ * in a fixed header is the kind of thing people learn to tune out — or leave.
+ *
+ * 🛑 The percentages and the duration are ONE number, not two. The keyframe
+ * stops are a fraction of the cycle, so changing `10s` alone silently
+ * stretches the nudge itself — at 20s the same stops would swing the bell over
+ * a full second, which reads as a glitch rather than a nudge. Rescale the
+ * stops with it: the window is 4.8% here, which is ~480ms of a 10s cycle.
+ *
+ * The pivot is near the TOP of the glyph so the motion reads as a bell swing
+ * rather than a wobble around the middle, which is what the notification bell
+ * wants and what the cart and wishlist tolerate.
+ */
+@keyframes appkit-nav-icon-nudge {
+  0%,
+  95.2%,
+  100% {
+    transform: rotate(0deg);
+  }
+  96.1% {
+    transform: rotate(-12deg);
+  }
+  97.3% {
+    transform: rotate(9deg);
+  }
+  98.5% {
+    transform: rotate(-5deg);
+  }
+  99.4% {
+    transform: rotate(2deg);
+  }
+}
+
+.appkit-nav-icon--has-items {
+  transform-origin: 50% 15%;
+  animation: appkit-nav-icon-nudge 10s ease-in-out infinite;
+}
+
+/*
+ * 🛑 Honoured, not approximated. This is decoration carrying no information
+ * the badge does not already carry, so for a reader who has asked for less
+ * motion the correct amount is none — not a shorter or gentler version.
+ */
+@media (prefers-reduced-motion: reduce) {
+  .appkit-nav-icon--has-items {
+    animation: none;
+  }
+}

package/dist/features/layout/useCtaReveal.d.ts

@@ -21,4 +21,19 @@
  * page that owns it mounts AFTER this dock — the dock lives in the app shell
  * and the CTA arrives with the route.
  */
-export declare function useCtaReveal(enabled?: boolean, anchorId?: string): boolean;
+export interface CtaRevealState {
+    /** Should the floating dock / bar be on screen? */
+    revealed: boolean;
+    /**
+     * Does this page mark an inline CTA at all?
+     *
+     * The discriminator between a DETAIL page (a real Buy button exists, so the
+     * floating control's job is to take you back to it) and a BULK screen (no
+     * Buy button was ever there, so the floating control IS the only affordance
+     * and must carry the actions itself).
+     */
+    hasAnchor: boolean;
+    /** Scroll the inline CTA back into view. A no-op when there is no anchor. */
+    scrollToAnchor: () => void;
+}
+export declare function useCtaReveal(enabled?: boolean, anchorId?: string): CtaRevealState;

package/dist/features/layout/useCtaReveal.js

@@ -1,29 +1,6 @@
 "use client";
 import { useEffect, useState } from "react";
 import { CTA_ANCHOR_ATTR } from "./cta-anchor.js";
-/**
- * useCtaReveal — "has the user met the Buy button and scrolled past it?"
- *
- * Returns true when the floating action dock should be on screen:
- *
- *  - the page marks NO CTA anchor          → true immediately (nothing to wait
- *    for; an admin bulk bar has no Buy button)
- *  - the page marks one, not yet seen      → false (the inline CTA is doing the
- *    job; a second copy of it beside itself is noise)
- *  - seen, and now out of view             → true
- *  - seen, and scrolled back into view      → false again
- *
- * 🛑 `IntersectionObserver`, never a scroll-position threshold. The bar this
- * replaces used `window.scrollY > 400`, which is a guess about where a CTA sits
- * — wrong on a short page (the dock appears while the real button is still on
- * screen) and wrong on a long gallery (it appears before the CTA is reached).
- * Observing the element itself is the same rule stated exactly, and it costs no
- * scroll handler.
- *
- * The anchor is looked up on an interval-free `MutationObserver` because the
- * page that owns it mounts AFTER this dock — the dock lives in the app shell
- * and the CTA arrives with the route.
- */
 export function useCtaReveal(enabled = true, anchorId) {
     const [anchor, setAnchor] = useState(null);
     const [anchorExists, setAnchorExists] = useState(false);
@@ -74,9 +51,23 @@ export function useCtaReveal(enabled = true, anchorId) {
         io.observe(anchor);
         return () => io.disconnect();
     }, [anchor]);
+    /*
+     * Re-read at CLICK time rather than closing over `anchor`. A client-side
+     * navigation swaps the page under a dock that never unmounts, and the
+     * element captured when the effect last ran may already be detached — a
+     * `scrollIntoView` on a detached node silently does nothing.
+     */
+    const scrollToAnchor = () => {
+        if (typeof document === "undefined")
+            return;
+        const el = anchorId
+            ? document.getElementById(anchorId)
+            : document.querySelector(`[${CTA_ANCHOR_ATTR}]`);
+        el?.scrollIntoView({ behavior: "smooth", block: "center" });
+    };
     if (!enabled)
-        return false;
+        return { revealed: false, hasAnchor: anchorExists, scrollToAnchor };
     if (!anchorExists)
-        return true;
-    return seen && !inView;
+        return { revealed: true, hasAnchor: false, scrollToAnchor };
+    return { revealed: seen && !inView, hasAnchor: true, scrollToAnchor };
 }