npm - @tokenoftrust/storefront-runner - Versions diffs - 1.3.2 - Mend

@tokenoftrust/storefront-runner 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (310) hide show

package/apps/storefront/src/lib/rawMarketingHtml.ts ADDED Viewed

@@ -0,0 +1,136 @@
+/**
+ * Raw marketing-HTML serving — the "vendor injects their own HTML" path.
+ *
+ * A marketing tenant can ship a self-contained document (`content/<tenant>/home.html`
+ * or `content/<tenant>/pages-html/<slug>.html`) that we serve VERBATIM, bypassing the
+ * block Layout. Two transforms are applied at serve time:
+ *   1. nonce-stamp the document's inline <style>/<script> so a strict CSP admits them;
+ *   2. under path-prefix tenant routing (locals.basePath set), prefix same-origin
+ *      root-absolute anchor hrefs with the base path so navigation stays in-tenant —
+ *      the raw doc bypasses the Layout's client base-path fixer, so we do it here.
+ *
+ * Single home for both routes (`index.astro`, `[...slug].astro`).
+ *
+ * SECURITY: this trusts the tenant's HTML (first-party marketing). The nonce
+ * injection is a deliberate string replace — robust for first-party documents, not a
+ * sanitizer. Untrusted vendor HTML must be sandboxed/sanitized instead.
+ */
+/**
+ * Marker a body-only page fragment's chrome wrapper uses to say "the page body
+ * goes here". A tenant's `content/<tenant>/chrome.html` is a full document with
+ * this comment where the fragment is spliced in. Kept as an HTML comment so the
+ * wrapper is still valid, previewable HTML on its own.
+ */
+export const CHROME_BODY_MARKER = "<!--PAGE_BODY-->";
+/**
+ * Marker in the chrome wrapper's <head> where a fragment's page-specific <head>
+ * (title / meta / canonical / OG / JSON-LD) is spliced in — so shared chrome does
+ * NOT flatten per-page SEO. A fragment may lead with a `<head>…</head>` block; its
+ * contents go here, the rest goes to CHROME_BODY_MARKER.
+ */
+export const CHROME_HEAD_MARKER = "<!--PAGE_HEAD-->";
+/**
+ * True when `html` is a complete document (has <html> or a doctype) rather than a
+ * body-only fragment. Full documents are served verbatim; fragments get wrapped
+ * in the tenant's shared chrome. This is what keeps the mechanism backward-
+ * compatible — every existing raw home/subpage is a full document.
+ */
+export function isFullDocument(html: string): boolean {
+  return /^\s*<!doctype/i.test(html) || /<html[\s>]/i.test(html);
+}
+/**
+ * Splice a body-only fragment into a tenant chrome wrapper at CHROME_BODY_MARKER.
+ * If the wrapper has no marker (misconfigured), the fragment is returned unwrapped
+ * so a page never disappears.
+ */
+export function wrapFragmentInChrome(fragment: string, chromeWrapper: string): string {
+  if (!chromeWrapper.includes(CHROME_BODY_MARKER)) return fragment;
+  // A fragment may lead with a <head>…</head> of page-specific SEO tags. Split it
+  // out so the shared wrapper keeps per-page title/meta/canonical/JSON-LD.
+  let head = "";
+  let body = fragment;
+  const m = fragment.match(/^\s*<head[^>]*>([\s\S]*?)<\/head>/i);
+  if (m) {
+    head = m[1] ?? "";
+    body = fragment.slice(m[0].length);
+  }
+  let out = chromeWrapper.replace(CHROME_BODY_MARKER, body);
+  if (out.includes(CHROME_HEAD_MARKER)) out = out.replace(CHROME_HEAD_MARKER, head);
+  return out;
+}
+/** Stamp `nonce` onto every inline `<style>`/`<script>` so a strict CSP admits them. */
+export function nonceInlineTags(html: string, nonce: string): string {
+  return html
+    .replaceAll("<style>", `<style nonce="${nonce}">`)
+    .replaceAll("<script", `<script nonce="${nonce}"`);
+}
+/**
+ * Prefix same-origin root-absolute hrefs (`href="/…"`) with the tenant base path,
+ * so `/pricing/` becomes `/<domain>/pricing/` under path-prefix routing. No-op when
+ * basePath is empty (host-routed prod). Skips protocol-relative `//…` and, crucially,
+ * the GLOBAL static-asset namespaces served at root under both routing modes, so they
+ * must NOT get the tenant prefix:
+ *   - `/tenants/…` — per-tenant static assets (logo, favicon, theme/mkt css);
+ *   - `/shared/…`  — platform-shipped shared assets (e.g. the shared commerce-chrome
+ *     stylesheet, unit F2) that every tenant links.
+ * Asset `src="…"` isn't matched at all (href-only).
+ */
+export function prefixTenantLinks(html: string, basePath: string): string {
+  if (!basePath) return html;
+  return html.replace(/href="\/(?!\/|tenants\/|shared\/)/g, `href="${basePath}/`);
+}
+/**
+ * Build the HTML Response for a raw marketing page (nonce + base-path).
+ *
+ * Shared-chrome mechanism: a page is served in one of two ways —
+ *   - FULL DOCUMENT (has <html>/doctype): served verbatim, as before.
+ *   - BODY FRAGMENT + a tenant `chromeWrapper`: the fragment is spliced into the
+ *     wrapper's CHROME_BODY_MARKER so chrome lives in ONE place, not copied into
+ *     every page. A fragment with no wrapper still serves (unwrapped) for safety.
+ * Either way, the FINAL document gets nonce-stamped and base-path-prefixed, so the
+ * chrome's own inline <style>/<script> and root-absolute nav links are handled too.
+ */
+export function rawHtmlResponse(
+  html: string,
+  opts: { nonce: string; basePath: string; chromeWrapper?: string | null },
+): Response {
+  let composed =
+    isFullDocument(html) || !opts.chromeWrapper
+      ? html
+      : wrapFragmentInChrome(html, opts.chromeWrapper);
+  // DEV ONLY: these pages are served verbatim, bypassing Astro's render pipeline,
+  // so the Vite HMR client is never injected — a save would reach the server (see
+  // the tenantHotReload plugin in astro.config.mjs) but the browser would have no
+  // listener to act on the full-reload. Inject the client so save→reload works.
+  // Stamped with the page nonce by nonceInlineTags below; tree-shaken from prod.
+  if (import.meta.env.DEV) {
+    const client = `<script type="module" src="/@vite/client"></script>`;
+    composed = composed.includes("</head>")
+      ? composed.replace("</head>", `${client}</head>`)
+      : `${client}${composed}`;
+    // Inline-AI edit loop's floating "✦ ask" affordance (WS5 G1) — same reason
+    // as the HMR client above, these pages bypass the Astro pipeline that
+    // inlineAiEditPlugin's transformIndexHtml hook (astro.config.mjs) covers
+    // for everything else, so it's injected here too. Unconditional in dev,
+    // matching the Vite client above: whether `tot dev` set an active tenant
+    // (TOT_DEV_TENANT) is a Node-process env var, invisible to this SSR code
+    // when it runs inside the Cloudflare/workerd dev runtime (see tot-dev.mjs's
+    // own note on this exact gap) — so the gate lives server-side instead, in
+    // inlineAiEditPlugin's Vite middleware, which DOES see the real env.
+    const widget = `<script type="module" src="/__tot/ai-widget-client.js"></script>`;
+    composed = composed.includes("</body>")
+      ? composed.replace("</body>", `${widget}</body>`)
+      : `${composed}${widget}`;
+  }
+  const doc = prefixTenantLinks(nonceInlineTags(composed, opts.nonce), opts.basePath);
+  return new Response(doc, {
+    headers: { "content-type": "text/html; charset=utf-8" },
+  });
+}

package/apps/storefront/src/lib/search/index.ts ADDED Viewed

@@ -0,0 +1,74 @@
+/**
+ * In-memory Fuse search index — the OFFLINE search floor.
+ *
+ * Used by FixtureToTClient.search (no D1 binding): typo-tolerant, relevance-ranked
+ * search over the bundled catalog snapshot, zero infra. When a D1 binding is wired
+ * (D1ToTClient), search instead goes through FTS5 — see lib/d1/catalog.ts and
+ * epics/edge-read-replica.md. This module is the portable floor an extracted
+ * merchant gets out of the box (docs/extraction-runbook.md).
+ */
+import Fuse, { type IFuseOptions } from "fuse.js";
+import type { CatalogProduct } from "@tot/public-runtime";
+export interface SearchHit {
+  product: CatalogProduct;
+  score: number;
+}
+export interface SearchIndex {
+  search(query: string, limit?: number): SearchHit[];
+}
+const FUSE_OPTIONS: IFuseOptions<CatalogProduct> = {
+  includeScore: true,
+  threshold: 0.38, // typo tolerance: lower = stricter
+  ignoreLocation: true,
+  minMatchCharLength: 2,
+  keys: [
+    { name: "title", weight: 0.5 },
+    { name: "vendor", weight: 0.15 },
+    { name: "product_type", weight: 0.15 },
+    { name: "tags", weight: 0.12 },
+    { name: "description_text", weight: 0.08 },
+  ],
+};
+export function buildSearchIndex(products: CatalogProduct[]): SearchIndex {
+  // Defensive: only ever index active products (the draft canary must never leak).
+  const active = products.filter((p) => p.status === "active");
+  const fuse = new Fuse(active, FUSE_OPTIONS);
+  return {
+    search(query: string, limit = 12): SearchHit[] {
+      const q = query.trim();
+      if (!q) return [];
+      return fuse.search(q, { limit }).map((r) => ({ product: r.item, score: r.score ?? 1 }));
+    },
+  };
+}
+/** Compact shape sent to the typeahead island (keeps client JSON tiny). */
+export interface TypeaheadDoc {
+  handle: string;
+  title: string;
+  vendor?: string;
+  type?: string;
+  price: number;
+  currency: string;
+  image?: string;
+  tags: string[];
+}
+export function toTypeaheadDoc(p: CatalogProduct): TypeaheadDoc {
+  const doc: TypeaheadDoc = {
+    handle: p.handle,
+    title: p.title,
+    price: p.price_range.min,
+    currency: p.price_range.currency,
+    tags: p.tags,
+  };
+  if (p.vendor) doc.vendor = p.vendor;
+  if (p.product_type) doc.type = p.product_type;
+  const img = p.images[0];
+  if (img?.url) doc.image = img.url;
+  return doc;
+}

package/apps/storefront/src/lib/sections.ts ADDED Viewed

@@ -0,0 +1,129 @@
+/**
+ * SectionSource — the single, typed contract every merchandising section binds
+ * to. A section component (ProductCarousel, ProductGrid, …) never talks to the
+ * catalog directly; it declares WHAT set of products it wants as a SectionSource
+ * and calls resolveSectionSource() to get them. This keeps the components
+ * tenant-agnostic and data-source-agnostic: swap the ToTClient backend (D1 vs
+ * fixture) and every section keeps working.
+ *
+ * Fidelity to a merchant's storefront comes from theme tokens + variant props +
+ * the source they point a section at — NEVER from forking a component per
+ * merchant. That's what keeps a tenant single-tenant-extractable.
+ */
+import type { CatalogProduct } from "@tot/public-runtime";
+import type { ToTClient } from "@/lib/tot/ToTClient";
+import { isOnSale } from "@/lib/tot/query";
+/**
+ * Where a merchandising section gets its products. Exactly one shape per source.
+ * `handle` placeholders are product/collection handles (unique per tenant).
+ */
+export type SectionSource =
+  | { collection: string } // products in a collection (by handle)
+  | { tag: string } // products carrying a tag
+  | { featured: true } // the curated/featured set (getFeatured)
+  | { newest: true } // newest-first
+  | { bestSelling: true } // bestseller-tagged
+  | { onSale: true } // anything with a live compare-at markdown
+  | { handles: string[] } // an explicit, ordered handle list
+  | { related: string } // products related to a base product (by handle)
+  | { recentlyViewed: true }; // client-personalized — resolves empty server-side
+export const DEFAULT_SECTION_LIMIT = 12;
+/** Bestseller signal is tag-based in Phase 1 (no order history at the edge). */
+const BESTSELLER_TAGS = new Set(["bestseller", "best-seller", "best-sellers"]);
+const isActive = (p: CatalogProduct) => p.status === "active";
+/**
+ * Resolve a SectionSource to a concrete, active product list via the tenant's
+ * ToTClient. Always returns at most `limit` ACTIVE products (drafts/archived are
+ * excluded from every public surface — see ToTClient docs). Backend-agnostic:
+ * tag/onSale/bestSelling filter over the client's list methods rather than
+ * assuming a SQL facet, so the fixture and D1 backends behave identically.
+ */
+export async function resolveSectionSource(
+  source: SectionSource,
+  tot: ToTClient,
+  limit: number = DEFAULT_SECTION_LIMIT,
+): Promise<CatalogProduct[]> {
+  if ("collection" in source) {
+    const { products } = await tot.listProducts({
+      collection: source.collection,
+      pageSize: limit,
+    });
+    return products.slice(0, limit);
+  }
+  if ("featured" in source) {
+    return (await tot.getFeatured(limit)).slice(0, limit);
+  }
+  if ("newest" in source) {
+    const { products } = await tot.listProducts({ sort: "newest", pageSize: limit });
+    return products.slice(0, limit);
+  }
+  if ("handles" in source) {
+    const found = await Promise.all(
+      source.handles.map((h) => tot.getProductByHandle(h)),
+    );
+    return found
+      .filter((p): p is CatalogProduct => !!p && isActive(p))
+      .slice(0, limit);
+  }
+  if ("tag" in source) {
+    const all = await tot.getAllActiveProducts();
+    return all.filter((p) => p.tags.includes(source.tag)).slice(0, limit);
+  }
+  if ("onSale" in source) {
+    const all = await tot.getAllActiveProducts();
+    return all.filter(isOnSale).slice(0, limit);
+  }
+  if ("bestSelling" in source) {
+    const all = await tot.getAllActiveProducts();
+    return all
+      .filter((p) => p.tags.some((t) => BESTSELLER_TAGS.has(t)))
+      .slice(0, limit);
+  }
+  if ("related" in source) {
+    const base = await tot.getProductByHandle(source.related);
+    if (!base) return [];
+    const baseCollections = new Set(base.collections);
+    const baseTags = new Set(base.tags);
+    const all = await tot.getAllActiveProducts();
+    const scored = all
+      .filter((p) => p.handle !== base.handle)
+      .map((p) => {
+        const shared =
+          p.collections.filter((c) => baseCollections.has(c)).length +
+          p.tags.filter((t) => baseTags.has(t)).length;
+        return { p, shared };
+      })
+      .filter((s) => s.shared > 0)
+      .sort((a, b) => b.shared - a.shared);
+    return scored.slice(0, limit).map((s) => s.p);
+  }
+  // recentlyViewed: server has no per-visitor history; the client island
+  // (RecentlyViewed.tsx) hydrates this. Resolve empty so the section can decide
+  // to hide or defer to its island.
+  return [];
+}
+/**
+ * Ready-made sources for the common merchandising rows. A preset carousel is
+ * just `<ProductCarousel source={SECTION_PRESETS.bestSellers} />` — there are no
+ * separate BestSellers/NewArrivals/OnSale components to maintain.
+ */
+export const SECTION_PRESETS = {
+  featured: { featured: true } as SectionSource,
+  bestSellers: { bestSelling: true } as SectionSource,
+  newArrivals: { newest: true } as SectionSource,
+  onSale: { onSale: true } as SectionSource,
+} as const;

package/apps/storefront/src/lib/securityHeaders.ts ADDED Viewed

@@ -0,0 +1,31 @@
+/**
+ * Baseline security response headers (Epic Phase-2 S1).
+ *
+ * Applied to every storefront response in middleware and baked into cached pages.
+ * The Content-Security-Policy itself (default-src/frame-ancestors/base-uri/…) is
+ * built separately in @tot/private-controlplane `csp.ts`; these are the complementary
+ * transport / sniffing / referrer / feature-permission headers that the appraisal
+ * flagged as missing.
+ */
+export const SECURITY_HEADERS: Readonly<Record<string, string>> = {
+  // 2-year HSTS with preload — production is HTTPS-only behind Cloudflare;
+  // browsers ignore this header on plain http (localhost dev), so it's safe to
+  // always set.
+  "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload",
+  "X-Content-Type-Options": "nosniff",
+  // Legacy backstop; modern browsers honour the CSP `frame-ancestors 'self'`.
+  "X-Frame-Options": "SAMEORIGIN",
+  "Referrer-Policy": "strict-origin-when-cross-origin",
+  // Lock powerful features off for the browse storefront. Verification and
+  // checkout (Powered by FoxyCart) run in their own surfaces that grant only
+  // what they need via per-frame Permissions-Policy.
+  "Permissions-Policy":
+    "camera=(), microphone=(), geolocation=(), browsing-topics=(), interest-cohort=()",
+};
+/** Set the baseline headers on a response, without clobbering anything already set. */
+export function applySecurityHeaders(headers: Headers): void {
+  for (const [key, value] of Object.entries(SECURITY_HEADERS)) {
+    if (!headers.has(key)) headers.set(key, value);
+  }
+}

package/apps/storefront/src/lib/storyblok/content-model.ts ADDED Viewed

@@ -0,0 +1,289 @@
+/**
+ * Editorial content model (Storyblok seam).
+ *
+ * These are OUR types, decoupled from Storyblok's wire shape. The provider maps
+ * either source (Storyblok delivery API OR local JSON) into these, so pages
+ * never see a raw Storyblok story. The block schemas here mirror the component
+ * schemas that live in the Storyblok PARENT space (shared components); the
+ * pilot CHILD space holds the content instances. See DECISIONS.md for the
+ * parent/child + Shared Components plan.
+ */
+export type HomeBlock =
+  | HeroBlock
+  | PromoTilesBlock
+  | FeaturedCollectionsBlock
+  | FeaturedProductsBlock
+  | EditorialBlock
+  | NewsletterBlock;
+export interface PromoTilesBlock {
+  component: "promo_tiles";
+  title?: string;
+  /** A row of promotional tiles (e.g. "New Additions", "On Sale") that link to
+   * collections — captured from the merchant's homepage. */
+  tiles: { label: string; href: string; image?: string }[];
+}
+export interface HeroBlock {
+  component: "hero";
+  /** The "thesis" line — the most characteristic thing about the catalog. */
+  eyebrow?: string;
+  headline: string;
+  /** Split second line gets the signature oversized treatment. */
+  headlineAccent?: string;
+  subhead?: string;
+  ctaLabel?: string;
+  ctaHref?: string;
+  /** Optional handle of a product/collection to feature visually. */
+  featureCollection?: string;
+  /** Direct hero image URL (e.g. the merchant's own homepage hero slide). */
+  image?: string;
+  imageAlt?: string;
+}
+export interface FeaturedCollectionsBlock {
+  component: "featured_collections";
+  title?: string;
+  /** Collection handles to surface; empty = all. */
+  handles: string[];
+}
+export interface FeaturedProductsBlock {
+  component: "featured_products";
+  title?: string;
+  /** "featured" | "newest" | explicit handles. */
+  source: "featured" | "newest";
+  handles?: string[];
+  limit?: number;
+}
+export interface EditorialBlock {
+  component: "editorial";
+  eyebrow?: string;
+  title: string;
+  body_html: string;
+  imageSeed?: string;
+  align?: "left" | "right";
+  ctaLabel?: string;
+  ctaHref?: string;
+}
+export interface NewsletterBlock {
+  component: "newsletter";
+  title: string;
+  body?: string;
+  placeholder?: string;
+  ctaLabel?: string;
+}
+// ---------------------------------------------------------------------------
+// Marketing blocks (non-commerce tenants). These render WITHOUT catalog data —
+// a marketing tenant composes its pages entirely from these. They're
+// tenant-agnostic: every color/space comes from theme tokens, and the copy
+// lives in tenant content JSON. See components/marketing/*.
+// ---------------------------------------------------------------------------
+/** A call-to-action button. `variant` picks primary/secondary styling; an
+ * `external` href (starts with http) opens the app/help/etc. surfaces. */
+export interface MarketingCta {
+  label: string;
+  href: string;
+  variant?: "primary" | "secondary" | "ghost";
+}
+export interface MarketingHeroBlock {
+  component: "marketing_hero";
+  eyebrow?: string;
+  headline: string;
+  subhead?: string;
+  body?: string;
+  /** Short trust chips shown under the CTAs (e.g. "200+ countries"). */
+  trust?: string[];
+  ctas?: MarketingCta[];
+  /** Optional right-hand "product moment": a titled list of demo/log lines. */
+  panel?: { title?: string; lines: string[] };
+}
+/** A horizontal strip of short proof tokens (countries, standards, ratings). */
+export interface TrustBarBlock {
+  component: "trust_bar";
+  items: string[];
+}
+/** Before/after comparison — the "one platform vs a patchwork" section. */
+export interface SplitCompareBlock {
+  component: "split_compare";
+  eyebrow?: string;
+  title: string;
+  subhead?: string;
+  before: { title: string; items: string[] };
+  after: { title: string; items: string[] };
+}
+/** Numbered/emoji journey steps. */
+export interface StepsBlock {
+  component: "steps";
+  eyebrow?: string;
+  title: string;
+  subhead?: string;
+  steps: { icon?: string; label: string; detail?: string }[];
+}
+/** A grid of capability/industry cards. `variant` tunes density/label style. */
+export interface CardGridBlock {
+  component: "card_grid";
+  /** Optional anchor id so header nav can jump to this section (e.g. "platform"). */
+  anchor?: string;
+  eyebrow?: string;
+  title: string;
+  subhead?: string;
+  variant?: "capability" | "industry" | "feature";
+  cards: {
+    icon?: string;
+    title: string;
+    body?: string;
+    /** Small meta line (e.g. "Use case: account opening"). */
+    meta?: string;
+    href?: string;
+  }[];
+  /** Optional footnote of extra capabilities under the grid. */
+  footnote?: string;
+}
+/** A single fenced code sample. NEVER put secret keys here — server-only. */
+export interface CodeSample {
+  language?: string;
+  code: string;
+  /** Optional caption/warning shown above the block. */
+  caption?: string;
+}
+/** Integration story: platform logos/labels + an optional safe code sample. */
+export interface IntegrationsBlock {
+  component: "integrations";
+  eyebrow?: string;
+  title: string;
+  subhead?: string;
+  platforms: { label: string; href?: string }[];
+  points?: string[];
+  code?: CodeSample;
+}
+/** Privacy / trust proof strip (e.g. "We will never sell your data"). */
+export interface ProofStripBlock {
+  component: "proof_strip";
+  eyebrow?: string;
+  title: string;
+  body?: string;
+  items?: string[];
+}
+export interface TestimonialsBlock {
+  component: "testimonials";
+  eyebrow?: string;
+  title?: string;
+  quotes: { stat?: string; quote: string; attribution?: string }[];
+  ratings?: string[];
+}
+export interface FaqBlock {
+  component: "faq";
+  eyebrow?: string;
+  title: string;
+  items: { q: string; a: string }[];
+}
+/** Final conversion band. */
+export interface CtaBandBlock {
+  component: "cta_band";
+  title: string;
+  subhead?: string;
+  ctas?: MarketingCta[];
+}
+export type MarketingBlock =
+  | MarketingHeroBlock
+  | TrustBarBlock
+  | SplitCompareBlock
+  | StepsBlock
+  | CardGridBlock
+  | IntegrationsBlock
+  | ProofStripBlock
+  | TestimonialsBlock
+  | FaqBlock
+  | CtaBandBlock;
+/** Discriminators that identify a marketing block (vs a commerce HomeBlock). */
+export const MARKETING_COMPONENTS = new Set<MarketingBlock["component"]>([
+  "marketing_hero",
+  "trust_bar",
+  "split_compare",
+  "steps",
+  "card_grid",
+  "integrations",
+  "proof_strip",
+  "testimonials",
+  "faq",
+  "cta_band",
+]);
+export function isMarketingBlock(
+  block: { component: string },
+): block is MarketingBlock {
+  return MARKETING_COMPONENTS.has(block.component as MarketingBlock["component"]);
+}
+export interface HomeContent {
+  /** SEO + social. */
+  seoTitle?: string;
+  seoDescription?: string;
+  /** Commerce home blocks OR marketing blocks — the page branches on tenant
+   * siteType/features and renders the matching set. */
+  blocks: (HomeBlock | MarketingBlock)[];
+}
+export interface EditorialPage {
+  slug: string;
+  title: string;
+  seoTitle?: string;
+  seoDescription?: string;
+  /** Sanitized HTML body. */
+  body_html: string;
+  /** Optional hero eyebrow/intro. */
+  eyebrow?: string;
+  intro?: string;
+  /** When true, listed in the footer policy column. */
+  isPolicy?: boolean;
+}
+export interface SiteNavItem {
+  label: string;
+  href: string;
+  /** Mega-menu children, e.g. collection links grouped under a category. */
+  children?: { label: string; href: string }[];
+}
+export interface SiteChrome {
+  nav: SiteNavItem[];
+  /**
+   * Header conversion buttons (marketing tenants). Rendered in the header's
+   * right cluster in place of the commerce search/saved controls. Commerce
+   * tenants omit this and keep the search + saved affordances.
+   */
+  headerCtas?: MarketingCta[];
+  footer: {
+    columns: { title: string; links: { label: string; href: string }[] }[];
+    social: { label: string; href: string }[];
+    tagline?: string;
+    /** Bottom-bar legal/compliance line (marketing tenants). Plain text. */
+    legal?: string;
+  };
+  announcement?: string;
+  /** Default legal/safety disclaimer HTML (fallback for unknown categories). */
+  disclaimer?: string;
+  /** Per-product-category disclaimer HTML, keyed by product_type (or
+   * compliance.product_category) — the source store renders a different legal
+   * block per type (sub-ohm on salts, battery on devices). */
+  disclaimers?: Record<string, string>;
+}