@tokenoftrust/storefront-runner 2.2.8 → 2.2.10

package/apps/storefront/public/js/dashboard-team.js

@@ -17,12 +17,95 @@
   if (!membersBody) return;
   const tenant = membersBody.dataset.tenant;
 
+  // One verdict from tot-mcp's access_explain, rendered the same everywhere: the Team row,
+  // the invite result and the resend result. `verified` is `true` or the failure object.
+  function verdictParts(verdict) {
+    if (verdict === true || (verdict && verdict.state === "verified")) {
+      return { cls: "ok", label: "Active", why: "" };
+    }
+    const v = verdict || { state: "unavailable", reason: "not verified" };
+    if (v.state === "awaiting-acceptance") {
+      return v.inviteStatus === "accepted"
+        ? { cls: "pend", label: "Accepted — not signed in", why: v.reason + " " + v.fix }
+        : { cls: "pend", label: "Pending", why: "Waiting for the developer to accept and sign in." };
+    }
+    if (v.state === "broken") {
+      return { cls: "bad", label: "Not resolving", why: v.reason + " Fix: " + v.fix };
+    }
+    return { cls: "pend", label: "Unverified", why: "Couldn't check: " + (v.reason || "unknown") + "." };
+  }
+
+  function renderAccessCell(td, verdict) {
+    const parts = verdictParts(verdict);
+    td.replaceChildren();
+    const label = document.createElement("span");
+    label.className = "access " + parts.cls;
+    label.textContent = parts.label;
+    td.appendChild(label);
+    if (parts.why) {
+      const why = document.createElement("span");
+      why.className = "access-why";
+      why.textContent = parts.why;
+      td.appendChild(why);
+    }
+  }
+
+  async function checkAccess(email, td, btn) {
+    if (btn) btn.disabled = true;
+    td.replaceChildren();
+    td.textContent = "Checking…";
+    td.className = "muted";
+    try {
+      const q = "tenant=" + encodeURIComponent(tenant) + "&email=" + encodeURIComponent(email);
+      const res = await fetch("/api/grants/team-access?" + q, { headers: { accept: "application/json" } });
+      const body = await res.json().catch(() => ({}));
+      td.className = "";
+      renderAccessCell(td, res.ok ? body.access
+        : { state: "unavailable", reason: body.error || ("HTTP " + res.status) });
+    } catch (e) {
+      td.className = "";
+      renderAccessCell(td, { state: "unavailable", reason: e && e.message ? e.message : String(e) });
+    } finally {
+      if (btn) btn.disabled = false;
+    }
+  }
+
+  // The invite / resend result: green only when tot-mcp proved the grant resolves; a
+  // broken grant is red with its step and fix and never reads as "invited".
+  function showVerdict(email, verdict, sentLine) {
+    const parts = verdictParts(verdict);
+    const wrap = document.createElement("div");
+    const tag = document.createElement("span");
+    tag.className = "advice";
+    tag.textContent = "tot-mcp advice";
+    wrap.appendChild(tag);
+    const line = document.createElement("p");
+    line.style.margin = ".2rem 0 0";
+    if (parts.cls === "ok") {
+      line.textContent = sentLine + " Access verified — " +
+        ((verdict && verdict.capability) || "preview-access") + " resolves for " + email + ".";
+      wrap.appendChild(line);
+      showMsg("ok", wrap);
+      return;
+    }
+    if (parts.cls === "pend") {
+      line.textContent = sentLine + " " + parts.why;
+      wrap.appendChild(line);
+      showMsg("ok", wrap);
+      return;
+    }
+    line.textContent = "Access for " + email + " will not work yet (step: " + verdict.failedStep +
+      "). " + verdict.reason + " Fix: " + verdict.fix + " No invite email was sent.";
+    wrap.appendChild(line);
+    showMsg("err", wrap);
+  }
+
   function renderMembers(members) {
     membersBody.replaceChildren();
     if (!members || !members.length) {
       const tr = document.createElement("tr");
       const td = document.createElement("td");
-      td.colSpan = 3; td.className = "muted";
+      td.colSpan = 4; td.className = "muted";
       td.textContent = "No developers invited yet.";
       tr.appendChild(td); membersBody.appendChild(tr);
       return;
@@ -33,8 +116,17 @@
       dev.textContent = m.developer;
       const roles = document.createElement("td");
       roles.textContent = (m.roles || []).join(", ") || "developer";
+      const access = document.createElement("td");
       const act = document.createElement("td");
       act.className = "act";
+      const checkBtn = document.createElement("button");
+      checkBtn.type = "button";
+      checkBtn.className = "rowbtn";
+      checkBtn.textContent = "Check access";
+      checkBtn.title = "Check whether " + m.developer + "'s access resolves right now";
+      checkBtn.style.marginRight = ".4rem";
+      checkBtn.addEventListener("click", () => checkAccess(m.developer, access, checkBtn));
+      act.appendChild(checkBtn);
       const btn = document.createElement("button");
       btn.type = "button";
       btn.className = "rowbtn";
@@ -52,8 +144,9 @@
         revokeBtn.addEventListener("click", () => revoke(m.developer, m.inviteId, revokeBtn));
         act.appendChild(revokeBtn);
       }
-      tr.appendChild(dev); tr.appendChild(roles); tr.appendChild(act);
+      tr.appendChild(dev); tr.appendChild(roles); tr.appendChild(access); tr.appendChild(act);
       membersBody.appendChild(tr);
+      checkAccess(m.developer, access, checkBtn);
     }
   }
 
