@tokenoftrust/storefront-runner 2.0.23 → 2.0.25

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

@@ -24,6 +24,13 @@
  * the renderer-inlined default-deny consent snapshot and holds a non-essential entry
  * back until its declared purposes are eligible. With an environment-only plan there
  * are no integrations, so the runtime boots inert and ready.
+ *
+ * The binding also constructs this document's managed-analytics bridge over the same
+ * commerce broker the adapters subscribe to, and hands the lifecycle the bootstrap
+ * page-view input built from the host document (path + minimized attribution). An
+ * adapter's subscription is receive-only, so this is what an active analytics
+ * integration actually receives — without it every adapter loads, subscribes, and then
+ * waits on a broker nothing emits into.
  */
 import { IntegrationLifecycle, type IntegrationModuleLoader } from "./lifecycle-runtime.js";
 import type { LifecycleObserver } from "./lifecycle-runtime.js";
@@ -36,6 +43,8 @@ import type { NavigationCompletedEvent, NavigationKind } from "./events.js";
 import { CommerceEventBroker } from "./commerce-broker.js";
 import { validateBrowserEnvironment, BROWSER_ENVIRONMENT_GLOBAL, type BrowserEnvironment } from "./environment.js";
 import { makePlatformAdapterRuntimeLoader } from "./platform-adapter-runtime.js";
+import { ManagedAnalyticsEventBrokerBridge } from "./managed-analytics-bridge.js";
+import { minimizePageAttribution, type ManagedPageViewInput } from "./managed-analytics.js";
 
 /** The window property holding the single per-document lifecycle (idempotent boot guard). */
 export const LIFECYCLE_SINGLETON_GLOBAL = "__TOT_INTEGRATION_LIFECYCLE__";
@@ -54,6 +63,12 @@ export interface LifecycleWindow {
   location: { pathname: string; search: string; hash: string; href: string };
   addEventListener(type: string, listener: (event: unknown) => void): void;
   fetch?: typeof fetch;
+  /**
+   * Read ONLY for the referrer the managed page view minimizes to a bare origin. The
+   * analytics data allowlist accepts no other document state — no title, no DOM, no
+   * globals — so this is deliberately the narrowest slice that supports attribution.
+   */
+  document?: { referrer?: string };
   [key: string]: unknown;
 }
 
@@ -83,6 +98,14 @@ export interface BootLifecycleOptions {
    * consent-filtered exactly like the platform path. Injectable for tests.
    */
   commerceBroker?: CommerceEventBroker;
+  /**
+   * The managed-analytics bridge that emits this document's governed page view into the
+   * commerce broker; defaults to one constructed over the resolved broker. Injectable so
+   * a test can assert the emission without a DOM.
+   */
+  managedAnalyticsBridge?: ManagedAnalyticsEventBrokerBridge;
+  /** Epoch-millisecond source for the page view's correlation expiry; defaults to the wall clock. */
+  now?: () => number;
   /** Host-owned fetch capability for reviewed first-party platform adapters. */
   fetchCapability?: typeof fetch;
   /** Entry import capability; injectable for tests and non-browser hosts. */
@@ -178,6 +201,47 @@ function makeDocumentCommerceBroker(
   });
 }
 
