@tokenoftrust/storefront-runner 2.2.9 → 2.2.10

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

@@ -322,7 +322,7 @@ a.article-card__tag:hover { text-decoration: underline; }
 .footer-brand .brand .b-prime,
 .footer-brand .brand .b-vapor,
 .footer-brand .brand .b-club { color: var(--color-primary-contrast); }
-.footer-col h4 { color: var(--color-primary-contrast); font-size: .82rem; letter-spacing: .1em; text-transform: uppercase; margin-bottom: 14px; }
+.footer-col .footer-col-title { color: var(--color-primary-contrast); font-size: .82rem; font-weight: bold; letter-spacing: .1em; text-transform: uppercase; margin: 0 0 14px; }
 .footer-col ul { display: flex; flex-direction: column; gap: 9px; }
 .footer-col a { color: color-mix(in srgb, var(--color-primary-contrast) 78%, transparent); font-size: .92rem; }
 .footer-col a:hover { color: var(--color-primary-contrast); text-decoration: underline; }

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

@@ -480,7 +480,7 @@ function renderFooter(footer: ChromeFooter): string {
         .join("");
       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>`;
+        : `      <div class="footer-col">\n        <p class="footer-col-title">${esc(c.title)}</p>\n        <ul>${links}</ul>\n      </div>`;
     })
     .join("\n");
   const trust = footer.trustMarks?.length

package/apps/storefront/src/pages/style-guide/[tenant]/chrome/[theme].astro

@@ -212,9 +212,9 @@ const componentVarsInline = Object.entries(componentVars)
                 </div>
                 <div class="pay-badges"><span>Visa</span><span>Mastercard</span><span>Amex</span><span>PayPal</span></div>
               </div>
-              <div class="footer-col"><h4>Shop</h4><ul><li><a href="#">Disposables</a></li><li><a href="#">E-Liquid</a></li><li><a href="#">Devices</a></li></ul></div>
-              <div class="footer-col"><h4>Support</h4><ul><li><a href="#">Contact</a></li><li><a href="#">Shipping</a></li><li><a href="#">Returns</a></li></ul></div>
-              <div class="footer-col"><h4>Company</h4><ul><li><a href="#">About</a></li><li><a href="#">Blog</a></li></ul></div>
+              <div class="footer-col"><p class="footer-col-title">Shop</p><ul><li><a href="#">Disposables</a></li><li><a href="#">E-Liquid</a></li><li><a href="#">Devices</a></li></ul></div>
+              <div class="footer-col"><p class="footer-col-title">Support</p><ul><li><a href="#">Contact</a></li><li><a href="#">Shipping</a></li><li><a href="#">Returns</a></li></ul></div>
+              <div class="footer-col"><p class="footer-col-title">Company</p><ul><li><a href="#">About</a></li><li><a href="#">Blog</a></li></ul></div>
             </div>
             <div class="trust-marks"><span>🔒 Secure checkout</span><span>✓ Age-verified</span><span>★ 4.9 / 5</span></div>
             <div class="footer-warning"><strong>WARNING:</strong><p>This product contains nicotine. Nicotine is an addictive chemical.</p></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.9",
+  "version": "2.2.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/ga4-sandbox-schedule.ts

@@ -0,0 +1,131 @@
+/**
+ * When the GA4 sandbox iframe may mount.
+ *
+ * The frame is same-process: once it loads, gtag.js runs on the page main
+ * thread. Mounting it on the first idle turn after `load` puts those long
+ * tasks inside the window Lighthouse scores as Total Blocking Time. This
+ * scheduler waits for the first of:
+ *
+ *   - a real pointer or key input (`pointerdown` / `keydown`, capture), or
+ *   - `load`, then a fixed delay long enough to outlast that quiet window.
+ *
+ * The delay is a minimum. Input before `load` still mounts immediately.
+ * The callback never runs synchronously on the call. Cancel is idempotent
+ * and drops both the listeners and the timer. Commands sent before the
+ * frame exists stay queued by the transport, not by this scheduler.
+ */
+
+/** How long after `load` the sandbox waits when nobody has interacted. */
+export const GA4_SANDBOX_POST_LOAD_DELAY_MS = 5_000;
+
+/** The narrow slice of `window` this scheduler depends on. */
+export interface Ga4SandboxScheduleWindow {
+  document?: {
+    readyState?: string;
+    addEventListener?(
+      type: string,
+      listener: (event: unknown) => void,
+      options?: { capture?: boolean },
+    ): void;
+    removeEventListener?(
+      type: string,
+      listener: (event: unknown) => void,
+      options?: { capture?: boolean },
+    ): void;
+  };
+  addEventListener(type: "load", listener: () => void, options?: { once?: boolean }): void;
+  removeEventListener?(type: "load", listener: () => void): void;
+  setTimeout(callback: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+export interface Ga4SandboxScheduleOptions {
+  /** Minimum wait after `load` before the sandbox mounts without input. */
+  postLoadDelayMs?: number;
+}
+
+export interface Ga4SandboxScheduleHandle {
+  /** Idempotent. Prevents the callback from running if it has not run yet. */
+  cancel(): void;
+}
+
+const INPUT_EVENTS = ["pointerdown", "keydown"] as const;
+const INPUT_CAPTURE = { capture: true } as const;
+
+/**
+ * Schedule `callback` for the first input, or for `postLoadDelayMs` after
+ * `load`, whichever comes first. Never runs on the call itself.
+ */
+export function scheduleGa4Sandbox(
+  win: Ga4SandboxScheduleWindow,
+  callback: () => void,
+  options: Ga4SandboxScheduleOptions = {},
+): Ga4SandboxScheduleHandle {
+  const delay = options.postLoadDelayMs ?? GA4_SANDBOX_POST_LOAD_DELAY_MS;
+  let cancelled = false;
+  let ran = false;
+  let timeoutHandle: unknown;
+  let loadListener: (() => void) | undefined;
+  const inputTarget = win.document;
+  const addInput = inputTarget?.addEventListener;
+  const removeInput = inputTarget?.removeEventListener;
+
+  const detachInput = (): void => {
+    if (typeof removeInput !== "function") return;
+    for (const type of INPUT_EVENTS) removeInput.call(inputTarget, type, onInput, INPUT_CAPTURE);
+  };
+
+  const finish = (): void => {
+    if (cancelled || ran) return;
+    ran = true;
+    detachInput();
+    if (loadListener) {
+      win.removeEventListener?.("load", loadListener);
+      loadListener = undefined;
+    }
+    if (timeoutHandle !== undefined) {
+      win.clearTimeout(timeoutHandle);
+      timeoutHandle = undefined;
+    }
+    callback();
+  };
+
+  function onInput(): void {
+    finish();
+  }
+
+  if (typeof addInput === "function") {
+    for (const type of INPUT_EVENTS) addInput.call(inputTarget, type, onInput, INPUT_CAPTURE);
+  }
+
+  const armDelay = (): void => {
+    if (cancelled || ran) return;
+    timeoutHandle = win.setTimeout(() => {
+      timeoutHandle = undefined;
+      finish();
+    }, delay);
+  };
+
+  if (win.document?.readyState === "complete") {
+    armDelay();
+  } else {
+    loadListener = () => {
+      loadListener = undefined;
+      armDelay();
+    };
+    win.addEventListener("load", loadListener, { once: true });
+  }
+
+  return {
+    cancel() {
+      if (cancelled || ran) {
+        cancelled = true;
+        return;
+      }
+      cancelled = true;
+      detachInput();
+      if (loadListener) win.removeEventListener?.("load", loadListener);
+      if (timeoutHandle !== undefined) win.clearTimeout(timeoutHandle);
+    },
+  };
+}

package/packages/public-runtime/src/integration/lifecycle-boot.ts

@@ -49,6 +49,7 @@ import {
   type NativeGa4SandboxScheduler,
 } from "./native-ga4-sandbox.js";
 import { schedulePostPaint, type PostPaintWindow } from "./post-paint.js";
+import { scheduleGa4Sandbox, type Ga4SandboxScheduleWindow } from "./ga4-sandbox-schedule.js";
 import { ManagedAnalyticsEventBrokerBridge } from "./managed-analytics-bridge.js";
 import { minimizePageAttribution, type ManagedPageViewInput } from "./managed-analytics.js";
 import { managedAnalyticsOpaqueRevision } from "./managed-analytics-value-safety.js";
@@ -124,14 +125,19 @@ export interface BootLifecycleOptions {
   /** 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.
+   * Defers the Amplitude HTTP capability until after first paint and idle —
+   * see `post-paint.ts`. Defaults to that scheduler over `window` (synchronous
+   * off the browser). Injectable so a test can hold the flush.
    */
   schedulePlatformAdapterStart?: NativeGa4SandboxScheduler;
+  /**
+   * Mounts the GA4 sandbox iframe on the first pointer or key input, or a
+   * fixed delay after `load`, whichever comes first — see
+   * `ga4-sandbox-schedule.ts`. Defaults to that scheduler over `window`
+   * (synchronous off the browser). Commands sent before the frame exists stay
+   * queued in the transport. Injectable so a test can hold the mount.
+   */
+  scheduleGa4Sandbox?: NativeGa4SandboxScheduler;
 }
 
 /**
@@ -328,7 +334,8 @@ function defaultConsentGate(
 /**
  * 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.
+ * import this module without a DOM) — never a hang. Amplitude uses this. The GA4
+ * sandbox does not.
  */
 function defaultPlatformAdapterScheduler(start: () => void): { cancel(): void } {
   if (typeof window === "undefined") {
@@ -338,12 +345,24 @@ function defaultPlatformAdapterScheduler(start: () => void): { cancel(): void }
   return schedulePostPaint(window as unknown as PostPaintWindow, start);
 }
 
+/**
+ * The default GA4 sandbox scheduler. Off the browser it starts synchronously so
+ * SSR and DOM-free tests do not hang. In the browser it never starts on this
+ * turn: first input, or the post-load delay, whichever comes first.
+ */
+function defaultGa4SandboxScheduler(start: () => void): { cancel(): void } {
+  if (typeof window === "undefined") {
+    start();
+    return { cancel() {} };
+  }
+  return scheduleGa4Sandbox(window as unknown as Ga4SandboxScheduleWindow, 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).
+ * all issued together once `schedule` fires. This keeps the Amplitude adapter's
+ * HTTP collection off the pre-paint critical path. `native-amplitude.ts` stays
+ * paint-timing-agnostic — it just calls the `fetch` capability it was given.
  */
 function deferFetchCapability(
   fetchCapability: typeof fetch,
@@ -395,6 +414,7 @@ export function bootIntegrationLifecycle(
     (typeof win.fetch === "function" ? win.fetch.bind(win) : undefined);
   const schedulePlatformAdapterStart =
     options.schedulePlatformAdapterStart ?? defaultPlatformAdapterScheduler;
+  const scheduleGa4SandboxStart = options.scheduleGa4Sandbox ?? defaultGa4SandboxScheduler;
   const fallbackLoader = options.importModule
     ? makeSameOriginEntryLoader(options.importModule)
     : sameOriginEntryLoader;
@@ -419,7 +439,7 @@ export function bootIntegrationLifecycle(
       return createNativeGa4SandboxTransport(
         createBrowserNativeGa4SandboxHost(document, MessageChannel),
         resolveNativeGa4SandboxUrl(win.location.href),
-        schedulePlatformAdapterStart,
+        scheduleGa4SandboxStart,
       );
     },
   });

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

@@ -111,10 +111,11 @@ const IMMEDIATE_SCHEDULER: NativeGa4SandboxScheduler = (start) => {
  * 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.
+ * The frame is not created or appended until `schedule` fires. Boot passes the
+ * GA4 sandbox schedule (`ga4-sandbox-schedule.ts`); a caller that omits
+ * `schedule` still mounts immediately. That append is what starts gtag.js.
+ * `configure`/`send` before the frame mounts stay queued and flush in order
+ * when the frame loads.
  */
 export function createNativeGa4SandboxTransport(
   host: NativeGa4SandboxHost,

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

@@ -1,19 +1,18 @@
 /**
- * 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:
+ * Paint-aware scheduling for platform adapter work that starts once the
+ * document has painted and the main thread is idle (Amplitude's HTTP
+ * collection). The GA4 sandbox uses `ga4-sandbox-schedule.ts` instead: its
+ * iframe shares the page process, so an idle start still runs gtag.js inside
+ * the Total Blocking Time window.
  *
  *   - 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 idle timeout is a maximum, not a minimum. 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. */