@@ -92,7 +185,9 @@
       });
       const body = await res.json().catch(() => ({}));
       if (res.ok) {
-        showMsg("ok", "Re-sent the sign-in email to " + (body.developer || email) + ".");
+        const who = body.developer || email;
+        showVerdict(who, body.verified, "Re-sent the sign-in email to " + who + ".");
+        loadMembers();
       } else {
         showMsg("err", body.error || ("Couldn't resend (HTTP " + res.status + ")."));
       }
@@ -107,7 +202,7 @@
     membersBody.replaceChildren();
     const tr = document.createElement("tr");
     const td = document.createElement("td");
-    td.colSpan = 2; td.className = "muted";
+    td.colSpan = 4; td.className = "muted";
     td.textContent = msg;
     tr.appendChild(td); membersBody.appendChild(tr);
   }
@@ -206,7 +301,9 @@
       const body = await res.json().catch(() => ({}));
       if (res.ok) {
         const already = body.changed === false;
-        showMsg("ok", (already ? "Already a developer — re-sent the sign-in email to " : "Invited ") + (body.developer || email) + ".");
+        const who = body.developer || email;
+        showVerdict(who, body.verified,
+          (already ? "Already a developer — re-sent the sign-in email to " : "Invited ") + who + ".");
         $("email").value = "";
         if (noteEl) noteEl.value = "";
         loadMembers();

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/lib/shared/accessExplain.ts

@@ -0,0 +1,156 @@
+/**
+ * Developer-access verification — asks tot-mcp whether an invited developer's access to a
+ * store actually resolves, walking the same chain their sign-in and checkout use, and
+ * classifies the answer for the granter.
+ *
+ *   POST {origin(MCP_APP_BINDING_URL)}/internal/dev-access/explain
+ *     header  x-mcp-service-secret: <MCP_SERVICE_SHARED_SECRET>
+ *     body    { person: <email>, tenant: <appDomain> }
+ *     → 200 { verified, failedStep?, reason?, fix?, capability?, expiry?, app?, steps[] }
+ * Contract source of truth: tot-mcp src/modules/mcp/access/access-explain.ts.
+ *
+ * A failure in a step that can only pass once the invitee accepts and signs in (identity,
+ * the store context, a fresh session, checkout) reads as "awaiting acceptance" while the
+ * invite is pending. Any other failure — the repo is not provisioned, the invite record
+ * and sign-in disagree — is broken now, and the granter is told before they leave.
+ *
+ * Nothing here is ever reported as verified unless tot-mcp said so: an unconfigured seam,
+ * a non-200 or a timeout is `unavailable`, which the UI shows as unverified.
+ */
+import { readEnv } from "@/lib/env";
+
+const EXPLAIN_TIMEOUT_MS = 8000;
+
+export interface ExplainStep {
+  step: string;
+  status: "pass" | "fail" | "skip" | "info";
+  dependsOnAcceptance: boolean;
+  detail: string;
+}
+
+/** tot-mcp's explain result, as sent. */
+export interface AccessExplanation {
+  verified: boolean;
+  tenant: string;
+  failedStep?: string;
+  reason?: string;
+  fix?: string;
+  capability?: string;
+  expiry?: "none";
+  app?: string;
+  steps: ExplainStep[];
+}
+
+/** The granter-facing verdict. */
+export type AccessVerification =
+  | { state: "verified"; capability: string; expiry: "none"; advice: "tot-mcp" }
+  | {
+    state: "awaiting-acceptance";
+    inviteStatus: "pending" | "accepted";
+    failedStep: string;
+    reason: string;
+    fix: string;
+    advice: "tot-mcp";
+  }
+  | { state: "broken"; failedStep: string; reason: string; fix: string; advice: "tot-mcp" }
+  | { state: "unavailable"; reason: string; advice: "tot-mcp" };
+
+/** POST transport seam (injectable for tests). */
+export interface ExplainTransport {
+  post(
+    url: string,
+    headers: Record<string, string>,
+    body: unknown,
+  ): Promise<{ status: number; json(): Promise<unknown> }>;
+}
+
+export class FetchExplainTransport implements ExplainTransport {
+  async post(url: string, headers: Record<string, string>, body: unknown) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), EXPLAIN_TIMEOUT_MS);
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...headers },
+        body: JSON.stringify(body),
+        signal: ctrl.signal,
+      });
+      return { status: res.status, json: () => res.json() };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/** Classify an explanation against what the storefront knows about the invite. */
+export function classifyExplanation(
+  explanation: AccessExplanation,
+  inviteStatus: "pending" | "accepted",
+): AccessVerification {
+  if (explanation.verified) {
+    return {
+      state: "verified",
+      capability: explanation.capability ?? "preview-access",
+      expiry: "none",
+      advice: "tot-mcp",
+    };
+  }
+  const failed = explanation.steps.find((s) => s.step === explanation.failedStep);
+  const verdict = {
+    failedStep: explanation.failedStep ?? "unknown",
+    reason: explanation.reason ?? "Access does not resolve.",
+    fix: explanation.fix ?? "Run access_explain for this developer and store.",
+    advice: "tot-mcp" as const,
+  };
+  // Accepting on the storefront does not enroll the tot identity — the developer's first
+  // tot sign-in does — so an unenrolled identity is still waiting on them, accepted or not.
+  if (
+    explanation.failedStep === "identity"
+    || (inviteStatus === "pending" && failed?.dependsOnAcceptance)
+  ) {
+    return { state: "awaiting-acceptance", inviteStatus, ...verdict };
+  }
+  return { state: "broken", ...verdict };
+}
+
+/** Ask tot-mcp to explain `email`'s access to `tenant`. Never throws. */
+export async function explainDeveloperAccess(
+  tenant: string,
+  email: string,
+  inviteStatus: "pending" | "accepted",
+  deps: { transport?: ExplainTransport } = {},
+): Promise<AccessVerification> {
+  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
+  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
+  if (!bindingUrl || !secret) {
+    return { state: "unavailable", reason: "verification is not configured here", advice: "tot-mcp" };
+  }
+  let endpoint: string;
+  try {
+    endpoint = `${new URL(bindingUrl).origin}/internal/dev-access/explain`;
+  } catch {
+    return { state: "unavailable", reason: "the tot-mcp address is malformed", advice: "tot-mcp" };
+  }
+  const transport = deps.transport ?? new FetchExplainTransport();
+  try {
+    const res = await transport.post(
+      endpoint,
+      { "x-mcp-service-secret": secret },
+      { person: email.trim().toLowerCase(), tenant: tenant.trim().toLowerCase() },
+    );
+    if (res.status < 200 || res.status >= 300) {
+      return { state: "unavailable", reason: `tot-mcp answered ${res.status}`, advice: "tot-mcp" };
+    }
+    const explanation = (await res.json()) as AccessExplanation;
+    if (typeof explanation?.verified !== "boolean" || !Array.isArray(explanation.steps)) {
+      return { state: "unavailable", reason: "tot-mcp sent an unreadable answer", advice: "tot-mcp" };
+    }
+    return classifyExplanation(explanation, inviteStatus);
+  } catch (cause) {
+    return {
+      state: "unavailable",
+      reason: "tot-mcp did not answer: " + (cause instanceof Error ? cause.message : String(cause)),
+      advice: "tot-mcp",
+    };
+  }
+}

