@tokenoftrust/storefront-runner 2.4.86 → 2.4.88

package/docs/widget-library-guide.md

@@ -62,7 +62,7 @@ CSS (decision `raw-chrome-single-stylesheet` / `materialization-compat`):
 - **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
+  component DOM. The server-side generator `lib/content/shared/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.
@@ -106,9 +106,9 @@ libs, and any tenant config/locals it reads), **Tokens consumed**, **Delivery**
 - §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`
+- §11 Shared raw-chrome library — `lib/content/shared/rawChrome.ts`, `lib/chrome/`, `public/shared/commerce-chrome.css`
 
-Shared chrome model (`lib/chrome/model.ts`), referenced throughout §2:
+Shared chrome model (`lib/content/chrome/model.ts`), referenced throughout §2:
 
 - `ChromeLink` — `{ label: string; href: string; external?: boolean; badge?: string }`
 - `MegaColumn` — `{ title?: string; links: ChromeLink[] }`
@@ -127,7 +127,7 @@ The site frame: announcement, utility bar, header, primary/mega nav, footer. All
 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`)
+### AnnouncementBar (`components/content/storefront/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).
@@ -145,7 +145,7 @@ raw-chrome twin in `public/shared/commerce-chrome.css`. Every href-emitting chro
   <AnnouncementBar text="Free US shipping on orders over $100!" variant="marquee" tone="sale" />
   ```
 
-### UtilityNav (`components/chrome/UtilityNav.astro`)
+### UtilityNav (`components/content/storefront/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).
@@ -166,7 +166,7 @@ raw-chrome twin in `public/shared/commerce-chrome.css`. Every href-emitting chro
   />
   ```
 
-### SiteHeader (`components/chrome/SiteHeader.astro`)
+### SiteHeader (`components/content/storefront/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.
@@ -195,7 +195,7 @@ raw-chrome twin in `public/shared/commerce-chrome.css`. Every href-emitting chro
   />
   ```
 
-### MegaMenu (`components/chrome/MegaMenu.astro`)
+### MegaMenu (`components/content/storefront/chrome/MegaMenu.astro`)
 
 - **Purpose:** Primary desktop nav bar — a horizontal `<ul>` of items, each rendered by
   `<NavDropdown>`. Hidden below `md`.
@@ -210,7 +210,7 @@ raw-chrome twin in `public/shared/commerce-chrome.css`. Every href-emitting chro
   <MegaMenu items={nav} />
   ```
 