+/**
+ * How long the bootstrap page view's attribution thread stays valid. It matches the
+ * correlation TTL the cart-handoff seam uses, so one visit's page view and any later
+ * commerce event it is threaded to expire together.
+ */
+const PAGE_VIEW_CORRELATION_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * Build this document's bootstrap page-view input from the host document.
+ *
+ * The data allowlist is the whole surface: the route PATH (never the query string, where
+ * preview/candidate wrappers and tokens live) plus attribution already minimized to a
+ * referrer ORIGIN and the five standard UTM tokens. Title, DOM state, and browser globals
+ * are not accepted by this seam and are not read.
+ *
+ * `logicalId` and the correlation id are derived from the plan revision rather than
+ * randomized: one traditional document is counted exactly once, each document load builds
+ * its own broker, and the broker's dedupe key is per-document — so a stable, opaque,
+ * non-identifying value is both sufficient and deterministically testable.
+ */
+function documentPageView(
+  win: LifecycleWindow,
+  descriptor: IntegrationBootDescriptor,
+  now: () => number,
+): ManagedPageViewInput {
+  const attribution = minimizePageAttribution({
+    referrerUrl: win.document?.referrer ?? null,
+    routeUrl: win.location.href,
+  });
+  const id = `pageview-${descriptor.planRevision}`;
+  return {
+    logicalId: id,
+    path: win.location.pathname,
+    correlation: {
+      id,
+      expiresAt: new Date(now() + PAGE_VIEW_CORRELATION_TTL_MS).toISOString(),
+    },
+    ...(attribution ? { attribution } : {}),
+  };
+}
+
 function readDescriptor(win: LifecycleWindow): IntegrationBootDescriptor | null {
   const descriptor = win[INTEGRATION_PLAN_GLOBAL];
   if (!descriptor || typeof descriptor !== "object") return null;
@@ -259,6 +323,9 @@ export function bootIntegrationLifecycle(
   const commerceBroker =
     options.commerceBroker ?? makeDocumentCommerceBroker(descriptor, getConsentSnapshot);
 
+  // The managed-analytics bridge over the SAME broker the adapters subscribe to — the
+  // only seam that emits this document's governed page view. The lifecycle owns when it
+  // fires (after every adapter has subscribed, and re-attempted on a consent grant).
   const lifecycle = new IntegrationLifecycle({
     descriptor,
     loadModule,
@@ -268,6 +335,11 @@ export function bootIntegrationLifecycle(
     environment,
     getConsentSnapshot,
     commerceBroker,
+    managedAnalytics: {
+      bridge: options.managedAnalyticsBridge ??
+        new ManagedAnalyticsEventBrokerBridge({ broker: commerceBroker }),
+      pageView: () => documentPageView(win, descriptor, options.now ?? Date.now),
+    },
   });
   win[LIFECYCLE_SINGLETON_GLOBAL] = lifecycle;
 

package/packages/public-runtime/src/integration/lifecycle-host-asset.d.mts

@@ -0,0 +1,3 @@
+/** Types for the dual-consumer (`.ts` engine + `.mjs` build plugin) host-asset path. */
+export declare const LIFECYCLE_HOST_ASSET_PATH: string;
+export declare const LIFECYCLE_HOST_ASSET_URL: string;

package/packages/public-runtime/src/integration/lifecycle-host-asset.mjs

@@ -0,0 +1,17 @@
+/**
+ * The stable public URL of the document.deferred lifecycle host bundle.
+ *
+ * It lives in a `.mjs` module because it has TWO consumers that cannot share a `.ts`
+ * one: the render engine (`render-phases.ts`) that emits the `<script src>`, and the
+ * build plugin (`apps/storefront/build-plugins/lifecycle-host-asset.mjs`) that produces
+ * the file at that exact path. One source of truth, so the tag and the artifact cannot
+ * disagree — a mismatch would leave every static tenant page with plan data and no host,
+ * which fails silently in exactly the way it is not allowed to.
+ *
+ * The path is version-pinned (`/v1/`) like a platform adapter entry, so a future host
+ * with a different boot contract ships alongside rather than replacing this one.
+ */
+export const LIFECYCLE_HOST_ASSET_PATH = "platform/lifecycle/v1/boot.mjs";
+
+/** The root-absolute, same-origin URL the served markup references. */
+export const LIFECYCLE_HOST_ASSET_URL = `/${LIFECYCLE_HOST_ASSET_PATH}`;

package/packages/public-runtime/src/integration/lifecycle-host-entry.ts

@@ -0,0 +1,16 @@
+/**
+ * The document.deferred lifecycle HOST — the side-effecting entry both document mounts
+ * load, bundled to the stable same-origin URL in `./lifecycle-host-asset.mjs`.
+ *
+ * It is deliberately the whole module: importing it BOOTS. That is what makes it usable
+ * from a plain `<script type="module" src>` tag, which in turn is what lets the raw
+ * marketing mount host the lifecycle at all — it serves a tenant's own document verbatim
+ * and never passes through a bundler, so it cannot host a module-graph import the way
+ * `Layout.astro` can.
+ *
+ * NOT exported from the package barrel: `index.ts` re-exports its modules, and a
+ * self-invoking module there would boot the lifecycle on any server-side import.
+ */
+import { bootIntegrationLifecycleFromDocument } from "./lifecycle-boot.js";
+
+bootIntegrationLifecycleFromDocument();

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

@@ -25,6 +25,8 @@ import type { CommerceEventBroker } from "./commerce-broker.js";
 import type { IntegrationBootDescriptor, BootDescriptorIntegration } from "./render-phases.js";
 import type { NavigationCompletedEvent, NavigationKind } from "./events.js";
 import { validateNavigationCompletedEvent } from "./events.js";
+import type { ManagedAnalyticsEventBrokerBridge } from "./managed-analytics-bridge.js";
+import type { ManagedPageViewInput } from "./managed-analytics.js";
 import { COMMERCE_EVENT_STOREFRONT_SCHEMA_VERSION, ENVIRONMENT_SCHEMA_VERSION } from "./version.js";
 import type { BrowserEnvironment } from "./environment.js";
 import type { ConsentSnapshot } from "./consent-broker.js";
@@ -125,6 +127,26 @@ export interface IntegrationLifecycleOptions {
    * shape a DOM-free unit test uses when it wires no broker.
    */
   commerceBroker?: CommerceEventBroker;
+  /**
+   * The document's managed-analytics bridge and the bootstrap page-view input for THIS
+   * document. Wiring it is what makes an active analytics adapter actually RECEIVE
+   * something: the bridge is the only seam that emits `storefront.page.viewed.v2` into
+   * {@link commerceBroker}, and an adapter's subscription is receive-only, so with no
+   * bridge every adapter initializes, subscribes, and then waits on a broker nothing
+   * ever emits into.
+   *
+   * The runtime owns the ORDERING, because the broker delivers to the subscribers
+   * registered at emit time and never replays: the bootstrap page view is emitted at the
+   * END of {@link init}, once every eligible integration has initialized (and so
+   * subscribed). `pageView` is a factory rather than a value because it is built from the
+   * host's DOM (path, referrer, UTM), which this DOM-free core must not read itself.
+   *
+   * Absent ⇒ no page view (the shape a DOM-free unit test uses when it wires no bridge).
+   */
+  managedAnalytics?: {
+    bridge: ManagedAnalyticsEventBrokerBridge;
+    pageView: () => ManagedPageViewInput;
+  };
   /** ISO-8601 timestamp source for the navigation event; defaults to wall clock. */
   now?: () => string;
   /** Opaque per-event id source; defaults to a monotonic, non-secret local counter. */
@@ -208,6 +230,34 @@ export class IntegrationLifecycle {
     }
     // A dispose that raced in during an await leaves us terminal; otherwise we are live.
     if (this.state === "initializing") this.state = "initialized";
+    // Last, so every adapter that just subscribed is registered when this emits: the
+    // broker has no replay, so a page view emitted before their `init` reaches nobody.
+    if (this.state === "initialized") this.emitBootstrapPageView();
+  }
+
+  /**
+   * Emit this document's bootstrap-owned page view through the managed-analytics bridge
+   * (`storefront.page.viewed.v2`), exactly once.
+   *
+   * Consent is a PRECONDITION here rather than something the bridge is left to discover:
+   * the bridge counts a document once and is then terminal for `initialize`, so calling
+   * it while `analytics` is ineligible would burn the document's only page view on a
+   * default-deny snapshot and lose it permanently. Instead the attempt is held and
+   * retried from {@link update}, so a visitor who grants analytics after load still gets
+   * counted for the document they are on.
+   *
+   * Analytics never breaks the page: a throwing bridge is swallowed exactly like a
+   * throwing integration.
+   */
+  private emitBootstrapPageView(): void {
+    const managed = this.opts.managedAnalytics;
+    if (!managed || managed.bridge.isInitialized || managed.bridge.isDisposed) return;
+    if (this.opts.commerceBroker?.isConsentEligible("analytics") === false) return;
+    try {
+      managed.bridge.initialize(managed.pageView());
+    } catch {
+      // A page view is never worth a broken document.
+    }
   }
 
   /** Whether the consent gate (when injected) permits loading this integration now. */
@@ -319,6 +369,10 @@ export class IntegrationLifecycle {
         this.observe({ stage: "update", integration, ok: false, reason, error: messageOf(error) });
       }
     }
+    // A consent grant is the case that matters: it both loads a previously-gated adapter
+    // (above) and makes the held-back bootstrap page view emittable, so the document the
+    // visitor consented ON is still counted rather than only its successors.
+    this.emitBootstrapPageView();
   }
 
   /**
@@ -340,6 +394,11 @@ export class IntegrationLifecycle {
     }
     this.active.length = 0;
     this.deferred = []; // gated integrations never loaded — nothing to dispose.
+    try {
+      this.opts.managedAnalytics?.bridge.dispose();
+    } catch {
+      // Teardown is best-effort; a throwing bridge cannot leave the document undisposed.
+    }
     this.state = "disposed";
   }
 

package/packages/public-runtime/src/integration/managed-analytics-api-v1.schemas.ts

@@ -28,6 +28,22 @@ const PUBLIC_IDENTIFIER = { ...SAFE_CONFIG_STRING, minLength: 1, maxLength: 128,
 const FINDING_CODE = { ...SAFE_CONFIG_STRING, pattern: "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$" } as const;
 const REDACTED_PATH = { ...SAFE_CONFIG_STRING, pattern: "^(?:\\$|[A-Za-z][A-Za-z0-9]*)(?:\\.[A-Za-z][A-Za-z0-9]*|\\[[0-9]+\\])*$" } as const;
 
+/**
+ * A per-stage destination map — the one non-primitive configuration value, and closed:
+ * only the declared stages, only safe strings. `local` is absent because the local dev
+ * loop ships no integrations, so a value there could never fire.
+ */
+const stageDestinationMap = {
+  type: "object",
+  additionalProperties: false,
+  minProperties: 1,
+  properties: {
+    candidate: SAFE_NON_EMPTY_STRING,
+    staged: SAFE_NON_EMPTY_STRING,
+    live: SAFE_NON_EMPTY_STRING,
+  },
+} as const;
+
 const primitiveConfiguration = {
   type: "object",
   propertyNames: SAFE_CONFIG_KEY,
@@ -36,6 +52,7 @@ const primitiveConfiguration = {
       SAFE_CONFIG_STRING,
       { type: "boolean" },
       { type: "integer" },
+      stageDestinationMap,
     ],
   },
 } as const;
