@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

package/apps/storefront/src/lib/publish/streamLogConsole.ts

@@ -0,0 +1,142 @@
+/**
+ * Pure formatting for the admin Publish tab's shared SCROLLING LIVE-LOG console —
+ * the "CI build log" panel reused across ALL FOUR long-running flows (build /
+ * integrate / rebuild / ship). Where `buildStream.ts` owns the build-flight
+ * stage-RAIL (checkmarks), this owns the LOG: one human-readable, timestamped line
+ * appended per server-pushed `phase` event, then a terminal ✓/✗ line.
+ *
+ * It is transport-agnostic (it consumes already-parsed {@link SseEvent}s from
+ * `parseSseChunk`) and flow-agnostic: ONE phase→label map covers every phase any of
+ * the four routes emits, so the SAME console renders an integrate merge, a ship
+ * promote, or a build read with no per-flow branching. The terminal-line extractor
+ * reads the union of the four routes' honest result shapes (build's
+ * `ok`/`outcome`/`errors`, the queue's `ok`/`queueState`/`statusMessage`/`reason`,
+ * ship's `ok`/`state`/`message`) without any one flow's assumptions leaking in.
+ *
+ * The DOM wiring that appends these to a scrollable `<div>` and auto-scrolls is
+ * verified on a live preview, per this codebase's client-island convention (see
+ * `reviewReleaseWorkspace/controller.ts`). Only this pure formatting is unit-tested.
+ */
+import type { SseEvent } from "./buildStream.js";
+
+/**
+ * The human label for every `phase` a streamed route emits, across all four flows.
+ * Deliberately honest-but-neutral wording so the SAME line reads true whether the
+ * phase came from a candidate build or an aggregate rebuild.
+ */
+export const STREAM_PHASE_LABEL: Record<string, string> = {
+  // Accept-to-preview (integrate) — the queue's merge boundary.
+  merging: "Merging your change into the shared preview…",
+  // Build (candidate) — head resolution.
+  resolving: "Locating the pull request's latest commit…",
+  // Shared reconcile boundaries (build candidate + aggregate integrate/rebuild).
+  reading: "Reading and validating your store's files…",
+  publishing: "Building and publishing this version…",
+  checking: "Re-running the combined evidence checks…",
+  // Publish-live (ship) — the orchestrator's post-gate boundaries.
+  pinning: "Pinning the exact reviewed build…",
+  promoting: "Promoting the reviewed build to your live channel…",
+  verifying: "Verifying your live store serves the new build…",
+  recording: "Recording the release in your ledger…",
+};
+
+/**
+ * The label for one phase: a server-supplied `label` wins (a route may send a more
+ * specific line, e.g. build's "Locating the latest commit for PR #12…"), else the
+ * shared map, else `null` for an unknown phase (the caller ignores it — never
+ * fabricates a line for a phase it doesn't understand).
+ */
+export function phaseLogLabel(phase: string, serverLabel?: string | null): string | null {
+  if (serverLabel && serverLabel.trim()) return serverLabel.trim();
+  return STREAM_PHASE_LABEL[phase] ?? null;
+}
+
+/** `m:ss` elapsed, matching the dialog's own elapsed-clock format. Clamps negatives to 0. */
+export function formatElapsed(ms: number): string {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+}
+
+/**
+ * The log line for a `phase` event, or `null` to skip (unknown phase / not a phase
+ * event). Shape: `[m:ss] <label>`. Pure — the console appends the returned string.
+ */
+export function logLineForPhase(
+  ev: SseEvent,
+  elapsedMs: number,
+): string | null {
+  if (ev.event !== "phase") return null;
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(ev.data);
+  } catch {
+    return null;
+  }
+  const phase = parsed && typeof (parsed as { phase?: unknown }).phase === "string"
+    ? (parsed as { phase: string }).phase
+    : null;
+  if (!phase) return null;
+  const serverLabel =
+    parsed && typeof (parsed as { label?: unknown }).label === "string"
+      ? (parsed as { label: string }).label
+      : null;
+  const label = phaseLogLabel(phase, serverLabel);
+  if (!label) return null;
+  return `[${formatElapsed(elapsedMs)}] ${label}`;
+}
+
+/** A terminal result across the four flows — the union of their honest shapes. */
+export interface StreamTerminalResult {
+  ok?: boolean;
+  /** build */
+  outcome?: string | null;
+  errors?: string[] | null;
+  error?: string | null;
+  /** integrate/rebuild */
+  queueState?: string | null;
+  statusMessage?: string | null;
+  reason?: string | null;
+  /** ship */
+  state?: string | null;
+  message?: string | null;
+}
+
+/** True iff the terminal result is a clean success, reading each flow's own success signal. */
+export function isStreamResultOk(result: StreamTerminalResult): boolean {
+  if (result.state !== undefined && result.state !== null) return result.state === "shipped";
+  if (result.ok === true) return true;
+  return result.outcome === "ok";
+}
+
+/** A SHORT one-line reason for a non-ok terminal (the full detail lives in the outcome phase). */
+function streamResultReason(result: StreamTerminalResult): string {
+  const first = (v: string[] | null | undefined) => (v && v.length ? v[0] : "");
+  const candidate =
+    result.statusMessage ||
+    result.message ||
+    first(result.errors) ||
+    result.error ||
+    (result.outcome === "blocked" ? "a check blocked this build" : "") ||
+    result.reason ||
+    result.queueState ||
+    result.state ||
+    "it did not complete";
+  const line = String(candidate).replace(/\s+/g, " ").trim();
+  return line.length > 160 ? line.slice(0, 157) + "…" : line;
+}
+
+/**
+ * The terminal log line for a `result` event: `{ ok, line }`. `line` is
+ * `[m:ss] ✓ Done.` on success, `[m:ss] ✗ Stopped — <short reason>` otherwise. Pure.
+ */
+export function terminalLogLine(
+  result: StreamTerminalResult,
+  elapsedMs: number,
+): { ok: boolean; line: string } {
+  const ok = isStreamResultOk(result);
+  const stamp = `[${formatElapsed(elapsedMs)}]`;
+  return {
+    ok,
+    line: ok ? `${stamp} ✓ Done.` : `${stamp} ✗ Stopped — ${streamResultReason(result)}`,
+  };
+}

