@mohasinac/appkit 4.62.1 → 4.63.1

package/dist/features/homepage/schemas/index.d.ts

@@ -867,16 +867,16 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
         opacity?: number | undefined;
         subtitle?: string | undefined;
     } | undefined;
+    settings?: {
+        height?: "medium" | "viewport" | "tall" | undefined;
+        autoplayDelayMs?: number | undefined;
+    } | undefined;
     analytics?: {
         views: number;
         lastViewed?: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough"> | undefined;
     } | undefined;
-    settings?: {
-        height?: "medium" | "viewport" | "tall" | undefined;
-        autoplayDelayMs?: number | undefined;
-    } | undefined;
     carouselId?: string | null | undefined;
 }, {
     id: string;
@@ -976,16 +976,16 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
         opacity?: number | undefined;
         subtitle?: string | undefined;
     } | undefined;
+    settings?: {
+        height?: "medium" | "viewport" | "tall" | undefined;
+        autoplayDelayMs?: number | undefined;
+    } | undefined;
     analytics?: {
         views: number;
         lastViewed?: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough"> | undefined;
     } | undefined;
-    settings?: {
-        height?: "medium" | "viewport" | "tall" | undefined;
-        autoplayDelayMs?: number | undefined;
-    } | undefined;
     carouselId?: string | null | undefined;
 }>;
 export type HomepageSectionFromSchema = z.infer<typeof homepageSectionFirestoreSchema>;

package/dist/features/inventory/schemas/stock-reservation.d.ts

