@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.1

package/apps/storefront/src/components/admin/AdminSettingsTab.astro

@@ -6,7 +6,7 @@ import { withBase } from "@/lib/basePath";
 const { envelope } = Astro.props;
 const settings = getSettingsViewModel(envelope);
 
-// Checkout styling editor (U12). Renders the current CheckoutStyle and saves it
+// Checkout styling editor. Renders the current CheckoutStyle and saves it
 // through the versioned publish spine (POST /api/preview/checkout-style —
 // colocated with reconcile/promote in the control-plane publish cluster). The
 // endpoint is base-path-prefixed so it stays inside a path-routed tenant, and
@@ -607,7 +607,7 @@ function formatChangeSummary(change: string): string {
     }
   }
 
-  /* Checkout styling editor (U12) */
+  /* Checkout styling editor */
   .checkout-style-editor {
     display: grid;
     gap: 14px;

package/apps/storefront/src/components/admin/orders/OrdersWorkspace.astro

@@ -38,13 +38,13 @@ interface Props {
 const { envelope } = Astro.props;
 const cspNonce = Astro.locals.cspNonce;
 
-// Real orders (U3): fetch this tenant's checkout orders via U2's client
+// Real orders: fetch this tenant's checkout orders via the checkout order client
 // and map to the view model. The per-tenant bearer is a server-side Worker secret;
 // absent (or any upstream error) → an empty-but-valid model so the tab still
-// renders (rich empty/error UX is U5). Live data is gated on the ToT-core orders
-// endpoint (see U1/U2) — until then this resolves empty on qa.
+// renders. Live data is gated on the ToT-core orders
+// endpoint — until then this resolves empty on qa.
 const orderBearer = await readEnv("FOXY_ORDER_API_KEY");
-// Server-backed filters + pagination (U5): the queue filter + cursor come from
+// Server-backed filters + pagination: the queue filter + cursor come from
 // the URL and are applied by the order API server-side; payment/search remain
 // client-side refinements on the returned page.
 const orderFilters = parseOrderFilters(Astro.url.searchParams);
@@ -444,7 +444,7 @@ const holdCount = vm.rows.filter((r) => r.shipState === "hold_review_required").
     const setLoading = () => root.setAttribute("data-orders-loading", "");
 
     // Queue filter + Refresh + pagination are SERVER-backed: they navigate so the
-    // order API re-applies the filter/cursor and returns a fresh page (U5). Any
+    // order API re-applies the filter/cursor and returns a fresh page. Any
     // filter change resets pagination to the first page (drops the cursor).
     const navTo = (mutate) => {
       const url = new URL(window.location.href);

package/apps/storefront/src/components/chrome/NavDropdown.astro

@@ -17,6 +17,7 @@
  */
 import type { ChromeNavItem, ChromeLink } from "@/lib/chrome/model";
 import { withBase } from "@/lib/basePath";
+import { isCurrentNavHref } from "@/lib/chrome/navCurrent";
 
 interface Props {
   item: ChromeNavItem;
@@ -32,6 +33,11 @@ const { basePath } = Astro.locals;
 
 const itemHref = withBase(basePath, item.href);
 const hrefOf = (l: ChromeLink) => (l.external ? l.href : withBase(basePath, l.href));
+// Exact-path match only — a parent item's own href never gets aria-current
+// just because the visitor is on a page nested under it. See navCurrent.ts.
+const currentPath = Astro.url.pathname;
+const itemCurrent = isCurrentNavHref(currentPath, itemHref);
+const isChildCurrent = (l: ChromeLink) => isCurrentNavHref(currentPath, hrefOf(l), l.external);
 const hasMenu =
   (item.columns && item.columns.length > 0) ||
   (item.children && item.children.length > 0);
@@ -77,6 +83,7 @@ const groups = isMega
                     <li>
                       <a
                         href={hrefOf(child)}
+                        aria-current={isChildCurrent(child) ? "page" : undefined}
                         class="flex items-center gap-1.5 rounded-sm px-2 py-1.5 text-sm text-muted transition-colors hover:bg-bg hover:text-primary"
                         {...(child.external ? { rel: "noopener noreferrer" } : { "data-astro-prefetch": true })}
                       >
@@ -100,6 +107,7 @@ const groups = isMega
         <a
           href={itemHref}
           data-astro-prefetch
+          aria-current={itemCurrent ? "page" : undefined}
           class:list={[
             "flex items-center gap-1.5 border-b border-border py-2.5 text-sm font-medium text-text transition-colors last:border-b-0 hover:text-accent",
             item.flag && "text-accent",
@@ -119,6 +127,7 @@ const groups = isMega
       <a
         href={itemHref}
         data-astro-prefetch
+        aria-current={itemCurrent ? "page" : undefined}
         class:list={[
           "inline-flex items-center gap-1 py-2 text-sm transition-colors hover:text-accent group-focus-within:text-accent",
           item.flag && "font-semibold text-accent",
@@ -149,6 +158,7 @@ const groups = isMega
                     <li>
                       <a
                         href={hrefOf(child)}
+                        aria-current={isChildCurrent(child) ? "page" : undefined}
                         class="flex items-center gap-1.5 rounded-sm px-2 py-1 text-sm text-muted transition-colors hover:bg-bg hover:text-primary"
                         {...(child.external ? { rel: "noopener noreferrer" } : { "data-astro-prefetch": true })}
                       >
@@ -171,6 +181,7 @@ const groups = isMega
               <li>
                 <a
                   href={hrefOf(child)}
+                  aria-current={isChildCurrent(child) ? "page" : undefined}
                   class="block rounded-sm px-3 py-1.5 text-sm text-muted transition-colors hover:bg-bg hover:text-primary"
                   {...(child.external ? { rel: "noopener noreferrer" } : { "data-astro-prefetch": true })}
                 >
@@ -187,6 +198,7 @@ const groups = isMega
       <a
         href={itemHref}
         data-astro-prefetch
+        aria-current={itemCurrent ? "page" : undefined}
         class:list={[
           "inline-flex items-center gap-1 py-2 text-sm transition-colors hover:text-accent",
           item.flag && "font-semibold text-accent",

package/apps/storefront/src/components/chrome/SiteFooter.astro

@@ -7,12 +7,16 @@
  * The newsletter is a plain POST form (progressive); it does not embed any cart
  * or checkout logic (commerce boundary).
  */
-import type { ChromeLink, FooterColumn, FooterNewsletter, SocialLink, ChromeLogo } from "@/lib/chrome/model";
+import type { ChromeLink, FooterColumn, FooterNewsletter, SocialLink, ChromeLogo, FooterVariant } from "@/lib/chrome/model";
 import { withBase } from "@/lib/basePath";
 
 interface Props {
   columns: FooterColumn[];
   brand?: { logo?: ChromeLogo; wordmark?: string; contact?: string[] };
+  /** Content-shape variant (lib/chrome/model.ts FooterVariant). Defaults to
+   * "default" — the only member today; threaded through so a future variant
+   * is a drop-in without touching every caller. */
+  variant?: FooterVariant;
   newsletter?: FooterNewsletter;
   /** Payment method labels rendered as chips (e.g. "Visa", "PayPal"). */
   payments?: string[];
@@ -29,6 +33,7 @@ interface Props {
 const {
   columns,
   brand,
+  variant = "default",
   newsletter,
   payments = [],
   social = [],
@@ -43,7 +48,7 @@ const hrefOf = (l: ChromeLink) => (l.external ? l.href : withBase(basePath, l.hr
 const showLogo = !!brand?.logo && /^(https?:|\/)/.test(brand.logo.src);
 ---
 
-<footer class:list={["border-t border-border bg-surface text-text", className]}>
+<footer class:list={["border-t border-border bg-surface text-text", className]} data-variant={variant}>
   <div class="container-prose py-12">
     <div class="grid gap-10 md:grid-cols-[1.4fr_repeat(3,1fr)]">
       <!-- Brand -->

package/apps/storefront/src/components/chrome/SiteHeader.astro

@@ -3,7 +3,7 @@
  * <SiteHeader> — logo/wordmark + search island + account/auth + cart-count
  * affordance, with the primary <MegaMenu> nav below and a mobile drawer (the
  * <MobileNav> island). Tenant-agnostic; theme-token skinned. This is the
- * CANONICAL site header (unit I4) — the former `components/nav/Header.astro`
+ * CANONICAL site header — the former `components/nav/Header.astro`
  * app-Layout implementation is retired; every feature it had (search typeahead,
  * mobile drawer with focus-trap/scroll-lock, the session-aware auth entry point,
  * the saved-items/wishlist cue, marketing header CTAs, a dark header variant)
@@ -13,8 +13,9 @@
  * COMMERCE BOUNDARY: the cart is a LINK only — no cart state, no add-to-cart.
  * The count is a static affordance the managed cart can hydrate later.
  */
-import type { ChromeNavItem, ChromeLogo, ChromeCta } from "@/lib/chrome/model";
+import type { ChromeNavItem, ChromeLogo, ChromeCta, HeaderVariant } from "@/lib/chrome/model";
 import MegaMenu from "@/components/chrome/MegaMenu.astro";
+import NavDropdown from "@/components/chrome/NavDropdown.astro";
 import SearchTypeahead from "@/components/islands/SearchTypeahead.tsx";
 import MobileNav from "@/components/islands/MobileNav.tsx";
 import { withBase } from "@/lib/basePath";
@@ -23,6 +24,11 @@ interface Props {
   logo?: ChromeLogo;
   /** Fallback wordmark text when no logo image. */
   wordmark?: string;
+  /**
+   * Home/brand link target (lib/chrome/model.ts ChromeBrand.href). Run through
+   * `withBase` same as every other same-origin href. Omit to default to "/".
+   */
+  brandHref?: string;
   nav?: ChromeNavItem[];
   /** Search form action (GET). Omit to hide search. Mounts the live SearchTypeahead island. */
   searchAction?: string;
@@ -41,6 +47,15 @@ interface Props {
   cartCount?: number;
   /** A brand-fixed "dark" header bar (e.g. a navy bar with a light logo) vs. the default light bar. */
   variant?: "light" | "dark";
+  /**
+   * Content-shape variant (lib/chrome/model.ts HeaderVariant) — independent of
+   * `variant`'s light/dark TONE above. "minimal" (e.g. checkout/policy pages)
+   * renders brand + a reduced action set only: no search, no marketing CTAs,
+   * no saved-items affordance, no primary-nav bar, no mobile-menu toggle.
+   * Defaults to "primary" (the full header) so every existing caller is
+   * unaffected.
+   */
+  layout?: HeaderVariant;
   sticky?: boolean;
   class?: string;
 }
@@ -48,6 +63,7 @@ interface Props {
 const {
   logo,
   wordmark,
+  brandHref,
   nav = [],
   searchAction,
   announcement,
@@ -58,14 +74,16 @@ const {
   cartHref,
   cartCount = 0,
   variant = "light",
+  layout = "primary",
   sticky = true,
   class: className,
 } = Astro.props;
 
 const { basePath } = Astro.locals;
-const homeHref = withBase(basePath, "/");
+const homeHref = withBase(basePath, brandHref ?? "/");
 const showLogo = !!logo && /^(https?:|\/)/.test(logo.src);
 const dark = variant === "dark";
+const minimal = layout === "minimal";
 
 const ctaClass = (v?: string) =>
   v === "secondary" || v === "ghost"
@@ -86,6 +104,11 @@ const mobileNav = nav.map((item) => ({
     href: withBase(basePath, child.href),
   })),
 }));
+
+// Current-page path, for aria-current="page" — threaded to the MobileNav
+// island (which can't read Astro.url itself) so it marks the same link the
+// server-rendered nav (NavDropdown, via Astro.url internally) marks.
+const currentPath = Astro.url.pathname;
 ---
 
 <header class:list={[sticky && "sticky top-0 z-40", className]}>
@@ -133,7 +156,7 @@ const mobileNav = nav.map((item) => ({
 
       <!-- Search (live typeahead island) -->
       {
-        searchAction && (
+        !minimal && searchAction && (
           <div class="hidden flex-1 md:flex">
             <SearchTypeahead client:idle action={searchAction} />
           </div>
@@ -143,7 +166,7 @@ const mobileNav = nav.map((item) => ({
       <!-- Actions: saved items + marketing CTAs + auth + account + cart (link only) + mobile menu -->
       <div class="ml-auto flex items-center gap-1">
         {
-          savedItemsHref && (
+          !minimal && savedItemsHref && (
             <a
               href={withBase(basePath, savedItemsHref)}
               aria-label="Saved items"
@@ -161,7 +184,7 @@ const mobileNav = nav.map((item) => ({
           )
         }
         {
-          headerCtas.length > 0 && (
+          !minimal && headerCtas.length > 0 && (
             <div class="hidden items-center gap-2 sm:flex">
               {headerCtas.map((cta) => (
                 <a href={withBase(basePath, cta.href)} class={ctaClass(cta.variant)}>
@@ -220,9 +243,9 @@ const mobileNav = nav.map((item) => ({
 
         <!-- Mobile menu: the MobileNav island (focus-trap, scroll-lock, Escape-to-close) -->
         {
-          nav.length > 0 && (
+          !minimal && nav.length > 0 && (
             <div class="md:hidden">
-              <MobileNav client:idle nav={mobileNav} announcement={announcement} />
+              <MobileNav client:idle nav={mobileNav} announcement={announcement} currentPath={currentPath} />
             </div>
           )
         }
@@ -230,12 +253,25 @@ const mobileNav = nav.map((item) => ({
     </div>
   </div>
 
-  <!-- Primary nav bar -->
+  <!-- Primary nav bar: desktop MegaMenu (hidden md:block) + a no-JS-safe mobile
+       fallback (md:hidden) below it. The fallback renders the SAME nav data as
+       real, crawlable <a href> links via a native <details>/<summary> accordion
+       (NavDropdown mode="accordion") — it works with zero JavaScript, since it
+       is below the `md` breakpoint the ONLY nav affordance a no-JS visitor has
+       (the MobileNav drawer above is a client:idle island and renders nothing
+       without JS). Once MobileNav hydrates it hides this fallback (see its
+       [data-mobile-nav-fallback] effect) so JS-enabled visitors get the drawer
+       as the primary/enhanced experience; this is additive, not a replacement. -->
   {
-    nav.length > 0 && (
+    !minimal && nav.length > 0 && (
       <div class="border-b border-border bg-surface">
         <div class="container-prose">
           <MegaMenu items={nav} />
+          <nav aria-label="Mobile" data-mobile-nav-fallback class="md:hidden">
+            <ul class="grid">
+              {nav.map((item) => <NavDropdown item={item} mode="accordion" />)}
+            </ul>
+          </nav>
         </div>
       </div>
     )

package/apps/storefront/src/components/compliance/AdultSignatureNotice.astro

@@ -4,7 +4,7 @@
  * require an of-age adult to sign; the wording is fixed here and the age
  * reflects tenant.compliance.minAge (defaults to 21). Renders NOTHING when
  * `enabled` is false. Driven by tenant.compliance.adultSignature — never hand-
- * authored on a marketing page (decision compliance-widgets-platform-owned).
+ * authored on a marketing page.
  */
 import ComplianceNotice from "./ComplianceNotice.astro";
 

package/apps/storefront/src/components/compliance/ComplianceNotice.astro

@@ -5,8 +5,7 @@
  * FDA NicotineWarning follows). It owns ONLY the chrome: the fixed legal text
  * is supplied by each sibling widget via <slot />, and every sibling renders it
  * ONLY when its tenant.compliance data is present. This component adds no copy
- * of its own — it never fabricates legal wording (decision
- * compliance-widgets-platform-owned).
+ * of its own — it never fabricates legal wording.
  *
  * Variants — one visual treatment per placement, token-styled so they re-skin
  * with the theme and never carry a hardcoded brand color:

package/apps/storefront/src/components/compliance/ExciseTaxNotice.astro

@@ -3,8 +3,7 @@
  * Excise-tax DISPLAY cue. Presentational only — it surfaces that applicable
  * excise taxes apply (and, optionally, a per-jurisdiction breakdown for shopper
  * transparency); it NEVER computes tax. The actual excise-tax CALCULATION is
- * product/commerce-owned (decision compliance-widgets-platform-owned). Renders
- * NOTHING when no note is supplied.
+ * product/commerce-owned. Renders NOTHING when no note is supplied.
  *
  * The optional jurisdiction breakdown is rendered as inline "label detail"
  * spans (valid inside the primitive's paragraph) so it re-skins with the theme

package/apps/storefront/src/components/compliance/PactActNotice.astro

@@ -6,7 +6,7 @@
  * Postal Service carriage; only whether it renders (and the age) comes from
  * tenant.compliance.pactAct / .minAge. Renders NOTHING when `enabled` is false,
  * so absent data never shows placeholder legal text. Never hand-author this on a
- * marketing page (decision compliance-widgets-platform-owned).
+ * marketing page.
  */
 import ComplianceNotice from "./ComplianceNotice.astro";
 

package/apps/storefront/src/components/compliance/Prop65Warning.astro

@@ -5,8 +5,7 @@
  * ("WARNING: … known to the State of California to cause …"), the ⚠ symbol, and
  * the official warnings URL. Only the variable slots — harm endpoint(s) and the
  * chemical name(s) named in the long form — come from tenant.compliance.prop65.
- * Renders NOTHING when the config is absent, so it never fabricates a warning
- * (decision compliance-widgets-platform-owned).
+ * Renders NOTHING when the config is absent, so it never fabricates a warning.
  *
  * `true` → short cancer + reproductive-harm warning. A Prop65Config selects the
  * harm endpoint(s); providing `chemicals` switches to the long form.

package/apps/storefront/src/components/compliance/PurchaseLimitNotice.astro

@@ -3,9 +3,8 @@
  * Purchase-quantity-limit DISPLAY. Surfaces a shopper-facing limit (e.g. state
  * or PACT-Act order caps). Display surface ONLY — the limit text comes from
  * tenant.compliance.purchaseLimit and the actual enforcement stays in the
- * product/commerce layer, never hand-built here (decision
- * compliance-widgets-platform-owned). Renders NOTHING when the config (or its
- * text) is absent.
+ * product/commerce layer, never hand-built here. Renders NOTHING when the
+ * config (or its text) is absent.
  */
 import type { PurchaseLimitConfig } from "@tot/public-runtime";
 import ComplianceNotice from "./ComplianceNotice.astro";

package/apps/storefront/src/components/compliance/ShippingRestrictionNotice.astro

@@ -3,8 +3,8 @@
  * Shipping-restriction DISPLAY notice (e.g. PACT Act no-ship states, adult
  * signature, carrier limits). Presentational only — it renders the tenant's
  * configured `compliance.shippingRestriction` text; the actual ship/no-ship
- * DECISION for an address stays in the product/commerce layer (decision
- * compliance-widgets-platform-owned). Renders NOTHING when `text` is absent.
+ * DECISION for an address stays in the product/commerce layer. Renders
+ * NOTHING when `text` is absent.
  *
  * This is the platform component behind the footer shipping band the app Layout
  * previously inlined — same data, same footer placement, now token-styled via

package/apps/storefront/src/components/compliance/StateEligibilityNotice.astro

@@ -3,9 +3,8 @@
  * State/jurisdiction sale-eligibility DISPLAY notice. Presentational only — it
  * SHOWS the tenant-configured eligibility messaging (which states a product is /
  * isn't available in); it does NOT decide whether a given cart/address is
- * eligible — that computation stays product-owned (decision
- * compliance-widgets-platform-owned). Renders NOTHING when no eligibility data
- * is supplied, so absent config never shows a placeholder.
+ * eligible — that computation stays product-owned. Renders NOTHING when no
+ * eligibility data is supplied, so absent config never shows a placeholder.
  *
  * Message precedence: an explicit `note` wins; otherwise a sentence is composed
  * from `restrictedStates` ("Not available for sale in: …") or, failing that,

package/apps/storefront/src/components/content/TrustStrip.astro

@@ -1,11 +1,11 @@
 ---
 /**
  * <TrustStrip> — the quiet row of proof tokens a store repeats across pages
- * ("Ships from USA", "Lab-tested", a rating). REAL-OR-ABSENT by construction
- * (f09): sanitizeTrustStrip() drops any claim that is scraped review-widget
- * markup and any rating that isn't a real positive aggregate, reusing f09's
+ * ("Ships from USA", "Lab-tested", a rating). REAL-OR-ABSENT by construction:
+ * sanitizeTrustStrip() drops any claim that is scraped review-widget
+ * markup and any rating that isn't a real positive aggregate, reusing the same
  * detector. If nothing real is left the strip renders NOTHING — never a
- * fabricated badge. Plain text + one rating glyph; styled from f06 tokens.
+ * fabricated badge. Plain text + one rating glyph; styled from design tokens.
  * data-widget="trust-strip".
  */
 import type { TrustStripItem } from "@/lib/content/trustStrip";

package/apps/storefront/src/components/islands/MobileNav.tsx

@@ -11,6 +11,7 @@
  * prefers-reduced-motion.
  */
 import { useCallback, useEffect, useRef, useState } from "preact/hooks";
+import { isCurrentNavHref } from "@/lib/chrome/navCurrent";
 
 interface NavChild {
   label: string;
@@ -25,9 +26,13 @@ interface NavItem {
 interface Props {
   nav: NavItem[];
   announcement?: string;
+  /** Current request path (Astro.url.pathname), for aria-current="page" — see navCurrent.ts. */
+  currentPath?: string;
 }
 
 const DRAWER_ID = "mobile-drawer";
+/** Matches SiteHeader.astro's no-JS fallback <nav data-mobile-nav-fallback>. */
+const FALLBACK_NAV_SELECTOR = "[data-mobile-nav-fallback]";
 
 function prefersReducedMotion(): boolean {
   return (
@@ -37,7 +42,7 @@ function prefersReducedMotion(): boolean {
   );
 }
 
-export default function MobileNav({ nav, announcement }: Props) {
+export default function MobileNav({ nav, announcement, currentPath }: Props) {
   const [open, setOpen] = useState(false);
   const buttonRef = useRef<HTMLButtonElement>(null);
   const panelRef = useRef<HTMLDivElement>(null);
@@ -45,6 +50,17 @@ export default function MobileNav({ nav, announcement }: Props) {
 
   const close = useCallback(() => setOpen(false), []);
 
+  // The no-JS fallback nav is only needed when JS never runs. Since this
+  // component mounting IS JS running, hide it in favor of the drawer above —
+  // additive progressive enhancement, not a replacement of either layer.
+  useEffect(() => {
+    document
+      .querySelectorAll<HTMLElement>(FALLBACK_NAV_SELECTOR)
+      .forEach((el) => {
+        el.hidden = true;
+      });
+  }, []);
+
   // Body scroll lock while open.
   useEffect(() => {
     if (!open) return;
@@ -202,6 +218,9 @@ export default function MobileNav({ nav, announcement }: Props) {
                       <div class="px-3 py-2">
                         <a
                           href={item.href}
+                          aria-current={
+                            currentPath && isCurrentNavHref(currentPath, item.href) ? "page" : undefined
+                          }
                           class="block font-display text-base font-medium text-text hover:text-primary"
                         >
                           {item.label}
@@ -211,6 +230,9 @@ export default function MobileNav({ nav, announcement }: Props) {
                             <li key={child.href}>
                               <a
                                 href={child.href}
+                                aria-current={
+                                  currentPath && isCurrentNavHref(currentPath, child.href) ? "page" : undefined
+                                }
                                 class="block rounded px-2 py-1.5 font-body text-sm text-muted hover:bg-border/40 hover:text-text"
                               >
                                 {child.label}
@@ -222,6 +244,9 @@ export default function MobileNav({ nav, announcement }: Props) {
                     ) : (
                       <a
                         href={item.href}
+                        aria-current={
+                          currentPath && isCurrentNavHref(currentPath, item.href) ? "page" : undefined
+                        }
                         class="block rounded px-3 py-2.5 font-display text-base font-medium text-text hover:bg-border/40 hover:text-primary"
                       >
                         {item.label}

package/apps/storefront/src/components/islands/VariantSelector.tsx

@@ -27,6 +27,7 @@ import type {
 } from "@tot/public-runtime";
 import { priceForPurchaseOption } from "@tot/public-runtime";
 import { formatPrice } from "@/lib/format";
+import { useCheckoutHandoffCorrelation } from "@/components/islands/useCheckoutHandoffCorrelation";
 
 interface OptionDef {
   name: string;
@@ -55,7 +56,7 @@ interface Props {
     byVariantId: Record<string, Record<string, VariantCartPayload>>;
   };
   /**
-   * Membership pricing (F10). Present only when an eligible member is resolved
+   * Membership pricing. Present only when an eligible member is resolved
    * for this request (Phase 2 shopper login). Undefined → list pricing only,
    * which is the Phase-1 anonymous behavior.
    */
@@ -63,6 +64,13 @@ interface Props {
     membershipRule: MembershipTierRule;
     stacking: MembershipStackingPolicy;
   };
+  /**
+   * Base-path-aware URL of the checkout-correlation mint endpoint
+   * (ext-commerce-10). When a store is wired the island posts the shopper's live
+   * consent snapshot here and, if the server attributes, carries the returned
+   * passthrough field on the managed-cart form. Undefined → no correlation.
+   */
+  handoffUrl?: string;
 }
 
 const LOW_STOCK_THRESHOLD = 5;
@@ -89,7 +97,14 @@ export default function VariantSelector({
   productTitle,
   checkoutCart,
   pricing,
+  handoffUrl,
 }: Props) {
+  // Checkout-correlation handoff mint (ext-commerce-10): resolved once the server
+  // attributes this shopper (analytics consent granted + signing secret present),
+  // else null → the buy form carries no correlation and the order is unattributed.
+  const correlationField = useCheckoutHandoffCorrelation(
+    checkoutCart ? handoffUrl : undefined,
+  );
   const sortedOptions = useMemo(
     () => [...options].sort((a, b) => a.position - b.position),
     [options],
@@ -219,7 +234,7 @@ export default function VariantSelector({
     }
   }
 
-  // Compose member + subscription pricing (F10). The pricing context carries the
+  // Compose member + subscription pricing. The pricing context carries the
   // resolved member tier only when an eligible member was resolved server-side;
   // otherwise it is a non-member and list pricing stands.
   const pricingCtx = pricing
@@ -474,6 +489,16 @@ export default function VariantSelector({
                 value={String(quantity)}
               />
             )}
+            {/* Checkout-correlation passthrough field (ext-commerce-10). Rides the
+                handoff as a never-signed hidden field the provider echoes back on
+                the order webhook; absent when unattributed. */}
+            {canBuy && correlationField && (
+              <input
+                type="hidden"
+                name={correlationField.name}
+                value={correlationField.value}
+              />
+            )}
             <button
               type="submit"
               disabled={!canBuy}

package/apps/storefront/src/components/islands/useCheckoutHandoffCorrelation.ts

@@ -0,0 +1,75 @@
+/**
+ * Client hook for the checkout-correlation handoff mint (ext-commerce-10).
+ *
+ * The shopper's analytics consent is a live CLIENT-side value, but the correlation
+ * token is minted under the SERVER-only signing secret. So at the handoff this hook
+ * posts the current consent snapshot (the renderer-owned `__TOT_INTEGRATION_CONSENT__`
+ * global) to `POST /api/commerce/checkout-handoff` and, when the server attributes,
+ * returns the opaque passthrough cart field for the managed-cart form to carry.
+ *
+ * Fail-safe by construction: no handoff URL, a network error, or an unattributed
+ * response yields `null` — the buy form renders and submits with NO correlation field,
+ * so the order is simply unattributed and checkout is never blocked.
+ */
+import { useEffect, useState } from "preact/hooks";
+
+/** The renderer-owned frozen consent-snapshot global (`render-phases.ts`). */
+const INTEGRATION_CONSENT_GLOBAL = "__TOT_INTEGRATION_CONSENT__";
+
+/** The opaque passthrough cart field to attach to the managed-cart form. */
+export interface HandoffCartField {
+  name: string;
+  value: string;
+}
+
+/**
+ * Read the `{ attributed, cartField }` handoff response fail-closed into a cart field,
+ * or `null` for any non-attributed / malformed shape. Pure — unit-tested directly.
+ */
+export function parseHandoffCartField(data: unknown): HandoffCartField | null {
+  if (!data || typeof data !== "object") return null;
+  const d = data as Record<string, unknown>;
+  if (d.attributed !== true) return null;
+  const field = d.cartField;
+  if (!field || typeof field !== "object") return null;
+  const { name, value } = field as Record<string, unknown>;
+  return typeof name === "string" && name.length > 0 && typeof value === "string" && value.length > 0
+    ? { name, value }
+    : null;
+}
+
+/** The live consent snapshot the renderer inlined + the CMP/native banner updates. */
+function readClientConsent(): unknown {
+  return (globalThis as Record<string, unknown>)[INTEGRATION_CONSENT_GLOBAL] ?? null;
+}
+
+/**
+ * Fetch the handoff correlation for this page. Returns the cart field to attach once
+ * the server attributes, else `null`. `handoffUrl` absent (no store / marketing
+ * tenant) is a no-op.
+ */
+export function useCheckoutHandoffCorrelation(handoffUrl?: string): HandoffCartField | null {
+  const [field, setField] = useState<HandoffCartField | null>(null);
+
+  useEffect(() => {
+    if (!handoffUrl) return;
+    let cancelled = false;
+    fetch(handoffUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ consent: readClientConsent() }),
+    })
+      .then((res) => res.json())
+      .then((data) => {
+        if (!cancelled) setField(parseHandoffCartField(data));
+      })
+      .catch(() => {
+        // Fail-safe: leave the order unattributed; never disturb the buy form.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [handoffUrl]);
+
+  return field;
+}

package/apps/storefront/src/components/membership/IllustrativeLabel.astro

@@ -4,8 +4,7 @@
  * offer" affordance shared by <TierCards>, <TierComparisonTable>, and the
  * subscription <SavingsExplainer>. When a group shows illustrative figures,
  * the widgets render this so an example price / savings number is never
- * mistaken for a live offer (decision compliance-widgets-platform-owned —
- * education only, no pricing mechanics).
+ * mistaken for a live offer — education only, no pricing mechanics.
  *
  * Two forms:
  *   - "badge" a compact pill placed at the group header (the visible marker)

package/apps/storefront/src/components/membership/TierCards.astro

@@ -6,8 +6,8 @@
  * checkout, or subscription mechanics — each tier's CTA is a plain handoff link
  * into the tenant's own (product-owned) subscribe/learn flow.
  *
- * Illustrative-figures affordance (decision compliance-widgets-platform-owned):
- * a tier's figure is treated as an EXAMPLE by default (isIllustrative). When any
+ * Illustrative-figures affordance: a tier's figure is treated as an EXAMPLE
+ * by default (isIllustrative). When any
  * shown tier is illustrative the group header carries a first-class
  * <IllustrativeLabel> badge, each such figure is prefixed with an "e.g."
  * affordance + data-illustrative hook, and a footnote spells it out — so an