-### NavDropdown (`components/chrome/NavDropdown.astro`)
+### NavDropdown (`components/content/storefront/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`),
@@ -228,7 +228,7 @@ raw-chrome twin in `public/shared/commerce-chrome.css`. Every href-emitting chro
   <NavDropdown item={item} mode="accordion" />
   ```
 
-### SiteFooter (`components/chrome/SiteFooter.astro`)
+### SiteFooter (`components/content/storefront/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
@@ -265,7 +265,7 @@ Product cards, merchandising rows, price/rating atoms, blog cards, and checkout
 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`)
+### PriceDisplay (`components/catalog/storefront/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.
@@ -282,7 +282,7 @@ class-only block in `public/shared/commerce-chrome.css` (`.article-card`, `.bran
   <PriceDisplay amount={42} from currency="USD" />
   ```
 
-### RatingStars (`components/commerce/RatingStars.astro`)
+### RatingStars (`components/catalog/storefront/commerce/RatingStars.astro`)
 
 - **Purpose:** 0–5 star rating with fractional fill (single clipped overlay) + accessible label;
   optional numeric review count. Presentation only.
@@ -297,7 +297,7 @@ class-only block in `public/shared/commerce-chrome.css` (`.article-card`, `.bran
   <RatingStars rating={4.5} count={128} />
   ```
 
-### ProductCarousel (`components/commerce/ProductCarousel.astro`)
+### ProductCarousel (`components/catalog/storefront/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
@@ -319,7 +319,7 @@ class-only block in `public/shared/commerce-chrome.css` (`.article-card`, `.bran
   <ProductCarousel title="Featured" tabs={[{ label: "New", products: newest }, { label: "On Sale", products: onSale }]} />
   ```
 
-### ProductGrid (`components/commerce/ProductGrid.astro`)
+### ProductGrid (`components/catalog/storefront/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.
@@ -337,7 +337,7 @@ class-only block in `public/shared/commerce-chrome.css` (`.article-card`, `.bran
   <ProductGrid title="All Products" products={products} columns={3} />
   ```
 
-### BrandGrid (`components/commerce/BrandGrid.astro`)
+### BrandGrid (`components/catalog/storefront/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.
@@ -354,7 +354,7 @@ class-only block in `public/shared/commerce-chrome.css` (`.article-card`, `.bran
   <BrandGrid title="Shop by Brands" eyebrow="Find your fav" brands={brands} viewAllHref="/brands" tone="surface" />
   ```
 
-### ArticleCard (`components/commerce/ArticleCard.astro`)
+### ArticleCard (`components/content/storefront/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
@@ -373,7 +373,7 @@ class-only block in `public/shared/commerce-chrome.css` (`.article-card`, `.bran
   <ArticleCard article={article} />
   ```
 
-### TagFilterCloud (`components/commerce/TagFilterCloud.astro`)
+### TagFilterCloud (`components/catalog/storefront/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
@@ -391,7 +391,7 @@ class-only block in `public/shared/commerce-chrome.css` (`.article-card`, `.bran
   <TagFilterCloud title="Browse by topic" tags={tags} allHref="/blog" allActive={false} />
   ```
 
-### CheckoutLoader (`components/commerce/CheckoutLoader.astro`)
+### CheckoutLoader (`components/checkout/storefront/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.
@@ -404,7 +404,7 @@ class-only block in `public/shared/commerce-chrome.css` (`.article-card`, `.bran
   <CheckoutLoader />
   ```
 
-### CartDrawerStyles (`components/commerce/CartDrawerStyles.astro`)
+### CartDrawerStyles (`components/checkout/storefront/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
@@ -432,7 +432,7 @@ types live in `packages/public-runtime/src/tenant.ts` (`ComplianceConfig`): `nic
 `pactAct`, `adultSignature` are `boolean`; `shippingRestriction` is `string`; `minAge` is `number`;
 `prop65`/`purchaseLimit`/`stateEligibility`/`exciseTax` are the config objects below.
 
-### ComplianceNotice (`components/compliance/ComplianceNotice.astro`)
+### ComplianceNotice (`components/compliance/storefront/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.
@@ -448,7 +448,7 @@ types live in `packages/public-runtime/src/tenant.ts` (`ComplianceConfig`): `nic
   `.topbar-warning` (top FDA band), `.footer-warning` (footer band).
 - **Usage:** consumed by the siblings below (not used directly).
 
-### NicotineWarning (`components/compliance/NicotineWarning.astro`)
+### NicotineWarning (`components/compliance/storefront/compliance/NicotineWarning.astro`)
 
 - **Purpose:** FDA-mandated nicotine warning (21 CFR 1143.3). Wording fixed by law, verbatim.
   Self-contained (does not use `ComplianceNotice`).
@@ -464,7 +464,7 @@ types live in `packages/public-runtime/src/tenant.ts` (`ComplianceConfig`): `nic
   <NicotineWarning variant="block" />
   ```
 
-### PactActNotice (`components/compliance/PactActNotice.astro`)
+### PactActNotice (`components/compliance/storefront/compliance/PactActNotice.astro`)
 
 - **Purpose:** PACT Act compliance notice (ENDS/vapor). Federal-requirement wording fixed here; only
   on/off + age come from config.
@@ -481,7 +481,7 @@ types live in `packages/public-runtime/src/tenant.ts` (`ComplianceConfig`): `nic
   <PactActNotice enabled minAge={21} variant="footer" />
   ```
 
-### AdultSignatureNotice (`components/compliance/AdultSignatureNotice.astro`)
+### AdultSignatureNotice (`components/compliance/storefront/compliance/AdultSignatureNotice.astro`)
 
 - **Purpose:** Adult-signature-on-delivery notice. Fixed wording; age reflects `minAge`.
 - **Props:** `enabled?: boolean` (default `false`; from `tenant.compliance.adultSignature`); `minAge?:
@@ -496,7 +496,7 @@ types live in `packages/public-runtime/src/tenant.ts` (`ComplianceConfig`): `nic
   <AdultSignatureNotice enabled minAge={21} variant="inline" />
   ```
 
-### Prop65Warning (`components/compliance/Prop65Warning.astro`)
+### Prop65Warning (`components/compliance/storefront/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
@@ -516,7 +516,7 @@ types live in `packages/public-runtime/src/tenant.ts` (`ComplianceConfig`): `nic
   <Prop65Warning config={{ harm: "reproductive", chemicals: ["nicotine"] }} variant="block" />
   ```
 
-### PurchaseLimitNotice (`components/compliance/PurchaseLimitNotice.astro`)
+### PurchaseLimitNotice (`components/compliance/storefront/compliance/PurchaseLimitNotice.astro`)
 
 - **Purpose:** Purchase-quantity-limit **display** (state/PACT order caps). Display surface only —
   enforcement stays product/commerce-owned.
@@ -532,7 +532,7 @@ types live in `packages/public-runtime/src/tenant.ts` (`ComplianceConfig`): `nic
   <PurchaseLimitNotice config={{ text: "2 units per order", reason: "per state law" }} variant="inline" />
   ```
 
-### StateEligibilityNotice (`components/compliance/StateEligibilityNotice.astro`)
+### StateEligibilityNotice (`components/compliance/storefront/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
@@ -550,7 +550,7 @@ types live in `packages/public-runtime/src/tenant.ts` (`ComplianceConfig`): `nic
   <StateEligibilityNotice config={{ restrictedStates: ["UT", "AR", "VT"] }} variant="block" />
   ```
 
-### ShippingRestrictionNotice (`components/compliance/ShippingRestrictionNotice.astro`)
+### ShippingRestrictionNotice (`components/compliance/storefront/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
@@ -567,7 +567,7 @@ types live in `packages/public-runtime/src/tenant.ts` (`ComplianceConfig`): `nic
   <ShippingRestrictionNotice text="Adult signature (21+) required on delivery. Not shipped via USPS." variant="footer" />
   ```
 
-### ExciseTaxNotice (`components/compliance/ExciseTaxNotice.astro`)
+### ExciseTaxNotice (`components/compliance/storefront/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.
@@ -661,9 +661,9 @@ Model types (`lib/membership/model.ts`):
 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="…"`.
+`lib/subscriptions/subscription/model.ts`. All emit `data-widget="…"`.
 
-Model types (`lib/subscription/model.ts`):
+Model types (`lib/subscriptions/subscription/model.ts`):
 
 - `SubscriptionStep` — `{ title: string; description: string }`.
 - `SubscriptionFigure` — `{ value: string; caption?: string; real?: boolean }` (`value` is display
@@ -671,7 +671,7 @@ Model types (`lib/subscription/model.ts`):
 - `SubscriptionManageEntry` — `{ label: string; description?: string; href: string }` (handoff URL).
 - `isIllustrative(figure: Pick<SubscriptionFigure, "real">): boolean` → `figure.real !== true`.
 
-### HowItWorksSteps (`components/subscription/HowItWorksSteps.astro`)
+### HowItWorksSteps (`components/subscriptions/storefront/subscription/HowItWorksSteps.astro`)
 
 - **Purpose:** Autopilot/subscription "how it works" explainer (numbered steps). Ships no
   scheduling/billing mechanics.
@@ -687,7 +687,7 @@ Model types (`lib/subscription/model.ts`):
   <HowItWorksSteps eyebrow="Autopilot" heading="How Autopilot works" subhead="Set it up once — we handle the rest." steps={steps} />
   ```
 
-### SavingsExplainer (`components/subscription/SavingsExplainer.astro`)
+### SavingsExplainer (`components/subscriptions/storefront/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 +
@@ -707,7 +707,7 @@ Model types (`lib/subscription/model.ts`):
   <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`)
+### ManageSubscriptionEntry (`components/subscriptions/storefront/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
@@ -730,11 +730,11 @@ Model types (`lib/subscription/model.ts`):
 
 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,
+from `lib/content/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`)
+### MarketingBlocks (`components/content/storefront/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
@@ -752,7 +752,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <MarketingBlocks blocks={blocks} basePath={basePath} />
   ```
 
-### MarketingHero (`components/marketing/MarketingHero.astro`)
+### MarketingHero (`components/content/storefront/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.
@@ -769,7 +769,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <MarketingHero block={block} basePath={basePath} />
   ```
 
-### MarketingCtas (`components/marketing/MarketingCtas.astro`)
+### MarketingCtas (`components/content/storefront/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
@@ -785,7 +785,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <MarketingCtas ctas={block.ctas} basePath={basePath} class="mt-8" />
   ```
 
-### TrustBar (`components/marketing/TrustBar.astro`)
+### TrustBar (`components/content/storefront/marketing/TrustBar.astro`)
 
 - **Purpose:** Quiet horizontal strip of proof tokens (countries, standards, ratings). Plain text,
   mono, dot-separated.
@@ -798,7 +798,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <TrustBar block={{ component: "trust_bar", items: ["200+ countries", "SOC 2 Type II"] }} />
   ```
 
-### SplitCompare (`components/marketing/SplitCompare.astro`)
+### SplitCompare (`components/content/storefront/marketing/SplitCompare.astro`)
 
 - **Purpose:** Before/after two-column comparison — `before` reads as the problem (muted, struck
   items), `after` as the solution (accent border, ✓).
@@ -814,7 +814,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <SplitCompare block={block} />
   ```
 
-### Steps (`components/marketing/Steps.astro`)
+### Steps (`components/content/storefront/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.
@@ -829,7 +829,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <Steps block={block} />
   ```
 
-### CardGrid (`components/marketing/CardGrid.astro`)
+### CardGrid (`components/content/storefront/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.
@@ -846,7 +846,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <CardGrid block={block} basePath={basePath} />
   ```
 
-### Integrations (`components/marketing/Integrations.astro`)
+### Integrations (`components/content/storefront/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.
@@ -862,7 +862,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <Integrations block={block} basePath={basePath} />
   ```
 
-### CodeSample (`components/marketing/CodeSample.astro`)
+### CodeSample (`components/content/storefront/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.
@@ -877,7 +877,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <CodeSample sample={{ language: "js", caption: "Client-side embed", code: "await verify({ minAge: 21 });" }} />
   ```
 
-### ProofStrip (`components/marketing/ProofStrip.astro`)
+### ProofStrip (`components/content/storefront/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.
@@ -892,7 +892,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <ProofStrip block={block} />
   ```
 
-### Testimonials (`components/marketing/Testimonials.astro`)
+### Testimonials (`components/content/storefront/marketing/Testimonials.astro`)
 
 - **Purpose:** Outcome/quote cards with optional stat lead-in + attribution, plus an optional row of
   rating tokens.
@@ -907,7 +907,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <Testimonials block={block} />
   ```
 
-### Faq (`components/marketing/Faq.astro`)
+### Faq (`components/content/storefront/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).
@@ -922,7 +922,7 @@ from `lib/storyblok/content-model.ts` (the `MarketingBlock` union) plus, where i
   <Faq block={block} />
   ```
 
-### CtaBand (`components/marketing/CtaBand.astro`)
+### CtaBand (`components/content/storefront/marketing/CtaBand.astro`)
 
 - **Purpose:** Final conversion band on the surface tone — headline + optional subhead + centered CTA
   row.
@@ -946,7 +946,7 @@ form carrying the query, so filtering needs no JS and is back-button safe. All t
 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`)
+### FacetSidebar (`components/catalog/storefront/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
@@ -963,7 +963,7 @@ ListProductsQuery` + `basePath: string` (from `@tot/public-runtime`) and share `
   <FacetSidebar facets={facets} query={query} basePath="/collections/bestsellers" />
   ```
 
-### ActiveFilters (`components/plp/ActiveFilters.astro`)
+### ActiveFilters (`components/catalog/storefront/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.
@@ -978,7 +978,7 @@ ListProductsQuery` + `basePath: string` (from `@tot/public-runtime`) and share `
   <ActiveFilters query={query} basePath="/collections/bestsellers" />
   ```
 
-### SortSelect (`components/plp/SortSelect.astro`)
+### SortSelect (`components/catalog/storefront/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.
@@ -993,7 +993,7 @@ ListProductsQuery` + `basePath: string` (from `@tot/public-runtime`) and share `
   <SortSelect query={query} basePath="/collections/bestsellers" />
   ```
 
-### Pagination (`components/plp/Pagination.astro`)
+### Pagination (`components/catalog/storefront/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
@@ -1019,7 +1019,7 @@ Client-hydrated Preact `.tsx`. Every island is tenant-agnostic and reads only fi
 `/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`)
+### AgeGate (`components/compliance/storefront/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
@@ -1033,13 +1033,13 @@ Client-hydrated Preact `.tsx`. Every island is tenant-agnostic and reads only fi
   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`).
+  shadow-DOM tamper pattern, produced server-side by `lib/content/shared/rawChrome.ts`).
 - **Usage:**
   ```astro
   <AgeGate client:load minAge={21} brand={tenant.brandName} />
   ```
 
-### IsolatedAgeGate (`components/islands/IsolatedAgeGate.tsx`)
+### IsolatedAgeGate (`components/compliance/storefront/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
@@ -1059,7 +1059,7 @@ Client-hydrated Preact `.tsx`. Every island is tenant-agnostic and reads only fi
   <IsolatedAgeGate client:load minAge={21} brand={tenant.brandName} />
   ```
 
-### VariantSelector (`components/islands/VariantSelector.tsx`)
+### VariantSelector (`components/catalog/storefront/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
@@ -1082,7 +1082,7 @@ Client-hydrated Preact `.tsx`. Every island is tenant-agnostic and reads only fi
   <VariantSelector client:load variants={product.variants} options={product.options} currency={product.price_range.currency} locale="en-US" />
   ```
 
-### ImageGallery (`components/islands/ImageGallery.tsx`)
+### ImageGallery (`components/catalog/storefront/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
@@ -1102,7 +1102,7 @@ Client-hydrated Preact `.tsx`. Every island is tenant-agnostic and reads only fi
   <ImageGallery client:load images={product.images} title={product.title} productHandle={product.handle} />
   ```
 
-### QuickView (`components/islands/QuickView.tsx`)
+### QuickView (`components/catalog/storefront/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 —
@@ -1122,7 +1122,7 @@ Client-hydrated Preact `.tsx`. Every island is tenant-agnostic and reads only fi
   <QuickView client:idle locale="en-US" />
   ```
 
-### SearchTypeahead (`components/islands/SearchTypeahead.tsx`)
+### SearchTypeahead (`components/catalog/storefront/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
@@ -1143,7 +1143,7 @@ Client-hydrated Preact `.tsx`. Every island is tenant-agnostic and reads only fi
   <SearchTypeahead client:idle />
   ```
 
-### MobileNav (`components/islands/MobileNav.tsx`)
+### MobileNav (`components/content/storefront/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
@@ -1162,7 +1162,7 @@ Client-hydrated Preact `.tsx`. Every island is tenant-agnostic and reads only fi
   <MobileNav client:idle nav={nav} announcement="Free US shipping on orders over $100" />
   ```
 
-### RecentlyViewed (`components/islands/RecentlyViewed.tsx`)
+### RecentlyViewed (`components/catalog/storefront/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
@@ -1210,7 +1210,7 @@ Client-hydrated Preact `.tsx`. Every island is tenant-agnostic and reads only fi
 
 Shared primitives composed by the higher-level widgets, plus the homepage hero.
 
-### Badge (`components/Badge.astro`)
+### Badge (`components/content/storefront/Badge.astro`)
 
 - **Purpose:** Tiny mono-uppercase pill used over product imagery and inline (sale %, New, low-stock,
   sold-out, compliance-verified).
@@ -1225,7 +1225,7 @@ Shared primitives composed by the higher-level widgets, plus the homepage hero.
   <Badge variant="compliant" label="Compliant" />
   ```
 
-### Breadcrumbs (`components/Breadcrumbs.astro`)
+### Breadcrumbs (`components/content/storefront/Breadcrumbs.astro`)
 
 - **Purpose:** Semantic breadcrumb trail; last crumb is the current page (`aria-current`, not a link).
 - **Props:** `crumbs: { label: string; href: string }[]`.
@@ -1238,7 +1238,7 @@ Shared primitives composed by the higher-level widgets, plus the homepage hero.
   <Breadcrumbs crumbs={[{ label: "Home", href: "/" }, { label: "Bestsellers", href: "/collections/bestsellers" }]} />
   ```
 
-### ProductCard (`components/ProductCard.astro`)
+### ProductCard (`components/catalog/storefront/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 +
@@ -1259,7 +1259,7 @@ Shared primitives composed by the higher-level widgets, plus the homepage hero.
   <ProductCard product={p} rating={4.5} reviewCount={128} />
   ```
 
-### CollectionCard (`components/CollectionCard.astro`)
+### CollectionCard (`components/catalog/storefront/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.
@@ -1273,7 +1273,7 @@ Shared primitives composed by the higher-level widgets, plus the homepage hero.
   <CollectionCard collection={collection} productCount={24} />
   ```
 
-### Section (`components/Section.astro`)
+### Section (`components/content/storefront/Section.astro`)
 
 - **Purpose:** Section wrapper with consistent vertical rhythm + optional eyebrow/title header +
   alternating band background.
@@ -1288,7 +1288,7 @@ Shared primitives composed by the higher-level widgets, plus the homepage hero.
   <Section eyebrow="Shop" title="Best Sellers" tone="surface"> … </Section>
   ```
 
-### EmptyState (`components/EmptyState.astro`)
+### EmptyState (`components/content/storefront/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`.
@@ -1333,7 +1333,7 @@ Shared primitives composed by the higher-level widgets, plus the homepage hero.
   <WidgetFrame src="/widgets/tenant-abc/reviews.html" title="Customer reviews" height="480px" />
   ```
 
-### Seo (`components/Seo.astro`)
+### Seo (`components/content/storefront/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).
@@ -1349,7 +1349,7 @@ Shared primitives composed by the higher-level widgets, plus the homepage hero.
   <Seo title="Merino Zip Hoodie" description="Soft, warm, everyday." path="/products/merino-zip-hoodie" ogType="product" jsonLd={productSchema} />
   ```
 
-### Hero (`components/home/Hero.astro`)
+### Hero (`components/content/storefront/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
@@ -1380,12 +1380,12 @@ Shared primitives composed by the higher-level widgets, plus the homepage hero.
 
 ---
 
-## 11. Shared raw-chrome library — `lib/rawChrome.ts`, `lib/chrome/`, `public/shared/commerce-chrome.css`
+## 11. Shared raw-chrome library — `lib/content/shared/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
+### `lib/content/shared/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
@@ -1417,7 +1417,7 @@ Exports:
   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
+### `lib/content/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
@@ -1430,7 +1430,7 @@ lede?; yesLabel?; noLabel?; denyText?; fineText?; mark?; showNo?; eyebrow?: stri
 helpLink?: { label; href } }`), `ChromeFooterBrand`, `ChromeTrustMark`,
 `ChromeHead`, `ChromeCta`, `ChromeNavItem`, and `ChromeConfig` itself.
 
-### `lib/chrome/parseConfig.ts` — the validation gate
+### `lib/content/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.86",
+  "version": "2.4.88",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/src/chrome.ts

@@ -3,11 +3,11 @@
  * plus its fail-closed validator.
  *
  * Consolidates what used to be two competing, undocumented shapes:
- *   - a lean `SiteChrome` (lib/storyblok/content-model.ts), consumed by the
+ *   - a lean `SiteChrome` (lib/content/storyblok/content-model.ts), consumed by the
  *     token-styled <SiteHeader>/<SiteFooter> components via
  *     Astro.locals.content.getChrome();
  *   - a superset `TenantChrome`, consumed by the raw `chrome.html` splice
- *     wrapper (lib/rawChrome.ts) via lib/chrome/parseConfig.ts, gated on an
+ *     wrapper (lib/content/shared/rawChrome.ts) via lib/content/chrome/parseConfig.ts, gated on an
  *     explicit `sharedChrome: true` flag.
  * Both read the same `tenants/<id>/content/chrome.json` file; neither was the
  * complete picture. This file is now the single source of truth for that
@@ -24,7 +24,7 @@
  * control-plane package — the `renderer-no-controlplane` fence
  * (apps/storefront/.dependency-cruiser.cjs) runs the other way: packages may
  * depend on `@tot/public-runtime`, but the renderer must never import
- * `@tot/private-controlplane`. `apps/storefront/src/lib/chrome/model.ts` and
+ * `@tot/private-controlplane`. `apps/storefront/src/lib/content/chrome/model.ts` and
  * `parseConfig.ts` re-export from here so every existing renderer import
  * keeps resolving unchanged.
  */
@@ -206,7 +206,7 @@ export interface ChromeAnnouncement {
  * 21+ age-gate interstitial config (regulated tenants). The raw-chrome renderer
  * (rawChrome.ts) embeds this as JSON; the shared behavior JS mounts the gate inside
  * a closed shadow root — the same tamper-resistance pattern
- * components/islands/IsolatedAgeGate.tsx uses for component pages — so tenant
+ * components/compliance/storefront/islands/IsolatedAgeGate.tsx uses for component pages — so tenant
  * CSS/JS can't reach the dialog.
  */
 export const CHROME_AGE_GATE_VARIANTS = ["default", "compact-modal"] as const;
@@ -302,7 +302,7 @@ export function isFooterVariant(v: unknown): v is FooterVariant {
 
 /**
  * Thrown by the renderer's `assertHeaderVariant` / `assertFooterVariant`
- * (apps/storefront/src/lib/chrome/variant.ts) when a page passes an unknown
+ * (apps/storefront/src/lib/content/chrome/variant.ts) when a page passes an unknown
  * variant. Fails closed
  * at validation time with an actionable message rather than silently falling
  * back to a default — an unrecognized variant is a bug in the caller, not a