package/apps/storefront/src/lib/shared/developerInvites.ts

@@ -55,6 +55,7 @@
 import { readEnv } from "@/lib/env";
 import { diagEmail } from "@/lib/diag/redact";
 import { checkStorePreviewReady, type PreflightDecision } from "@/lib/shared/invitePreflight";
+import { explainDeveloperAccess, type AccessVerification } from "@/lib/shared/accessExplain";
 
 /**
  * The header carrying the storefront-signed staff BROKER ASSERTION to tot20
@@ -244,6 +245,8 @@ export interface DeveloperInviteSummary {
   tenant: string;
   developer: string;
   roles: string[];
+  /** tot20's invite state; an entry predating the field is an active member (`accepted`). */
+  status: "pending" | "accepted";
 }
 
 /** Result of listing a tenant's developer invites (typed failure, fail-closed). */
@@ -729,6 +732,7 @@ export function normalizeInvitesListResponse(
         roles: Array.isArray(r.roles)
           ? r.roles.filter((x): x is string => typeof x === "string")
           : [],
+        status: r.status === "pending" ? "pending" : "accepted",
       };
     });
     return { ok: true, tenant, invites };
@@ -945,6 +949,7 @@ export class MockDeveloperInviteClient implements DeveloperInviteClient {
           tenant: t,
           developer: email,
           roles: ["developer"],
+          status: "pending" as const,
         };
       });
     return { ok: true, tenant: t, invites };
