@tokenoftrust/storefront-runner 2.0.28 → 2.0.30

package/apps/storefront/env.d.ts

@@ -10,6 +10,7 @@ import type {
   BrowserEnvironment,
   CompiledIntegrationCsp,
   EffectivePlan,
+  IntegrationDeclarationInput,
   ConsentSnapshot,
   ResolvedRouteTierV1,
   PublicationRoutePlanV1,
@@ -170,6 +171,13 @@ declare global {
        * wired; carries no secret and no nonce.
        */
       integrationPlan: EffectivePlan;
+      /**
+       * The exact declaration set used to resolve this request's integration
+       * plan. Exact candidate/staged renderers reuse it with their server-owned
+       * stage and immutable revision; public browse requests never receive
+       * request-time managed declarations.
+       */
+      integrationDeclarations: readonly IntegrationDeclarationInput[];
       /**
        * The tenant's actual initial consent snapshot — computed once by the
        * middleware from its saved {@link TenantConsentConfig} (ext-admin-03) via

package/apps/storefront/src/lib/auth/loginGate.ts

@@ -210,12 +210,14 @@ export function isStaticBundleUploadPath(pathname: string): boolean {
  *   /preview/change/<changeId>                the per-change review dashboard
  *   /<tenant>/preview/pr/<n>                  the friendly PR-number alias
  *   /<tenant>/preview/rev/<sha>/...           the immutable per-revision renderer
+ *   /<tenant>/preview/staged/<sha>/...        the immutable combined-release renderer
  */
 export function isCandidatePreviewPath(pathname: string): boolean {
   if (pathname.startsWith("/preview/render/")) return true;
   if (pathname === "/preview/change" || pathname.startsWith("/preview/change/")) return true;
   // /<tenant>/preview/pr and /<tenant>/preview/pr/<n> — the PR-number alias.
   if (/^\/[^/]+\/preview\/pr(?:\/|$)/.test(pathname)) return true;
+  if (/^\/[^/]+\/preview\/staged(?:\/|$)/.test(pathname)) return true;
   // /<tenant>/preview/rev/<sha> and /<tenant>/preview/rev/<sha>/<path...> — the
   // immutable per-revision alias.
   return /^\/[^/]+\/preview\/rev(?:\/|$)/.test(pathname);

package/apps/storefront/src/lib/integration/browserEnvironment.ts

@@ -12,12 +12,18 @@
  */
 import {
   resolveBrowserEnvironment,
-  resolveEnvironmentOnlyPlan,
   type BrowserEnvironment,
   type EffectivePlan,
+  type IntegrationDeclarationInput,
+  type IntegrationEnvironment,
   type IntegrationSiteSurface,
+  type ObligationTenant,
 } from "@tot/public-runtime";
 import { isAdminPath } from "@/lib/auth/loginGate";
+import {
+  resolveIntegrationRenderState,
+  type IntegrationRenderState,
+} from "@/lib/integration/renderIntegrationState";
 
 /**
  * The non-secret render revision: the commit SHA this build was cut from (baked at
@@ -109,11 +115,28 @@ export function candidateBrowserEnvironment(input: {
   canonicalHost: string;
   revision: string;
   siteSurface?: IntegrationSiteSurface;
+}): BrowserEnvironment {
+  return previewBrowserEnvironment({ ...input, stage: "candidate" });
+}
+
+/**
+ * The renderer-owned environment for an exact preview artifact. A per-change
+ * render is `candidate`; the combined release preview is `staged`. The stage is
+ * supplied only by the server-owned route that selected the artifact, never by
+ * query string or tenant content.
+ */
+export function previewBrowserEnvironment(input: {
+  canonicalHost: string;
+  revision: string;
+  stage: Extract<IntegrationEnvironment, "candidate" | "staged">;
+  siteSurface?: IntegrationSiteSurface;
 }): BrowserEnvironment {
   return resolveBrowserEnvironment({
-    dev: import.meta.env.DEV,
+    // This is an explicit server-owned preview route, even while exercised by
+    // Astro dev/Vitest. Do not let the process mode erase its signed stage.
+    dev: false,
     localHost: false,
-    candidate: true,
+    candidate: input.stage === "candidate",
     previewHost: true,
     customizationEnv: "test",
     siteSurface: input.siteSurface ?? "marketing",
@@ -123,15 +146,80 @@ export function candidateBrowserEnvironment(input: {
 }
 
 /**
- * The resolved effective plan for a candidate render — the `candidate`-stage
- * environment wrapped in an environment-only plan so `rawHtmlResponse` (the raw
- * mount of the fixed-phase engine) renders the same renderer-owned phases a live
- * page gets. No integration declarations are materialized on the candidate hot
- * path, so this is environment-only until that wiring lands.
+ * Resolve an exact preview artifact through the same declaration and regulated-
+ * tenant bridge as a normal page. Invalid declarations fail closed to an
+ * environment-only plan; a preview can never fall back to the live plan.
  */
+export function previewIntegrationPlan(
+  input: {
+    canonicalHost: string;
+    revision: string;
+    stage: Extract<IntegrationEnvironment, "candidate" | "staged">;
+    siteSurface?: IntegrationSiteSurface;
+  },
+  tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
+): EffectivePlan {
+  return previewIntegrationState(input, tenantPublicId, tenant, declarations).plan;
+}
+
+/** Resolve an exact preview plan and CSP atomically. */
+export function previewIntegrationState(
+  input: {
+    canonicalHost: string;
+    revision: string;
+    stage: Extract<IntegrationEnvironment, "candidate" | "staged">;
+    siteSurface?: IntegrationSiteSurface;
+  },
+  tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
+): IntegrationRenderState {
+  return resolveIntegrationRenderState({
+    tenantPublicId,
+    tenant,
+    environment: previewBrowserEnvironment(input),
+    declarations,
+  });
+}
+
+/** Resolve a per-change preview against the candidate destination set. */
 export function candidateIntegrationPlan(
   input: { canonicalHost: string; revision: string; siteSurface?: IntegrationSiteSurface },
   tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
+): EffectivePlan {
+  return previewIntegrationPlan({ ...input, stage: "candidate" }, tenantPublicId, tenant, declarations);
+}
+
+/** Resolve a combined-release preview against the staged destination set. */
+export function stagedIntegrationPlan(
+  input: { canonicalHost: string; revision: string; siteSurface?: IntegrationSiteSurface },
+  tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
 ): EffectivePlan {
-  return resolveEnvironmentOnlyPlan(candidateBrowserEnvironment(input), tenantPublicId);
+  return previewIntegrationPlan({ ...input, stage: "staged" }, tenantPublicId, tenant, declarations);
+}
+
+/** Resolve a per-change preview plan and CSP atomically. */
+export function candidateIntegrationState(
+  input: { canonicalHost: string; revision: string; siteSurface?: IntegrationSiteSurface },
+  tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
+): IntegrationRenderState {
+  return previewIntegrationState({ ...input, stage: "candidate" }, tenantPublicId, tenant, declarations);
+}
+
+/** Resolve a combined-release preview plan and CSP atomically. */
+export function stagedIntegrationState(
+  input: { canonicalHost: string; revision: string; siteSurface?: IntegrationSiteSurface },
+  tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
+): IntegrationRenderState {
+  return previewIntegrationState({ ...input, stage: "staged" }, tenantPublicId, tenant, declarations);
 }

package/apps/storefront/src/lib/integration/renderIntegrationState.ts

@@ -0,0 +1,44 @@
+import {
+  collectDeclaredCspProfiles,
+  compileIntegrationCspFromPlan,
+  resolveEnvironmentOnlyPlan,
+  resolveInterimBridgePlan,
+  type BrowserEnvironment,
+  type CompiledIntegrationCsp,
+  type EffectivePlan,
+  type IntegrationDeclarationInput,
+  type ObligationTenant,
+} from "@tot/public-runtime";
+
+export interface IntegrationRenderState {
+  plan: EffectivePlan;
+  compiledCsp?: CompiledIntegrationCsp;
+}
+
+/**
+ * Resolve the plan and CSP as one fail-closed unit. A document either receives
+ * the reviewed plan with the CSP compiled from that exact plan, or an
+ * environment-only plan with no integration origins. Partial state never serves.
+ */
+export function resolveIntegrationRenderState(input: {
+  tenantPublicId: string;
+  tenant: ObligationTenant;
+  environment: BrowserEnvironment;
+  declarations: readonly IntegrationDeclarationInput[];
+}): IntegrationRenderState {
+  const fallback = (): IntegrationRenderState => ({
+    plan: resolveEnvironmentOnlyPlan(input.environment, input.tenantPublicId),
+  });
+  if (input.declarations.length === 0) return fallback();
+
+  const bridge = resolveInterimBridgePlan(input);
+  if (!bridge.ok) return fallback();
+
+  const compiled = compileIntegrationCspFromPlan(
+    bridge.plan,
+    collectDeclaredCspProfiles(input.declarations),
+  );
+  if (!compiled.ok) return fallback();
+
+  return { plan: bridge.plan, compiledCsp: compiled.value };
+}

package/apps/storefront/src/middleware/candidatePin.ts

@@ -14,6 +14,7 @@ import { CANDIDATE_CONTENT_PIN_PARAM, verifyContentPinToken } from "@tot/public-
 export interface CandidateContentPin {
   versionId: string;
   basePath: string;
+  integrationStage: "candidate" | "staged";
 }
 
 /**
@@ -31,5 +32,9 @@ export async function resolveCandidateContentPin(
   if (!secret) return null;
   const verified = await verifyContentPinToken(secret, param, Math.floor(Date.now() / 1000));
   if (!verified.ok || verified.claims.tenantId !== tenantId) return null;
-  return { versionId: verified.claims.versionId, basePath: verified.claims.basePath };
+  return {
+    versionId: verified.claims.versionId,
+    basePath: verified.claims.basePath,
+    integrationStage: verified.claims.integrationStage,
+  };
 }

package/apps/storefront/src/middleware/renderChain.ts

@@ -49,9 +49,6 @@ import {
   resolveServableChannelVersion,
   channelFromEnv,
   resolveEnvironmentOnlyPlan,
-  resolveInterimBridgePlan,
-  compileIntegrationCspFromPlan,
-  collectDeclaredCspProfiles,
   INTEGRATION_NONCE_PLACEHOLDER,
   defaultConsentSnapshot,
   exactPublicationTimestamp,
@@ -82,8 +79,14 @@ import {
 } from "@tot/public-runtime";
 import { loadTenantIntegrationDeclarations } from "@/lib/integration/tenantDeclarations";
 import { resolveTenantCommerce } from "@/lib/checkoutCommerce";
-import { requestBrowserEnvironment, deriveSiteSurface, cspHeaderName } from "@/lib/integration/browserEnvironment";
+import {
+  requestBrowserEnvironment,
+  previewBrowserEnvironment,
+  deriveSiteSurface,
+  cspHeaderName,
+} from "@/lib/integration/browserEnvironment";
 import { freshNonce, stampResponseNonce } from "@/lib/integration/nonceStamp";
+import { resolveIntegrationRenderState } from "@/lib/integration/renderIntegrationState";
 import { recordActivity } from "@/lib/activity/recordActivity";
 import { middlewareRewriteTargetV1 } from "./routeBranch.js";
 import {
@@ -271,32 +274,32 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     ...loadTenantIntegrationDeclarations(tenant),
     ...managedIntegrationDeclarations,
   ];
+  locals.integrationDeclarations = integrationDeclarations;
   if (integrationDeclarations.length > 0) {
     const declFeatures = resolveTenantFeatures(tenant);
-    resolvedBrowserEnvironment = requestBrowserEnvironment({
-      host,
-      isPreviewHost,
-      customizationEnv: customization.env,
-      canonicalHost: tenant.canonicalDomain || host,
-      siteSurface: deriveSiteSurface({ catalog: declFeatures.catalog, pathname: renderPath }),
-    });
-    const bridge = resolveInterimBridgePlan({
+    const siteSurface = deriveSiteSurface({ catalog: declFeatures.catalog, pathname: renderPath });
+    resolvedBrowserEnvironment = candidatePin
+      ? previewBrowserEnvironment({
+          stage: candidatePin.integrationStage,
+          canonicalHost: tenant.canonicalDomain || host,
+          revision: candidatePin.versionId,
+          siteSurface,
+        })
+      : requestBrowserEnvironment({
+          host,
+          isPreviewHost,
+          customizationEnv: customization.env,
+          canonicalHost: tenant.canonicalDomain || host,
+          siteSurface,
+        });
+    const state = resolveIntegrationRenderState({
       tenantPublicId: tenant.tenant_id,
       tenant,
       environment: resolvedBrowserEnvironment,
       declarations: integrationDeclarations,
     });
-    if (bridge.ok) {
-      // A resolved plan serves; its compiled CSP additions + `planRevision` reach the
-      // cache key and the header. A refusal (regulated) or an invalid set leaves the
-      // plan unset here → the environment-only fallback below fills it (nothing loads).
-      locals.integrationPlan = bridge.plan;
-      const compiled = compileIntegrationCspFromPlan(
-        bridge.plan,
-        collectDeclaredCspProfiles(integrationDeclarations),
-      );
-      if (compiled.ok) locals.integrationCsp = compiled.value;
-    }
+    locals.integrationPlan = state.plan;
+    if (state.compiledCsp) locals.integrationCsp = state.compiledCsp;
   }
 
   // ---- Consent snapshot: the tenant's ACTUAL initial consent state, not a
@@ -586,13 +589,20 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // never diverge; an undeclared tenant computes it here for the first time.
   locals.browserEnvironment =
     resolvedBrowserEnvironment ??
-    requestBrowserEnvironment({
-      host,
-      isPreviewHost,
-      customizationEnv: customization.env,
-      canonicalHost: tenant.canonicalDomain || host,
-      siteSurface: deriveSiteSurface({ catalog: locals.features.catalog, pathname: renderPath }),
-    });
+    (candidatePin
+      ? previewBrowserEnvironment({
+          stage: candidatePin.integrationStage,
+          canonicalHost: tenant.canonicalDomain || host,
+          revision: candidatePin.versionId,
+          siteSurface: deriveSiteSurface({ catalog: locals.features.catalog, pathname: renderPath }),
+        })
+      : requestBrowserEnvironment({
+          host,
+          isPreviewHost,
+          customizationEnv: customization.env,
+          canonicalHost: tenant.canonicalDomain || host,
+          siteSurface: deriveSiteSurface({ catalog: locals.features.catalog, pathname: renderPath }),
+        }));
   // Resolved effective plan (ext-kernel-03) for this request — the fixed-phase
   // render engine (ext-kernel-04) consumes it in BOTH document mounts (Layout.astro
   // + rawHtmlResponse). A declared tenant's plan is already resolved above (through

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.0.28",
+  "version": "2.0.30",
   "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/customization-preview.ts

@@ -150,6 +150,8 @@ export const CANDIDATE_CONTENT_PIN_PARAM = "__tot_candidate_pin";
 export interface ContentPinClaims {
   tenantId: string;
   versionId: string;
+  /** Analytics stage selected by the server-owned preview route. */
+  integrationStage: "candidate" | "staged";
   /** basePath the pinned render's own generated links must stay under. */
   basePath: string;
   /** Expiry, epoch seconds. */
@@ -221,6 +223,7 @@ export async function verifyContentPinToken(
     !claims ||
     typeof claims.tenantId !== "string" ||
     typeof claims.versionId !== "string" ||
+    (claims.integrationStage !== "candidate" && claims.integrationStage !== "staged") ||
     typeof claims.basePath !== "string" ||
     typeof claims.exp !== "number"
   ) {

package/packages/public-runtime/src/integration/contact-sales-action-source.ts

@@ -0,0 +1,75 @@
+/**
+ * The platform-owned browser binding for the two reviewed contact-sales CTAs.
+ *
+ * This is deliberately not a general interaction adapter. Both DOM identifiers and
+ * the emitted semantic name are fixed below; the source reads no labels, URLs,
+ * selectors supplied by a caller, event detail, or arbitrary DOM data.
+ */
+import type { PlatformManagedActionActivation, PlatformManagedActionSource } from "./managed-analytics-bridge.js";
+
+/** The only reviewed CTA identities that may raise this marketing action. */
+export const CONTACT_SALES_ACTION_SOURCES = [
+  { ctaId: "cta-book-demo", logicalId: "contact-sales-book-demo" },
+  { ctaId: "contact-sales", logicalId: "contact-sales-lower" },
+] as const;
+
+const CONTACT_SALES_ACTION_NAME = "user_clicked_contact_sales_mktg" as const;
+const CORRELATION_TTL_MS = 60 * 60 * 1000;
+
+export interface ContactSalesActionElement {
+  addEventListener(type: "click", listener: () => void): void;
+  removeEventListener(type: "click", listener: () => void): void;
+}
+
+/** The narrow DOM seam used only to find the two fixed platform CTA identities. */
+export interface ContactSalesActionDocument {
+  querySelectorAll(selector: string): ArrayLike<ContactSalesActionElement>;
+}
+
+export interface ContactSalesActionSourceOptions {
+  document?: ContactSalesActionDocument;
+  planRevision: string;
+  now?: () => number;
+}
+
+/**
+ * Bind literal `data-cta-id` values to a typed source for the managed-analytics
+ * bridge. A keyboard activation of an anchor/button produces its native `click`, so
+ * it follows this same semantic path without a separate key listener.
+ */
+export function createContactSalesActionSource(
+  options: ContactSalesActionSourceOptions,
+): PlatformManagedActionSource {
+  const document = options.document;
+  const now = options.now ?? Date.now;
+  let sequence = 0;
+
+  return {
+    subscribe(listener) {
+      if (!document || typeof document.querySelectorAll !== "function") return () => {};
+      const removals: Array<() => void> = [];
+      for (const source of CONTACT_SALES_ACTION_SOURCES) {
+        const nodes = document.querySelectorAll(`[data-cta-id="${source.ctaId}"]`);
+        for (const node of Array.from(nodes)) {
+          const emit = (): void => {
+            sequence += 1;
+            const at = now();
+            const activation: PlatformManagedActionActivation = {
+              logicalId: `${source.logicalId}-${options.planRevision}-${sequence}`,
+              name: CONTACT_SALES_ACTION_NAME,
+              correlation: {
+                id: `contact-sales-${options.planRevision}`,
+                expiresAt: new Date(at + CORRELATION_TTL_MS).toISOString(),
+              },
+              sequence,
+            };
+            listener(activation);
+          };
+          node.addEventListener("click", emit);
+          removals.push(() => node.removeEventListener("click", emit));
+        }
+      }
+      return () => removals.splice(0).forEach((remove) => remove());
+    },
+  };
+}

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

@@ -76,6 +76,7 @@ export * from "./events-catalog.js";
 export * from "./commerce-broker.js";
 export * from "./managed-analytics.js";
 export * from "./managed-analytics-bridge.js";
+export * from "./contact-sales-action-source.js";
 export * from "./g2-action-boundary.js";
 export * from "./correlation-token.js";
 export * from "./order-conversion.js";

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

@@ -45,6 +45,10 @@ import { validateBrowserEnvironment, BROWSER_ENVIRONMENT_GLOBAL, type BrowserEnv
 import { makePlatformAdapterRuntimeLoader } from "./platform-adapter-runtime.js";
 import { ManagedAnalyticsEventBrokerBridge } from "./managed-analytics-bridge.js";
 import { minimizePageAttribution, type ManagedPageViewInput } from "./managed-analytics.js";
+import {
+  createContactSalesActionSource,
+  type ContactSalesActionDocument,
+} from "./contact-sales-action-source.js";
 
 /** The window property holding the single per-document lifecycle (idempotent boot guard). */
 export const LIFECYCLE_SINGLETON_GLOBAL = "__TOT_INTEGRATION_LIFECYCLE__";
@@ -68,7 +72,7 @@ export interface LifecycleWindow {
    * 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 };
+  document?: { referrer?: string; querySelectorAll?: ContactSalesActionDocument["querySelectorAll"] };
   [key: string]: unknown;
 }
 
@@ -337,7 +341,16 @@ export function bootIntegrationLifecycle(
     commerceBroker,
     managedAnalytics: {
       bridge: options.managedAnalyticsBridge ??
-        new ManagedAnalyticsEventBrokerBridge({ broker: commerceBroker }),
+        new ManagedAnalyticsEventBrokerBridge({
+          broker: commerceBroker,
+          actionSource: createContactSalesActionSource({
+            document: typeof win.document?.querySelectorAll === "function"
+              ? win.document as ContactSalesActionDocument
+              : undefined,
+            planRevision: descriptor.planRevision,
+            now: options.now ?? Date.now,
+          }),
+        }),
       pageView: () => documentPageView(win, descriptor, options.now ?? Date.now),
     },
   });