@tokenoftrust/storefront-runner 2.0.40 → 2.0.42

package/apps/storefront/src/lib/rawChrome.ts

@@ -29,6 +29,7 @@ import { isCurrentNavHref } from "./chrome/navCurrent.js";
 import { ctaIdentityAttr } from "./chrome/ctaIdentity.js";
 import { CHROME_PLACEMENT } from "./chrome/trackingPlacements.js";
 import { LEGAL_NAV_LABEL, splitFooterLegal } from "./chrome/footerLegal.js";
+import { resolveNewsletterAgeAttestation } from "./chrome/newsletterAgeAttestation.js";
 import { trackingAttributesHtml } from "@tot/public-runtime";
 import type {
   ChromeAgeGate,
@@ -44,7 +45,7 @@ import type {
   HeaderVariant,
   SocialLink,
 } from "./chrome/model.js";
-import { resolveChromeAssignment } from "./chrome/model.js";
+import { resolveAgeGateCopy, resolveChromeAssignment } from "./chrome/model.js";
 import { resolveHeaderVariant } from "./chrome/variant.js";
 
 /** HTML-escape text/attribute content. Covers the five significant characters. */
@@ -289,6 +290,7 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
   const cart = header.cartHref
     ? `<a class="cart" href="${esc(header.cartHref)}" aria-label="Cart">${ICON_CART}<span class="count">0</span></a>`
     : "";
+  const compact = variant === "compact-centered";
   // "minimal" (e.g. checkout/policy pages): brand + a reduced action set only —
   // no primary nav bar, no search, no mobile-menu toggle. "primary": the full header.
   const minimal = variant === "minimal";
@@ -323,24 +325,49 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
   const navItems = header.nav
     .map((item, i) => renderNavItem(item, i, currentPath))
     .join("\n          ");
+  const primaryNav =
+    `<nav class="primary-nav" id="primaryNav" aria-label="Primary">\n` +
+    `        <ul>\n          ${navItems}\n        </ul>\n` +
+    `      </nav>`;
   const navBar = minimal
     ? ""
+    : compact
+      ? ""
     : `  <nav class="primary-nav-bar" aria-label="Primary">\n` +
       `    <div class="container">\n` +
-      `      <nav class="primary-nav" id="primaryNav">\n` +
-      `        <ul>\n          ${navItems}\n        </ul>\n` +
-      `      </nav>\n` +
+      `      ${primaryNav}\n` +
       `    </div>\n` +
       `  </nav>\n`;
+  const compactSearch =
+    compact && header.search
+      ? `<a class="header-search-trigger" href="${esc(header.search.action ?? "/search")}" aria-label="${esc(header.search.label ?? "Search")}">${ICON_SEARCH}</a>`
+      : "";
+  const mobileBottom =
+    compact
+      ? `<nav class="mobile-bottom-nav" aria-label="Quick links">` +
+        `<a href="/" aria-label="Home"><span aria-hidden="true">⌂</span><small>Home</small></a>` +
+        (header.search
+          ? `<a href="${esc(header.search.action ?? "/search")}" aria-label="${esc(header.search.label ?? "Search")}">${ICON_SEARCH}<small>Search</small></a>`
+          : "") +
+        (header.accountHref
+          ? `<a href="${esc(header.accountHref)}" aria-label="Account">${ICON_ACCOUNT}<small>Account</small></a>`
+          : "") +
+        (header.cartHref
+          ? `<a href="${esc(header.cartHref)}" aria-label="Cart">${ICON_CART}<small>Cart</small></a>`
+          : "") +
+        `</nav>`
+      : "";
   return (
     `<header class="site-header" data-variant="${esc(variant)}">\n` +
     `  <div class="container header-row">\n` +
+    (compact ? `    ${primaryNav}\n` : "") +
     `    ${renderBrand(header.brand)}\n` +
-    (!minimal && search ? `    ${search}\n` : "") +
-    `    <div class="header-actions">${memberCue}${ctas}${account}${cart}${hamburger}</div>\n` +
+    (!minimal && !compact && search ? `    ${search}\n` : "") +
+    `    <div class="header-actions">${memberCue}${ctas}${compactSearch}${account}${cart}${hamburger}</div>\n` +
     `  </div>\n` +
     navBar +
-    `</header>`
+    `</header>` +
+    mobileBottom
   );
 }
 
