@tokenoftrust/storefront-runner 2.1.9 → 2.1.10

package/apps/storefront/public/shared/commerce-chrome.css

@@ -64,6 +64,10 @@ body { overflow-x: clip; }
    caught as a real color-contrast failure once accent is a deep brand hue). */
 .announce-bar { background: var(--color-accent); color: var(--color-primary-contrast); }
 .announce-bar[hidden] { display: none; }
+/* A returning visitor who already dismissed the bar gets `.announce-dismissed`
+   stamped on <html> pre-paint (see rawChrome.ts's head script) so it never
+   flashes in before CHROME_BEHAVIOR_JS's end-of-body script sets [hidden]. */
+.announce-dismissed .announce-bar { display: none; }
 .announce-bar .container { display: flex; align-items: center; justify-content: center; gap: 14px; padding-block: 9px; position: relative; }
 .announce-bar__msg { font-size: .875rem; font-weight: 700; letter-spacing: .01em; text-align: center; }
 .announce-bar__msg a { color: var(--color-primary-contrast); text-decoration: underline; }

package/apps/storefront/src/layouts/Layout.astro

@@ -23,7 +23,7 @@ import { referenceTheme } from "@/themes/reference";
 import { mergeTheme } from "@/themes/schema";
 import { organizationLd, websiteLd } from "@/lib/jsonld";
 import { nonceInlineTags, CHROME_BODY_MARKER } from "@/lib/rawMarketingHtml";
-import { CHROME_BEHAVIOR_JS, sanitizeSharedChromeFragment } from "@/lib/rawChrome";
+import { CHROME_BEHAVIOR_JS, CHROME_HEAD_JS, sanitizeSharedChromeFragment } from "@/lib/rawChrome";
 import { ASYNC_CSS_SWAP_JS } from "@/lib/asyncCss";
 import { reportTrackingChainHealth } from "@/lib/tracking/interactionHealth";
 import { resolveHeaderVariant, resolveFooterVariant } from "@/lib/chrome/variant";