package/apps/storefront/src/lib/publish/versionNumber.ts

@@ -0,0 +1,52 @@
+/**
+ * The merchant-facing version counter — a monotonic, human "v1, v2, …" label for
+ * the tenant's published versions, DERIVED from the live-promotion history so it is
+ * never fabricated and never the raw SHA (which is meaningless to a merchant).
+ *
+ * A version's number is its rank by FIRST promotion to `live`: the earliest-ever
+ * promoted sha is v1, the next distinct sha is v2, and so on. This has the two
+ * properties merchants expect:
+ *   - monotonic increasing — a newer publish always gets a higher number; and
+ *   - stable for a given sha — a rollback re-points `live` at a prior version (per
+ *     `PromotionEvent`'s contract a plain rollback is not even recorded, and a
+ *     re-promote keeps the sha's ORIGINAL first-promotion rank), so "rolled back to
+ *     v3" reads honestly and a subsequent fresh publish becomes v(N+1), never
+ *     reusing a retired number.
+ *
+ * Pure (no I/O) so it unit-tests without a Worker/KV, and shared by both the
+ * live-version resolver (the "Live version" metric) and the versions-panel view so
+ * the two surfaces always agree on a version's number.
+ */
+import type { PromotionEvent } from "@tot/public-runtime";
+
+/**
+ * Map each promoted versionId → its 1-based version number, ranked by earliest
+ * promotion time. Input order is irrelevant (the rank is computed from the `at`
+ * timestamps), so it accepts the newest-first list `listPromotions` returns as-is.
+ * A tie on `at` between two distinct shas is broken by versionId for determinism.
+ */
+export function assignVersionNumbers(promotions: PromotionEvent[]): Map<string, number> {
+  const earliest = new Map<string, string>();
+  for (const p of promotions) {
+    const seen = earliest.get(p.versionId);
+    if (seen == null || p.at < seen) earliest.set(p.versionId, p.at);
+  }
+  const ordered = [...earliest.entries()].sort((a, b) =>
+    a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0,
+  );
+  const numbers = new Map<string, number>();
+  ordered.forEach(([versionId], i) => numbers.set(versionId, i + 1));
+  return numbers;
+}
+
+/**
+ * The version number for one versionId, or `null` when nothing in the promotion
+ * history matches (an unpromoted/unknown sha — the label falls back to the raw SHA).
+ */
+export function versionNumberFor(
+  promotions: PromotionEvent[],
+  versionId: string | null | undefined,
+): number | null {
+  if (!versionId) return null;
+  return assignVersionNumbers(promotions).get(versionId) ?? null;
+}

