@tokenoftrust/storefront-runner 2.4.87 → 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
@@ -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
@@ -730,11 +730,11 @@ Model types (`lib/subscriptions/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.
@@ -1033,7 +1033,7 @@ 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} />
@@ -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
@@ -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 }[]`.
@@ -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.87",
+  "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.
  */
@@ -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

package/packages/public-runtime/src/tracking-id-derivation.ts

@@ -82,7 +82,7 @@
  * consumer builds {@link DerivationTarget}s from whatever it already has:
  *
  * - a git-time rewriter walks `parse5`'s `parseFragment` tree keeping a tag
- *   stack (the pattern `apps/storefront/src/lib/the-build/toc.ts` already uses
+ *   stack (the pattern `apps/storefront/src/lib/content/the-build/toc.ts` already uses
  *   to add heading anchors and re-`serialize()` byte-preserving when nothing
  *   changed);
  * - a publish-time `HTMLRewriter` handler keeps the same stack across