@@ -64,7 +81,7 @@ export const ADAPTER_DEFINITION_V1_JSON_SCHEMA = {
           key: SAFE_CONFIG_KEY,
           label: SAFE_NON_EMPTY_STRING,
           description: SAFE_NON_EMPTY_STRING,
-          kind: { type: "string", enum: ["string", "boolean", "integer"] },
+          kind: { type: "string", enum: ["string", "boolean", "integer", "stageMap"] },
           required: { type: "boolean" },
         },
       },

package/packages/public-runtime/src/integration/managed-analytics-api-v1.ts

@@ -28,9 +28,30 @@ export type IntegrationRevisionStatus = (typeof INTEGRATION_REVISION_STATUSES)[n
 export const ADAPTER_AVAILABILITY = ["available", "deprecated"] as const;
 export type AdapterAvailability = (typeof ADAPTER_AVAILABILITY)[number];
 
-export const ADAPTER_CONFIG_VALUE_KINDS = ["string", "boolean", "integer"] as const;
+export const ADAPTER_CONFIG_VALUE_KINDS = ["string", "boolean", "integer", "stageMap"] as const;
 export type AdapterConfigValueKind = (typeof ADAPTER_CONFIG_VALUE_KINDS)[number];
-export type AdapterConfigValue = string | boolean | number;
+
+/**
+ * The stages a merchant may address a destination at. `local` is deliberately absent:
+ * the local dev loop ships no integrations and grants only essential consent, so a value
+ * there could never fire and offering one would imply otherwise.
+ */
+export const ADAPTER_CONFIG_STAGES = ["candidate", "staged", "live"] as const;
+export type AdapterConfigStage = (typeof ADAPTER_CONFIG_STAGES)[number];
+
+/**
+ * A per-stage destination map — the one non-primitive configuration value.
+ *
+ * Its shape is CLOSED: keys come from {@link ADAPTER_CONFIG_STAGES} and every value is a
+ * plain string held to the same executable-content and PII checks as any other
+ * configuration value. So the property that makes this contract safe is intact — a
+ * merchant still cannot supply markup, selectors, secrets, or arbitrary structure — while
+ * a destination can differ per stage, which is what makes the devbook's own rule (a
+ * non-live stage must not reuse the live property) satisfiable through the console at all.
+ */
+export type AdapterConfigStageMap = Partial<Record<AdapterConfigStage, string>>;
+
+export type AdapterConfigValue = string | boolean | number | AdapterConfigStageMap;
 /** Public identifiers are opaque handles: never emails, names, or user-provided labels. */
 export type OpaquePublicId = string;
 /** Stable, redacted machine code; migration findings never contain source text or PII. */
@@ -535,12 +556,36 @@ export function validateManagedAnalyticsSafePayload(input: unknown): ContractRes
   return v.ok ? prepared : { ok: false, violations: v.items };
 }
 