package/apps/storefront/src/lib/rate/kvWindow.ts

@@ -0,0 +1,53 @@
+/**
+ * Fixed-window KV rate limiter — the storefront's first throttle, built small
+ * and generic so any public POST can share it (reactions today; blog comments
+ * and other reader writes next).
+ *
+ * A request is counted into the bucket for the current fixed window
+ * (`floor(now / windowSeconds)`), keyed `<key>:<bucket>`. The counter TTLs out a
+ * window after it is first written, so old buckets self-expire — no sweep.
+ *
+ * Best-effort by construction: a KV read/write hiccup FAILS OPEN (returns
+ * `allowed: true`) and never throws. A rate limiter must never turn a KV blip
+ * into a rejected legitimate request; the abuse it guards against is low-stakes
+ * (mirrors the "never throws" discipline of `blog/viewCounts.ts`).
+ */
+
+export interface RateLimitOptions {
+  /** Window length in seconds; the counter resets each window. */
+  windowSeconds: number;
+  /** Max requests permitted per key per window before rejecting. */
+  maxRequests: number;
+}
+
+/** The current fixed-window bucket index for `now` (ms epoch). */
+function windowBucket(windowSeconds: number, nowMs: number): number {
+  return Math.floor(nowMs / 1000 / windowSeconds);
+}
+
+/**
+ * Count one request against `key` and report whether it is within the cap for
+ * the current window. Increment is a read-modify-write, so under concurrency a
+ * few increments can be lost to KV's last-write-wins — acceptable for a soft
+ * abuse throttle, not a hard quota. Fails OPEN on any KV error.
+ */
+export async function checkRateLimit(
+  kv: KVNamespace | undefined,
+  key: string,
+  opts: RateLimitOptions,
+  nowMs: number = Date.now(),
+): Promise<{ allowed: boolean }> {
+  if (!kv) return { allowed: true };
+  try {
+    const bucket = windowBucket(opts.windowSeconds, nowMs);
+    const bucketKey = `${key}:${bucket}`;
+    const raw = await kv.get(bucketKey);
+    const current = raw == null ? 0 : Number.parseInt(raw, 10);
+    const count = Number.isFinite(current) && current >= 0 ? current : 0;
+    if (count >= opts.maxRequests) return { allowed: false };
+    await kv.put(bucketKey, String(count + 1), { expirationTtl: opts.windowSeconds });
+    return { allowed: true };
+  } catch {
+    return { allowed: true };
+  }
+}

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

