@tokenoftrust/storefront-runner 2.2.126 → 2.3.1

package/docs/widget-library-guide.md

@@ -0,0 +1,1496 @@
+# Storefront widget library — user guide
+
+**Status:** maintained reference, workstream `shared-ecommerce-widgets`. This is the
+human- and agent-facing guide to the shared regulated-ecommerce widget library that every
+storefront tenant inherits. It is the **source of truth**; the style-guide route
+`/_style-guide/<tenant>/guide/<theme>/` renders this same file as HTML.
+
+> **How to keep this accurate.** Every widget entry is enumerated from real code under
+> `apps/storefront/src/components/**` and the shared libs in `apps/storefront/src/lib/`.
+> When you add, rename, or reshape a component's props, update its entry here in the same change.
+> Where a fact is load-bearing (a prop name, a token, a data attribute) it is quoted from the source.
+
+---
+
+## 1. Overview — how the library works
+
+The library is a set of **platform-owned Astro/Preact components**. A tenant never forks a
+component: it restyles the whole library by supplying **theme tokens** and drives regulated
+surfaces with **data**. Three ideas underpin everything below.
+
+### 1.1 The token contract (the library's public API)
+
+Components read only the **`themeToCssVars` `--color-*` vocabulary** (plus `--font-*`, `--fs-*`,
+`--space-*`, `--radius-*`, `--shadow-*`, `--container-max`, `--section-rhythm`). This CSS
+custom-property vocabulary is the library's public API — the full spec, reference values, and the
+rule for aliasing a tenant's own brand vars onto it live in
+[`docs/architecture/token-contract.md`](architecture/token-contract.md).
+
+- **Core palette (every theme states these):** `--color-{bg, surface, text, muted, primary,
+  primary-contrast, accent, border, success, sale}`.
+- **Semantic / state (bridge-defaulted — always resolvable):** `--color-{surface-2, warning,
+  error, info, accent-ink, primary-hover, accent-hover}`.
+- **The rule for components:** read tokens only — `var(--color-…)` or the Tailwind utility that
+  maps to it (`bg-bg`, `text-primary`, `text-error`, `rounded-md`, `border-border`). Never
+  hard-code a hex; never read a tenant-private brand var (`var(--brand-red)`) — those are aliased
+  onto the contract.
+
+Two equivalent token-reference styles appear across the library and both resolve to the same
+contract: chrome + several atoms use **Tailwind token utilities** (`bg-primary`, `text-muted`,
+`border-border`), while PLP components and most marketing blocks use **arbitrary
+`[var(--color-*)]` utilities** or scoped `<style>` blocks with `var(--color-*)`.
+
+### 1.2 The shared-vs-tenant boundary
+
+What is shared platform vs. what is per-tenant is drawn in
+[`docs/architecture/shared-vs-tenant-assets.md`](architecture/shared-vs-tenant-assets.md):
+
+- **Tier 1 — shared platform:** every component in this guide + `styles/global.css` + the style
+  guide. Driven by theme tokens.
+- **Tier 3 — per-tenant:** theme tokens, content (`home`/pages/catalog), brand assets. Differences
+  between tenants must be **data + tokens, never re-authored component CSS**.
+
+### 1.3 Two delivery paths, one look
+
+Many chrome/commerce widgets ship **both** as a platform component **and** as shared raw-chrome
+CSS, so a tenant that renders hand-authored raw marketing HTML gets the same look without copying
+CSS (decision `raw-chrome-single-stylesheet` / `materialization-compat`):
+
+- **Platform component** — the `.astro`/`.tsx` in `components/**`, token-styled, used by
+  token-driven storefronts and the style guide.
+- **Shared raw-chrome CSS** — one platform stylesheet, `public/shared/commerce-chrome.css`
+  (linked as `/shared/commerce-chrome.css`), whose class vocabulary (`.site-header`, `.announce`,
+  `.primary-nav`/`.mega`, `.site-footer`, `.compliance-strip`, `.age-gate`, …) mirrors the
+  component DOM. The server-side generator `lib/rawChrome.ts` emits that DOM from a tenant's typed
+  `chrome.json`, links exactly that one stylesheet, and emits **no inline chrome CSS**. See §11.
+
+Where a component has a raw-chrome twin, its entry notes the matching selectors.
+
+### 1.4 Compliance widgets are platform-owned and data-driven (never faked in marketing)
+
+Regulated-commerce notices (`components/compliance/**`) are **platform-owned and data-driven from
+`tenant.compliance`** (decision `compliance-widgets-platform-owned`). They:
+
+- render **only** from tenant config, and render **nothing** when their `tenant.compliance` field
+  is absent;
+- **never fabricate legal copy** — the mandated wording (FDA nicotine warning, PACT Act, Prop 65
+  skeleton) is owned by the platform component; only the on/off flag and small parameters
+  (`minAge`, chemical names, state lists) come from config;
+- for display-only cues (purchase limit, state eligibility, shipping restriction, excise tax), the
+  **enforcement/decision/calculation stays product-owned** — the widget only surfaces the message.
+
+Marketing blocks (§7) must never hand-author a fake compliance notice; use the platform widget fed
+from `tenant.compliance`.
+
+The parallel discipline for **membership/subscription** figures (§5, §6): figures are
+**illustrative by default** — unless a tier/figure asserts `real: true`, the widget shows a
+first-class "illustrative figures" affordance (`IllustrativeLabel`) so an example number is never
+shown as a live offer.
+
+### 1.5 How to read each entry
+
+Every widget lists: **Purpose**, **Props** (exact names + TS types), **Dependencies** (components,
+libs, and any tenant config/locals it reads), **Tokens consumed**, **Delivery** (platform component
++ any raw-chrome twin), and a realistic **Usage** snippet. The live style guide
+`/_style-guide/<tenant>/<theme>/` renders almost every widget below with sample data.
+
+### 1.6 Category index
+
+- §2 Chrome — `components/chrome/`
+- §3 Commerce — `components/commerce/`
+- §4 Compliance — `components/compliance/`
+- §5 Membership — `components/membership/`
+- §6 Subscription — `components/subscription/`
+- §7 Marketing / widget blocks — `components/marketing/`
+- §8 PLP controls — `components/plp/`
+- §9 Islands — `components/islands/`
+- §10 Foundational atoms + home — `components/*` + `components/home/`
+- §11 Shared raw-chrome library — `lib/rawChrome.ts`, `lib/chrome/`, `public/shared/commerce-chrome.css`
+
+Shared chrome model (`lib/chrome/model.ts`), referenced throughout §2:
+
+- `ChromeLink` — `{ label: string; href: string; external?: boolean; badge?: string }`
+- `MegaColumn` — `{ title?: string; links: ChromeLink[] }`
+- `ChromeNavItem` — `{ label: string; href: string; badge?: string; flag?: boolean; children?: ChromeLink[]; columns?: MegaColumn[] }` (plain link / single-column dropdown / multi-column mega)
+- `SocialLink` — `{ label: string; href: string; iconPath?: string }`
+- `ChromeLogo` — `{ src: string; alt: string; width?: number; height?: number }`
+- `ChromeCta` — `{ label: string; href: string; variant?: "primary" | "secondary" | "ghost" }`
+- `FooterColumn` — `{ title: string; links: ChromeLink[] }`
+- `FooterNewsletter` — `{ title?: string; body?: string; action?: string; placeholder?: string; source?: string; ageAttestation?: boolean }`
+
+---
+
+## 2. Chrome — `components/chrome/`
+
+The site frame: announcement, utility bar, header, primary/mega nav, footer. All six have a
+raw-chrome twin in `public/shared/commerce-chrome.css`. Every href-emitting chrome component reads
+`Astro.locals.basePath` via `withBase` (`@/lib/basePath`) for path-prefix tenant routing.
+
+### AnnouncementBar (`components/chrome/AnnouncementBar.astro`)
+
+- **Purpose:** Top promo strip — `static` centered single line or `marquee` continuously-scrolling
+  track (duplicated for a seamless loop). Reduced-motion-safe (freezes to static copy).
+- **Props:** `text: string`; `variant?: "static" | "marquee"`; `repeat?: number` (marquee phrase
+  repeats, default 6); `tone?: "primary" | "sale" | "accent"`; `label?: string` (region aria-label);
+  `class?: string`.
+- **Dependencies:** none (self-contained; no imports, no locals).
+- **Tokens consumed:** `--font-mono`; tone → `bg-primary text-primary-contrast` /
+  `bg-[var(--color-sale)]` / `bg-accent`.
+- **Delivery:** platform component + raw-chrome twin `.announce` (solid), `.announce-marquee` /
+  `.announce-marquee__track` (marquee), `.announce-bar` / `.announce-bar__msg` /
+  `.announce-bar__close` (dismissible/rotating bar).
+- **Usage:**
+  ```astro
+  <AnnouncementBar text="Free US shipping on orders over $100!" variant="marquee" tone="sale" />
+  ```
+
+### UtilityNav (`components/chrome/UtilityNav.astro`)
+
+- **Purpose:** Thin secondary bar above the header — minor links, locale/currency indicator, social
+  icons. Hidden below `md` (the mobile menu carries the links).
+- **Props:** `links?: ChromeLink[]`; `locale?: string`; `currency?: string`; `social?: SocialLink[]`;
+  `class?: string`.
+- **Dependencies:** `type ChromeLink, SocialLink` from `@/lib/chrome/model`; `withBase`.
+- **Tokens consumed:** `border-border`, `bg-surface`, `text-muted`, `hover:text-primary`,
+  `font-mono`.
+- **Delivery:** platform component + raw-chrome twin `.utility-nav` / `.utility-nav__right` /
+  `.sel` / `.social` / `.member-cue`.
+- **Usage:**
+  ```astro
+  <UtilityNav
+    links={[{ label: "News", href: "/news" }, { label: "Contact", href: "/contact" }]}
+    locale="English"
+    currency="United States (USD $)"
+    social={social}
+  />
+  ```
+
+### SiteHeader (`components/chrome/SiteHeader.astro`)
+
+- **Purpose:** Canonical site header — logo/wordmark + search typeahead island + saved / marketing
+  CTA / auth / account / cart affordances, with `<MegaMenu>` below and a `<MobileNav>` drawer.
+  Cart is a **link only** (managed checkout; count is static). Pure component — the caller resolves
+  session/theme/feature state and passes props.
+- **Props:** `logo?: ChromeLogo`; `wordmark?: string`; `nav?: ChromeNavItem[]`; `searchAction?:
+  string` (omit to hide search); `announcement?: string` (surfaced in the mobile drawer);
+  `accountHref?: string`; `authLink?: { label: string; href: string }`; `savedItemsHref?: string`;
+  `headerCtas?: ChromeCta[]`; `cartHref?: string`; `cartCount?: number`; `variant?: "light" |
+  "dark"`; `sticky?: boolean` (default `true`); `class?: string`.
+- **Dependencies:** `type ChromeNavItem, ChromeLogo, ChromeCta` from `@/lib/chrome/model`;
+  `MegaMenu`; islands `SearchTypeahead` (`client:idle`) and `MobileNav` (`client:idle`); `withBase`.
+- **Tokens consumed:** `border-border`, `bg-surface`/`bg-surface/95`, `text-text`, `bg-primary`,
+  `text-primary-contrast`, `hover:text-accent`, `bg-accent`, `bg-[var(--color-sale)]`.
+- **Delivery:** platform component + raw-chrome twin `.site-header` / `.header-row`, `.brand`,
+  `.primary-nav-bar`.
+- **Usage:**
+  ```astro
+  <SiteHeader
+    wordmark="Sample Store"
+    nav={nav}
+    searchAction="/search"
+    accountHref="/account"
+    cartHref="/cart"
+    cartCount={2}
+  />
+  ```
+
+### MegaMenu (`components/chrome/MegaMenu.astro`)
+
+- **Purpose:** Primary desktop nav bar — a horizontal `<ul>` of items, each rendered by
+  `<NavDropdown>`. Hidden below `md`.
+- **Props:** `items: ChromeNavItem[]`; `ariaLabel?: string` (default `"Primary"`); `class?: string`.
+- **Dependencies:** `type ChromeNavItem` from `@/lib/chrome/model`; `NavDropdown`.
+- **Tokens consumed:** none directly (layout utilities only; token styling delegated to
+  `NavDropdown`).
+- **Delivery:** platform component + raw-chrome twin `.primary-nav` / `.primary-nav > ul` /
+  `.primary-nav .nav-item`.
+- **Usage:**
+  ```astro
+  <MegaMenu items={nav} />
+  ```
+
+### NavDropdown (`components/chrome/NavDropdown.astro`)
+
+- **Purpose:** One primary-nav item in two modes. `mode="bar"` (default) = desktop item with a
+  CSS-only hover/focus single-column dropdown (`children`) or multi-column mega panel (`columns`),
+  zero-JS and keyboard accessible. `mode="accordion"` = mobile stacked item using native
+  `<details>/<summary>`. Supports caret, `badge`, and highlighted `flag`.
+- **Props:** `item: ChromeNavItem`; `mode?: "bar" | "accordion"` (default `"bar"`).
+- **Dependencies:** `type ChromeNavItem, ChromeLink` from `@/lib/chrome/model`; `withBase`.
+- **Tokens consumed:** `text-text`, `text-muted`, `text-accent`, `text-primary`, `border-border`,
+  `bg-surface`, `bg-primary`, `text-primary-contrast`, `hover:bg-bg`, `bg-[var(--color-sale)]`,
+  `shadow-md`, `rounded-md`, `rounded-sm`.
+- **Delivery:** platform component + raw-chrome twin `.nav-item`, `.mega` / `.mega--wide` /
+  `.mega__cols` / `.mega__col`, `.caret`, `.new-badge`, `.is-flag`.
+- **Usage:**
+  ```astro
+  <NavDropdown item={item} mode="accordion" />
+  ```
+
+### SiteFooter (`components/chrome/SiteFooter.astro`)
+
+- **Purpose:** Brand block + link columns + newsletter POST form + payment-badge chip row +
+  trust/compliance line + legal bottom bar. Payment badges are text chips (CSP-clean, no external
+  images). No cart/checkout logic (commerce boundary).
+- **Props:** `columns: FooterColumn[]`; `brand?: { logo?: ChromeLogo; wordmark?: string; contact?:
+  string[] }`; `newsletter?: FooterNewsletter`; `payments?: string[]`; `social?: SocialLink[]`;
+  `compliance?: string`; `legal?: string`; `bottomLinks?: ChromeLink[]`; `class?: string`.
+- **Dependencies:** `type ChromeLink, FooterColumn, FooterNewsletter, SocialLink, ChromeLogo` from
+  `@/lib/chrome/model`; `withBase`.
+- **Tokens consumed:** `border-border`, `bg-surface`, `text-text`, `text-muted`,
+  `hover:text-primary`, `bg-bg`, `bg-primary`, `text-primary-contrast`, `font-display`, `font-mono`.
+- **Delivery:** platform component + raw-chrome twin `.site-footer`, `.footer-grid`,
+  `.footer-brand`, `.footer-col`, `.footer-news` (+ `__row`), `.footer-attest`, `.trust-marks`,
+  `.footer-warning`, `.footer-bottom`.
+- **Usage:**
+  ```astro
+  <SiteFooter
+    brand={{ wordmark: "Sample Store", contact: ["hello@example.com"] }}
+    columns={footerCols}
+    newsletter={{ title: "Join the community", placeholder: "Email" }}
+    payments={["Visa", "Mastercard", "Amex", "PayPal"]}
+    social={social}
+    compliance="Must be 21+ to purchase. Products intended for adults of legal age only."
+    legal="© Sample Store. All rights reserved."
+  />
+  ```
+
+---
+
+## 3. Commerce — `components/commerce/`
+
+Product cards, merchandising rows, price/rating atoms, blog cards, and checkout wiring.
+`ArticleCard`, `BrandGrid`, and `TagFilterCloud` each carry a scoped `<style>` that mirrors a
+class-only block in `public/shared/commerce-chrome.css` (`.article-card`, `.brand-grid`/`.brand-tile`,
+`.tag-cloud`/`.tag-chip`) — keep the two visually equal.
+
+### PriceDisplay (`components/commerce/PriceDisplay.astro`)
+
+- **Purpose:** Price atom — struck compare-at when on sale, "From $X" prefix for variant ranges,
+  optional sale-percent badge. Accepts a `product` (derives everything) or raw primitives.
+- **Props:** `product?: CatalogProduct`; `amount?: number`; `compareAt?: number | null`; `from?:
+  boolean`; `currency?: string`; `locale?: string` (default `"en-US"`); `showBadge?: boolean`
+  (default `false`); `size?: "sm" | "md" | "lg"` (default `"md"`); `class?: string`.
+- **Dependencies:** `CatalogProduct` from `@tot/public-runtime`; `formatPrice, discountPercent`
+  (`@/lib/format`); `fromPrice, isOnSale` (`@/lib/tot/query`); `Badge`.
+- **Tokens consumed:** `text-muted`, `text-sale`, `font-display`; sale badge carries `--color-sale`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <PriceDisplay amount={64} compareAt={96} currency="USD" showBadge />
+  <PriceDisplay amount={42} from currency="USD" />
+  ```
+
+### RatingStars (`components/commerce/RatingStars.astro`)
+
+- **Purpose:** 0–5 star rating with fractional fill (single clipped overlay) + accessible label;
+  optional numeric review count. Presentation only.
+- **Props:** `rating: number` (0–5); `count?: number`; `max?: number` (default `5`); `size?: "sm" |
+  "md"` (default `"sm"`); `showCount?: boolean` (default `true`); `class?: string`.
+- **Dependencies:** none.
+- **Tokens consumed:** `text-[var(--color-border)]` (empty track), `text-[var(--color-accent)]`
+  (filled), `text-muted` (count).
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <RatingStars rating={4.5} count={128} />
+  ```
+
+### ProductCarousel (`components/commerce/ProductCarousel.astro`)
+
+- **Purpose:** Horizontal-scroll row of `<ProductCard>`s bound to a `SectionSource`, with optional
+  CSS-only tabs (each tab its own source; radio + adjacent-sibling reveal, zero JS). Presets
+  (BestSellers / NewArrivals / OnSale) are this + a `SECTION_PRESETS.*` source.
+- **Props:** `source?: SectionSource`; `products?: CatalogProduct[]` (wins over source); `tabs?:
+  Tab[]` (wins over both, where `Tab = { label: string; source?: SectionSource; products?:
+  CatalogProduct[] }`); `limit?: number` (default `DEFAULT_SECTION_LIMIT`); `title?: string`;
+  `eyebrow?: string`; `columns?: 2 | 3 | 4 | 5` (default `4`); `variant?: "default" | "compact"`
+  (default `"default"`); `tone?: "bg" | "surface"` (default `"bg"`); `class?: string`.
+- **Dependencies:** `CatalogProduct` from `@tot/public-runtime`; `Section`, `ProductCard`;
+  `resolveSectionSource, DEFAULT_SECTION_LIMIT, SectionSource` (`@/lib/sections`). Reads
+  `Astro.locals.tot`.
+- **Tokens consumed:** `--color-border`, `--color-muted`, `--color-text`, `--color-primary`,
+  `--color-primary-contrast`, `--color-accent`, `--radius-full`, `--font-mono`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <ProductCarousel title="Best Sellers" eyebrow="Shop" products={products} tone="surface" />
+  <ProductCarousel title="Featured" tabs={[{ label: "New", products: newest }, { label: "On Sale", products: onSale }]} />
+  ```
+
+### ProductGrid (`components/commerce/ProductGrid.astro`)
+
+- **Purpose:** Non-scrolling paginated-look grid of `<ProductCard>`s bound to a `SectionSource`.
+  Thin sibling of `ProductCarousel`; `columns` tunes density; hides itself when empty.
+- **Props:** `source?: SectionSource`; `products?: CatalogProduct[]` (wins over source); `limit?:
+  number` (default `DEFAULT_SECTION_LIMIT`); `title?: string`; `eyebrow?: string`; `columns?: 2 | 3
+  | 4 | 5` (default `4`); `tone?: "bg" | "surface"` (default `"bg"`); `hideWhenEmpty?: boolean`
+  (default `true`); `class?: string`.
+- **Dependencies:** `CatalogProduct` from `@tot/public-runtime`; `Section`, `ProductCard`,
+  `EmptyState`; `@/lib/sections`. Reads `Astro.locals.tot`.
+- **Tokens consumed:** none directly (token surface from child `ProductCard` / `Section` /
+  `EmptyState`).
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <ProductGrid title="All Products" products={products} columns={3} />
+  ```
+
+### BrandGrid (`components/commerce/BrandGrid.astro`)
+
+- **Purpose:** "Shop by Brands" logo wall — grid of tiles linking to brand collections; each tile is
+  a rehosted logo image OR a text-wordmark fallback. Optional "View all brands" CTA.
+- **Props:** `brands: Brand[]` where `export interface Brand { label: string; href: string; logoSrc?:
+  string; logoRehosted?: boolean; logoWidth?: number; logoHeight?: number }`; `title?: string`;
+  `eyebrow?: string`; `tone?: "bg" | "surface"` (default `"bg"`); `viewAllHref?: string`;
+  `viewAllLabel?: string` (default `"View all brands"`); `class?: string`.
+- **Dependencies:** `Section`, `Img`; `withBase`.
+- **Tokens consumed:** `--color-surface`, `--color-border`, `--color-text`, `--color-primary`,
+  `--radius-md`, `--radius-full`, `--shadow-md`, `--font-display`.
+- **Delivery:** platform component + raw-chrome twin `.brand-grid` / `.brand-tile`.
+- **Usage:**
+  ```astro
+  <BrandGrid title="Shop by Brands" eyebrow="Find your fav" brands={brands} viewAllHref="/brands" tone="surface" />
+  ```
+
+### ArticleCard (`components/commerce/ArticleCard.astro`)
+
+- **Purpose:** One blog/article card — featured image + category tag chip + title + excerpt + meta
+  (author · date · read-time). Presentational; omits any absent field's row, never fabricates
+  authors/dates/excerpts.
+- **Props:** `article: Article` where `export interface Article { title: string; href: string;
+  excerpt?: string; image?: ArticleImage; tag?: string; tagHref?: string; author?: string; date?:
+  string; dateTime?: string; readMinutes?: number }` and `ArticleImage = { src: string; alt?: string;
+  rehosted?: boolean; width?: number; height?: number }`; `as?: "h2" | "h3" | "h4"` (default `"h3"`);
+  `class?: string`.
+- **Dependencies:** `Img`; `withBase`.
+- **Tokens consumed:** `--color-surface`, `--color-border`, `--color-surface-2`, `--color-primary`,
+  `--color-text`, `--color-muted`, `--radius-lg`, `--shadow-md`, `--font-display`.
+- **Delivery:** platform component + raw-chrome twin `.article-card`.
+- **Usage:**
+  ```astro
+  <ArticleCard article={article} />
+  ```
+
+### TagFilterCloud (`components/commerce/TagFilterCloud.astro`)
+
+- **Purpose:** Cloud of tag/category chips for a blog/article index, each a plain link to its
+  filtered view (URL-addressable, zero-JS). Active tag filled + `aria-current`; optional leading
+  "All" chip clears the filter.
+- **Props:** `tags: TagItem[]` where `export interface TagItem { label: string; href: string; count?:
+  number; active?: boolean }`; `title?: string`; `allHref?: string`; `allLabel?: string` (default
+  `"All"`); `allActive?: boolean` (default `false`); `ariaLabel?: string` (default `"Filter by
+  tag"`); `class?: string`.
+- **Dependencies:** `withBase`.
+- **Tokens consumed:** `--color-muted`, `--color-border`, `--color-surface`, `--color-text`,
+  `--color-primary`, `--color-primary-contrast`, `--radius-full`, `--font-display`.
+- **Delivery:** platform component + raw-chrome twin `.tag-cloud` / `.tag-chip`.
+- **Usage:**
+  ```astro
+  <TagFilterCloud title="Browse by topic" tags={tags} allHref="/blog" allActive={false} />
+  ```
+
+### CheckoutLoader (`components/commerce/CheckoutLoader.astro`)
+
+- **Purpose:** Injects the managed checkout loader near end of `<body>` to enable the cart drawer +
+  hosted checkout. Rendered only for commerce tenants; marketing tenants ship nothing.
+- **Props:** none. Reads `Astro.locals.commerce` (`commerce.loaderSrc`).
+- **Dependencies:** none.
+- **Tokens consumed:** none.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <CheckoutLoader />
+  ```
+
+### CartDrawerStyles (`components/commerce/CartDrawerStyles.astro`)
+
+- **Purpose:** Emits a nonce'd `<style>` mapping the in-page cart drawer (`#fc` light DOM)
+  selectors to the tenant's theme tokens so the cart is brand-matched. Baseline layer plus optional
+  tenant `cartDrawerCss` override appended verbatim.
+  Commerce tenants only.
+- **Props:** none. Reads `Astro.locals.commerce` (`commerce.cartDrawerCss`) and `Astro.locals.cspNonce`.
+- **Dependencies:** none.
+- **Tokens consumed (scoped under `#fc`):** `--font-body`, `--font-display`, `--color-text`,
+  `--color-primary`, `--color-primary-contrast`, `--radius-md`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <CartDrawerStyles />
+  ```
+
+---
+
+## 4. Compliance — `components/compliance/`
+
+Platform-owned, data-driven from `tenant.compliance` (decision `compliance-widgets-platform-owned`).
+Every widget renders **nothing** when its config field is absent, **never fabricates legal copy**,
+and emits `role="note"` + a `data-compliance="…"` hook. All share the presentational
+`ComplianceNotice` base except `NicotineWarning` (self-contained). The `tenant.compliance` config
+types live in `packages/public-runtime/src/tenant.ts` (`ComplianceConfig`): `nicotineWarning`,
+`pactAct`, `adultSignature` are `boolean`; `shippingRestriction` is `string`; `minAge` is `number`;
+`prop65`/`purchaseLimit`/`stateEligibility`/`exciseTax` are the config objects below.
+
+### ComplianceNotice (`components/compliance/ComplianceNotice.astro`)
+
+- **Purpose:** Shared presentational shell for the compliance widgets. Owns only the visual
+  treatment; the fixed legal text is supplied by each sibling via `<slot />`. Adds no copy of its own.
+- **Props:** `variant?: "bar" | "block" | "inline" | "footer"` (default `"block"`); `tone?: "warning"
+  | "info" | "neutral"` (default `"neutral"`); `hook: string` (required — the `data-compliance`
+  value); `label: string` (required — accessible label); `symbol?: string` (optional leading glyph,
+  e.g. `⚠`).
+- **`data-compliance`:** emits the caller's `hook`.
+- **Dependencies:** none (leaf base). Reads no tenant field directly — siblings pass data in.
+- **Tokens consumed:** `--color-border`, `--color-surface-2`, `--color-bg`, `--color-text`,
+  `--color-muted`, `--color-warning`, `--color-info`, `--radius-md`.
+- **Delivery:** platform base + raw-chrome counterparts `.compliance-strip` (bar/block),
+  `.topbar-warning` (top FDA band), `.footer-warning` (footer band).
+- **Usage:** consumed by the siblings below (not used directly).
+
+### NicotineWarning (`components/compliance/NicotineWarning.astro`)
+
+- **Purpose:** FDA-mandated nicotine warning (21 CFR 1143.3). Wording fixed by law, verbatim.
+  Self-contained (does not use `ComplianceNotice`).
+- **Props:** `variant?: "bar" | "block"` (default `"bar"`).
+- **`data-compliance`:** `"nicotine-warning"`. Gated by `tenant.compliance.nicotineWarning`.
+- **Dependencies:** none.
+- **Tokens consumed:** `--color-text` (inverted bg/border), `--color-bg` (text on bar),
+  `--radius-md`.
+- **Delivery:** platform component + raw-chrome twin `.topbar-warning`.
+- **Usage:**
+  ```astro
+  <NicotineWarning variant="bar" />
+  <NicotineWarning variant="block" />
+  ```
+
+### PactActNotice (`components/compliance/PactActNotice.astro`)
+
+- **Purpose:** PACT Act compliance notice (ENDS/vapor). Federal-requirement wording fixed here; only
+  on/off + age come from config.
+- **Props:** `enabled?: boolean` (default `false`; from `tenant.compliance.pactAct`); `minAge?:
+  number` (default `21`; from `tenant.compliance.minAge`); `variant?: "bar" | "block" | "inline" |
+  "footer"` (default `"block"`). Passes `tone="info"`.
+- **`data-compliance`:** `"pact-act"`.
+- **Dependencies:** `ComplianceNotice`. Reads `tenant.compliance.pactAct` + `.minAge`.
+- **Tokens consumed:** info tone → `--color-info` (+ base tokens).
+- **Delivery:** platform component + raw-chrome `.compliance-strip` / `.footer-warning`.
+- **Usage:**
+  ```astro
+  <PactActNotice enabled minAge={21} variant="bar" />
+  <PactActNotice enabled minAge={21} variant="footer" />
+  ```
+
+### AdultSignatureNotice (`components/compliance/AdultSignatureNotice.astro`)
+
+- **Purpose:** Adult-signature-on-delivery notice. Fixed wording; age reflects `minAge`.
+- **Props:** `enabled?: boolean` (default `false`; from `tenant.compliance.adultSignature`); `minAge?:
+  number` (default `21`); `variant?: "bar" | "block" | "inline" | "footer"` (default `"inline"`).
+  Passes `tone="neutral"`.
+- **`data-compliance`:** `"adult-signature"`.
+- **Dependencies:** `ComplianceNotice`. Reads `tenant.compliance.adultSignature` + `.minAge`.
+- **Tokens consumed:** neutral tone → `--color-text` / `--color-muted`.
+- **Delivery:** platform component + raw-chrome `.compliance-strip`.
+- **Usage:**
+  ```astro
+  <AdultSignatureNotice enabled minAge={21} variant="inline" />
+  ```
+
+### Prop65Warning (`components/compliance/Prop65Warning.astro`)
+
+- **Purpose:** California Prop 65 safe-harbor warning. Owns the mandated skeleton, the `⚠` symbol,
+  and the official warnings URL. Only harm endpoint(s) + chemical name(s) come from config. Short
+  form (`config={true}`) vs long form (when `chemicals` supplied).
+- **Props:** `config?: Prop65Config | boolean` (from `tenant.compliance.prop65`; `true` normalizes to
+  `{ harm: "cancer-and-reproductive" }`), where `Prop65Config = { harm: "cancer" | "reproductive" |
+  "cancer-and-reproductive"; chemicals?: string[]; url?: string }`; `variant?: "bar" | "block" |
+  "inline" | "footer"` (default `"block"`). Passes `tone="warning"`, `symbol="⚠"`.
+- **`data-compliance`:** `"prop65"`.
+- **Dependencies:** `ComplianceNotice`, `type Prop65Config` from `@tot/public-runtime`. Reads
+  `tenant.compliance.prop65`.
+- **Tokens consumed:** warning tone → `--color-warning`; underlined `<a>`.
+- **Delivery:** platform component + raw-chrome `.compliance-strip`.
+- **Usage:**
+  ```astro
+  <Prop65Warning config={true} variant="block" />
+  <Prop65Warning config={{ harm: "reproductive", chemicals: ["nicotine"] }} variant="block" />
+  ```
+
+### PurchaseLimitNotice (`components/compliance/PurchaseLimitNotice.astro`)
+
+- **Purpose:** Purchase-quantity-limit **display** (state/PACT order caps). Display surface only —
+  enforcement stays product/commerce-owned.
+- **Props:** `config?: PurchaseLimitConfig` (from `tenant.compliance.purchaseLimit`), where
+  `PurchaseLimitConfig = { text: string; reason?: string }`; `variant?: "bar" | "block" | "inline" |
+  "footer"` (default `"inline"`). Passes `tone="neutral"`.
+- **`data-compliance`:** `"purchase-limit"`.
+- **Dependencies:** `ComplianceNotice`, `type PurchaseLimitConfig` from `@tot/public-runtime`.
+- **Tokens consumed:** neutral tone via base.
+- **Delivery:** platform component + raw-chrome `.compliance-strip`.
+- **Usage:**
+  ```astro
+  <PurchaseLimitNotice config={{ text: "2 units per order", reason: "per state law" }} variant="inline" />
+  ```
+
+### StateEligibilityNotice (`components/compliance/StateEligibilityNotice.astro`)
+
+- **Purpose:** State/jurisdiction sale-eligibility **display**. Shows tenant-configured messaging;
+  does **not** decide eligibility for a cart/address. Precedence: explicit `note` wins, else composes
+  from `restrictedStates` or `eligibleStates`.
+- **Props:** `config?: StateEligibilityConfig` (from `tenant.compliance.stateEligibility`), where
+  `StateEligibilityConfig = { restrictedStates?: string[]; eligibleStates?: string[]; note?: string }`;
+  `variant?: "bar" | "block" | "inline" | "footer"` (default `"block"`). Passes `tone="warning"`,
+  `symbol="⚠"`.
+- **`data-compliance`:** `"state-eligibility"`.
+- **Dependencies:** `ComplianceNotice`, `type StateEligibilityConfig` from `@tot/public-runtime`.
+- **Tokens consumed:** warning tone → `--color-warning`.
+- **Delivery:** platform component + raw-chrome `.compliance-strip`.
+- **Usage:**
+  ```astro
+  <StateEligibilityNotice config={{ restrictedStates: ["UT", "AR", "VT"] }} variant="block" />
+  ```
+
+### ShippingRestrictionNotice (`components/compliance/ShippingRestrictionNotice.astro`)
+
+- **Purpose:** Shipping-restriction **display** (PACT no-ship states, adult signature, carrier
+  limits). Renders the tenant's configured text; the ship/no-ship decision stays product-owned. This
+  is the platform component behind the footer shipping band the app Layout previously inlined.
+- **Props:** `text?: string` (from `tenant.compliance.shippingRestriction`, display text only);
+  `variant?: "bar" | "block" | "inline" | "footer"` (default `"footer"`). Passes `tone="neutral"`.
+- **`data-compliance`:** `"shipping-restriction"`.
+- **Dependencies:** `ComplianceNotice`. Reads `tenant.compliance.shippingRestriction` (`string`).
+- **Tokens consumed:** neutral tone; footer variant uses `--color-bg`, `--color-border`,
+  `--color-muted`.
+- **Delivery:** platform component + raw-chrome twin `.footer-warning`.
+- **Usage:**
+  ```astro
+  <ShippingRestrictionNotice text="Adult signature (21+) required on delivery. Not shipped via USPS." variant="footer" />
+  ```
+
+### ExciseTaxNotice (`components/compliance/ExciseTaxNotice.astro`)
+
+- **Purpose:** Excise-tax **display** cue. Surfaces that excise taxes apply (+ optional
+  per-jurisdiction breakdown); **never computes tax** — calculation is product/commerce-owned.
+- **Props:** `config?: ExciseTaxConfig` (from `tenant.compliance.exciseTax`), where `ExciseTaxConfig =
+  { note: string; jurisdictions?: Array<{ label: string; detail: string }> }`; `variant?: "bar" |
+  "block" | "inline" | "footer"` (default `"inline"`). Passes `tone="info"`. Renders only if
+  `config.note` is non-empty.
+- **`data-compliance`:** `"excise-tax"`.
+- **Dependencies:** `ComplianceNotice`, `type ExciseTaxConfig` from `@tot/public-runtime`.
+- **Tokens consumed:** info tone → `--color-info`; jurisdiction spans use `--color-muted`.
+- **Delivery:** platform component + raw-chrome `.compliance-strip`.
+- **Usage:**
+  ```astro
+  <ExciseTaxNotice config={{ note: "Applicable state vapor excise taxes are calculated at checkout." }} variant="inline" />
+  <ExciseTaxNotice config={{ note: "State excise taxes apply:", jurisdictions: [{ label: "CA", detail: "$0.05/ml" }, { label: "NY", detail: "20% wholesale" }] }} variant="block" />
+  ```
+
+---
+
+## 5. Membership — `components/membership/`
+
+Presentational + **education-only** (no pricing/checkout/subscription mechanics; CTAs are plain
+handoff links). Figures are **illustrative by default**: a tier's figure is an example unless the
+tier asserts `real: true` (`isIllustrative(tier)` returns `tier.real !== true`). Model in
+`lib/membership/model.ts`. All emit `data-widget="…"`.
+
+Model types (`lib/membership/model.ts`):
+
+- `TierFigure` — `{ value: string; caption?: string }` (`value` is display text like `"$0"`,
+  `"$19/mo"`, `"Save 15%"` — never a computed number).
+- `TierFeature` — `{ label: string; included?: boolean }` (`true`→check, `false`→dash+strikethrough,
+  omitted→plain bullet).
+- `TierCta` — `{ label: string; href: string }` (education/handoff link only).
+- `Tier` — `{ name: string; tagline?: string; figure?: TierFigure; features?: TierFeature[]; cta?:
+  TierCta; featured?: boolean; badge?: string; real?: boolean }`.
+- `ComparisonRow` — `{ label: string; cells: Array<boolean | string | null> }` (aligned to `tiers`
+  by index: boolean→check/dash, string→text, null→em dash).
+- `isIllustrative(tier: Pick<Tier, "real">): boolean` → `tier.real !== true`.
+
+### IllustrativeLabel (`components/membership/IllustrativeLabel.astro`)
+
+- **Purpose:** The first-class "these figures are examples, not an offer" affordance shared by
+  `TierCards`, `TierComparisonTable`, and `SavingsExplainer`.
+- **Props:** `as?: "badge" | "note"` (default `"badge"`); `text?: string` (override copy).
+- **`data-illustrative`:** `"badge"` or `"note"` (note: `data-illustrative`, not `data-widget`).
+- **Dependencies:** none (leaf; driven by the parent widget's illustrative state).
+- **Tokens consumed:** `--color-muted` (note), `--color-info` (badge border + text), `--radius-full`.
+- **Delivery:** platform component (no raw-chrome twin).
+- **Usage:** rendered internally by the tier/savings widgets; `<IllustrativeLabel as="badge" />`.
+
+### TierCards (`components/membership/TierCards.astro`)
+
+- **Purpose:** Membership/pricing tier comparison card row (e.g. Guest / Member / Autopilot). Shows
+  tiers, headline figures, feature bullets; each CTA is a plain handoff link. When any shown tier is
+  illustrative, the header carries an `IllustrativeLabel` badge, each illustrative figure is prefixed
+  "e.g." + `data-illustrative="figure"`, and a footnote spells it out.
+- **Props:** `tiers: Tier[]` (required); `eyebrow?: string`; `heading?: string`; `subhead?: string`.
+- **`data-widget`:** `"tier-cards"` (per-tier `data-tier={tier.name}`).
+- **Dependencies:** `type Tier` + `isIllustrative` (`@/lib/membership/model`); `IllustrativeLabel`.
+  No tenant-config field (tenant supplies `tiers` on a membership page).
+- **Tokens consumed:** `--color-accent-ink`, `--color-text`, `--color-muted`, `--color-surface`,
+  `--color-border`, `--color-primary`, `--color-primary-contrast`, `--color-success`, `--radius-lg`,
+  `--radius-full`, `--shadow-md`.
+- **Delivery:** platform component (no raw-chrome twin).
+- **Usage:**
+  ```astro
+  <TierCards eyebrow="Membership" heading="Choose how you shop" subhead="Compare guest checkout with our membership tiers." tiers={tiers} />
+  ```
+
+### TierComparisonTable (`components/membership/TierComparisonTable.astro`)
+
+- **Purpose:** Feature matrix companion to `TierCards` — tiers across the top, features down the side,
+  one cell per (feature × tier). Same illustrative-figure affordance. Horizontally scrollable.
+- **Props:** `tiers: Tier[]` (required); `rows: ComparisonRow[]` (required, cells align to `tiers` by
+  index); `eyebrow?: string`; `heading?: string`.
+- **`data-widget`:** `"tier-comparison-table"`.
+- **Dependencies:** `type Tier, ComparisonRow` + `isIllustrative` (`@/lib/membership/model`);
+  `IllustrativeLabel`.
+- **Tokens consumed:** `--color-accent-ink`, `--color-text`, `--color-muted`, `--color-surface-2`,
+  `--color-border`, `--color-success`, `--radius-md`.
+- **Delivery:** platform component (no raw-chrome twin).
+- **Usage:**
+  ```astro
+  <TierComparisonTable eyebrow="Compare" heading="What each tier includes" tiers={tiers} rows={comparisonRows} />
+  ```
+
+---
+
+## 6. Subscription — `components/subscription/`
+
+Presentational + **education-only**: explain recurring/Autopilot ordering and hand off to the
+tenant's product-owned subscribe/manage flow; **no scheduling/billing/cancellation mechanics**. The
+savings figure is illustrative by default (same discipline as §5). Model in
+`lib/subscription/model.ts`. All emit `data-widget="…"`.
+
+Model types (`lib/subscription/model.ts`):
+
+- `SubscriptionStep` — `{ title: string; description: string }`.
+- `SubscriptionFigure` — `{ value: string; caption?: string; real?: boolean }` (`value` is display
+  text like `"Save 15%"` — never computed).
+- `SubscriptionManageEntry` — `{ label: string; description?: string; href: string }` (handoff URL).
+- `isIllustrative(figure: Pick<SubscriptionFigure, "real">): boolean` → `figure.real !== true`.
+
+### HowItWorksSteps (`components/subscription/HowItWorksSteps.astro`)
+
+- **Purpose:** Autopilot/subscription "how it works" explainer (numbered steps). Ships no
+  scheduling/billing mechanics.
+- **Props:** `steps: SubscriptionStep[]` (required); `eyebrow?: string`; `heading?: string`;
+  `subhead?: string`.
+- **`data-widget`:** `"subscription-how-it-works"`.
+- **Dependencies:** `type SubscriptionStep` (`@/lib/subscription/model`).
+- **Tokens consumed:** `--color-accent-ink`, `--color-text`, `--color-muted`, `--color-border`,
+  `--color-surface`, `--color-primary`, `--color-primary-contrast`, `--radius-lg`, `--radius-full`.
+- **Delivery:** platform component (no raw-chrome twin).
+- **Usage:**
+  ```astro
+  <HowItWorksSteps eyebrow="Autopilot" heading="How Autopilot works" subhead="Set it up once — we handle the rest." steps={steps} />
+  ```
+
+### SavingsExplainer (`components/subscription/SavingsExplainer.astro`)
+
+- **Purpose:** Autopilot/subscription savings headline (e.g. "Save 15% — vs. one-time purchase") +
+  supporting bullets + plain handoff CTA. Figure illustrative by default → "e.g." affordance +
+  `IllustrativeLabel` when illustrative.
+- **Props:** `figure: SubscriptionFigure` (required); `eyebrow?: string`; `heading?: string`;
+  `bullets?: string[]`; `cta?: { label: string; href: string }` (education/handoff, never a checkout
+  mechanic).
+- **`data-widget`:** `"subscription-savings-explainer"`.
+- **Dependencies:** `type SubscriptionFigure` + `isIllustrative` (`@/lib/subscription/model`);
+  `IllustrativeLabel` (cross-imports the membership affordance).
+- **Tokens consumed:** `--color-accent-ink`, `--color-text`, `--color-muted`, `--color-border`,
+  `--color-surface`, `--color-success`, `--color-primary`, `--color-primary-contrast`, `--radius-lg`,
+  `--radius-full`.
+- **Delivery:** platform component (no raw-chrome twin).
+- **Usage:**
+  ```astro
+  <SavingsExplainer eyebrow="Autopilot savings" heading="Save on every order" figure={{ value: "Save 15%", caption: "vs. one-time purchase" }} bullets={["Free shipping on every Autopilot order", "Pause or cancel anytime"]} cta={{ label: "How Autopilot works", href: "/autopilot" }} />
+  ```
+
+### ManageSubscriptionEntry (`components/subscription/ManageSubscriptionEntry.astro`)
+
+- **Purpose:** Set of manage-subscription entry points (e.g. "Update delivery date", "Pause or
+  cancel"), each a plain link into the tenant's product-owned manage flow. Renders no controls of its
+  own.
+- **Props:** `entries: SubscriptionManageEntry[]` (required); `eyebrow?: string`; `heading?: string`;
+  `subhead?: string`.
+- **`data-widget`:** `"subscription-manage-entry"`.
+- **Dependencies:** `type SubscriptionManageEntry` (`@/lib/subscription/model`).
+- **Tokens consumed:** `--color-accent-ink`, `--color-text`, `--color-muted`, `--color-border`,
+  `--color-surface`, `--color-primary`, `--radius-lg`.
+- **Delivery:** platform component (no raw-chrome twin).
+- **Usage:**
+  ```astro
+  <ManageSubscriptionEntry eyebrow="Manage" heading="Manage your Autopilot" entries={entries} />
+  ```
+
+---
+
+## 7. Marketing / widget blocks — `components/marketing/`
+
+The block library a `siteType: "marketing"` tenant composes pages from — token-driven, distinct from
+the ported `mkt.css` composition layer. Every block takes a discriminated-union `block` view-model
+from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where it emits links,
+`basePath: string`. `MarketingCta = { label: string; href: string; variant?: "primary" |
+"secondary" | "ghost" }`.
+
+### MarketingBlocks (`components/marketing/MarketingBlocks.astro`)
+
+- **Purpose:** The marketing page renderer — dispatches a `MarketingBlock[]` discriminated union to
+  its block components by `block.component`. Tenant-agnostic; reused by homepage + future marketing
+  pages.
+- **Props:** `blocks: MarketingBlock[]`; `basePath: string`.
+- **Dispatch table** (`block.component` → component): `"marketing_hero"` → `MarketingHero`;
+  `"trust_bar"` → `TrustBar`; `"split_compare"` → `SplitCompare`; `"steps"` → `Steps`; `"card_grid"`
+  → `CardGrid`; `"integrations"` → `Integrations`; `"proof_strip"` → `ProofStrip`; `"testimonials"`
+  → `Testimonials`; `"faq"` → `Faq`; `"cta_band"` → `CtaBand`; default → `null`.
+- **Dependencies:** all 10 block components; `MarketingBlock` type.
+- **Tokens consumed:** none directly (delegates to children).
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <MarketingBlocks blocks={blocks} basePath={basePath} />
+  ```
+
+### MarketingHero (`components/marketing/MarketingHero.astro`)
+
+- **Purpose:** Signature top-of-page hero for marketing tenants — eyebrow + oversized headline +
+  subhead/body + CTAs + trust chips; optional right-hand "product moment" panel of mono log lines.
+- **Props:** `block: MarketingHeroBlock` (`{ component: "marketing_hero"; eyebrow?: string; headline:
+  string; subhead?: string; body?: string; trust?: string[]; ctas?: MarketingCta[]; panel?: { title?:
+  string; lines: string[] } }`); `basePath: string`.
+- **Dependencies:** `MarketingCtas`.
+- **Tokens consumed:** `--color-bg`, `--color-text`, `--color-muted`, `--color-accent`,
+  `--color-border`, `--color-surface`, `--radius-lg`, `--shadow-lg`; helper classes `container-prose`,
+  `display-xl`, `eyebrow eyebrow--tick`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <MarketingHero block={block} basePath={basePath} />
+  ```
+
+### MarketingCtas (`components/marketing/MarketingCtas.astro`)
+
+- **Purpose:** Row of CTA buttons for marketing blocks. External `http[s]` hrefs open a new tab with
+  `rel="noopener noreferrer"`; root-absolute same-origin hrefs get the base-path prefix. Three variant
+  styles.
+- **Props:** `ctas?: MarketingCta[]` (default `[]`); `basePath: string`; `class?: string`.
+- **Dependencies:** `withBase`.
+- **Tokens consumed:** primary → `bg-accent` + `--color-primary-contrast` + `--shadow-sm`; secondary
+  → `--color-border` + `--color-surface` + `--color-text` + hover `--color-primary`; ghost →
+  `--color-primary`; `rounded-full`.
+- **Delivery:** platform component (used internally by `MarketingHero` / `CtaBand`).
+- **Usage:**
+  ```astro
+  <MarketingCtas ctas={block.ctas} basePath={basePath} class="mt-8" />
+  ```
+
+### TrustBar (`components/marketing/TrustBar.astro`)
+
+- **Purpose:** Quiet horizontal strip of proof tokens (countries, standards, ratings). Plain text,
+  mono, dot-separated.
+- **Props:** `block: TrustBarBlock` (`{ component: "trust_bar"; items: string[] }`).
+- **Dependencies:** `TrustBarBlock` type.
+- **Tokens consumed:** `--color-border`, `--color-surface`, `--color-muted`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <TrustBar block={{ component: "trust_bar", items: ["200+ countries", "SOC 2 Type II"] }} />
+  ```
+
+### SplitCompare (`components/marketing/SplitCompare.astro`)
+
+- **Purpose:** Before/after two-column comparison — `before` reads as the problem (muted, struck
+  items), `after` as the solution (accent border, ✓).
+- **Props:** `block: SplitCompareBlock` (`{ component: "split_compare"; eyebrow?: string; title:
+  string; subhead?: string; before: { title: string; items: string[] }; after: { title: string;
+  items: string[] } }`).
+- **Dependencies:** `Section`.
+- **Tokens consumed:** `--color-muted`, `--color-border`, `--color-surface`, `--color-primary`,
+  `--color-text`, `--color-accent`, `--radius-lg`, `--shadow-md`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <SplitCompare block={block} />
+  ```
+
+### Steps (`components/marketing/Steps.astro`)
+
+- **Purpose:** Numbered/emoji journey (e.g. a checkout verification flow) — a grid of step cards, each
+  with a circular number/icon badge + label + optional detail.
+- **Props:** `block: StepsBlock` (`{ component: "steps"; eyebrow?: string; title: string; subhead?:
+  string; steps: { icon?: string; label: string; detail?: string }[] }`).
+- **Dependencies:** `Section`.
+- **Tokens consumed:** `--color-muted`, `--color-border`, `--color-bg`, `--color-primary`,
+  `--color-primary-contrast`, `--color-text`, `--radius-lg`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <Steps block={block} />
+  ```
+
+### CardGrid (`components/marketing/CardGrid.astro`)
+
+- **Purpose:** Responsive grid of capability/industry/feature cards (one component, three variants
+  tuning density/columns). Cards optionally link internally (base-path) or externally.
+- **Props:** `block: CardGridBlock` (`{ component: "card_grid"; anchor?: string; eyebrow?: string;
+  title: string; subhead?: string; variant?: "capability" | "industry" | "feature"; cards: { icon?:
+  string; title: string; body?: string; meta?: string; href?: string }[]; footnote?: string }`);
+  `basePath: string`.
+- **Dependencies:** `Section`; `withBase`.
+- **Tokens consumed:** `--color-muted`, `--color-border`, `--color-surface`, `--color-text`,
+  `--radius-lg`, `--shadow-md` (hover).
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <CardGrid block={block} basePath={basePath} />
+  ```
+
+### Integrations (`components/marketing/Integrations.astro`)
+
+- **Purpose:** "Fits the store you already run" section — a strip of platform name/link chips,
+  optional implementation points (✓ list), and an optional safe code sample.
+- **Props:** `block: IntegrationsBlock` (`{ component: "integrations"; eyebrow?: string; title:
+  string; subhead?: string; platforms: { label: string; href?: string }[]; points?: string[]; code?:
+  CodeSample }`); `basePath: string`.
+- **Dependencies:** `Section`; `CodeSample`; `withBase`.
+- **Tokens consumed:** `--color-muted`, `--color-border`, `--color-bg`, `--color-text`,
+  `--color-primary` (hover), `--color-accent` (✓).
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <Integrations block={block} basePath={basePath} />
+  ```
+
+### CodeSample (`components/marketing/CodeSample.astro`)
+
+- **Purpose:** Display-only fenced code block; code rendered as **escaped** text inside `<pre><code>`
+  (never `set:html`). Never embed secrets. Caption + language label.
+- **Props:** `sample: CodeSample` where `export interface CodeSample { language?: string; code: string;
+  caption?: string }`.
+- **Dependencies:** `CodeSample` type.
+- **Tokens consumed:** `--radius-lg`, `--color-border`, `--color-text` (dark code surface); code text
+  colors are deliberately not tokenized.
+- **Delivery:** platform component (usually nested inside `Integrations`).
+- **Usage:**
+  ```astro
+  <CodeSample sample={{ language: "js", caption: "Client-side embed", code: "await verify({ minAge: 21 });" }} />
+  ```
+
+### ProofStrip (`components/marketing/ProofStrip.astro`)
+
+- **Purpose:** Privacy/trust proof band painted in the primary color (a single strong moment) — bold
+  statement + supporting copy + grid of proof bullets.
+- **Props:** `block: ProofStripBlock` (`{ component: "proof_strip"; eyebrow?: string; title: string;
+  body?: string; items?: string[] }`).
+- **Dependencies:** `ProofStripBlock` type.
+- **Tokens consumed:** `--color-primary`, `--color-primary-contrast`, `--radius-md`; chips use
+  `color-mix(... --color-primary-contrast ...)`; helper classes `container-prose`, `display-lg`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <ProofStrip block={block} />
+  ```
+
+### Testimonials (`components/marketing/Testimonials.astro`)
+
+- **Purpose:** Outcome/quote cards with optional stat lead-in + attribution, plus an optional row of
+  rating tokens.
+- **Props:** `block: TestimonialsBlock` (`{ component: "testimonials"; eyebrow?: string; title?:
+  string; quotes: { stat?: string; quote: string; attribution?: string }[]; ratings?: string[] }`).
+- **Dependencies:** `Section`.
+- **Tokens consumed:** `--color-border`, `--color-surface`, `--color-accent` (stat), `--color-text`,
+  `--color-muted`, `--radius-lg`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <Testimonials block={block} />
+  ```
+
+### Faq (`components/marketing/Faq.astro`)
+
+- **Purpose:** No-JS accordion of Q/A pairs using native `<details>`/`<summary>`; emits FAQPage
+  JSON-LD for rich results. Answers plain text (auto-escaped).
+- **Props:** `block: FaqBlock` (`{ component: "faq"; eyebrow?: string; title: string; lede?: string;
+  items: { q: string; a: string }[] }`).
+- **Dependencies:** `Section`.
+- **Tokens consumed:** `divide-[var(--color-border)]`, `--color-text`, `--color-accent` (the `+`
+  toggle), `--color-muted`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <Faq block={block} />
+  ```
+
+### CtaBand (`components/marketing/CtaBand.astro`)
+
+- **Purpose:** Final conversion band on the surface tone — headline + optional subhead + centered CTA
+  row.
+- **Props:** `block: CtaBandBlock` (`{ component: "cta_band"; title: string; subhead?: string; ctas?:
+  MarketingCta[] }`); `basePath: string`.
+- **Dependencies:** `MarketingCtas`.
+- **Tokens consumed:** `--color-surface`, `--color-muted`; helper classes `container-prose`,
+  `display-lg`; CTA tokens via `MarketingCtas`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <CtaBand block={block} basePath={basePath} />
+  ```
+
+---
+
+## 8. PLP controls — `components/plp/`
+
+URL-addressable faceted-search chrome for a collection page — every control is a real link or GET
+form carrying the query, so filtering needs no JS and is back-button safe. All take `query:
+ListProductsQuery` + `basePath: string` (from `@tot/public-runtime`) and share `@/lib/url`
+(`toggleFacet`, `buildQueryString`). None have a raw-chrome twin (PLP-body, not site chrome).
+
+### FacetSidebar (`components/plp/FacetSidebar.astro`)
+
+- **Purpose:** Faceted filtering UI — each facet value is a real link toggling a querystring param;
+  price range is a GET form preserving other params via hidden inputs. Facets ordered: options, then
+  tags, availability last.
+- **Props:** `facets: Facet[]` (from `@tot/public-runtime`); `query: ListProductsQuery`; `basePath:
+  string`.
+- **Dependencies:** `type Facet, ListProductsQuery` from `@tot/public-runtime`; `toggleFacet,
+  buildQueryString` (`@/lib/url`).
+- **Tokens consumed:** `--color-text`, `--color-muted`, `--color-accent-ink` (hover), `--radius-sm`,
+  `--color-primary`, `--color-primary-contrast`, `--color-border`, `--color-bg`; `.eyebrow` class.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <FacetSidebar facets={facets} query={query} basePath="/collections/bestsellers" />
+  ```
+
+### ActiveFilters (`components/plp/ActiveFilters.astro`)
+
+- **Purpose:** Removable filter chips above the grid; each chip is a link that drops exactly one
+  filter, plus a "Clear all" link.
+- **Props:** `query: ListProductsQuery`; `basePath: string`.
+- **Dependencies:** `type ListProductsQuery` from `@tot/public-runtime`; `toggleFacet,
+  buildQueryString` (`@/lib/url`).
+- **Tokens consumed:** `--color-border`, `--color-surface`, `--color-accent-ink` (hover),
+  `--color-muted`, `--color-primary-contrast` (group-hover fill).
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <ActiveFilters query={query} basePath="/collections/bestsellers" />
+  ```
+
+### SortSelect (`components/plp/SortSelect.astro`)
+
+- **Purpose:** Sort control — a plain GET `<form>` `<select>` that auto-submits on change (nonce'd
+  `is:inline` script; `<noscript>` Apply fallback). Other query params ride along as hidden inputs.
+  Fixed options: `featured`, `newest`, `price-asc`, `price-desc`, `title-asc`.
+- **Props:** `query: ListProductsQuery`; `basePath: string`.
+- **Dependencies:** `type ListProductsQuery` from `@tot/public-runtime`. Reads `Astro.locals.cspNonce`.
+- **Tokens consumed:** `--color-muted`, `--radius-sm`, `--color-border`, `--color-surface`;
+  `font-display`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <SortSelect query={query} basePath="/collections/bestsellers" />
+  ```
+
+### Pagination (`components/plp/Pagination.astro`)
+
+- **Purpose:** SEO-friendly numbered pagination (compact 5-page window with first/last + ellipses) +
+  a "Load more" next-page link. All plain anchors carrying the full query — crawlable, back-button
+  safe, no-JS correct.
+- **Props:** `query: ListProductsQuery`; `basePath: string`; `page: number`; `pageSize: number`;
+  `total: number`.
+- **Dependencies:** `type ListProductsQuery` from `@tot/public-runtime`; `buildQueryString`
+  (`@/lib/url`).
+- **Tokens consumed:** `--color-border`, `--color-surface`, `--color-accent` (hover),
+  `--color-accent-ink`, `--radius-sm`, `--color-muted`, `--color-primary`, `--color-primary-contrast`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <Pagination query={query} basePath="/collections/bestsellers" page={2} pageSize={12} total={58} />
+  ```
+
+---
+
+## 9. Islands — `components/islands/`
+
+Client-hydrated Preact `.tsx`. Every island is tenant-agnostic and reads only fixtures / `localStorage`
+/ its own props — **no live catalog, cart, or ToT calls** (`SearchTypeahead` fetches the tenant's own
+`/search` endpoint). Cross-island wiring uses `window` CustomEvents; `localStorage` keys in play:
+`"tot:age-affirmed"`, `"tot:recently-viewed"`, `"tot:wishlist"`.
+
+### AgeGate (`components/islands/AgeGate.tsx`)
+
+- **Purpose:** Soft `minAge`+ affirmation overlay, shown once per device for regulated tenants.
+  Front-door affirmation only — real ToT identity/age verification is a later phase (the "Yes" path is
+  where that handoff will live).
+- **Props:** `{ minAge: number; brand: string }`. Directive: `client:load`.
+- **State:** reads/writes `localStorage` `"tot:age-affirmed"` (`"yes"`); local state machine; locks
+  page scroll while asking. No network.
+- **Dependencies:** `preact/hooks`.
+- **Tokens consumed:** `--color-text` (backdrop mix), `--radius-lg`, `--color-surface`, `--shadow-lg`,
+  `--radius-md`, `--color-primary`, `--color-primary-contrast`, `--color-border`, `--color-muted`;
+  classes `eyebrow eyebrow--tick`, `display-md`, `link-accent`.
+- **Delivery:** platform island + raw-chrome twin `.age-gate` / `.age-gate__panel` / `__mark` /
+  `__actions` / `__deny` / `__fine` / `.is-open` / `.is-denied` (same `localStorage` key + closed
+  shadow-DOM tamper pattern, produced server-side by `lib/rawChrome.ts`).
+- **Usage:**
+  ```astro
+  <AgeGate client:load minAge={21} brand={tenant.brandName} />
+  ```
+
+### IsolatedAgeGate (`components/islands/IsolatedAgeGate.tsx`)
+
+- **Purpose:** Tamper-resistant wrapper that mounts `<AgeGate>` inside a **closed shadow root** so no
+  tenant CSS/JS can select, restyle, or hide it. A light-DOM host `<div data-tot-compliance>` is
+  re-asserted by a `MutationObserver` (restored if detached / `display:none` / `hidden`). "Customize
+  anything except what keeps you legal," as a technical guarantee — this is the production age-gate
+  mount for component pages.
+- **Props:** `{ minAge: number; brand: string }` (passed through). Returns `null`; mounts via
+  `useEffect`. Directive: `client:load`.
+- **State:** no own state; clones `link[rel=stylesheet]` into the shadow root (`:root` tokens inherit
+  across the boundary); inherits AgeGate's localStorage behavior. No network.
+- **Dependencies:** `preact` (`render`), `preact/hooks`; `./AgeGate`.
+- **Tokens consumed:** none of its own (delegates to AgeGate; relies on `:root` token inheritance).
+- **Delivery:** platform island (server/raw-chrome equivalent is the closed-shadow gate in
+  `CHROME_BEHAVIOR_JS`).
+- **Usage:**
+  ```astro
+  <IsolatedAgeGate client:load minAge={21} brand={tenant.brandName} />
+  ```
+
+### VariantSelector (`components/islands/VariantSelector.tsx`)
+
+- **Purpose:** PDP variant picker (the centerpiece interaction) — one radiogroup per product option;
+  resolves the matching variant, disables unbuyable combinations, updates a polite live region
+  (price/compare-at/SKU/stock), and drives cross-island events. Add-to-cart is a real checkout form
+  when a signed payload is wired, else a disabled placeholder.
+- **Props:** `{ variants: CatalogVariant[]; options: OptionDef[]; currency: string; locale?: string;
+  checkoutCart?: { action: string; purchaseOptions: ProductPurchaseOption[]; byVariantId: Record<string, Record<string, VariantCartPayload>> } }` where local
+  `OptionDef = { name: string; position: number; values: string[] }`; `CatalogVariant` /
+  `VariantCartPayload` from `@tot/public-runtime`. Directive: `client:load`.
+- **State:** props only. Default selection = first available variant. Dispatches `window` CustomEvents
+  `variant:image { imageId }` (consumed by `ImageGallery`) and `variant:change { variantId, available
+  }`. No storage; no catalog/ToT fetch.
+- **Dependencies:** `preact/hooks`; `formatPrice` (`@/lib/format`); types from `@tot/public-runtime`.
+- **Tokens consumed:** `text-muted`, `text-sale`, `text-accent`, `text-primary`, `text-text`,
+  `border-border`, `bg-surface`, `border-primary`/`bg-primary`/`text-primary-contrast`,
+  `outline-primary`, `bg-border/40`.
+- **Delivery:** platform island (PDP).
+- **Usage:**
+  ```astro
+  <VariantSelector client:load variants={product.variants} options={product.options} currency={product.price_range.currency} locale="en-US" />
+  ```
+
+### ImageGallery (`components/islands/ImageGallery.tsx`)
+
+- **Purpose:** PDP image gallery — main image + thumbnail strip; thumbnails swap the main image, main
+  image has click-to-toggle zoom (reduced-motion safe). First image is the LCP candidate until first
+  interaction.
+- **Props:** `{ images: CatalogImage[]; title: string; productHandle: string; activeImageId?: string }`
+  (`CatalogImage` from `@tot/public-runtime`). Realistic directive: `client:load`.
+- **State:** props only. Listens on `window` for `variant:image { imageId }` (dispatched by
+  `VariantSelector`) and switches to the matching image. Dead fixture URLs fall back to a deterministic
+  placeholder. No network.
+- **Dependencies:** `preact/hooks`; `placeholderDataUri, isUsableImageUrl` (`@/lib/placeholder`);
+  type from `@tot/public-runtime`.
+- **Tokens consumed:** `--color-border` (placeholder bg); `outline-primary` (focus), `border-primary`
+  / `border-border` (thumbnails).
+- **Delivery:** platform island (PDP).
+- **Usage:**
+  ```astro
+  <ImageGallery client:load images={product.images} title={product.title} productHandle={product.handle} />
+  ```
+
+### QuickView (`components/islands/QuickView.tsx`)
+
+- **Purpose:** One global native `<dialog>` any product card opens via a `[data-quickview]` button
+  (event-delegated, so cards stay zero-JS). Shows a peek — image, price, colors, short description —
+  and routes to the full PDP. No cart action (Phase 1 browse-only).
+- **Props:** `{ locale: string }`. Directive: `client:idle`. The per-card payload is parsed from the
+  button's `data-quickview` JSON attribute.
+- **State:** props + DOM-delegated clicks. Reads product data from the clicked button's attribute, not
+  storage/network.
+- **Dependencies:** `preact/hooks`; `formatPrice` (`@/lib/format`), `@/lib/placeholder`, `withClientBase`
+  (`@/lib/basePath`).
+- **Tokens consumed:** `--radius-lg`, `--color-surface`, `--color-text` (+ backdrop mix),
+  `--color-border`, `--color-muted`, `--color-sale`, `--color-bg`, `--radius-md`, `--color-primary`,
+  `--color-primary-contrast`.
+- **Delivery:** platform island (global, mounted once per page).
+- **Usage:**
+  ```astro
+  <QuickView client:idle locale="en-US" />
+  ```
+
+### SearchTypeahead (`components/islands/SearchTypeahead.tsx`)
+
+- **Purpose:** Compact header search with debounced typeahead dropdown. Fetches `GET
+  {action}?q=<q>&format=json` and renders up to 6 results as an ARIA combobox/listbox; submitting
+  navigates to the full results page.
+- **Props:** `{ action?: string }` (default `"/search"`). Directive: `client:idle`. `TypeaheadDoc`
+  from `@/lib/search`.
+- **State:** local state only; debounced `fetch` (150 ms, min 2 chars, `AbortController`) against the
+  tenant's own `/search` endpoint (base-path prefixed) — a same-app fetch, not a catalog/cart/ToT API.
+  Failures degrade to "no dropdown". No storage.
+- **Dependencies:** `preact/hooks`; `type TypeaheadDoc` (`@/lib/search`), `@/lib/format`,
+  `@/lib/placeholder`, `withClientBase` (`@/lib/basePath`).
+- **Tokens consumed:** `border-border`, `bg-surface`, `border-primary`/`focus-within:border-primary`,
+  `text-muted`, `text-text`, `placeholder:text-muted`, `shadow-lg`, `bg-border/50`; thumb uses
+  `--color-border`.
+- **Delivery:** platform island (header).
+- **Usage:**
+  ```astro
+  <SearchTypeahead client:idle />
+  ```
+
+### MobileNav (`components/islands/MobileNav.tsx`)
+
+- **Purpose:** Hamburger button + slide-in drawer for small screens (`md:hidden`). WCAG 2.2 AA:
+  `aria-expanded`/`aria-controls`, focus trap, Escape + backdrop close, body-scroll lock, focus
+  restore, reduced-motion guard.
+- **Props:** `{ nav: NavItem[]; announcement?: string }` where `NavItem = { label: string; href: string;
+  children?: { label: string; href: string }[] }`. Directive: `client:idle`.
+- **State:** props only; local `open` state; toggles body scroll. No storage/network.
+- **Dependencies:** `preact/hooks`.
+- **Tokens consumed:** `text-text`, `bg-surface`, `outline-primary`, `bg-text/40` (backdrop),
+  `border-border`, `text-muted`, `bg-primary`, `text-primary-contrast`, `text-primary`, `bg-border/40`,
+  `shadow-xl`.
+- **Delivery:** platform island (mobile chrome; raw-chrome analog is the hamburger/`#primaryNav` toggle
+  in `CHROME_BEHAVIOR_JS` + the off-canvas `.primary-nav`/`.hamburger` rules).
+- **Usage:**
+  ```astro
+  <MobileNav client:idle nav={nav} announcement="Free US shipping on orders over $100" />
+  ```
+
+### RecentlyViewed (`components/islands/RecentlyViewed.tsx`)
+
+- **Purpose:** "Recently viewed" discovery rail. On a PDP it records the current product to
+  localStorage and renders the rest as a quiet strip. Renders nothing until it has something to show
+  (no layout shift / empty-state noise).
+- **Props:** `{ current?: RVItem; locale: string; title?: string; max?: number }` (`title` default
+  `"Recently viewed"`, `max` default `5`) where `export interface RVItem { handle: string; title:
+  string; price: number; currency: string; vendor?: string; img?: string; rehosted?: boolean; seed:
+  string }`. Directive: `client:idle`.
+- **State:** reads/writes `localStorage` `"tot:recently-viewed"` (JSON array, capped at 12); excludes
+  `current`. No network.
+- **Dependencies:** `preact/hooks`; `formatPrice` (`@/lib/format`), `@/lib/placeholder`,
+  `withClientBase` (`@/lib/basePath`).
+- **Tokens consumed:** `--color-border`, `--color-muted`, `--color-primary`; class `eyebrow
+  eyebrow--tick`, `container-prose`.
+- **Delivery:** platform island.
+- **Usage:**
+  ```astro
+  <RecentlyViewed client:idle locale="en-US" />
+  <!-- On a PDP, pass current so it's recorded + excluded: -->
+  <RecentlyViewed client:idle current={rvItem} locale="en-US" />
+  ```
+
+### SavedList (`components/islands/SavedList.tsx`)
+
+- **Purpose:** Renders the wishlist from localStorage on the `/saved` page. Client-only; each item
+  links to its PDP and can be removed inline; empty state invites browsing. Phase 2 swaps the store for
+  an account-backed list without touching the component.
+- **Props:** `{ locale: string }`. Directive: `client:only="preact"` (no SSR — the list only exists
+  client-side). `SavedItem` from `@/lib/wishlist`.
+- **State:** reads `localStorage` `"tot:wishlist"` via `readWishlist()`; listens for `WISHLIST_EVENT`
+  (`"tot:wishlist-changed"`) to refresh; removes via `toggleSaved()`. Renders `null` pre-hydration.
+- **Dependencies:** `preact/hooks`; `readWishlist, toggleSaved, WISHLIST_EVENT, type SavedItem`
+  (`@/lib/wishlist`), `@/lib/format`, `@/lib/placeholder`, `@/lib/basePath`.
+- **Tokens consumed:** `--radius-lg`, `--color-border`, `--color-surface`, `--color-muted`,
+  `--radius-md`, `--color-primary`, `--color-primary-contrast`, `--color-sale` (heart).
+- **Delivery:** platform island (`/saved` page).
+- **Usage:**
+  ```astro
+  <SavedList client:only="preact" locale="en-US" />
+  ```
+
+---
+
+## 10. Foundational atoms + home — `components/*`, `components/home/`
+
+Shared primitives composed by the higher-level widgets, plus the homepage hero.
+
+### Badge (`components/Badge.astro`)
+
+- **Purpose:** Tiny mono-uppercase pill used over product imagery and inline (sale %, New, low-stock,
+  sold-out, compliance-verified).
+- **Props:** `variant: "sale" | "new" | "low-stock" | "soldout" | "compliant"`; `label?: string` (or
+  default slot); `class?: string`.
+- **Dependencies:** none.
+- **Tokens consumed:** `bg-sale`, `bg-primary text-primary-contrast`, `bg-accent`, `bg-surface
+  text-muted border-border`, `bg-[var(--color-success)]`; `font-mono`, `rounded-full`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <Badge variant="compliant" label="Compliant" />
+  ```
+
+### Breadcrumbs (`components/Breadcrumbs.astro`)
+
+- **Purpose:** Semantic breadcrumb trail; last crumb is the current page (`aria-current`, not a link).
+- **Props:** `crumbs: { label: string; href: string }[]`.
+- **Dependencies:** `withBase`.
+- **Tokens consumed:** `text-muted`, `text-border`, `text-text`, `hover:text-primary`.
+- **Delivery:** platform component (`.crumbs` exists in the marketing `mkt.css` layer, not
+  commerce-chrome.css).
+- **Usage:**
+  ```astro
+  <Breadcrumbs crumbs={[{ label: "Home", href: "/" }, { label: "Bestsellers", href: "/collections/bestsellers" }]} />
+  ```
+
+### ProductCard (`components/ProductCard.astro`)
+
+- **Purpose:** PLP/grid card using the stretched-link pattern (title is the link; an `::after` overlay
+  makes the whole card clickable so wishlist/quick-view controls sit above it). Image hover-zoom +
+  optional second image; status badges; color swatches; price with struck compare-at; optional rating.
+- **Props:** `product: CatalogProduct`; `position?: number`; `list?: string`; `priority?: boolean`;
+  `rating?: number`; `reviewCount?: number`.
+- **Dependencies:** `CatalogProduct` from `@tot/public-runtime`; `discountPercent, truncate`
+  (`@/lib/format`); `isOnSale, isNew, isAvailable, fromPrice` (`@/lib/tot/query`); `colorOptionValues,
+  resolveSwatch, isLightFill` (`@/lib/colors`); `Img`, `Badge`, `PriceDisplay`, `RatingStars`;
+  `withBase`. Reads `Astro.locals.tenant` (`.locale`) + `Astro.locals.basePath`. The compliance badge
+  is tag-driven (`compliant`/`lab-tested`/`age-verified`) — tenant-agnostic, no per-merchant branch.
+- **Tokens consumed:** `bg-border`, `ring-[var(--color-border)]`, `shadow-[var(--shadow-md)]`,
+  `rounded-md`, `rounded-[var(--radius-sm)]`, `text-[var(--color-text)]`, `hover:text-[var(--color-sale)]`,
+  `text-muted`, `group-hover:text-primary`, `font-display`, `font-mono`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <ProductCard product={p} rating={4.5} reviewCount={128} />
+  ```
+
+### CollectionCard (`components/CollectionCard.astro`)
+
+- **Purpose:** Editorial collection tile with a dark gradient scrim so the overlaid title (+ optional
+  piece count) reads on any image. `data-reveal` scroll-in.
+- **Props:** `collection: CatalogCollection` (from `@tot/public-runtime`); `productCount?: number`.
+- **Dependencies:** `CatalogCollection` from `@tot/public-runtime`; `Img`; `withBase`.
+- **Tokens consumed:** `bg-border`, `rounded-md`, `font-display`, `font-mono` (overlay uses fixed
+  `text-white` / `from-black/75` scrim).
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <CollectionCard collection={collection} productCount={24} />
+  ```
+
+### Section (`components/Section.astro`)
+
+- **Purpose:** Section wrapper with consistent vertical rhythm + optional eyebrow/title header +
+  alternating band background.
+- **Props:** `title?: string`; `eyebrow?: string`; `tone?: "bg" | "surface"`; `class?: string`; `id?:
+  string`. Slots: default + named `header-aside`.
+- **Dependencies:** none.
+- **Tokens consumed:** `bg-[var(--color-surface)]` / `bg-[var(--color-bg)]`; classes `container-prose`,
+  `eyebrow eyebrow--tick`, `display-lg`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <Section eyebrow="Shop" title="Best Sellers" tone="surface"> … </Section>
+  ```
+
+### EmptyState (`components/EmptyState.astro`)
+
+- **Purpose:** Intentional empty result (search/PLP). Copy passed in by the parent; optional CTA.
+- **Props:** `title: string`; `body?: string`; `ctaLabel?: string`; `ctaHref?: string`.
+- **Dependencies:** `withBase`.
+- **Tokens consumed:** `text-muted`, `bg-primary`, `text-primary-contrast`, `font-display`,
+  `rounded-full`; class `display-md`.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <EmptyState title="No results" body="Try broadening your filters." ctaLabel="Browse all" ctaHref="/collections/all" />
+  ```
+
+### Img (`components/Img.astro`)
+
+- **Purpose:** CLS-free, theme-agnostic image with offline placeholder fallback — dead fixture URLs
+  render a deterministic gradient SVG keyed by `seed`; real rehosted / Shopify `?width=` URLs get
+  responsive srcset/sizes. Explicit width/height always set.
+- **Props:** `src?: string`; `alt: string`; `width: number`; `height: number`; `seed: string`; `label?:
+  string`; `rehosted?: boolean`; `priority?: boolean` (LCP: eager+high); `sizes?: string`; `class?:
+  string`; `loading?: "eager" | "lazy"`.
+- **Dependencies:** `resolveImage` (`@/lib/imageAttrs`).
+- **Tokens consumed:** `--color-border` (placeholder backdrop).
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <Img src={image?.url} rehosted={image?.rehosted} seed={image?.id ?? handle} alt={title} width={800} height={1000} sizes="(min-width:1024px) 25vw, 100vw" priority />
+  ```
+
+### WidgetFrame (`components/WidgetFrame.astro`)
+
+- **Purpose:** Renders a tenant-registered widget (`isolation: "sandbox"`) in a sandboxed iframe —
+  `allow-scripts` without `allow-same-origin` puts it in an opaque origin (can't read page
+  cookies/DOM/storage); bundle hash-pinned in CSP.
+- **Props:** `src: string` (same-origin bundle URL); `title: string` (required a11y); `strategy?:
+  ScriptStrategy` (from `@tot/public-runtime`, default `"on-idle"`); `height?: string` (default
+  `"auto"`).
+- **Dependencies:** `widgetFrameAttrs, type ScriptStrategy` from `@tot/public-runtime`.
+- **Tokens consumed:** none (`.tot-widget-frame` + inline sizing; no theme tokens).
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <WidgetFrame src="/widgets/tenant-abc/reviews.html" title="Customer reviews" height="480px" />
+  ```
+
+### Seo (`components/Seo.astro`)
+
+- **Purpose:** Per-page `<title>`/meta, Open Graph, Twitter card, canonical, JSON-LD. Tenant-aware —
+  OG image + site name from the resolved tenant. Head-only (renders no styled markup).
+- **Props:** `title: string`; `description?: string`; `path: string` (path-only canonical, joined to
+  the tenant canonical base); `ogType?: "website" | "product" | "article"`; `ogImage?: string`;
+  `noindex?: boolean`; `jsonLd?: JsonLd | JsonLd[]` (`JsonLd = { [key: string]: unknown }`).
+- **Dependencies:** none. Reads `Astro.locals.tenant` (`.displayName`, `.theme_tokens?.brand?.ogImage`)
+  + `Astro.locals.canonicalBase`.
+- **Tokens consumed:** none.
+- **Delivery:** platform component.
+- **Usage:**
+  ```astro
+  <Seo title="Merino Zip Hoodie" description="Soft, warm, everyday." path="/products/merino-zip-hoodie" ogType="product" jsonLd={productSchema} />
+  ```
+
+### Hero (`components/home/Hero.astro`)
+
+- **Purpose:** The signature homepage moment ("hero is a thesis"). Treatments: `"bold"` (default —
+  full-bleed primary background, contrast text), `"light"` (page background, brand color as
+  headline/CTA accent), `"banner"` (merchant artwork edge-to-edge); non-empty `slides` render a
+  slideshow. Feature image is the merchant's own hero slide (`block.image`) when adopted, else the
+  hero collection's first product. `block.notice` renders a `.hero__notice` status pill in every
+  treatment.
+- **Props:** `block: HeroBlock` (from `@/lib/storyblok/content-model`: `{ component: "hero"; notice?:
+  string; eyebrow?: string; headline: string; headlineAccent?: string; subhead?: string; ctaLabel?: string; ctaHref?:
+  string; featureCollection?: string; image?: string; imageAlt?: string }`); `featureProduct?:
+  CatalogProduct | null`.
+- **Dependencies:** `Img`; `withBase`; `HeroBlock` + `CatalogProduct` (`@tot/public-runtime`).
+- **Note:** the bold/light variant is read from
+  `Astro.locals.tenant?.theme_tokens?.brand?.heroVariant` — **not a prop**. Also reads
+  `Astro.locals.basePath`.
+- **Tokens consumed:** `--color-bg`, `--color-text`, `--color-primary`, `--color-primary-contrast`,
+  `--color-muted`, `--color-accent`, `--radius-lg`, `--shadow-lg`, `--radius-md`, `--color-surface`,
+  `--color-border`, `--color-hero-eyebrow`, `--heading-hero`; classes `display-hero`,
+  `hero__eyebrow eyebrow eyebrow--tick`, `hero__notice`, `container-prose`.
+- **Delivery:** platform component (SSR, homepage).
+- **Usage:**
+  ```astro
+  ---
+  // tenant sets Astro.locals.tenant.theme_tokens.brand.heroVariant = "bold" | "light" | "banner"
+  ---
+  <Hero block={heroBlock} featureProduct={featureProduct} />
+  ```
+
+---
+
+## 11. Shared raw-chrome library — `lib/rawChrome.ts`, `lib/chrome/`, `public/shared/commerce-chrome.css`
+
+The raw-chrome path exists so a tenant that ships **hand-authored raw marketing HTML** still gets the
+platform chrome look without copying CSS. It is the second delivery path referenced throughout §2–§4.
+
+### `lib/rawChrome.ts` — the canonical raw-chrome generator
+
+Replaces the three divergent hand-authored `content/<tenant>/chrome.html` documents with **one
+deterministic server-side generator** driven entirely by a tenant's `chrome.json` (typed
+`TenantChrome`) — **content only, no styling**.
+
+- **Single-stylesheet model** (`raw-chrome-single-stylesheet`): the wrapper `<link>`s exactly one
+  platform stylesheet, `SHARED_CHROME_STYLESHEET = "/shared/commerce-chrome.css"`, and emits **no
+  inline chrome CSS**. Every color/space/type comes from theme tokens the tenant's own linked
+  `*-theme.css` sets on `:root`. The markup mirrors, class-for-class, the DOM the F2 stylesheet styles.
+- **Splice-marker output** (`materialization-compat`): returns a full `<!DOCTYPE html>` document
+  carrying `<!--PAGE_HEAD-->` / `<!--PAGE_BODY-->` markers (`CHROME_HEAD_MARKER` / `CHROME_BODY_MARKER`)
+  so body-only page fragments get spliced in and the result is nonce-stamped + base-path-prefixed
+  downstream. `rawMarketingHtml.prefixTenantLinks` exempts `/shared/` so the shared link survives
+  path-prefix routing.
+- **Security:** all authored values are HTML-escaped (`esc`/`escSingle`) — defense-in-depth for
+  first-party config.
+
+Exports:
+
+- `renderRawChrome(chrome: TenantChrome): string` — the entry point. Builds `<head>` (theme-color,
+  favicon, tenant `themeStylesheets`, then the shared stylesheet), a skip link, then conditional
+  sections in order: `warningBar` → `announcement` → `utilityNav` → header; the body marker; then
+  `complianceStrip` → footer; then the age-gate JSON `<script>` + the inlined behavior script.
+- `CHROME_BEHAVIOR_JS: string` — the ONE shared, nonce-safe progressive-enhancement script (never
+  copy-pasted per tenant). Three guarded blocks: (1) mobile nav drawer toggle (`#hamburger`/
+  `#primaryNav`), (2) announcement-bar dismiss (remembered in `localStorage`, default key
+  `tot_announce_dismissed`) + message rotation, (3) the 21+ age gate built inside a **closed shadow
+  root** with a `data-tot-compliance` light-DOM host + `MutationObserver` re-assert — the same
+  tamper-resistance pattern as `IsolatedAgeGate.tsx`, keyed on `tot:age-affirmed`.
+- `SHARED_CHROME_STYLESHEET: string` = `"/shared/commerce-chrome.css"`.
+
+### `lib/chrome/model.ts` — typed chrome config
+
+Re-exports `@tot/public-runtime`'s `ChromeConfig` (`packages/public-runtime/src/chrome.ts`) — the
+ONE schema for a tenant's site chrome, content-only, skinned by tokens. `header` and `footer` are
+independent, separately-evolvable sub-shapes; every nav item, header CTA and footer link carries a
+stable `id` (a governed-action-registry substitute, independent of the visible `label`). In addition
+to `ChromeHeader`/`ChromeFooter`, it exports `ChromeBrand`, `ChromeSearch`, `ChromeUtilityNav`,
+`ChromeAnnouncement` (`{ variant: "marquee" | "bar" | "solid"; messages: string[]; label?;
+dismissible?; rotateMs?; storageKey? }`), `ChromeAgeGate` (`{ minAge: number; storageKey?; title?;
+lede?; yesLabel?; noLabel?; denyText?; fineText?; mark? }`), `ChromeFooterBrand`, `ChromeTrustMark`,
+`ChromeHead`, `ChromeCta`, `ChromeNavItem`, and `ChromeConfig` itself.
+
+### `lib/chrome/parseConfig.ts` — the validation gate
+
+Re-exports `@tot/public-runtime`'s `validateChromeConfig`/`parseChromeConfig`. `parseChromeConfig(raw:
+unknown): ChromeConfig | null` returns a config only when `raw.header` and `raw.footer` both validate
+(header: a valid `variant`, `brand.label` string, `nav` array; footer: a valid `variant`, `columns`
+array — see {@link validateChromeConfig} for the full per-field rules). Any other shape (missing,
+malformed, or half-authored) returns `null`, so the caller keeps serving the tenant's hand-authored
+`chrome.html`. `validateChromeConfig(raw)` returns the actionable, path-prefixed error list instead of
+collapsing to `null` — this is what `@tot/private-controlplane`'s write-side `ArtifactValidator` for
+`tenants/<id>/content/chrome.json` calls, so a malformed `chrome.json` is rejected with real diagnostics
+at candidate-submission time.
+
+### `public/shared/commerce-chrome.css` — the one shared stylesheet (F2)
+
+ONE platform-shipped, token-driven sheet that generalizes the three per-tenant `mkt.css` files into a
+single themed layer. **Contract-token-only** — reads only `--color-*` / `--font-*` / `--radius-*` /
+`--shadow-*` / `--container-max`, no tenant-private brand vars or hard-coded hex; on-dark surfaces
+(footer, age-gate overlay, category cards) derive from `--color-text` + `--color-primary-contrast` via
+`color-mix`. Its header documents the old-var → contract-token mapping (`--navy`/`--brand-red` →
+`--color-primary`, `--sale` → `--color-sale`, `--brand-blue` → `--color-accent`). Main selector groups:
+
+- **Layout:** `.container`, `.section` / `.section--tight` / `.section--surface`.
+- **Buttons:** `.btn` + `.btn-primary` / `.btn-secondary` / `.btn-line` / `.btn-ghost` / `.btn-outline`.
+- **Announcement:** `.announce`, `.announce-marquee` / `__track` (`@keyframes chrome-marquee`,
+  reduced-motion stops it), `.announce-bar` / `__msg` / `__close`.
+- **Utility / top bar:** `.topbar-warning` (FDA strip), `.utility-nav` / `__right` / `.sel` / `.social`,
+  `.member-cue`.
+- **Header / nav:** `.site-header` (sticky) / `.header-row`, `.brand` (+ `.b-prime`/`.b-vapor`/`.b-club`),
+  `.header-search`, `.header-actions` / `.cart` / `.count`, `.hamburger`.
+- **Primary nav + mega:** `.primary-nav` / `> ul`, `.is-flag`, `.nav-item`, `.caret`, `.new-badge`,
+  `.primary-nav-bar`, `.mega` / `.mega--wide` / `.mega__cols` / `.mega__col`.
+- **Section headers:** `.sec-head` / `--between` / `.eyebrow` / `.link-more`.
+- **Tiles / grids:** `.tile-grid` / `.tile`, `.brand-grid` / `.brand-tile` / `__text`, `.article-grid`
+  / `.article-card` (+ `__media`/`__body`/`__tag`/`__title`/`__excerpt`/`__meta`), `.tag-cloud` /
+  `.tag-chip`.
+- **Category cards:** `.cat-grid` / `.cat-card` (gradient primary→primary-hover).
+- **Compliance:** `.compliance-strip` (source-copied legal band).
+- **Age gate:** `.age-gate` / `.is-open` / `__panel` / `__mark` (+ `.is-red`) / `__actions` / `__deny` /
+  `.is-denied` / `__fine` / `__lede`.
+- **Footer:** `.site-footer` / `.footer-grid` / `.footer-brand` / `.footer-col` / `.footer-news`
+  (+ `__row`, `.footer-attest`) / `.pay-badges` / `.trust-marks` / `.footer-warning` / `.footer-bottom`.
+- **Reveal-on-scroll:** `.reveal` / `.reveal.in`.
+- **Responsive:** breakpoints at 1000 / 960 / 860 (off-canvas `.primary-nav` drawer, `.hamburger`,
+  mega→inline accordion) / 560 px.
+
+---
+
+## Appendix — cross-cutting reference
+
+**Cross-island `window` CustomEvents:** `variant:image` (VariantSelector → ImageGallery),
+`variant:change` (VariantSelector → any listener), `tot:wishlist-changed` / `WISHLIST_EVENT`
+(`lib/wishlist` → SavedList + header count), and delegated `[data-quickview]` buttons → QuickView.
+
+**`localStorage` keys:** `"tot:age-affirmed"` (age gate), `"tot:recently-viewed"` (RecentlyViewed),
+`"tot:wishlist"` (SavedList/wishlist), `tot_announce_dismissed` (raw-chrome announce dismissal).
+
+**`data-compliance` hooks (9):** `nicotine-warning`, `pact-act`, `adult-signature`, `prop65`,
+`purchase-limit`, `state-eligibility`, `shipping-restriction`, `excise-tax`, plus `ComplianceNotice`
+re-emitting the caller's `hook`.
+
+**`data-widget` hooks (5):** `tier-cards`, `tier-comparison-table`, `subscription-how-it-works`,
+`subscription-savings-explainer`, `subscription-manage-entry`. Illustrative surfaces are marked
+`data-illustrative="badge" | "note" | "figure"`.
+
+**Related architecture docs:** [`token-contract.md`](architecture/token-contract.md),
+[`shared-vs-tenant-assets.md`](architecture/shared-vs-tenant-assets.md).