+/** A plain object, i.e. a candidate per-stage map rather than a primitive. */
+function isStageMap(value: unknown): boolean {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function validateConfig(input: unknown, v: Violations, path: string): void {
   const obj = object(input, v, path);
   if (!obj) return;
   for (const [key, value] of Object.entries(obj)) {
     if (!/^[a-z][a-zA-Z0-9]{0,63}$/.test(key)) v.add(pathAt(path, key), "format", "Configuration keys must be lower camel-case identifiers.");
-    if (!(typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isInteger(value)))) v.add(pathAt(path, key), "type", "Configuration values must be strings, booleans, or integers.");
+    // A per-stage map is the one permitted non-primitive, and it is CLOSED: stage keys
+    // only, string values only, each held to the same executable-content check below. So
+    // no arbitrary structure or depth can enter configuration through it.
+    if (isStageMap(value)) {
+      const entries = Object.entries(value as Record<string, unknown>);
+      if (entries.length === 0) v.add(pathAt(path, key), "empty", "A per-stage map must name at least one stage.");
+      for (const [stage, id] of entries) {
+        const stagePath = pathAt(pathAt(path, key), stage);
+        if (!(ADAPTER_CONFIG_STAGES as readonly string[]).includes(stage)) {
+          v.add(stagePath, "unknown_enum", `Stage must be one of: ${ADAPTER_CONFIG_STAGES.join(", ")}.`);
+        }
+        if (typeof id !== "string") {
+          v.add(stagePath, "type", "A per-stage value must be a string.");
+        } else if (EXECUTABLE_OR_INSTRUCTION_VALUE.test(id)) {
+          v.add(stagePath, "executable_value", "Configuration cannot contain markup, JavaScript, templates, selectors, or storage instructions.");
+        }
+      }
+      continue;
+    }
+    if (!(typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isInteger(value)))) v.add(pathAt(path, key), "type", "Configuration values must be strings, booleans, integers, or a per-stage map of strings.");
     if (typeof value === "string" && EXECUTABLE_OR_INSTRUCTION_VALUE.test(value)) v.add(pathAt(path, key), "executable_value", "Configuration cannot contain markup, JavaScript, templates, selectors, or storage instructions.");
   }
   const safe = validateManagedAnalyticsSafePayload(obj);