@@ -0,0 +1,114 @@
+/**
+ * A HOLD on stock that is not yet an order.
+ *
+ * ## 🛑 Why this has to exist before S5b (Part 6)
+ *
+ * The plan calls this "the largest hidden cost" of the shared-purchase work,
+ * and the reason is that today there is no way to hold stock at all. The only
+ * mechanism is: `onOrderCreate` decrements `availableQuantity`, and
+ * `pendingOrderTimeout` puts it back if the buyer does not pay inside the
+ * 15-minute window. Both are keyed to an ORDER.
+ *
+ * A shared purchase runs for DAYS while co-buyers pay. With no primitive,
+ * either the coordinator places an order up front — which starts a 15-minute
+ * payment clock on a multi-day agreement — or nothing is held, and the item is
+ * sold out from under the arrangement by an ordinary buyer who happened to
+ * check out first. Neither is a product.
+ *
+ * ## The invariant, and where it already lives
+ *
+ * `products.repository.ts` already states it:
+ *
+ *     reserved = stockQuantity - availableQuantity
+ *
+ * …as the comment on `resolveStockResync` puts it, *"the difference between
+ * the two IS the outstanding reservation"*. This collection does not invent a
+ * new idea; it makes that difference ADDRESSABLE — every held unit gets a row
+ * saying who holds it and until when, instead of being an anonymous gap
+ * between two numbers that only an order can close.
+ *
+ * 🛑 So a reservation MUST move `availableQuantity` in the same transaction
+ * that writes its row. A row without the decrement holds nothing; a decrement
+ * without a row is the anonymous gap again, and nothing can expire it.
+ *
+ * ## Why a TTL rather than a cancel button
+ *
+ * A hold with no expiry is a leak: the holder closes the tab, and those units
+ * are off the shelf until a human notices. `expiresAt` means the worst case is
+ * bounded by the sweep interval, and the seller never has to ask anyone to
+ * release anything.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const STOCK_RESERVATION_COLLECTION = "stockReservations";
+/**
+ * Who is holding, and therefore what releases it.
+ *
+ * 🛑 A plain `holderId: string` was the first draft and it is wrong: the sweep
+ * and the release path both need to know WHICH system owns the hold before
+ * they can decide whether it is still legitimate. A discriminator makes
+ * "release every hold belonging to arrangement X" expressible; an opaque id
+ * makes it a string-prefix convention nobody enforces.
+ */
+export declare const RESERVATION_HOLDER_KINDS: readonly ["shared-purchase", "manual"];
+export type ReservationHolderKind = (typeof RESERVATION_HOLDER_KINDS)[number];
+/**
+ * 🛑 `cart` and `order` are deliberately NOT holder kinds.
+ *
+ * A cart holds nothing today — adding an item does not decrement anything —
+ * and making it hold would silently turn every abandoned cart into held
+ * stock. An order already has its own hold through `onOrderCreate` +
+ * `pendingOrderTimeout`; a second mechanism over the same units would
+ * double-decrement, which is exactly the class of bug `resolveStockResync`'s
+ * delta exists to prevent. Add a kind only when the thing that owns it also
+ * owns its release.
+ */
+export declare const RESERVATION_STATUSES: readonly ["held", "consumed", "released", "expired"];
+export type ReservationStatus = (typeof RESERVATION_STATUSES)[number];
+export interface StockReservationDocument extends BaseDocument {
+    productId: string;
+    /** Denormalised so the sweep can restore stock without reading the product first. */
+    quantity: number;
+    holderKind: ReservationHolderKind;
+    /** The arrangement / manual-hold id. Scoped by `holderKind`, never globally unique. */
+    holderId: string;
+    /** Who asked for it — an Auth uid, for the audit trail and for admin release. */
+    createdBy: string;
+    status: ReservationStatus;
+    /**
+     * 🛑 The whole point. A hold with no expiry is a leak: the holder closes the
+     * tab and the units are gone until a human notices.
+     */
+    expiresAt: Date;
+    /**
+     * Set when the hold ENDS, whichever way it ended. One field rather than
+     * three (`consumedAt`/`releasedAt`/`expiredAt`) because `status` already
+     * says which, and three nullable dates is three chances for the one that
+     * matters to be the one nobody set.
+     */
+    endedAt?: Date;
+    /** Free text on a manual release — why an admin took the hold back. */
+    endedReason?: string;
+}
+/** Default hold, when a caller names none. */
+export declare const RESERVATION_DEFAULT_TTL_HOURS = 72;
+/**
+ * 🛑 A ceiling, and it is load-bearing rather than defensive.
+ *
+ * A caller may pass any TTL it likes, which makes "hold this for a year" one
+ * typo away — and a year-long hold is indistinguishable from permanently
+ * deleted stock, because nothing in the UI shows a seller why their own
+ * product is unbuyable. 30 days is longer than any agreement window Part 6
+ * contemplates and short enough that a mistake self-heals.
+ */
+export declare const RESERVATION_MAX_TTL_HOURS: number;
+/** A reservation is only holding stock while it is `held` and unexpired. */
+export declare function isReservationActive(reservation: Pick<StockReservationDocument, "status" | "expiresAt">, now?: Date): boolean;
+/**
+ * Firestore hands back a `Timestamp`, a `Date` or an ISO string depending on
+ * the path a document took to get here, and the adapter that normalises those
+ * is not reachable from this file. Returning `null` on anything unparseable is
+ * the honest answer — and callers treat an unparseable expiry as NOT active,
+ * so the failure mode is a hold released early rather than one held forever.
+ */
+declare function toDate(value: unknown): Date | null;
+export { toDate as reservationExpiryDate };

package/dist/features/inventory/schemas/stock-reservation.js