@@ -1035,7 +1040,7 @@ export type AppBindingResult =
  *
  * WIRED (confirmed contract):
  *   POST `${MCP_APP_BINDING_URL}`  — the keyless subject-capability writer,
- *     e.g. https://mcp.qa.tokenoftrust.com/api/internal/dev-access/subject-capability
+ *     e.g. https://mcp.qa.tokenoftrust.com/internal/dev-access/subject-capability
  *   Auth: header `x-mcp-service-secret: <MCP_SERVICE_SHARED_SECRET>` (compared
  *     constant-time to the MCP's shared secret) — NOT an Authorization bearer.
  *   Body: { subject:<email>, tenant, capability:'preview-access', app:'storefront' }
@@ -1191,6 +1196,8 @@ export interface InviteDeveloperOutcome {
    * (a failed invite has nothing to bind); undefined otherwise.
    */
   appBinding?: AppBindingResult;
+  /** Whether the grant resolves for the invitee (tot-mcp access_explain); success only. */
+  verification?: AccessVerification;
 }
 
 /** Injectable collaborators (tests); both default to the env-configured impls. */
@@ -1207,6 +1214,12 @@ export interface InviteDeveloperDeps {
    * any inconclusive answer fails open (see invitePreflight).
    */
   preflight?: (tenant: string) => Promise<PreflightDecision>;
+  /** The post-write verification. Defaults to {@link explainDeveloperAccess}. */
+  explain?: (
+    tenant: string,
+    email: string,
+    inviteStatus: "pending" | "accepted",
+  ) => Promise<AccessVerification>;
 }
 
 /**
@@ -1291,5 +1304,17 @@ export async function inviteDeveloperToTenant(
     tenant: invite.tenant,
     capability,
   });
-  return { invite, appBinding };
+
+  // Prove the grant resolves before the granter leaves: tot-mcp walks the invitee's real
+  // sign-in + checkout chain. The invite's own state decides whether an acceptance-bound
+  // failure is "awaiting acceptance" or broken — a re-invite of an accepted developer must
+  // resolve now.
+  const listed = await client.listInvites(invite.tenant, input.brokerAssertion);
+  const inviteStatus = listed.ok
+    ? listed.invites.find((i) => i.developer.toLowerCase() === invite.developer.toLowerCase())
+      ?.status ?? "pending"
+    : "pending";
+  const explain = deps.explain ?? explainDeveloperAccess;
+  const verification = await explain(invite.tenant, invite.developer, inviteStatus);
+  return { invite, appBinding, verification };
 }

package/apps/storefront/src/lib/shared/viewerGrant.ts

@@ -3,7 +3,8 @@
  * VIEWER's REAL, owner-revocable ship capability over a tenant, LIVE from the MCP
  * subject-capability store. This is the near-side read of the Step-1 tot-mcp seam:
  *
- *   GET `${origin}/api/internal/dev-access/subject-capability?subject=<email>&tenant=<appDomain>&app=storefront`
+ *   GET `${origin}/internal/dev-access/subject-capability?subject=<email>&tenant=<appDomain>&app=storefront`
+ *   (outside tot-mcp's session-guarded `/api` surface, which answers this caller 401)
  *   Auth: header `x-mcp-service-secret: <MCP_SERVICE_SHARED_SECRET>` (NOT a bearer)
  *   → 200 { capability: "ship-on-behalf" | "preview-access" }
  *        · an ABSENT / REVOKED grant answers `preview-access`
@@ -58,7 +59,7 @@ export interface ViewerShipGrantDeps {
 }
 
 /** The Step-1 subject-capability reader path (mounted OUTSIDE the session guard). */
-const SUBJECT_CAPABILITY_PATH = "/api/internal/dev-access/subject-capability";
+const SUBJECT_CAPABILITY_PATH = "/internal/dev-access/subject-capability";
 
 /** The viewer's blog-contribute capability — a NEW, blog-scoped projection kept OUT
  * of the forge `Capability` union (which stays exactly two rungs). `ship-on-behalf`

package/apps/storefront/src/pages/api/auth/magic-exchange.ts

@@ -26,6 +26,7 @@ import {
 import { createSession, DEFAULT_SESSION_TTL_SECONDS } from "@/lib/auth/session";
 import { normalizeEmailHint } from "@/lib/privacy/emailHint";
 import { acceptDeveloperInvite } from "@/lib/shared/developerInvites";
+import { explainDeveloperAccess } from "@/lib/shared/accessExplain";
 
 export const prerender = false;
 
@@ -158,5 +159,20 @@ export async function POST(context: APIContext): Promise<Response> {
     });
   }
 
+  // The granter left at Send invite; re-prove the grant now that the invitee accepted, so a
+  // break shows on the granter's Team page (team-access re-runs the same check) and in the
+  // logs, not only in the invitee's terminal. Best-effort: never blocks the sign-in.
+  try {
+    const verification = await explainDeveloperAccess(tenant, derived.email, "accepted");
+    if (verification.state === "broken") {
+      console.warn("auth/magic-exchange: accepted invite does not resolve", {
+        tenant,
+        failedStep: verification.failedStep,
+      });
+    }
+  } catch {
+    /* verification must never break the sign-in */
+  }
+
   return context.redirect(next, 303);
 }

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.8",
+  "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. */