@@ -1,22 +1,22 @@
 /**
- * Canonical RAW chrome renderer (unit F3).
+ * Canonical RAW chrome renderer.
  *
  * ONE platform-shipped chrome wrapper, driven entirely by a tenant's `chrome.json`
- * (typed `TenantChrome`, lib/chrome/model.ts) — CONTENT ONLY. It replaces the three
+ * (typed `ChromeConfig`, lib/chrome/model.ts) — CONTENT ONLY. It replaces the three
  * divergent, hand-authored `content/<tenant>/chrome.html` documents with a single
  * generator, so chrome lives in ONE place and a tenant supplies only data. The
  * output is a full wrapper document carrying the splice markers the rawMarketingHtml
  * pipeline understands (`<!--PAGE_HEAD-->` / `<!--PAGE_BODY-->`), so body-only page
  * fragments get wrapped exactly as before (see lib/rawMarketingHtml.ts,
- * wrapFragmentInChrome). Per decisions:
- *   - raw-chrome-single-stylesheet: the wrapper LINKS the platform stylesheet
- *     (/shared/commerce-chrome.css, unit F2) and emits NO inline chrome CSS — every
+ * wrapFragmentInChrome). Two governing constraints:
+ *   - Single stylesheet: the wrapper LINKS the platform stylesheet
+ *     (/shared/commerce-chrome.css) and emits NO inline chrome CSS — every
  *     color/space/type comes from theme tokens the tenant's linked *-theme.css sets.
- *   - materialization-compat: this is a deterministic server-side string; the spliced
+ *   - Materialization-compatible: this is a deterministic server-side string; the spliced
  *     document is a stable, self-contained artifact SEOMaterialize can capture (the
  *     behavior JS is progressive enhancement over already-rendered markup).
  *
- * The markup mirrors, class-for-class, the semantic markup the F2 stylesheet styles
+ * The markup mirrors, class-for-class, the semantic markup the shared chrome stylesheet styles
  * (`.site-header`, `.header-row`, `.primary-nav`, `.mega`, `.site-footer`, …) — the
  * SAME DOM the retired tenant chrome.html files carried, now generated from config.
  *
@@ -25,17 +25,23 @@
  * defense-in-depth, not a sanitizer for untrusted input.
  */
 import { CHROME_BODY_MARKER, CHROME_HEAD_MARKER } from "./rawMarketingHtml.js";
+import { isCurrentNavHref } from "./chrome/navCurrent.js";
 import type {
   ChromeAgeGate,
   ChromeAnnouncement,
+  ChromeAssignments,
   ChromeBrand,
+  ChromeConfig,
   ChromeFooter,
+  ChromeHeader,
   ChromeLink,
   ChromeNavItem,
   ChromeUtilityNav,
+  HeaderVariant,
   SocialLink,
-  TenantChrome,
 } from "./chrome/model.js";
+import { resolveChromeAssignment } from "./chrome/model.js";
+import { resolveHeaderVariant } from "./chrome/variant.js";
 
 /** HTML-escape text/attribute content. Covers the five significant characters. */
 function esc(value: string): string {
@@ -177,8 +183,18 @@ function renderUtilityNav(u: ChromeUtilityNav): string {
   );
 }
 