@@ -264,6 +264,11 @@ const footerWidgets = await renderWidgetSlot(
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
 
+    {/* MUST run before body content paints — see CHROME_HEAD_JS's doc comment
+        in rawChrome.ts (the same statement CHROME_BEHAVIOR_JS used to run at
+        end of body, which shifted the mobile nav's layout post-paint). */}
+    <script is:inline nonce={cspNonce} set:html={CHROME_HEAD_JS}></script>
+
     {/* Renderer-owned head phases (platform.environment → consent.defaults →
         head.early), emitted before any tenant/app code — the Layout half of "one
         engine, two mounts" (rawHtmlResponse is the other). Same engine output, so

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

@@ -19,7 +19,7 @@ export const STATIC_SCRIPT_HASHES: readonly string[] = [
   "'sha256-YicfxUFBkKrQapZ/tzZKlaKTdNHgwVfv7y2Wa0NC6/k='",
   "'sha256-eIXWvAmxkr251LJZkjniEK5LcPF3NkapbJepohwYRIc='",
   "'sha256-elMLh/6Oubj8u9FRLwZLyRa6TqKikGs75mf0jfWcoxI='",
-  "'sha256-yxhGRh5KeGL1P3NgVN7YoKE4N5zBl1XGEycWPbX0TWo='",
+  "'sha256-Rl3sizqw4AmEkfQgkgajKo4uJC7JkyVCYiPJY/DJbIE='",
 ];
 
 export const STATIC_STYLE_HASHES: readonly string[] = [

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

@@ -531,6 +531,45 @@ function renderFooter(footer: ChromeFooter): string {
   );
 }
 
+/**
+ * The ONE canonical statement that marks the document JS-enabled so
+ * commerce-chrome.css can turn the always-reachable stacked mobile nav into an
+ * off-canvas drawer (`.js-nav` gate, commerce-chrome.css's max-width:860px
+ * block) — progressive enhancement, not a requirement. Shared verbatim by both
+ * document mounts that emit this chrome (the raw-HTML wrapper below and
+ * Layout.astro's Astro-rendered mount) so it is one source, never copy-pasted.
+ *
+ * MUST run from `<head>`, before any body content paints: run from end of body
+ * (as CHROME_BEHAVIOR_JS used to), the browser paints the stacked in-flow nav
+ * first and then reflows it into the fixed drawer once this line runs,
+ * producing a mobile-only layout shift (measured CLS 0.232 on
+ * `body > main#main`). Run from `<head>`, the drawer layout is what the
+ * browser paints first — no reflow, no shift.
+ */
+export const CHROME_HEAD_JS = `document.documentElement.classList.add('js-nav');`;
+
+/**
+ * The wrapper's `<head>` behavior script: {@link CHROME_HEAD_JS}, plus — only when
+ * the announcement is a dismissible "bar" — a pre-paint check of the SAME
+ * localStorage key CHROME_BEHAVIOR_JS's dismiss handler reads, so a returning
+ * visitor who already dismissed it never sees it flash in before being hidden
+ * (the same before/after-paint shape as `.js-nav`, for a returning visitor
+ * rather than every visitor). Marks `<html>` with `.announce-dismissed`, which
+ * commerce-chrome.css hides the bar behind; CHROME_BEHAVIOR_JS's own
+ * `bar.hidden` logic (which also gates the message-rotation interval) is
+ * unchanged and still runs.
+ */
+function renderChromeHeadScript(chrome: ChromeConfig): string {
+  const announcement = chrome.header.announcement;
+  const announceKey = announcement?.variant === "bar" && announcement.dismissible
+    ? announcement.storageKey || "tot_announce_dismissed"
+    : null;
+  const announceCheck = announceKey
+    ? ` try { if (localStorage.getItem(${JSON.stringify(announceKey)}) === '1') document.documentElement.classList.add('announce-dismissed'); } catch (e) {}`
+    : "";
+  return `<script>(function () { ${CHROME_HEAD_JS}${announceCheck} })();</script>`;
+}
+
 /**
  * The ONE shared, nonce-safe chrome behavior script. Inlined into the wrapper (the
  * rawMarketingHtml pipeline stamps it with the page nonce, so a strict CSP admits it)
@@ -542,11 +581,6 @@ function renderFooter(footer: ChromeFooter): string {
  * 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');
@@ -808,6 +842,7 @@ export function renderRawChrome(
     `<head>\n` +
     `<meta charset="UTF-8">\n` +
     `<meta name="viewport" content="width=device-width, initial-scale=1.0">\n` +
+    `${renderChromeHeadScript(chrome)}\n` +
     `${headLinks}\n` +
     `${CHROME_HEAD_MARKER}\n` +
     `</head>\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.1.9",
+  "version": "2.1.10",
   "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/integration/lifecycle-boot.ts

@@ -46,7 +46,9 @@ import { resolveNativeGa4SandboxUrl, type NativeGa4Transport } from "./native-ga
 import {
   createBrowserNativeGa4SandboxHost,
   createNativeGa4SandboxTransport,
+  type NativeGa4SandboxScheduler,
 } from "./native-ga4-sandbox.js";
+import { schedulePostPaint, type PostPaintWindow } from "./post-paint.js";
 import { ManagedAnalyticsEventBrokerBridge } from "./managed-analytics-bridge.js";
 import { minimizePageAttribution, type ManagedPageViewInput } from "./managed-analytics.js";
 import { managedAnalyticsOpaqueRevision } from "./managed-analytics-value-safety.js";
@@ -121,6 +123,15 @@ export interface BootLifecycleOptions {
   importModule?: (url: string) => Promise<unknown>;
   /** Reviewed isolated-origin GA4 transport; injectable for DOM-free tests. */
   nativeGa4Transport?: NativeGa4Transport;
+  /**
+   * Defers non-essential platform-adapter work (the GA4 sandbox iframe mount and
+   * the Amplitude HTTP capability) until after first paint and idle — see
+   * `post-paint.ts`. Defaults to the real post-paint scheduler over `window`
+   * (a guarded synchronous no-op off the browser). Injectable so a test can
+   * assert nothing runs before the scheduler fires with a fake, controllable
+   * scheduler instead of real paint/idle timing.
+   */
+  schedulePlatformAdapterStart?: NativeGa4SandboxScheduler;
 }
 
 /**
@@ -314,6 +325,58 @@ function defaultConsentGate(
   return (integration) => integrationConsentEligible(integration, readConsentSnapshot(win));
 }
 
+/**
+ * The default `schedulePlatformAdapterStart`: the real post-paint scheduler over the
+ * global `window`, or a synchronous immediate start off the browser (SSR, tests that
+ * import this module without a DOM) — never a hang.
+ */
+function defaultPlatformAdapterScheduler(start: () => void): { cancel(): void } {
+  if (typeof window === "undefined") {
+    start();
+    return { cancel() {} };
+  }
+  return schedulePostPaint(window as unknown as PostPaintWindow, start);
+}
+
+/**
+ * Wrap a `fetch` capability so calls queue instead of running immediately, and are
+ * all issued together once `schedule` fires. This is what keeps the Amplitude
+ * adapter's HTTP collection off the pre-paint critical path exactly like the GA4
+ * sandbox's deferred iframe mount, without touching `native-amplitude.ts` (which
+ * stays paint-timing-agnostic — it just calls the `fetch` capability it was given).
+ */
+function deferFetchCapability(
+  fetchCapability: typeof fetch,
+  schedule: (start: () => void) => { cancel(): void },
+): typeof fetch {
+  interface Pending {
+    args: Parameters<typeof fetch>;
+    resolve: (value: Response) => void;
+    reject: (reason: unknown) => void;
+  }
+  let queue: Pending[] = [];
+  let scheduled = false;
+  const flush = (): void => {
+    scheduled = false;
+    const pending = queue;
+    queue = [];
+    for (const { args, resolve, reject } of pending) {
+      fetchCapability(...args).then(resolve, reject);
+    }
+  };
+  return ((...args: Parameters<typeof fetch>) =>
+    new Promise<Response>((resolve, reject) => {
+      queue.push({ args, resolve, reject });
+      // Re-arm on every fresh burst: a flush disarms itself so a LATER call (e.g. a
+      // same-document route commit long after boot) still gets scheduled, not just
+      // the first ever call through this capability.
+      if (!scheduled) {
+        scheduled = true;
+        schedule(flush);
+      }
+    })) as typeof fetch;
+}
+
 /**
  * Boot the lifecycle for `win` exactly once. A second call returns the same instance
  * (nested-layout safety). Returns `null` when there is no boot descriptor to act on.
@@ -330,6 +393,8 @@ export function bootIntegrationLifecycle(
 
   const hostFetch = options.fetchCapability ??
     (typeof win.fetch === "function" ? win.fetch.bind(win) : undefined);
+  const schedulePlatformAdapterStart =
+    options.schedulePlatformAdapterStart ?? defaultPlatformAdapterScheduler;
   const fallbackLoader = options.importModule
     ? makeSameOriginEntryLoader(options.importModule)
     : sameOriginEntryLoader;
@@ -340,7 +405,10 @@ export function bootIntegrationLifecycle(
   // Platform authority is resolved before any caller/window override: exact registry
   // matches run; unknown/mismatched platform claims fail closed without delegation.
   const loadModule = makePlatformAdapterRuntimeLoader({
-    fetchCapability: hostFetch,
+    // Deferred so the Amplitude adapter's HTTP collection never starts pre-paint
+    // (F4/CLASS 1). The subscribe/mapping logic in native-amplitude.ts is unchanged
+    // and unaware of this — it just calls whatever `fetch` capability it was given.
+    fetchCapability: hostFetch ? deferFetchCapability(hostFetch, schedulePlatformAdapterStart) : hostFetch,
     importModule: options.importModule,
     fallback: ordinaryLoader,
     nativeGa4Transport: () => {
@@ -351,6 +419,7 @@ export function bootIntegrationLifecycle(
       return createNativeGa4SandboxTransport(
         createBrowserNativeGa4SandboxHost(document, MessageChannel),
         resolveNativeGa4SandboxUrl(win.location.href),
+        schedulePlatformAdapterStart,
       );
     },
   });

package/packages/public-runtime/src/integration/native-ga4-sandbox.ts

@@ -92,15 +92,34 @@ export function createBrowserNativeGa4SandboxHost(
   };
 }
 
+/**
+ * Starts (or cancels) the deferred mount of the sandbox iframe. Defaults to
+ * running `start` synchronously, so a caller that does not care about paint
+ * timing (every existing test, and any future non-browser host) gets the
+ * original immediate-mount behavior unchanged.
+ */
+export type NativeGa4SandboxScheduler = (start: () => void) => { cancel(): void };
+
+const IMMEDIATE_SCHEDULER: NativeGa4SandboxScheduler = (start) => {
+  start();
+  return { cancel() {} };
+};
+
 /**
  * Mount one hidden same-site, cross-origin iframe and transfer exactly one MessagePort
  * after load. gtag suppresses collection in an opaque third-party frame, so the receiver
  * needs a real same-site origin. The exact origin, iframe window, and one-shot transfer
  * are the authority boundary. No general parent `message` listener is installed.
+ *
+ * The frame is not created or appended until `schedule` fires (default: immediately,
+ * i.e. unchanged from before) — that append is what starts gtag.js loading, so gating
+ * it behind a paint-aware scheduler (see `post-paint.ts`) keeps it off the LCP path.
+ * `configure`/`send` calls before the frame mounts queue exactly as they always have.
  */
 export function createNativeGa4SandboxTransport(
   host: NativeGa4SandboxHost,
   sandboxUrl: string,
+  schedule: NativeGa4SandboxScheduler = IMMEDIATE_SCHEDULER,
 ): NativeGa4SandboxTransport {
   const sandboxOrigin = new URL(sandboxUrl, host.parentOrigin).origin;
   if (!host.parentOrigin || sandboxOrigin === host.parentOrigin) {
@@ -110,15 +129,8 @@ export function createNativeGa4SandboxTransport(
   if (sandboxOrigin !== expectedSandboxOrigin) {
     throw new Error("ga4_sandbox_origin_not_same_site");
   }
-  const frame = host.createFrame();
-  frame.setAttribute("sandbox", "allow-scripts allow-same-origin");
-  frame.setAttribute("referrerpolicy", "no-referrer");
-  frame.setAttribute("aria-hidden", "true");
-  frame.setAttribute("tabindex", "-1");
-  frame.setAttribute("title", "Analytics transport");
-  frame.hidden = true;
-  frame.src = sandboxUrl;
 
+  let frame: NativeGa4SandboxFrame | null = null;
   let port: NativeGa4MessagePort | null = null;
   let disposed = false;
   let unavailable = false;
@@ -129,34 +141,49 @@ export function createNativeGa4SandboxTransport(
     unavailable = true;
     queue = [];
     host.clearTimer(timer);
-    frame.remove();
+    frame?.remove();
   };
 
-  frame.addEventListener("load", () => {
-    if (disposed || port) return;
-    const target = frame.contentWindow;
-    if (!target) return reject();
-    const channel = host.createChannel();
-    port = channel.port1;
-    try {
-      target.postMessage(
-        Object.freeze({ protocol: NATIVE_GA4_SANDBOX_PROTOCOL, type: "bind", parentOrigin: host.parentOrigin }),
-        sandboxOrigin,
-        [channel.port2],
-      );
-    } catch {
-      port.close();
-      port = null;
-      return reject();
-    }
-    host.clearTimer(timer);
-    const pending = queue;
-    queue = [];
-    for (const message of pending) port.postMessage(Object.freeze(message));
-  }, { once: true });
-  frame.addEventListener("error", reject, { once: true });
-  timer = host.setTimer(reject, 5_000);
-  host.appendFrame(frame);
+  const mount = (): void => {
+    if (disposed || unavailable || frame) return;
+    const mounted = host.createFrame();
+    frame = mounted;
+    mounted.setAttribute("sandbox", "allow-scripts allow-same-origin");
+    mounted.setAttribute("referrerpolicy", "no-referrer");
+    mounted.setAttribute("aria-hidden", "true");
+    mounted.setAttribute("tabindex", "-1");
+    mounted.setAttribute("title", "Analytics transport");
+    mounted.hidden = true;
+    mounted.src = sandboxUrl;
+
+    mounted.addEventListener("load", () => {
+      if (disposed || port) return;
+      const target = mounted.contentWindow;
+      if (!target) return reject();
+      const channel = host.createChannel();
+      port = channel.port1;
+      try {
+        target.postMessage(
+          Object.freeze({ protocol: NATIVE_GA4_SANDBOX_PROTOCOL, type: "bind", parentOrigin: host.parentOrigin }),
+          sandboxOrigin,
+          [channel.port2],
+        );
+      } catch {
+        port.close();
+        port = null;
+        return reject();
+      }
+      host.clearTimer(timer);
+      const pending = queue;
+      queue = [];
+      for (const message of pending) port.postMessage(Object.freeze(message));
+    }, { once: true });
+    mounted.addEventListener("error", reject, { once: true });
+    timer = host.setTimer(reject, 5_000);
+    host.appendFrame(mounted);
+  };
+
+  const scheduled = schedule(mount);
 
   const post = (message: NativeGa4SandboxPortMessage): void => {
     if (disposed || unavailable) throw new Error("ga4_sandbox_unavailable");
@@ -174,6 +201,7 @@ export function createNativeGa4SandboxTransport(
     },
     dispose() {
       if (disposed) return;
+      scheduled.cancel();
       if (port) {
         post({ schemaVersion: 1, type: "dispose" });
         port.close();
@@ -183,7 +211,7 @@ export function createNativeGa4SandboxTransport(
       port = null;
       disposed = true;
       host.clearTimer(timer);
-      frame.remove();
+      frame?.remove();
     },
   };
 }

package/packages/public-runtime/src/integration/post-paint.ts

@@ -0,0 +1,95 @@
+/**
+ * Paint-aware scheduling for non-essential platform work (ext-kernel-05 follow-on).
+ *
+ * Nothing in the lifecycle boot chain waited for a real paint before starting
+ * heavy adapter transports (GA4's isolated-origin iframe, Amplitude's HTTP
+ * collection), so Lighthouse's simulated dependency graph charged their bytes
+ * and main-thread time straight to LCP. This scheduler defers a callback until
+ * AFTER the document has painted and the main thread is otherwise idle:
+ *
+ *   - if the document has already finished loading, schedule on idle immediately;
+ *   - otherwise wait for `load`, then schedule on idle;
+ *   - "idle" is `requestIdleCallback` with a bounded timeout, falling back to a
+ *     macrotask (`setTimeout(0)`) where `requestIdleCallback` does not exist.
+ *
+ * Cancellable at every stage (before `load`, and while idle-queued), so a
+ * document torn down before the deferred work starts never runs it.
+ */
+
+/** The narrow slice of `window` this scheduler depends on — structural, edge-safe. */
+export interface PostPaintWindow {
+  document?: { readyState?: string };
+  addEventListener(type: "load", listener: () => void, options?: { once?: boolean }): void;
+  removeEventListener?(type: "load", listener: () => void): void;
+  requestIdleCallback?(callback: (deadline: unknown) => void, options?: { timeout: number }): number;
+  cancelIdleCallback?(handle: number): void;
+  setTimeout(callback: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+export interface PostPaintScheduleOptions {
+  /** Bound on how long `requestIdleCallback` may wait before firing anyway. */
+  idleTimeoutMs?: number;
+}
+
+export interface PostPaintHandle {
+  /** Idempotent. Prevents the callback from running if it has not run yet. */
+  cancel(): void;
+}
+
+/** Default bound so a busy main thread cannot indefinitely starve deferred work. */
+export const DEFAULT_POST_PAINT_IDLE_TIMEOUT_MS = 4_000;
+
+/**
+ * Schedule `callback` to run after first paint and idle. Never runs synchronously,
+ * even when the document is already `complete` — always at least one idle/macrotask
+ * turn later — so a caller can rely on "nothing runs before this returns".
+ */
+export function schedulePostPaint(
+  win: PostPaintWindow,
+  callback: () => void,
+  options: PostPaintScheduleOptions = {},
+): PostPaintHandle {
+  let cancelled = false;
+  let ran = false;
+  let idleHandle: number | undefined;
+  let timeoutHandle: unknown;
+  let loadListener: (() => void) | undefined;
+
+  const runIdle = (): void => {
+    if (cancelled) return;
+    if (typeof win.requestIdleCallback === "function") {
+      idleHandle = win.requestIdleCallback(
+        () => {
+          if (cancelled || ran) return;
+          ran = true;
+          callback();
+        },
+        { timeout: options.idleTimeoutMs ?? DEFAULT_POST_PAINT_IDLE_TIMEOUT_MS },
+      );
+    } else {
+      timeoutHandle = win.setTimeout(() => {
+        if (cancelled || ran) return;
+        ran = true;
+        callback();
+      }, 0);
+    }
+  };
+
+  if (win.document?.readyState === "complete") {
+    runIdle();
+  } else {
+    loadListener = runIdle;
+    win.addEventListener("load", loadListener, { once: true });
+  }
+
+  return {
+    cancel() {
+      if (cancelled) return;
+      cancelled = true;
+      if (loadListener) win.removeEventListener?.("load", loadListener);
+      if (idleHandle !== undefined) win.cancelIdleCallback?.(idleHandle);
+      if (timeoutHandle !== undefined) win.clearTimeout(timeoutHandle);
+    },
+  };
+}