package/packages/public-runtime/src/integration/render-phases.ts

@@ -9,7 +9,9 @@
  * `bodyStart` (body.start fallback), and `bodyDeferred` (document.deferred global
  * entry). Both document mounts — `Layout.astro` and `rawHtmlResponse()` — splice
  * the SAME strings, so their per-phase markup is identical by construction (golden
- * parity is a property of calling one function, not of keeping two in sync).
+ * parity is a property of calling one function, not of keeping two in sync). The
+ * `document.deferred` region includes the lifecycle HOST tag, so "the plan is
+ * published" and "the plan runs" cannot come apart between mounts.
  *
  * Nonce discipline (ADR 0018): the engine stamps the {@link INTEGRATION_NONCE_PLACEHOLDER}
  * sentinel, never a live nonce, onto its inline `<script>`s. The renderer replaces
@@ -37,6 +39,10 @@ import {
   serializeForInlineScript,
 } from "./environment.js";
 import { defaultConsentSnapshot, type ConsentSnapshot } from "./consent-broker.js";
+import { LIFECYCLE_HOST_ASSET_URL } from "./lifecycle-host-asset.mjs";
+
+/** Re-exported so consumers and tests read the host URL from the engine that emits it. */
+export { LIFECYCLE_HOST_ASSET_PATH, LIFECYCLE_HOST_ASSET_URL } from "./lifecycle-host-asset.mjs";
 
 /**
  * The sentinel a renderer stamps in place of a live CSP nonce. It is a valid
@@ -163,11 +169,33 @@ export function renderIntegrationPhases(
     phaseBoundary("body.start") + `<div data-tot-integration-root hidden></div>`;
 
   const bodyDeferred =
-    phaseBoundary("document.deferred") + `<div data-tot-integration-deferred hidden></div>`;
+    phaseBoundary("document.deferred") +
+    `<div data-tot-integration-deferred hidden></div>` +
+    lifecycleHostScript();
 
   return { head, bodyStart, bodyDeferred };
 }
 
+/**
+ * The document.deferred lifecycle HOST tag — what actually boots the plan.
+ *
+ * It belongs to the ENGINE, not to a mount. The engine's promise is that both mounts
+ * emit identical per-phase markup because they call one function; a host installed by
+ * only one of them breaks that promise in the way that matters most, because the mount
+ * that lacks it still publishes `__TOT_INTEGRATION_PLAN__`. A page then advertises a
+ * complete, enabled integration plan and runs none of it — indistinguishable, from every
+ * surface that reports configuration, from a working install.
+ *
+ * Carries no nonce by design: it is a same-origin `src` reference, admitted by
+ * `script-src 'self'` (see `csp.ts`), so it needs neither a nonce nor a content hash —
+ * the same treatment the static `/js/*.js` behaviors get. That also keeps it correct
+ * under the raw mount, which stamps nonces onto the tenant's own inline tags BEFORE
+ * splicing engine bytes.
+ */
+function lifecycleHostScript(): string {
+  return `<script type="module" src="${LIFECYCLE_HOST_ASSET_URL}"></script>`;
+}
+
 /**
  * Replace every {@link INTEGRATION_NONCE_PLACEHOLDER} in `text` (an HTML body or a
  * CSP header value) with one fresh per-response `nonce`. Idempotent on text with no