-/** A primary-nav item — flat link, or a mega panel when it has columns/children. */
-function renderNavItem(item: ChromeNavItem): string {
+/**
+ * A primary-nav item — flat link, or a mega panel when it has columns/children.
+ *
+ * `currentPath`, when given, is the tenant-relative request path (e.g. "/" or
+ * "/collections/all") in the SAME unprefixed form the config's own `href`
+ * values are authored in — basePath prefixing happens later, as a single
+ * pass over the whole composed document (rawMarketingHtml.ts,
+ * prefixTenantLinks), so comparing here before that pass keeps both sides
+ * unprefixed and exact-match-only (see navCurrent.ts). Omitted ⇒ no item is
+ * ever marked current (callers that don't know the request path, e.g. tests).
+ */
+function renderNavItem(item: ChromeNavItem, currentPath?: string): string {
   const columns = item.columns?.length
     ? item.columns
     : item.children?.length
@@ -189,14 +205,23 @@ function renderNavItem(item: ChromeNavItem): string {
   const badge = item.badge ? `<span class="new-badge">${esc(item.badge)}</span>` : "";
   const caret = hasPanel ? `<span class="caret" aria-hidden="true">▾</span>` : "";
   const haspopup = hasPanel ? ' aria-haspopup="true"' : "";
-  const link = `<a${linkClass} href="${esc(item.href)}"${haspopup}>${esc(item.label)}${badge}${caret}</a>`;
+  const itemCurrent = currentPath !== undefined && isCurrentNavHref(currentPath, item.href);
+  const ariaCurrent = itemCurrent ? ' aria-current="page"' : "";
+  const link = `<a${linkClass} href="${esc(item.href)}"${haspopup}${ariaCurrent}>${esc(item.label)}${badge}${caret}</a>`;
   if (!hasPanel) return `<li class="nav-item">${link}</li>`;
 
   const wide = columns.length > 1 ? " mega--wide" : "";
   const cols = columns
     .map((c) => {
       const heading = c.title ? `<h4>${esc(c.title)}</h4>` : "";
-      const links = c.links.map((l) => `<a href="${esc(l.href)}"${relFor(l)}>${esc(l.label)}</a>`).join("");
+      const links = c.links
+        .map((l) => {
+          const childCurrent =
+            currentPath !== undefined && isCurrentNavHref(currentPath, l.href, l.external);
+          const childAriaCurrent = childCurrent ? ' aria-current="page"' : "";
+          return `<a href="${esc(l.href)}"${relFor(l)}${childAriaCurrent}>${esc(l.label)}</a>`;
+        })
+        .join("");
       return `<div class="mega__col">${heading}${links}</div>`;
     })
     .join("");
@@ -204,46 +229,73 @@ function renderNavItem(item: ChromeNavItem): string {
   return `<li class="nav-item">${link}${mega}</li>`;
 }
 
-function renderHeader(chrome: TenantChrome): string {
-  const search = chrome.search
-    ? `<form class="header-search" action="${esc(chrome.search.action ?? "/search")}" method="get" role="search">\n` +
-      `      <label class="sr-only" for="hdr-q">${esc(chrome.search.label ?? "Search")}</label>\n` +
-      `      <input id="hdr-q" type="search" name="q" placeholder="${esc(chrome.search.placeholder ?? "Search")}" autocomplete="off">\n` +
+/**
+ * `variant` is the RESOLVED header variant for this page — the page-assignment
+ * override applied over `header.variant` by the caller. It is passed in rather
+ * than read off `header` so the rendered markup and its `data-variant` can
+ * never disagree with the variant the assignment actually decided.
+ */
+function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?: string): string {
+  const search = header.search
+    ? `<form class="header-search" action="${esc(header.search.action ?? "/search")}" method="get" role="search">\n` +
+      `      <label class="sr-only" for="hdr-q">${esc(header.search.label ?? "Search")}</label>\n` +
+      `      <input id="hdr-q" type="search" name="q" placeholder="${esc(header.search.placeholder ?? "Search")}" autocomplete="off">\n` +
       `      <button type="submit" aria-label="Search">${ICON_SEARCH}</button>\n` +
       `    </form>`
     : "";
-  const memberCue = chrome.memberCue
-    ? `<a class="member-cue" href="${esc(chrome.memberCue.href)}" aria-label="${esc(chrome.memberCue.label)}">${esc(chrome.memberCue.label)}</a>`
+  const memberCue = header.memberCue
+    ? `<a class="member-cue" href="${esc(header.memberCue.href)}" aria-label="${esc(header.memberCue.label)}">${esc(header.memberCue.label)}</a>`
     : "";
-  const account = chrome.accountHref
-    ? `<a href="${esc(chrome.accountHref)}" aria-label="Account">${ICON_ACCOUNT}</a>`
+  const account = header.accountHref
+    ? `<a href="${esc(header.accountHref)}" aria-label="Account">${ICON_ACCOUNT}</a>`
     : "";
-  const cart = chrome.cartHref
-    ? `<a class="cart" href="${esc(chrome.cartHref)}" aria-label="Cart">${ICON_CART}<span class="count">0</span></a>`
+  const cart = header.cartHref
+    ? `<a class="cart" href="${esc(header.cartHref)}" aria-label="Cart">${ICON_CART}<span class="count">0</span></a>`
     : "";
-  const hamburger =
-    `<button class="hamburger" id="hamburger" aria-label="Toggle navigation menu" aria-expanded="false" aria-controls="primaryNav"><span></span><span></span><span></span></button>`;
-  const navItems = chrome.nav.map(renderNavItem).join("\n          ");
+  // "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";
+  // Header CTAs, on the same `!minimal` rule the Astro SiteHeader applies, so the
+  // two surfaces render the same governed config identically. Each carries its
+  // stable `id` as `data-cta-id`, so the governed identity is present in the
+  // served DOM rather than implied by label or href.
+  const ctas =
+    minimal || !header.ctas?.length
+      ? ""
+      : header.ctas
+          .map(
+            (c) =>
+              `<a class="header-cta header-cta--${esc(c.variant ?? "primary")}" ` +
+              `data-cta-id="${esc(c.id)}" href="${esc(c.href)}">${esc(c.label)}</a>`,
+          )
+          .join("");
+  const hamburger = minimal
+    ? ""
+    : `<button class="hamburger" id="hamburger" aria-label="Toggle navigation menu" aria-expanded="false" aria-controls="primaryNav"><span></span><span></span><span></span></button>`;
+  const navItems = header.nav.map((item) => renderNavItem(item, currentPath)).join("\n          ");
+  const navBar = minimal
+    ? ""
+    : `  <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` +
+      `    </div>\n` +
+      `  </nav>\n`;
   return (
-    `<header class="site-header">\n` +
+    `<header class="site-header" data-variant="${esc(variant)}">\n` +
     `  <div class="container header-row">\n` +
-    `    ${renderBrand(chrome.brand)}\n` +
-    (search ? `    ${search}\n` : "") +
-    `    <div class="header-actions">${memberCue}${account}${cart}${hamburger}</div>\n` +
+    `    ${renderBrand(header.brand)}\n` +
+    (!minimal && search ? `    ${search}\n` : "") +
+    `    <div class="header-actions">${memberCue}${ctas}${account}${cart}${hamburger}</div>\n` +
     `  </div>\n` +
-    `  <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` +
-    `    </div>\n` +
-    `  </nav>\n` +
+    navBar +
     `</header>`
   );
 }
 
 /**
- * Age-gate config, embedded as JSON (unit C1). The CHROME_BEHAVIOR_JS mechanism
+ * Age-gate config, embedded as JSON. The CHROME_BEHAVIOR_JS mechanism
  * reads this and builds the dialog itself inside a closed shadow root — the same
  * tamper-resistance pattern components/islands/IsolatedAgeGate.tsx uses for
  * component pages (see its header comment). `<` is escaped so an authored value
@@ -335,9 +387,16 @@ function renderFooter(footer: ChromeFooter): string {
  * — a single canonical source, never copy-pasted per tenant. Each block is guarded on
  * the presence of its elements, so a wrapper that omits the announce bar / age gate
  * runs the remaining behavior harmlessly. Progressive enhancement: the markup already
- * works without it (nav is visible, gate defaults open only when JS enables it).
+ * works without it (nav is a normal in-flow stacked list at mobile widths — see the
+ * `.js-nav` gate in commerce-chrome.css's max-width:860px block — and the age gate
+ * defaults open only when JS enables it).
  */
 export const CHROME_BEHAVIOR_JS = `(function () {
+  // Marks the document as JS-enabled so commerce-chrome.css can turn the
+  // always-reachable stacked mobile nav into an off-canvas drawer (progressive
+  // enhancement, not a requirement — see the .js-nav rules there).
+  document.documentElement.classList.add('js-nav');
+
   // Mobile nav drawer
   var burger = document.getElementById('hamburger');
   var nav = document.getElementById('primaryNav');
@@ -367,7 +426,7 @@ export const CHROME_BEHAVIOR_JS = `(function () {
     }
   }
 
-  // 21+ age gate — shadow-isolated (unit C1). Only the host <div> lives in light
+  // 21+ age gate — shadow-isolated. Only the host <div> lives in light
   // 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
@@ -444,11 +503,11 @@ export const CHROME_BEHAVIOR_JS = `(function () {
   }
 })();`;
 
-/** The platform-shipped chrome stylesheet every rendered wrapper links (unit F2). */
+/** The platform-shipped chrome stylesheet every rendered wrapper links. */
 export const SHARED_CHROME_STYLESHEET = "/shared/commerce-chrome.css";
 
 /**
- * The platform-shipped RAW-PAGE-BODY marketing stylesheet (unit F5). Linked only
+ * The platform-shipped RAW-PAGE-BODY marketing stylesheet. Linked only
  * when a tenant opts in (chrome.sharedMarketingCss) and AFTER the chrome sheet, so
  * its page-level variants (e.g. .sec-head) win over chrome's home-section ones.
  */
@@ -480,8 +539,22 @@ function faviconMime(href: string): string {
  * `chromeWrapper` so a body-only fragment is spliced in and the whole thing is
  * nonce-stamped + base-path-prefixed. Optional sections (age gate, announcement,
  * utility nav, member cue, footer extras) render only when their config is present.
+ *
+ * `currentPath`, when given, is the tenant-relative request path in the same
+ * unprefixed form nav `href`s are authored in (see renderNavItem) — drives
+ * `aria-current="page"` on the primary-nav link that exactly matches it.
+ *
+ * `assignments`, when given, is the tenant's page-assignment manifest: the
+ * entry matching `currentPath` overrides `chrome.header.variant` for THIS page
+ * only. Resolution happens once, here, through the same fail-closed
+ * resolveHeaderVariant the Layout.astro prop path uses, and the resolved value
+ * is what reaches the markup.
  */
-export function renderRawChrome(chrome: TenantChrome): string {
+export function renderRawChrome(
+  chrome: ChromeConfig,
+  currentPath?: string,
+  assignments?: ChromeAssignments | null,
+): string {
   const lang = esc(chrome.lang ?? "en");
   const head = chrome.head ?? {};
   const headLinks = [
@@ -491,20 +564,25 @@ export function renderRawChrome(chrome: TenantChrome): string {
       : "",
     ...(head.themeStylesheets ?? []).map((h) => `<link rel="stylesheet" href="${esc(h)}">`),
     `<link rel="stylesheet" href="${SHARED_CHROME_STYLESHEET}">`,
-    // Opt-in raw-page-body layer, after the chrome sheet so its variants win (F5).
+    // Opt-in raw-page-body layer, after the chrome sheet so its variants win.
     chrome.sharedMarketingCss ? `<link rel="stylesheet" href="${SHARED_MARKETING_STYLESHEET}">` : "",
   ]
     .filter(Boolean)
     .join("\n");
 
+  const headerVariant = resolveHeaderVariant(
+    resolveChromeAssignment(assignments, currentPath)?.headerVariant,
+    chrome.header.variant,
+  );
+
   const skipHref = esc(chrome.skipLink?.href ?? "#main");
   const skipLabel = esc(chrome.skipLink?.label ?? "Skip to main content");
 
   const sections = [
     chrome.warningBar ? `<div class="topbar-warning"><p>${esc(chrome.warningBar)}</p></div>` : "",
-    chrome.announcement ? renderAnnouncement(chrome.announcement) : "",
-    chrome.utilityNav ? renderUtilityNav(chrome.utilityNav) : "",
-    renderHeader(chrome),
+    chrome.header.announcement ? renderAnnouncement(chrome.header.announcement) : "",
+    chrome.header.utilityNav ? renderUtilityNav(chrome.header.utilityNav) : "",
+    renderHeader(chrome.header, headerVariant, currentPath),
   ].filter(Boolean);
 
   const trailing = [

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

@@ -15,6 +15,11 @@
  * injection is a deliberate string replace — robust for first-party documents, not a
  * sanitizer. Untrusted vendor HTML must be sandboxed/sanitized instead.
  */
+import {
+  renderIntegrationPhases,
+  type EffectivePlan,
+} from "@tot/public-runtime";
+
 export { rawHtmlPolicy } from "@tot/public-runtime";
 
 /**
@@ -64,6 +69,50 @@ export function wrapFragmentInChrome(fragment: string, chromeWrapper: string): s
   return out;
 }
 
+/**
+ * Insert `snippet` at the very start of the document's `<head>` (or, absent a
+ * head, right after `<html>`, else at the document start) — so the renderer-owned
+ * head phases precede any tenant/app `<script>`/`<style>` in the served document.
+ * A body-only fragment with no wrapper has neither tag, so it is prepended.
+ */
+function injectHeadStart(html: string, snippet: string): string {
+  // `(?:\s[^>]*)?>` matches `<head>` / `<head lang=…>` but NOT `<header>`.
+  const head = /<head(?:\s[^>]*)?>/i.exec(html);
+  if (head) {
+    const at = head.index + head[0].length;
+    return html.slice(0, at) + snippet + html.slice(at);
+  }
+  const htmlTag = /<html(?:\s[^>]*)?>/i.exec(html);
+  if (htmlTag) {
+    const at = htmlTag.index + htmlTag[0].length;
+    return html.slice(0, at) + snippet + html.slice(at);
+  }
+  return snippet + html;
+}
+
+/**
+ * Insert `snippet` at the very start of `<body>` (the body.start boundary), or —
+ * for a body-only fragment with no `<body>` — at the document start.
+ */
+function injectBodyStart(html: string, snippet: string): string {
+  const body = /<body(?:\s[^>]*)?>/i.exec(html);
+  if (body) {
+    const at = body.index + body[0].length;
+    return html.slice(0, at) + snippet + html.slice(at);
+  }
+  return snippet + html;
+}
+
+/**
+ * Insert `snippet` immediately before `</body>` (the document.deferred boundary),
+ * or — for a body-only fragment with no `</body>` — at the document end.
+ */
+function injectBodyEnd(html: string, snippet: string): string {
+  const at = html.toLowerCase().lastIndexOf("</body>");
+  if (at >= 0) return html.slice(0, at) + snippet + html.slice(at);
+  return html + snippet;
+}
+
 /** Stamp `nonce` onto every inline `<style>`/`<script>` so a strict CSP admits them. */
 export function nonceInlineTags(html: string, nonce: string): string {
   return html
@@ -79,7 +128,7 @@ export function nonceInlineTags(html: string, nonce: string): string {
  * 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.
+ *     stylesheet) that every tenant links.
  * Asset `src="…"` isn't matched at all (href-only).
  */
 export function prefixTenantLinks(html: string, basePath: string): string {
@@ -100,7 +149,19 @@ export function prefixTenantLinks(html: string, basePath: string): string {
  */
 export function rawHtmlResponse(
   html: string,
-  opts: { nonce: string; basePath: string; chromeWrapper?: string | null },
+  opts: {
+    nonce: string;
+    basePath: string;
+    chromeWrapper?: string | null;
+    /**
+     * The resolved effective plan for this request — the raw-mount half of the
+     * "one engine, two mounts" contract (Layout.astro is the other). The SAME
+     * render engine emits the renderer-owned phases into this document, so its
+     * phase markup is byte-identical to Layout's. Required: no render path may
+     * silently omit it. Nonces are stamped per response, never serialized (ADR 0018).
+     */
+    plan: EffectivePlan;
+  },
 ): Response {
   let composed =
     isFullDocument(html) || !opts.chromeWrapper
@@ -130,7 +191,17 @@ export function rawHtmlResponse(
       ? composed.replace("</body>", `${widget}</body>`)
       : `${composed}${widget}`;
   }
-  const doc = prefixTenantLinks(nonceInlineTags(composed, opts.nonce), opts.basePath);
+  // Stamp the page nonce onto the TENANT's inline tags first, then splice the render
+  // engine's phase markup — which already carries the nonce — so the engine bytes are
+  // never double-stamped and match Layout.astro's mount exactly. `opts.nonce` is the
+  // per-response nonce placeholder; the middleware substitutes a fresh nonce at serve
+  // time (ADR 0018), so the same engine output feeds both mounts identically.
+  composed = nonceInlineTags(composed, opts.nonce);
+  const phases = renderIntegrationPhases(opts.plan, opts.nonce);
+  composed = injectHeadStart(composed, phases.head);
+  composed = injectBodyStart(composed, phases.bodyStart);
+  composed = injectBodyEnd(composed, phases.bodyDeferred);
+  const doc = prefixTenantLinks(composed, opts.basePath);
   return new Response(doc, {
     headers: { "content-type": "text/html; charset=utf-8" },
   });