@tokenoftrust/storefront-runner 2.1.9 → 2.1.11

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/components/Seo.astro

@@ -3,7 +3,7 @@
  * <Seo> — per-page title/meta, Open Graph, Twitter card, canonical, JSON-LD.
  * (brief §8). Tenant-aware: OG image + site name come from the resolved tenant.
  */
-import { articleSeoMetaTags, type ArticleMeta } from "@/lib/seo/meta.js";
+import { articleSeoMetaTags, resolveOgImage, type ArticleMeta } from "@/lib/seo/meta.js";
 import { withXDefault, type Alternate } from "@/lib/seo/alternates.js";
 import { safeJsonScriptContent } from "@/lib/jsonScript";
 
@@ -64,23 +64,23 @@ const {
 const { tenant, canonicalBase } = Astro.locals;
 const canonical =
   canonicalOverride ?? new URL(path, canonicalBase + "/").toString();
+// Don't double-append the brand: merchant SEO titles (title_tag) often already
+// end with the store name.
+const fullTitle = title.includes(tenant.displayName)
+  ? title
+  : `${title} — ${tenant.displayName}`;
+const image = resolveOgImage({
+  ogImage, themeOgImage: tenant.theme_tokens?.brand?.ogImage ?? null, canonicalBase,
+});
 const articleMeta = articleSeoMetaTags({
   ogType,
   article,
-  imageAlt,
-  imageWidth,
-  imageHeight,
+  imageAlt: image ? imageAlt : undefined,
+  imageWidth: image ? imageWidth : undefined,
+  imageHeight: image ? imageHeight : undefined,
   twitterSite,
   twitterCreator,
 });
-// Don't double-append the brand: merchant SEO titles (title_tag) often already
-// end with the store name.
-const fullTitle = title.includes(tenant.displayName)
-  ? title
-  : `${title} — ${tenant.displayName}`;
-const image = ogImage
-  ? new URL(ogImage, canonicalBase + "/").toString()
-  : new URL(tenant.theme_tokens?.brand?.ogImage ?? "/brand/northwind-og.svg", canonicalBase + "/").toString();
 
 const graphs = jsonLd ? (Array.isArray(jsonLd) ? jsonLd : [jsonLd]) : [];
 const alternateLinks = withXDefault(alternates);
@@ -108,12 +108,12 @@ const alternateLinks = withXDefault(alternates);
 <meta property="og:title" content={fullTitle} />
 {description && <meta property="og:description" content={description} />}
 <meta property="og:url" content={canonical} />
-<meta property="og:image" content={image} />
+{image && <meta property="og:image" content={image} />}
 
 <meta name="twitter:card" content="summary_large_image" />
 <meta name="twitter:title" content={fullTitle} />
 {description && <meta name="twitter:description" content={description} />}
-<meta name="twitter:image" content={image} />
+{image && <meta name="twitter:image" content={image} />}
 
 {
   articleMeta.map((t) =>

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/apps/storefront/src/lib/seo/meta.ts

@@ -34,6 +34,20 @@ export interface ArticleSeoInput {
   twitterCreator?: string;
 }
 
+/**
+ * The og:image/twitter:image URL, or `null` when neither the page nor the
+ * tenant's theme declares one. Never falls back to a platform placeholder --
+ * a shared image path that 404s live for every tenant that hasn't set one.
+ */
+export function resolveOgImage(input: {
+  ogImage?: string;
+  themeOgImage?: string | null;
+  canonicalBase: string;
+}): string | null {
+  const declared = input.ogImage ?? input.themeOgImage ?? null;
+  return declared ? new URL(declared, input.canonicalBase + "/").toString() : null;
+}
+
 /**
  * The article-only OG/Twitter meta tags. Returns `[]` for any non-article page
  * so `article:*`, `og:image:alt`, and `twitter:site`/`creator` can never leak

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.1.9",
+  "version": "2.1.11",
   "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/image-dependencies.ts

@@ -43,6 +43,17 @@ export interface PlatformHostedImageConfig {
 
 export interface ImageDependencyScanOptions {
   tenantId: string;
+  /**
+   * The tenant's own public origins (e.g. `https://tokenoftrust.com`), from declared tenant
+   * config -- never derived from the tenant id. An absolute URL on one of these origins is
+   * classified by its path exactly as a root-relative locator would be (tenant-hosted,
+   * platform-hosted, capture-required/local, or cross-tenant), instead of being treated as a
+   * third-party reference. Required (empty is valid) so every caller states its origins
+   * explicitly; six call sites compute finding identities and must agree, or a capture and a
+   * later publish scanning with different origins would diverge and the publish gate would
+   * refuse on an identity mismatch it can't explain.
+   */
+  tenantOrigins: readonly string[];
   platformHosted?: PlatformHostedImageConfig;
 }
 
@@ -164,6 +175,8 @@ const URL_TAB_OR_NEWLINE_RE = /[\t\n\r]/g;
 const ASCII_WHITESPACE_RE = /[\t\n\f\r ]/;
 const ASCII_WHITESPACE_RUN_RE = /[\t\n\f\r ]+/;
 const MAX_VISIBLE_FINDINGS = 100;
+/** Shared artifact-scan cap for both the publish gate and the preview capture endpoint. */
+export const MAX_IMAGE_SCAN_ARTIFACTS = 5000;
 const MAX_PERCENT_DECODE_PASSES = 8;
 const MAX_CATALOG_WALK_ITEMS = 1_000_000;
 const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
@@ -447,12 +460,25 @@ function adoptCssReferences(refs: ExtractedReference[], cssRefs: readonly Extrac
   for (const ref of cssRefs) refs.push(afterBase ? { ...ref, afterBase: true } : ref);
 }
 
+const NO_DECLARED_CUSTOM_PROPERTIES: ReadonlySet<string> = new Set();
+
 /**
  * CSS extraction uses a JavaScript parser because this module is imported by
  * Worker routes. A native CSS binding cannot be evaluated by workerd, which
  * would prevent every route sharing its bundle chunk from loading.
+ *
+ * `declaredCustomProperties` names every `--foo` declared anywhere in the
+ * scanned artifact set (see `collectDeclaredCustomProperties`). The scanner
+ * already scans `url(...)` wherever it appears, including inside a custom
+ * property's own declaration, so a `var(--foo)` reference is only deferred
+ * (unresolvable statically) when `--foo` is not declared anywhere — or when
+ * its fallback argument itself contains no scannable image source.
  */
-function cssReferences(css: string, kind: "stylesheet" | "declaration"): ExtractedReference[] {
+function cssReferences(
+  css: string,
+  kind: "stylesheet" | "declaration",
+  declaredCustomProperties: ReadonlySet<string> = NO_DECLARED_CUSTOM_PROPERTIES,
+): ExtractedReference[] {
   if (!css) return [];
   const refs: ExtractedReference[] = [];
   const parseValue = (value: string): CssScanNode | null => {
@@ -467,6 +493,28 @@ function cssReferences(css: string, kind: "stylesheet" | "declaration"): Extract
     if (imageValue) rememberDeferred(refs, name);
   };
 
+  // `var(--foo)`'s own declaration site already captured any image inside it (scanValue's
+  // Url case is unconditional); a top-level `var()` reference only needs its own deferred
+  // marker when `--foo` is not declared anywhere AND its fallback argument (present only
+  // when the parse produced [Identifier, Operator, Raw]) has no scannable image source
+  // either. Scoped to scanValue's top-level property-value position only: a var() nested
+  // inside image()/image-set() keeps the existing conservative "always defer, never resolve
+  // its fallback" behaviour — those constructs are rare/synthetic and untouched by this rule.
+  const resolveVar = (node: CssScanNode, imageValue: boolean): void => {
+    if (!imageValue) return;
+    // cssChildren() is css-tree's own iterable List, not a real array (no index access,
+    // no .length) — spread it once to get an indexable copy for the fixed [name, ",", fallback] shape.
+    const children = [...cssChildren(node)];
+    const propertyName = children[0]?.type === "Identifier" ? children[0].name ?? "" : "";
+    if (propertyName && declaredCustomProperties.has(propertyName)) return;
+    const rawFallback = children[2];
+    if (rawFallback?.type === "Raw") {
+      const parsedFallback = parseValue(rawFallback.value ?? "");
+      if (parsedFallback && firstImageSource(cssChildren(parsedFallback))) return;
+    }
+    rememberDeferred(refs, "var");
+  };
+
   // image() resolves one source. A discarded non-image argument does not consume it.
   const scanNestedDeferred = (node: CssScanNode): void => {
     if (node.type !== "Function") {
@@ -481,7 +529,7 @@ function cssReferences(css: string, kind: "stylesheet" | "declaration"): Extract
     for (const child of cssChildren(node)) scanNestedDeferred(child);
   };
 
-  const firstImageSource = (nodes: CssScanNode[]): boolean => {
+  function firstImageSource(nodes: CssScanNode[]): boolean {
     let chosen = false;
     for (const node of nodes) {
       if (chosen) {
@@ -509,7 +557,7 @@ function cssReferences(css: string, kind: "stylesheet" | "declaration"): Extract
       if (firstImageSource(cssChildren(node))) chosen = true;
     }
     return chosen;
-  };
+  }
 
   const imageSetSources = (nodes: CssScanNode[]): void => {
     let option: CssScanNode[] = [];
@@ -541,6 +589,10 @@ function cssReferences(css: string, kind: "stylesheet" | "declaration"): Extract
         continue;
       }
       const name = (node.name ?? "").toLowerCase();
+      if (name === "var") {
+        resolveVar(node, imageValue);
+        continue;
+      }
       const deferred = deferredFunctionName(name);
       if (deferred) {
         noteDeferred(deferred, imageValue);
@@ -706,6 +758,7 @@ function collectHtmlElement(
   sourceContext: HtmlSourceContext,
   artifactPath: string,
   inheritedBase: ResolvedBase | null,
+  declaredCustomProperties: ReadonlySet<string>,
 ): void {
   const tag = element.tagName;
   const html = element.namespaceURI === HTML_NAMESPACE;
@@ -717,7 +770,7 @@ function collectHtmlElement(
   if (tag === "style") return;
   const styleValue = htmlAttribute(element, "style");
   const emitStyle = (): void => {
-    if (styleValue != null) adoptCssReferences(refs, cssReferences(styleValue, "declaration"), afterBase);
+    if (styleValue != null) adoptCssReferences(refs, cssReferences(styleValue, "declaration", declaredCustomProperties), afterBase);
   };
   if (!html) {
     if (element.namespaceURI === SVG_NAMESPACE && (tag === "image" || tag.toLowerCase() === "feimage")) {
@@ -732,7 +785,7 @@ function collectHtmlElement(
   if (tag === "iframe") {
     const srcdoc = htmlAttribute(element, "srcdoc");
     if (srcdoc != null && !isBlankLocator(srcdoc)) {
-      for (const nested of htmlReferences(srcdoc, artifactPath, inheritedBase)) {
+      for (const nested of htmlReferences(srcdoc, artifactPath, inheritedBase, declaredCustomProperties)) {
         refs.push({
           locator: nested.locator,
           surface: nested.surface,
@@ -800,7 +853,12 @@ function collectHtmlElement(
   emitStyle();
 }
 
-function htmlReferences(html: string, artifactPath: string, inherited: ResolvedBase | null = null): ExtractedReference[] {
+function htmlReferences(
+  html: string,
+  artifactPath: string,
+  inherited: ResolvedBase | null = null,
+  declaredCustomProperties: ReadonlySet<string> = NO_DECLARED_CUSTOM_PROPERTIES,
+): ExtractedReference[] {
   const refs: ExtractedReference[] = [];
   let baseHref: string | null = null;
   let sawBase = false;
@@ -815,7 +873,7 @@ function htmlReferences(html: string, artifactPath: string, inherited: ResolvedB
     const frame = stack.pop()!;
     const { node, inTemplate, sourceContext } = frame;
     if (isHtmlText(node)) {
-      if (frame.cssText) adoptCssReferences(refs, cssReferences(node.value, "stylesheet"), sawBase);
+      if (frame.cssText) adoptCssReferences(refs, cssReferences(node.value, "stylesheet", declaredCustomProperties), sawBase);
       continue;
     }
     if (node.nodeName === "#document" || node.nodeName === "#document-fragment") {
@@ -823,7 +881,7 @@ function htmlReferences(html: string, artifactPath: string, inherited: ResolvedB
       continue;
     }
     if (!isHtmlElement(node)) continue;
-    collectHtmlElement(node, refs, inTemplate, noteBase, sawBase, sourceContext, artifactPath, enclosingBase());
+    collectHtmlElement(node, refs, inTemplate, noteBase, sawBase, sourceContext, artifactPath, enclosingBase(), declaredCustomProperties);
     const childContext = childSourceContext(node.tagName, node.namespaceURI);
     if (node.tagName === "template" && node.namespaceURI === HTML_NAMESPACE && "content" in node) {
       pushHtmlChildren(stack, node.content.childNodes, true, false, childContext);
@@ -1134,15 +1192,23 @@ export function classifyImageDependency(
     tenantId: string;
     artifactPath: string;
     platformHosted?: PlatformHostedImageConfig;
+    tenantOrigins?: readonly string[];
   },
 ): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
-  return classifyImageDependencyWithPrepared(locator, context, preparePlatformHostedConfig(context.platformHosted));
+  return classifyImageDependencyWithPrepared(
+    locator, context, preparePlatformHostedConfig(context.platformHosted), prepareTenantOrigins(context.tenantOrigins ?? []),
+  );
+}
+
+function prepareTenantOrigins(tenantOrigins: readonly string[]): ReadonlySet<string> {
+  return new Set(tenantOrigins.map(normalizedOrigin).filter((origin): origin is string => origin != null));
 }
 
 function classifyParsedHttpUrl(
   absolute: URL,
-  context: { tenantId: string },
+  context: { tenantId: string; artifactPath: string },
   platformHosted: PreparedPlatformHostedImageConfig,
+  tenantOrigins: ReadonlySet<string>,
 ): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
   if (!absolute.hostname || absolute.username || absolute.password) {
     return { canonicalLocator: "invalid:", disposition: "security-error", reason: "malformed" };
@@ -1150,6 +1216,13 @@ function classifyParsedHttpUrl(
   if (absolutePathEscapes(absolute.pathname)) {
     return { canonicalLocator: "escape:", disposition: "security-error", reason: "tenant-escape" };
   }
+  if (tenantOrigins.has(absolute.origin) && !absolute.pathname.startsWith("//")) {
+    // The tenant's own origin: classify by path exactly as a root-relative locator would be,
+    // instead of the third-party fallback below. The pathname.startsWith("//") exclusion
+    // guards a URL like https://tenant.example//evil.example/x.png, whose pathname would
+    // otherwise re-parse as scheme-relative to a DIFFERENT origin on the recursive call.
+    return classifyImageDependencyWithPrepared(`${absolute.pathname}${absolute.search}`, context, platformHosted, tenantOrigins);
+  }
   absolute.hash = "";
   const canonical = absolute.toString();
   if (platformHosted.origins.has(absolute.origin) || platformHosted.references.has(stripQueryHash(canonical))) {
@@ -1166,6 +1239,7 @@ function classifyImageDependencyWithPrepared(
   locator: string,
   context: { tenantId: string; artifactPath: string },
   platformHosted: PreparedPlatformHostedImageConfig,
+  tenantOrigins: ReadonlySet<string>,
 ): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
   const raw = normalizeUrlInput(locator);
   if (!raw || CONTROL_RE.test(raw)) {
@@ -1184,14 +1258,14 @@ function classifyImageDependencyWithPrepared(
     } catch {
       return { canonicalLocator: "invalid:", disposition: "security-error", reason: "malformed" };
     }
-    return classifyParsedHttpUrl(absolute, context, platformHosted);
+    return classifyParsedHttpUrl(absolute, context, platformHosted, tenantOrigins);
   }
 
   if (/^[a-z][a-z0-9+.-]*:/i.test(raw)) {
     return { canonicalLocator: "unsafe:", disposition: "security-error", reason: "unsafe-scheme" };
   }
   const networkUrl = backslashNetworkUrl(raw, context.artifactPath);
-  if (networkUrl) return classifyParsedHttpUrl(networkUrl, context, platformHosted);
+  if (networkUrl) return classifyParsedHttpUrl(networkUrl, context, platformHosted, tenantOrigins);
   const pathOnly = stripQueryHash(raw);
   const structural = structuralPath(pathOnly);
   if (structural.startsWith("/") && hasDotDotSegment(pathOnly)) {
@@ -1279,6 +1353,79 @@ export function buildImageDependencyWarningBatch(
   };
 }
 
+function declaredCustomPropertyNames(css: string, kind: "stylesheet" | "declaration"): Set<string> {
+  const declared = new Set<string>();
+  const walk = (node: CssScanNode): void => {
+    if (node.type === "Declaration") {
+      const property = node.property ?? "";
+      if (property.startsWith("--")) declared.add(property);
+      return;
+    }
+    if (node.block) walk(node.block);
+    for (const child of cssChildren(node)) walk(child);
+  };
+  try {
+    const parsed = parse(css, {
+      context: kind === "declaration" ? "declarationList" : "stylesheet",
+      list: false,
+    }) as unknown as CssScanNode;
+    walk(parsed);
+  } catch {
+    // Invalid CSS contributes no declarations; the real scan fails open the same way.
+  }
+  return declared;
+}
+
+/** Every `style=""` attribute value (declaration context) and `<style>` text (stylesheet context). */
+function rawCssChunksInHtml(html: string): Array<{ css: string; kind: "stylesheet" | "declaration" }> {
+  const chunks: Array<{ css: string; kind: "stylesheet" | "declaration" }> = [];
+  const stack: HtmlNode[] = [parseFragment(html)];
+  while (stack.length > 0) {
+    const node = stack.pop()!;
+    if (isHtmlText(node)) continue;
+    if (node.nodeName === "#document" || node.nodeName === "#document-fragment") {
+      for (const child of node.childNodes) stack.push(child);
+      continue;
+    }
+    if (!isHtmlElement(node)) continue;
+    const styleValue = htmlAttribute(node, "style");
+    if (styleValue != null) chunks.push({ css: styleValue, kind: "declaration" });
+    if (node.tagName === "style") {
+      for (const child of node.childNodes) {
+        if (isHtmlText(child)) chunks.push({ css: child.value, kind: "stylesheet" });
+      }
+      continue;
+    }
+    if (node.tagName === "template" && node.namespaceURI === HTML_NAMESPACE && "content" in node) {
+      for (const child of node.content.childNodes) stack.push(child);
+      continue;
+    }
+    for (const child of node.childNodes) stack.push(child);
+  }
+  return chunks;
+}
+
+/**
+ * Pre-pass: every `--foo` declared anywhere in the artifact set (CSS files, `<style>` blocks,
+ * `style=""` attributes). `scanImageDependencies` threads this into every `var()` decision so a
+ * reference to a declared custom property is never deferred — its image, if any, was already
+ * captured at the declaration itself.
+ */
+function collectDeclaredCustomProperties(artifacts: readonly ImageDependencyArtifact[]): Set<string> {
+  const declared = new Set<string>();
+  for (const artifact of artifacts) {
+    const kind = inferKind(artifact);
+    if (kind === "css") {
+      for (const name of declaredCustomPropertyNames(artifact.content, "stylesheet")) declared.add(name);
+    } else if (kind === "html") {
+      for (const chunk of rawCssChunksInHtml(artifact.content)) {
+        for (const name of declaredCustomPropertyNames(chunk.css, chunk.kind)) declared.add(name);
+      }
+    }
+  }
+  return declared;
+}
+
 /** Scan a revision's already-read artifacts with no network or filesystem I/O. */
 export function scanImageDependencies(
   artifacts: readonly ImageDependencyArtifact[],
@@ -1286,12 +1433,14 @@ export function scanImageDependencies(
 ): ImageDependencyScan {
   const dependencies: ImageDependency[] = [];
   const platformHosted = preparePlatformHostedConfig(options.platformHosted);
+  const tenantOrigins = prepareTenantOrigins(options.tenantOrigins);
+  const declaredCustomProperties = collectDeclaredCustomProperties(artifacts);
   let occurrence = 0;
   for (const [artifactIndex, artifact] of artifacts.entries()) {
     const kind = inferKind(artifact);
     let refs: ExtractedReference[];
-    if (kind === "html") refs = htmlReferences(artifact.content, artifact.path);
-    else if (kind === "css") refs = cssReferences(artifact.content, "stylesheet");
+    if (kind === "html") refs = htmlReferences(artifact.content, artifact.path, null, declaredCustomProperties);
+    else if (kind === "css") refs = cssReferences(artifact.content, "stylesheet", declaredCustomProperties);
     else {
       const parsed = catalogReferences(artifact.content, artifact.path);
       if (parsed == null) {
@@ -1317,7 +1466,7 @@ export function scanImageDependencies(
       const classified = classifyImageDependencyWithPrepared(ref.classificationLocator ?? ref.locator, {
         tenantId: options.tenantId,
         artifactPath: artifact.path,
-      }, platformHosted);
+      }, platformHosted, tenantOrigins);
       dependencies.push({
         locator: ref.locator,
         artifactIndex,

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);
+    },
+  };
+}