@@ -352,13 +379,52 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
  * can't close the tag early.
  */
 function renderAgeGate(g: ChromeAgeGate): string {
-  const json = JSON.stringify(g).replace(/</g, "\\u003c");
+  const resolved = {
+    ...g,
+    title: resolveAgeGateCopy(g.title, g.minAge),
+    lede: resolveAgeGateCopy(g.lede, g.minAge),
+    yesLabel: resolveAgeGateCopy(g.yesLabel, g.minAge),
+    noLabel: resolveAgeGateCopy(g.noLabel, g.minAge),
+    denyText: resolveAgeGateCopy(g.denyText, g.minAge),
+    fineText: resolveAgeGateCopy(g.fineText, g.minAge),
+  };
+  const json = JSON.stringify(resolved).replace(/</g, "\\u003c");
   return `<script type="application/json" id="tot-age-gate-config">${json}</script>`;
 }
 
+/** Remove a wrapper's raw gate payload before Layout mounts its governed component gate. */
+export function stripRawChromeAgeGateConfig(html: string): string {
+  return html.replace(
+    /<script\b(?=[^>]*\bid=["']tot-age-gate-config["'])[^>]*>[\s\S]*?<\/script>\s*/gi,
+    "",
+  );
+}
+
+/** Neutralize the reserved light-DOM marker before tenant-authored chrome is inserted. */
+export function stripReservedComplianceMarkers(html: string): string {
+  return html.replace(
+    /\sdata-tot-compliance(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?/gi,
+    "",
+  );
+}
+
+/** Remove executable tenant script elements, including unterminated tags. */
+export function stripTenantScripts(html: string): string {
+  return html.replace(
+    /<script\b[^>]*>(?:[\s\S]*?<\/script\s*>|[\s\S]*$)/gi,
+    "",
+  );
+}
+
+/** Compliance-safe shared-chrome fragment for Layout's component-rendered path. */
+export function sanitizeSharedChromeFragment(html: string): string {
+  return stripReservedComplianceMarkers(stripTenantScripts(html));
+}
+
 function renderFooterNewsletter(n: NonNullable<ChromeFooter["newsletter"]>): string {
-  const attest = n.ageAttestation
-    ? `\n          <label class="footer-attest"><input type="checkbox" name="age_attestation" value="21plus" required> I confirm I am 21 years of age or older and agree to receive marketing emails.</label>`
+  const ageAttestation = resolveNewsletterAgeAttestation(n.ageAttestation);
+  const attest = ageAttestation
+    ? `\n          <label class="footer-attest"><input type="checkbox" name="${ageAttestation.name}" value="${ageAttestation.value}" required> ${esc(ageAttestation.label)}</label>`
     : "";
   const title = n.title ? `<h4>${esc(n.title)}</h4>` : "";
   const body = n.body ? `<p>${esc(n.body)}</p>` : "";
@@ -376,6 +442,7 @@ function renderFooterNewsletter(n: NonNullable<ChromeFooter["newsletter"]>): str
 }
 
 function renderFooter(footer: ChromeFooter): string {
+  const collapsible = footer.variant === "light-collapsible";
   const brand = footer.brand;
   const brandBlock =
     brand || footer.newsletter
@@ -411,7 +478,9 @@ function renderFooter(footer: ChromeFooter): string {
           return `<li><a href="${esc(l.href)}"${relFor(l)}${stamp}>${esc(l.label)}</a></li>`;
         })
         .join("");
-      return `      <div class="footer-col">\n        <h4>${esc(c.title)}</h4>\n        <ul>${links}</ul>\n      </div>`;
+      return collapsible
+        ? `      <div class="footer-col"><details>\n        <summary>${esc(c.title)}</summary>\n        <ul>${links}</ul>\n      </details></div>`
+        : `      <div class="footer-col">\n        <h4>${esc(c.title)}</h4>\n        <ul>${links}</ul>\n      </div>`;
     })
     .join("\n");
   const trust = footer.trustMarks?.length
@@ -453,7 +522,7 @@ function renderFooter(footer: ChromeFooter): string {
   const bottom =
     bottomText || legalNav ? `\n    <div class="footer-bottom">${bottomText}${legalNav}</div>` : "";
   return (
-    `<footer class="site-footer">\n` +
+    `<footer class="site-footer" data-variant="${esc(footer.variant)}">\n` +
     `  <div class="container">\n` +
     `    <div class="footer-grid">\n${brandBlock}${columns}\n    </div>` +
     `${trust}${social}${payments}${warning}${bottom}\n` +
@@ -511,8 +580,8 @@ export const CHROME_BEHAVIOR_JS = `(function () {
   // DOM (data-tot-compliance, the same marker components/islands/IsolatedAgeGate.tsx
   // uses); its contents sit behind a closed shadow root, so tenant CSS/JS can't
   // select, restyle, or hide the dialog. A MutationObserver re-asserts the host the
-  // same way that component does. Config comes from the JSON payload rawChrome.ts
-  // renders (ChromeAgeGate, unchanged shape) so authoring stays the same.
+  // same way that component does. Config comes from the validated ChromeAgeGate
+  // JSON payload rawChrome.ts renders.
   var gateConfigEl = document.getElementById('tot-age-gate-config');
   if (gateConfigEl && !document.querySelector('[data-tot-compliance]')) {
     var gcfg; try { gcfg = JSON.parse(gateConfigEl.textContent || 'null'); } catch (e) { gcfg = null; }
@@ -524,10 +593,39 @@ export const CHROME_BEHAVIOR_JS = `(function () {
 
       var host = document.createElement('div');
       host.setAttribute('data-tot-compliance', '');
+      var gharden = function () {
+        var floor = { all: 'initial', display: 'block', position: 'fixed', inset: '0', 'z-index': '2147483647', visibility: 'visible', opacity: '1', 'pointer-events': 'none' };
+        Object.keys(floor).forEach(function (property) {
+          if (host.style.getPropertyValue(property) !== floor[property] || host.style.getPropertyPriority(property) !== 'important') {
+            host.style.setProperty(property, floor[property], 'important');
+          }
+        });
+      };
+      gharden();
       var shadow = host.attachShadow({ mode: 'closed' });
-      document.querySelectorAll('link[rel="stylesheet"]').forEach(function (l) {
-        shadow.appendChild(l.cloneNode(true));
+      var gcopiedSheets = {};
+      var gcopyPlatformSheet = function (l) {
+        var href = l.getAttribute('href') || '';
+        var sheetUrl; try { sheetUrl = new URL(href, document.baseURI); } catch (e) { sheetUrl = null; }
+        var platformPath = sheetUrl && sheetUrl.origin === location.origin &&
+          (sheetUrl.pathname.indexOf('/_astro/') === 0 || sheetUrl.pathname.indexOf('/shared/') === 0);
+        if (platformPath && !gcopiedSheets[sheetUrl.href]) {
+          gcopiedSheets[sheetUrl.href] = true;
+          shadow.appendChild(l.cloneNode(true));
+        }
+      };
+      document.head.querySelectorAll('link[rel="stylesheet"]').forEach(gcopyPlatformSheet);
+      // Astro may append an extracted island stylesheet after this behavior
+      // script runs. Copy the late, same-origin platform link into the closed
+      // root; never synthesize an inline style element, which strict CSP would block.
+      var gsheetObserver = new MutationObserver(function (records) {
+        records.forEach(function (record) {
+          record.addedNodes.forEach(function (node) {
+            if (node.nodeType === 1 && node.tagName === 'LINK' && node.rel === 'stylesheet') gcopyPlatformSheet(node);
+          });
+        });
       });
+      gsheetObserver.observe(document.head, { childList: true });
       var mount = document.createElement('div');
       shadow.appendChild(mount);
 
@@ -554,10 +652,41 @@ export const CHROME_BEHAVIOR_JS = `(function () {
         '</div></div>';
 
       var gate = mount.querySelector('#ageGate');
+      gate.style.pointerEvents = 'auto';
+      if (gcfg.variant === 'compact-modal') {
+        gate.style.background = 'rgba(0,0,0,.5)';
+        gate.style.padding = '16px';
+        gate.style.alignItems = 'flex-start';
+        var panel = mount.querySelector('.age-gate__panel');
+        panel.style.width = 'min(600px, calc(100vw - 32px))';
+        panel.style.minHeight = 'min(382px, calc(100vh - 32px))';
+        panel.style.borderRadius = '5px';
+        panel.style.boxShadow = '0 20px 60px rgba(0,0,0,.35)';
+        var actions = mount.querySelector('.age-gate__actions');
+        actions.style.flexDirection = 'column';
+        Array.prototype.forEach.call(actions.querySelectorAll('button'), function (button) {
+          button.style.width = '100%';
+          button.style.minHeight = '48px';
+          button.style.borderRadius = '3px';
+        });
+      }
       var gok = false;
       try { gok = localStorage.getItem(gkey) === 'yes'; } catch (e) {}
+      // Hiding overflow REMOVES the scrollbar, which widens the viewport and reflows the whole
+      // document behind the gate. Measured at CLS 0.82-0.90 on every page long enough to
+      // scroll — pages that never scrolled were untouched — costing ~25 Lighthouse performance
+      // points while every timing metric stayed green. Reserve the gutter first so the viewport
+      // keeps its width; measure BEFORE hiding, because afterwards the gutter reads 0.
+      var ggutter = function () {
+        var w = window.innerWidth - document.documentElement.clientWidth;
+        return (isFinite(w) && w > 0) ? w : 0;
+      };
       if (!gok) {
         gate.classList.add('is-open');
+        var gw = ggutter();
+        if (gw > 0 && !document.documentElement.style.paddingRight) {
+          document.documentElement.style.paddingRight = gw + 'px';
+        }
         document.documentElement.style.overflow = 'hidden';
       }
       var gyes = mount.querySelector('#ageYes');
@@ -566,16 +695,16 @@ export const CHROME_BEHAVIOR_JS = `(function () {
         try { localStorage.setItem(gkey, 'yes'); } catch (e) {}
         gate.classList.remove('is-open');
         document.documentElement.style.overflow = '';
+        document.documentElement.style.paddingRight = '';
       });
       if (gno) gno.addEventListener('click', function () { gate.classList.add('is-denied'); });
 
       document.body.appendChild(host);
 
       var gensure = function () {
-        if (!host.isConnected) document.body.appendChild(host);
-        if (host.style.display === 'none') host.style.display = '';
-        if (host.style.visibility === 'hidden') host.style.visibility = '';
+        if (!host.isConnected || document.body.lastElementChild !== host) document.body.appendChild(host);
         if (host.hasAttribute('hidden')) host.removeAttribute('hidden');
+        gharden();
       };
       var gobserver = new MutationObserver(gensure);
       gobserver.observe(document.body, { childList: true });

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

@@ -16,12 +16,15 @@
  * sanitizer. Untrusted vendor HTML must be sandboxed/sanitized instead.
  */
 import {
+  normalizePublicationPath,
   renderIntegrationPhases,
   INTERACTION_TRACKING_BOOT_JS,
   type EffectivePlan,
   type ConsentSnapshot,
 } from "@tot/public-runtime";
 import { reportTrackingChainHealth } from "./tracking/interactionHealth.js";
+import { ASYNC_CSS_SWAP_JS } from "./asyncCss.js";
+import { ROOT_SERVED_HREF_NAMESPACES } from "./basePath.js";
 
 export { rawHtmlPolicy } from "@tot/public-runtime";
 
@@ -133,6 +136,21 @@ export function interactionTrackingScript(nonce: string): string {
   return `<script${nonceAttr}>${INTERACTION_TRACKING_BOOT_JS}</script>`;
 }
 
+/**
+ * Swaps every `data-async-css`-tagged `<link rel="preload">` to
+ * `rel="stylesheet"` once fetched — the raw-mount half of the
+ * `<AsyncStylesheet>` primitive (lib/asyncCss.ts; Layout.astro is the other,
+ * same one-engine-two-mounts discipline as {@link interactionTrackingScript}).
+ * A raw-HTML tenant hand-authors the plain `<link rel="preload" as="style"
+ * data-async-css>` + `<noscript>` markup directly (no Astro component
+ * needed for that part); this script is what makes it actually async instead
+ * of a permanently-inert preload.
+ */
+export function asyncCssSwapScript(nonce: string): string {
+  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  return `<script${nonceAttr}>${ASYNC_CSS_SWAP_JS}</script>`;
+}
+
 /** Stamp `nonce` onto every inline `<style>`/`<script>` so a strict CSP admits them. */
 export function nonceInlineTags(html: string, nonce: string): string {
   return html
@@ -140,20 +158,105 @@ export function nonceInlineTags(html: string, nonce: string): string {
     .replaceAll("<script", `<script nonce="${nonce}"`);
 }
 
+/**
+ * Matches `href="/` NOT followed by `/` or a {@link ROOT_SERVED_HREF_NAMESPACES}
+ * entry. A namespace must be followed by `/`, a query, a fragment, or the closing
+ * quote — `favicon.svg` is a file, and `/favicon.svg?v=2` is still that file.
+ */
+const ROOT_SERVED_HREF_RE = new RegExp(
+  `href="/(?!/|(?:${ROOT_SERVED_HREF_NAMESPACES.join("|").replace(/\./g, "\\.")})(?:[/?#"]))`,
+  "g",
+);
+
 /**
  * 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) that every tenant links.
+ * basePath is empty (host-routed prod). Skips protocol-relative `//…` and every
+ * namespace in {@link ROOT_SERVED_HREF_NAMESPACES}.
  * 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}/`);
+  return html.replace(ROOT_SERVED_HREF_RE, `href="${basePath}/`);
+}
+
+/** Raw pages with a robots `noindex` directive remain routable but stay out of discovery. */
+export function isIndexableHtml(html: string): boolean {
+  for (const match of html.matchAll(/<meta\b([^>]*)>/gi)) {
+    const attrs: Record<string, string> = {};
+    for (const attr of (match[1] ?? "").matchAll(
+      /([a-zA-Z_:][\w:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g,
+    )) {
+      const name = attr[1];
+      if (name) attrs[name.toLowerCase()] = attr[2] ?? attr[3] ?? attr[4] ?? "";
+    }
+    if (attrs.name?.trim().toLowerCase() !== "robots") continue;
+    if ((attrs.content ?? "").toLowerCase().split(/[\s,]+/).includes("noindex")) return false;
+  }
+  return true;
+}
+
+/**
+ * The one canonical URL constructor for raw marketing subpages.
+ *
+ * Raw content providers supply slugs, not trusted URL paths. Normalize those
+ * slugs with the publication-space path contract, preserve a path-prefixed
+ * preview base, and add the raw-page route's single trailing slash. Both the
+ * page renderer and sitemap call this function so they cannot disagree.
+ */
+export function rawPageCanonicalUrl(canonicalBase: string, slug: string): string {
+  const path = normalizePublicationPath(`/${slug}`, { mode: "mount" });
+  if (!path.ok || path.value === "/") {
+    throw new Error(`Invalid canonical raw-page path: ${slug}`);
+  }
+
+  let base: URL;
+  try {
+    base = new URL(canonicalBase);
+  } catch {
+    throw new Error(`Invalid canonical base URL: ${canonicalBase}`);
+  }
+  if (
+    !["http:", "https:"].includes(base.protocol) ||
+    base.username ||
+    base.password ||
+    base.search ||
+    base.hash
+  ) {
+    throw new Error(`Invalid canonical base URL: ${canonicalBase}`);
+  }
+
+  const basePath = normalizePublicationPath(base.pathname || "/", { mode: "mount" });
+  if (!basePath.ok) throw new Error(`Invalid canonical base URL: ${canonicalBase}`);
+
+  const prefix = basePath.value === "/" ? "" : basePath.value;
+  base.pathname = `${prefix}${path.value}/`;
+  base.search = "";
+  base.hash = "";
+  return base.toString();
+}
+
+/**
+ * Resolve the raw document's `<link rel="canonical">` to an absolute URL.
+ * The caller supplies the renderer-owned canonical route URL; this function
+ * defensively preserves the raw-subpage trailing-slash contract. No-op when
+ * `canonicalUrl` is omitted: preview/candidate renders don't pass one, so
+ * their canonical stays exactly as tenant-authored (relative), which
+ * `prefixTenantLinks` then base-path-prefixes as before — unchanged
+ * behavior there, since those responses are already `noindex`.
+ */
+export function resolveCanonicalHref(html: string, canonicalUrl: string | undefined): string {
+  if (!canonicalUrl) return html;
+  const resolved = new URL(canonicalUrl);
+  if (resolved.pathname !== "/" && !resolved.pathname.endsWith("/")) {
+    resolved.pathname += "/";
+  }
+  const href = resolved.toString();
+  return html.replace(/<link\b[^>]*\brel=["']canonical["'][^>]*>/i, (tag) =>
+    /\bhref=["'][^"']*["']/i.test(tag)
+      ? tag.replace(/\bhref=["'][^"']*["']/i, `href="${href}"`)
+      : tag.replace(/<link\b/i, `<link href="${href}"`),
+  );
 }
 
 /**
@@ -188,6 +291,14 @@ export function rawHtmlResponse(
      * config (candidate/preview renders).
      */
     consentSnapshot?: ConsentSnapshot;
+    /**
+     * The absolute production URL for this page (`tenant.canonicalDomain` +
+     * path), matching Seo.astro's `canonical` derivation. Pass this only from
+     * production render paths (index.astro/[...slug].astro); preview/candidate
+     * callers omit it so their canonical stays relative and base-path-prefixed,
+     * unchanged from today (see resolveCanonicalHref).
+     */
+    canonicalUrl?: string;
   },
 ): Response {
   let composed =
@@ -239,6 +350,8 @@ export function rawHtmlResponse(
   // `chrome.html`, or a fragment spliced into the generated `renderRawChrome`
   // wrapper — is already present when the delegated listener binds.
   composed = injectBodyEnd(composed, interactionTrackingScript(opts.nonce));
+  composed = injectBodyEnd(composed, asyncCssSwapScript(opts.nonce));
+  composed = resolveCanonicalHref(composed, opts.canonicalUrl);
   const doc = prefixTenantLinks(composed, opts.basePath);
   return new Response(doc, {
     headers: { "content-type": "text/html; charset=utf-8" },

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

@@ -8,25 +8,53 @@
  * pilot CHILD space holds the content instances. See DECISIONS.md for the
  * parent/child + Shared Components plan.
  */
-import type { ProductSectionSource } from "@tot/public-runtime";
+import type { ProductSectionSource, FeaturedProductPresentation } from "@tot/public-runtime";
 import type { ProseSection } from "@/lib/content/prose";
 import type { Tier } from "@/lib/membership/model";
+import type { TrustStripItem } from "@/lib/content/trustStrip";
+import type { PromoTilePresentation } from "@tot/public-runtime";
 
 export type HomeBlock =
   | HeroBlock
   | PromoTilesBlock
+  | CommerceTrustStripBlock
   | FeaturedCollectionsBlock
   | FeaturedProductsBlock
   | MembershipBandBlock
   | EditorialBlock
-  | NewsletterBlock;
+  | NewsletterBlock
+  | FaqBlock;
+
+export interface CommerceTrustStripBlock {
+  component: "trust_strip";
+  items: TrustStripItem[];
+  /** Optional small-screen treatment. Claims remain governed by real-or-absent sanitization. */
+  mobile?: {
+    hidden?: boolean;
+    /** Preferred item labels first; unmatched items retain their authored order. */
+    order?: string[];
+  };
+}
+
+export interface PromoTile {
+  label: string;
+  href: string;
+  image?: string;
+  imageAlt?: string;
+  meta?: string;
+}
 
 export interface PromoTilesBlock {
   component: "promo_tiles";
+  eyebrow?: string;
   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 }[];
+  tiles: PromoTile[];
+  /** Defaults to the original image-overlay card. */
+  presentation?: PromoTilePresentation;
+  ctaLabel?: string;
+  ctaHref?: string;
 }
 
 export interface HeroBlock {
@@ -44,6 +72,14 @@ export interface HeroBlock {
   /** Direct hero image URL (e.g. the merchant's own homepage hero slide). */
   image?: string;
   imageAlt?: string;
+  /** Optional static, governed campaign slides. The first slide is the LCP image. */
+  slides?: Array<{
+    image: string;
+    imageAlt: string;
+    headline?: string;
+    ctaLabel?: string;
+    ctaHref?: string;
+  }>;
 }
 
 export interface FeaturedCollectionsBlock {
@@ -60,6 +96,8 @@ export interface FeaturedProductsBlock {
   source?: ProductSectionSource;
   handles?: string[];
   limit?: number;
+  /** Defaults to the existing grid. Carousel is static/CSS scroll output. */
+  presentation?: FeaturedProductPresentation;
 }
 
 /**
@@ -84,6 +122,9 @@ export interface EditorialBlock {
   title: string;
   body_html: string;
   imageSeed?: string;
+  /** Rehosted editorial photography; preferred over a generated placeholder. */
+  image?: string;
+  imageAlt?: string;
   align?: "left" | "right";
   ctaLabel?: string;
   ctaHref?: string;
@@ -211,6 +252,8 @@ export interface FaqBlock {
   component: "faq";
   eyebrow?: string;
   title: string;
+  /** Optional plain-text introduction rendered below the FAQ heading. */
+  lede?: string;
   items: { q: string; a: string }[];
 }
 

package/apps/storefront/src/lib/styleGuideThemes.ts

@@ -0,0 +1,107 @@
+import { tenantDirSegment } from "@tot/public-runtime";
+import type { ContentProvider } from "@/lib/storyblok/provider";
+
+export type StyleGuideTheme = Record<string, unknown> & {
+  id: string;
+  role?: string;
+  name?: string;
+  status?: string;
+  description?: string;
+};
+
+const localThemeModules = import.meta.glob<Record<string, unknown>>(
+  [
+    "../../../../tenants/*/content/themes/*.json",
+    "../../../../tenants/e2e/*/content/themes/*.json",
+  ],
+  { eager: true, import: "default" },
+);
+
+const localChromeModules = import.meta.glob<Record<string, unknown>>(
+  [
+    "../../../../tenants/*/content/chrome.json",
+    "../../../../tenants/e2e/*/content/chrome.json",
+  ],
+  { eager: true, import: "default" },
+);
+
+function isTheme(value: unknown): value is StyleGuideTheme {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      typeof (value as { id?: unknown }).id === "string",
+  );
+}
+
+function localThemes(tenant: string): StyleGuideTheme[] {
+  const segment = `${tenantDirSegment(tenant)}content/themes/`;
+  return Object.entries(localThemeModules)
+    .filter(([path]) => path.includes(segment))
+    .map(([, value]) => value)
+    .filter(isTheme);
+}
+
+function contentBelongsToRequestedTenant(
+  requestedTenant: string,
+  resolvedTenant: { tenant_id: string; appDomain?: string },
+): boolean {
+  const requested = requestedTenant.toLowerCase();
+  return [resolvedTenant.tenant_id, resolvedTenant.appDomain]
+    .filter((value): value is string => Boolean(value))
+    .some((value) => value.toLowerCase() === requested);
+}
+
+/**
+ * Read registered-tenant descriptors from the request's pinned/published
+ * content before falling back to build-time colocated tenants.
+ */
+export async function loadStyleGuideThemes(
+  requestedTenant: string,
+  resolvedTenant: { tenant_id: string; appDomain?: string },
+  content: Pick<ContentProvider, "listArtifactPaths" | "readArtifact">,
+): Promise<StyleGuideTheme[]> {
+  if (contentBelongsToRequestedTenant(requestedTenant, resolvedTenant)) {
+    try {
+      const paths = await content.listArtifactPaths("themes/");
+      if (paths !== null) {
+        const themes = (
+          await Promise.all(
+            paths
+              .filter((path) => path.startsWith("themes/") && path.endsWith(".json"))
+              .map(async (path) => {
+                const raw = await content.readArtifact(path);
+                if (!raw) return null;
+                try {
+                  return JSON.parse(raw) as unknown;
+                } catch {
+                  return null;
+                }
+              }),
+          )
+        ).filter(isTheme);
+        if (themes.length > 0) return themes;
+      }
+    } catch {
+      // A colocated build-time descriptor is the availability fallback.
+    }
+  }
+
+  return localThemes(requestedTenant);
+}
+
+export async function loadStyleGuideChrome(
+  requestedTenant: string,
+  resolvedTenant: { tenant_id: string; appDomain?: string },
+  content: Pick<ContentProvider, "getChrome">,
+): Promise<Record<string, unknown> | null> {
+  if (contentBelongsToRequestedTenant(requestedTenant, resolvedTenant)) {
+    try {
+      return (await content.getChrome()) as unknown as Record<string, unknown>;
+    } catch {
+      // A colocated build-time descriptor is the availability fallback.
+    }
+  }
+
+  const segment = `${tenantDirSegment(requestedTenant)}content/chrome.json`;
+  return Object.entries(localChromeModules).find(([path]) => path.includes(segment))?.[1] ?? null;
+}