@tokenoftrust/storefront-runner 2.0.3 → 2.0.5

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

@@ -26,6 +26,9 @@
  */
 import { CHROME_BODY_MARKER, CHROME_HEAD_MARKER } from "./rawMarketingHtml.js";
 import { isCurrentNavHref } from "./chrome/navCurrent.js";
+import { ctaIdentityAttr } from "./chrome/ctaIdentity.js";
+import { CHROME_PLACEMENT } from "./chrome/trackingPlacements.js";
+import { trackingAttributesHtml } from "@tot/public-runtime";
 import type {
   ChromeAgeGate,
   ChromeAnnouncement,
@@ -165,12 +168,27 @@ function renderAnnouncement(a: ChromeAnnouncement): string {
 
 function renderUtilityNav(u: ChromeUtilityNav): string {
   const links = (u.links ?? [])
-    .map((l) => `<li><a href="${esc(l.href)}"${relFor(l)}>${esc(l.label)}</a></li>`)
+    .map((l, i) => {
+      const stamp = trackingAttributesHtml({
+        el: l.id,
+        action: l.action,
+        tracking: l.tracking,
+        placement: CHROME_PLACEMENT.utilityNav,
+        scope: "utility-nav",
+        index: i,
+      });
+      return `<li><a href="${esc(l.href)}"${relFor(l)}${stamp}>${esc(l.label)}</a></li>`;
+    })
     .join("");
   const locale = (u.locale ?? []).map((s) => `<span class="sel">${esc(s)}</span>`).join("");
   const social = u.social?.length ? `<span class="social">${renderSocial(u.social)}</span>` : "";
   const cue = u.memberCue
-    ? `<a class="member-cue" href="${esc(u.memberCue.href)}">${esc(u.memberCue.label)}</a>`
+    ? `<a class="member-cue" href="${esc(u.memberCue.href)}"${trackingAttributesHtml({
+        el: u.memberCue.id,
+        action: u.memberCue.action,
+        tracking: u.memberCue.tracking,
+        placement: CHROME_PLACEMENT.utilityNav,
+      })}>${esc(u.memberCue.label)}</a>`
     : "";
   const right = `${locale}${social}${cue}`;
   return (
@@ -194,7 +212,7 @@ function renderUtilityNav(u: ChromeUtilityNav): string {
  * unprefixed and exact-match-only (see navCurrent.ts). Omitted ⇒ no item is
  * ever marked current (callers that don't know the request path, e.g. tests).
  */
-function renderNavItem(item: ChromeNavItem, currentPath?: string): string {
+function renderNavItem(item: ChromeNavItem, index: number, currentPath?: string): string {
   const columns = item.columns?.length
     ? item.columns
     : item.children?.length
@@ -207,9 +225,19 @@ function renderNavItem(item: ChromeNavItem, currentPath?: string): string {
   const haspopup = hasPanel ? ' aria-haspopup="true"' : "";
   const itemCurrent = currentPath !== undefined && isCurrentNavHref(currentPath, item.href);
   const ariaCurrent = itemCurrent ? ' aria-current="page"' : "";
-  const link = `<a${linkClass} href="${esc(item.href)}"${haspopup}${ariaCurrent}>${esc(item.label)}${badge}${caret}</a>`;
+  const itemStamp = trackingAttributesHtml({
+    el: item.id,
+    action: item.action,
+    tracking: item.tracking,
+    placement: CHROME_PLACEMENT.primaryNav,
+    scope: "nav-primary",
+    index,
+  });
+  const link = `<a${linkClass} href="${esc(item.href)}"${haspopup}${ariaCurrent}${itemStamp}>${esc(item.label)}${badge}${caret}</a>`;
   if (!hasPanel) return `<li class="nav-item">${link}</li>`;
 
+  const megaScope = `nav-mega:${item.id}`;
+  let childIndex = 0;
   const wide = columns.length > 1 ? " mega--wide" : "";
   const cols = columns
     .map((c) => {
@@ -219,7 +247,15 @@ function renderNavItem(item: ChromeNavItem, currentPath?: string): string {
           const childCurrent =
             currentPath !== undefined && isCurrentNavHref(currentPath, l.href, l.external);
           const childAriaCurrent = childCurrent ? ' aria-current="page"' : "";
-          return `<a href="${esc(l.href)}"${relFor(l)}${childAriaCurrent}>${esc(l.label)}</a>`;
+          const childStamp = trackingAttributesHtml({
+            el: l.id,
+            action: l.action,
+            tracking: l.tracking,
+            placement: CHROME_PLACEMENT.megaMenu,
+            scope: megaScope,
+            index: childIndex++,
+          });
+          return `<a href="${esc(l.href)}"${relFor(l)}${childAriaCurrent}${childStamp}>${esc(l.label)}</a>`;
         })
         .join("");
       return `<div class="mega__col">${heading}${links}</div>`;
@@ -257,22 +293,35 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
   const minimal = variant === "minimal";
   // Header CTAs, on the same `!minimal` rule the Astro SiteHeader applies, so the
   // two surfaces render the same governed config identically. Each carries its
-  // stable `id` as `data-cta-id`, so the governed identity is present in the
-  // served DOM rather than implied by label or href.
+  // identity attribute (ctaIdentityAttr, shared with SiteHeader.astro), so the
+  // governed identity is present in the served DOM rather than implied by label
+  // or href.
   const ctas =
     minimal || !header.ctas?.length
       ? ""
       : header.ctas
-          .map(
-            (c) =>
+          .map((c, i) => {
+            const idAttr = ctaIdentityAttr(c);
+            const stamp = trackingAttributesHtml({
+              el: c.id,
+              action: c.action,
+              tracking: c.tracking,
+              placement: CHROME_PLACEMENT.header,
+              scope: "header-ctas",
+              index: i,
+            });
+            return (
               `<a class="header-cta header-cta--${esc(c.variant ?? "primary")}" ` +
-              `data-cta-id="${esc(c.id)}" href="${esc(c.href)}">${esc(c.label)}</a>`,
-          )
+              `${idAttr.name}="${esc(idAttr.value)}" href="${esc(c.href)}"${stamp}>${esc(c.label)}</a>`
+            );
+          })
           .join("");
   const hamburger = minimal
     ? ""
     : `<button class="hamburger" id="hamburger" aria-label="Toggle navigation menu" aria-expanded="false" aria-controls="primaryNav"><span></span><span></span><span></span></button>`;
-  const navItems = header.nav.map((item) => renderNavItem(item, currentPath)).join("\n          ");
+  const navItems = header.nav
+    .map((item, i) => renderNavItem(item, i, currentPath))
+    .join("\n          ");
   const navBar = minimal
     ? ""
     : `  <nav class="primary-nav-bar" aria-label="Primary">\n` +
@@ -343,9 +392,19 @@ function renderFooter(footer: ChromeFooter): string {
         })()
       : "";
   const columns = footer.columns
-    .map((c) => {
+    .map((c, colIndex) => {
       const links = c.links
-        .map((l) => `<li><a href="${esc(l.href)}"${relFor(l)}>${esc(l.label)}</a></li>`)
+        .map((l, i) => {
+          const stamp = trackingAttributesHtml({
+            el: l.id,
+            action: l.action,
+            tracking: l.tracking,
+            placement: CHROME_PLACEMENT.footer,
+            scope: `footer-col:${colIndex}`,
+            index: i,
+          });
+          return `<li><a href="${esc(l.href)}"${relFor(l)}${stamp}>${esc(l.label)}</a></li>`;
+        })
         .join("");
       return `      <div class="footer-col">\n        <h4>${esc(c.title)}</h4>\n        <ul>${links}</ul>\n      </div>`;
     })

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

@@ -17,8 +17,10 @@
  */
 import {
   renderIntegrationPhases,
+  INTERACTION_TRACKING_BOOT_JS,
   type EffectivePlan,
 } from "@tot/public-runtime";
+import { reportTrackingChainHealth } from "./tracking/interactionHealth.js";
 
 export { rawHtmlPolicy } from "@tot/public-runtime";
 
@@ -113,6 +115,23 @@ function injectBodyEnd(html: string, snippet: string): string {
   return html + snippet;
 }
 
+/**
+ * The declarative-interaction-tracking listener as a nonce-carrying inline
+ * `<script>` — the raw-mount half of the install (`Layout.astro` is the other,
+ * ADR 0015 one-engine-two-mounts). Both mounts embed the SAME serialized
+ * listener from `@tot/public-runtime`, so no markup path can drift into a
+ * second implementation, and the listener's install-once marker makes a second
+ * copy in the same document (a tenant `chrome.html` wrapper that also carries
+ * it) a no-op.
+ *
+ * Carries the nonce itself because it is spliced AFTER `nonceInlineTags` has
+ * run — same discipline as the render engine's phase markup.
+ */
+export function interactionTrackingScript(nonce: string): string {
+  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  return `<script${nonceAttr}>${INTERACTION_TRACKING_BOOT_JS}</script>`;
+}
+
 /** Stamp `nonce` onto every inline `<style>`/`<script>` so a strict CSP admits them. */
 export function nonceInlineTags(html: string, nonce: string): string {
   return html
@@ -167,6 +186,12 @@ export function rawHtmlResponse(
     isFullDocument(html) || !opts.chromeWrapper
       ? html
       : wrapFragmentInChrome(html, opts.chromeWrapper);
+  // HEALTH: a raw surface bypasses governed chrome, so `validateChromeConfig`
+  // never saw it and `trackingAttributes()` never stamped it. If NOT ONE of its
+  // actionable elements carries an identity, no click on this page can ever be
+  // collected — and every other layer is silent about that by design (absence
+  // is also how a legitimate opt-out looks). One structured line, never a throw.
+  reportTrackingChainHealth(composed, { surface: `raw:${opts.basePath || "/"}` });
   // DEV ONLY: these pages are served verbatim, bypassing Astro's render pipeline,
   // so the Vite HMR client is never injected — a save would reach the server (see
   // the tenantHotReload plugin in astro.config.mjs) but the browser would have no
@@ -201,6 +226,11 @@ export function rawHtmlResponse(
   composed = injectHeadStart(composed, phases.head);
   composed = injectBodyStart(composed, phases.bodyStart);
   composed = injectBodyEnd(composed, phases.bodyDeferred);
+  // Declarative interaction tracking, last in the body so the whole document —
+  // a verbatim tenant document, a fragment spliced into a hand-authored
+  // `chrome.html`, or a fragment spliced into the generated `renderRawChrome`
+  // wrapper — is already present when the delegated listener binds.
+  composed = injectBodyEnd(composed, interactionTrackingScript(opts.nonce));
   const doc = prefixTenantLinks(composed, opts.basePath);
   return new Response(doc, {
     headers: { "content-type": "text/html; charset=utf-8" },

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

@@ -0,0 +1,68 @@
+/**
+ * Ship/owner capability primitives — genuinely shared between the control-plane
+ * ship surface (`@/lib/change`, `@/lib/grants`, `@/lib/forge` — all moat, dropped
+ * from the public storefront-runner) and renderer-adjacent code that ships in the
+ * runner (`@/lib/auth/adminEntry`, the order-admin API guard). Pure types + pure
+ * functions only — no I/O, no MCP/forge calls, no secrets — which is exactly why
+ * they can live outside the moat cluster instead of forcing a KEPT file to import
+ * a DROPped one.
+ *
+ * Canonical home for these five exports; `@/lib/forge/types`, `@/lib/grants/session`,
+ * `@/lib/change/route/route`, and `@/lib/change/route/ship-capabilities` re-export
+ * from here (not the other way around) so the moat cluster still has one place to
+ * read them, while nothing outside the moat needs to import INTO it.
+ */
+
+/** Access level the acting operator holds. */
+export type Capability = "preview-access" | "ship-on-behalf";
+
+/** Capabilities that carry tenant-owner standing (vs. a granted developer). */
+export const OWNER_CAPABILITIES: ReadonlySet<string> = new Set(["owner", "admin"]);
+
+/** Pure inputs to the owner-principal decision (session only, no I/O). */
+export interface OwnerPrincipalInput {
+  /** Whether the request is authenticated for the resolved tenant. */
+  authorized: boolean;
+  /** The signed-in viewer's capability over the resolved tenant, if any. */
+  viewerCapability: string | undefined;
+}
+
+/**
+ * Decide whether the acting principal IS the tenant owner. Owner iff the
+ * request is authorized AND a signed-in viewer holds an owner/admin capability
+ * over the resolved tenant.
+ */
+export function decideIsOwner(input: OwnerPrincipalInput): boolean {
+  if (!input.authorized) return false;
+  return !!input.viewerCapability && OWNER_CAPABILITIES.has(input.viewerCapability);
+}
+
+/**
+ * The acting principal's ship-relevant relationship to the tenant, resolved
+ * SERVER-SIDE (never from request input).
+ */
+export interface ShipPrincipal {
+  /** True when the acting principal IS the tenant owner (see {@link decideIsOwner}). */
+  isOwner: boolean;
+  /** The developer grant capability the principal holds. Fail-closed default is `preview-access`. */
+  capability: Capability;
+}
+
+/** The two distinct ship-gate capabilities, derived per-principal. */
+export interface ShipCapabilities {
+  /** May invoke ship-on-behalf (accept / reject / rollback). Owner is a superset. */
+  shipOnBehalf: boolean;
+  /** May invoke the apex (DNS) cutover. OWNER-ONLY. */
+  apexCutover: boolean;
+}
+
+/**
+ * Resolve the two capabilities from the principal. Owner ⊇ ship-on-behalf for the
+ * ship axis; apex-cutover is owner-only.
+ */
+export function resolveShipCapabilities(principal: ShipPrincipal): ShipCapabilities {
+  return {
+    shipOnBehalf: principal.isOwner || principal.capability === "ship-on-behalf",
+    apexCutover: principal.isOwner,
+  };
+}