@@ -0,0 +1,103 @@
+/**
+ * A HOLD on stock that is not yet an order.
+ *
+ * ## 🛑 Why this has to exist before S5b (Part 6)
+ *
+ * The plan calls this "the largest hidden cost" of the shared-purchase work,
+ * and the reason is that today there is no way to hold stock at all. The only
+ * mechanism is: `onOrderCreate` decrements `availableQuantity`, and
+ * `pendingOrderTimeout` puts it back if the buyer does not pay inside the
+ * 15-minute window. Both are keyed to an ORDER.
+ *
+ * A shared purchase runs for DAYS while co-buyers pay. With no primitive,
+ * either the coordinator places an order up front — which starts a 15-minute
+ * payment clock on a multi-day agreement — or nothing is held, and the item is
+ * sold out from under the arrangement by an ordinary buyer who happened to
+ * check out first. Neither is a product.
+ *
+ * ## The invariant, and where it already lives
+ *
+ * `products.repository.ts` already states it:
+ *
+ *     reserved = stockQuantity - availableQuantity
+ *
+ * …as the comment on `resolveStockResync` puts it, *"the difference between
+ * the two IS the outstanding reservation"*. This collection does not invent a
+ * new idea; it makes that difference ADDRESSABLE — every held unit gets a row
+ * saying who holds it and until when, instead of being an anonymous gap
+ * between two numbers that only an order can close.
+ *
+ * 🛑 So a reservation MUST move `availableQuantity` in the same transaction
+ * that writes its row. A row without the decrement holds nothing; a decrement
+ * without a row is the anonymous gap again, and nothing can expire it.
+ *
+ * ## Why a TTL rather than a cancel button
+ *
+ * A hold with no expiry is a leak: the holder closes the tab, and those units
+ * are off the shelf until a human notices. `expiresAt` means the worst case is
+ * bounded by the sweep interval, and the seller never has to ask anyone to
+ * release anything.
+ */
+export const STOCK_RESERVATION_COLLECTION = "stockReservations";
+/**
+ * Who is holding, and therefore what releases it.
+ *
+ * 🛑 A plain `holderId: string` was the first draft and it is wrong: the sweep
+ * and the release path both need to know WHICH system owns the hold before
+ * they can decide whether it is still legitimate. A discriminator makes
+ * "release every hold belonging to arrangement X" expressible; an opaque id
+ * makes it a string-prefix convention nobody enforces.
+ */
+export const RESERVATION_HOLDER_KINDS = ["shared-purchase", "manual"];
+/**
+ * 🛑 `cart` and `order` are deliberately NOT holder kinds.
+ *
+ * A cart holds nothing today — adding an item does not decrement anything —
+ * and making it hold would silently turn every abandoned cart into held
+ * stock. An order already has its own hold through `onOrderCreate` +
+ * `pendingOrderTimeout`; a second mechanism over the same units would
+ * double-decrement, which is exactly the class of bug `resolveStockResync`'s
+ * delta exists to prevent. Add a kind only when the thing that owns it also
+ * owns its release.
+ */
+export const RESERVATION_STATUSES = ["held", "consumed", "released", "expired"];
+/** Default hold, when a caller names none. */
+export const RESERVATION_DEFAULT_TTL_HOURS = 72;
+/**
+ * 🛑 A ceiling, and it is load-bearing rather than defensive.
+ *
+ * A caller may pass any TTL it likes, which makes "hold this for a year" one
+ * typo away — and a year-long hold is indistinguishable from permanently
+ * deleted stock, because nothing in the UI shows a seller why their own
+ * product is unbuyable. 30 days is longer than any agreement window Part 6
+ * contemplates and short enough that a mistake self-heals.
+ */
+export const RESERVATION_MAX_TTL_HOURS = 24 * 30;
+/** A reservation is only holding stock while it is `held` and unexpired. */
+export function isReservationActive(reservation, now = new Date()) {
+    if (reservation.status !== "held")
+        return false;
+    const expires = toDate(reservation.expiresAt);
+    return expires !== null && expires.getTime() > now.getTime();
+}
+/**
+ * Firestore hands back a `Timestamp`, a `Date` or an ISO string depending on
+ * the path a document took to get here, and the adapter that normalises those
+ * is not reachable from this file. Returning `null` on anything unparseable is
+ * the honest answer — and callers treat an unparseable expiry as NOT active,
+ * so the failure mode is a hold released early rather than one held forever.
+ */
+function toDate(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    if (value && typeof value.toDate === "function") {
+        const d = value.toDate();
+        return d instanceof Date && !Number.isNaN(d.getTime()) ? d : null;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+    return null;
+}
+export { toDate as reservationExpiryDate };

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;