@tokenoftrust/storefront-runner 2.0.3 → 2.0.5

package/apps/storefront/src/pages/api/tracking/interaction.ts

@@ -0,0 +1,123 @@
+/**
+ * POST /api/tracking/interaction (dt-collector-v1) — the beacon sink for
+ * declarative interaction tracking.
+ *
+ * The browser collector (`@/lib/tracking/interactionCollector`) batches
+ * `TotInteraction`s captured off `installInteractionTracking` /
+ * `onInteraction` (`@tot/public-runtime`) — via `dt-consent-environment-gate`'s
+ * consent/environment wrapper in front of it — and POSTs them here with
+ * `navigator.sendBeacon`, same transport contract as the F14 RUM beacon
+ * (`pages/api/rum/vitals.ts`): unauthenticated (a beacon carries no
+ * credentials), tenant resolved from `context.locals.tenant.tenant_id`
+ * (never the body), 204 on every outcome so a beacon never errors, retries,
+ * or blocks page unload.
+ *
+ * VALIDATION — `collectorIngest.ts` re-derives every field from the raw body
+ * under a default-deny allowlist (`collectorAllowlist.ts`): an unlisted key is
+ * dropped and counted, a listed-but-wrong-typed field rejects that event. Never
+ * trust the client for `tenant_id` or `stream` — both are stamped here, always.
+ *
+ * STORAGE — two sinks, fanned out past the response (`interactionStore.ts`,
+ * same shape as `pages/api/activity.ts`'s `fanOutActivity`):
+ *
+ *   • RAW ROWS → the tenant's OWN D1 database, resolved (and provisioned on
+ *     first sight) by `tenantD1Registry.resolveTenantStore`. ONE DATABASE PER
+ *     TENANT, so cross-tenant leakage is impossible by construction, not by a
+ *     correct `WHERE tenant_id = ?`. The directory that maps tenant → database
+ *     lives in the shared `STOREFRONT_APPS_DB`
+ *     (`tracking_tenant_databases`); the rows never do.
+ *   • AGGREGATES → the DEDICATED `INTERACTION_ANALYTICS` Analytics Engine
+ *     dataset (`storefront_interactions`) — NOT the operational spine's
+ *     `storefront_activity` dataset — rolled up to one point per dimension
+ *     tuple, so no per-event identity reaches AE.
+ *
+ * Both sinks are best-effort: unconfigured or failing, the batch falls back to
+ * the Workers Logs firehose and the beacon still 204s. `stream` (always
+ * `"interaction"` today) is the discriminator column to route on if a second
+ * stream is ever added.
+ */
+import type { APIContext } from "astro";
+import { readD1, readAnalytics, runAfterResponse, type CfExecutionContextLike } from "@/lib/env";
+import { fromD1 } from "@/lib/d1/catalog";
+import { ingestInteractions, type StampedInteractionEvent } from "@/lib/tracking/collectorIngest";
+import { readD1Control } from "@/lib/tracking/d1Control";
+import { resolveTenantStore, trackingNamePrefix } from "@/lib/tracking/tenantD1Registry";
+import { persistInteractions } from "@/lib/tracking/interactionStore";
+import type { AnalyticsEngineLike } from "@/lib/activity/store";
+
+export const prerender = false;
+
+/** Cap the batch so one beacon can't fan out unbounded off-path work. */
+const MAX_BATCH = 50;
+
+/**
+ * Resolve both sinks and write the batch. Runs PAST the response
+ * (`runAfterResponse`), so binding resolution + the D1 REST round-trip never
+ * hold the beacon open. Never throws — a telemetry beacon must not fail because
+ * storage is unconfigured or unreachable.
+ */
+async function storeInteractions(
+  tenantId: string,
+  events: StampedInteractionEvent[],
+  ingestedAt: string,
+): Promise<void> {
+  try {
+    const [appsDb, analyticsBinding, control, namePrefix] = await Promise.all([
+      readD1("STOREFRONT_APPS_DB"),
+      readAnalytics("INTERACTION_ANALYTICS"),
+      readD1Control(),
+      trackingNamePrefix(),
+    ]);
+
+    // The raw sink needs BOTH the directory (shared apps D1) and the D1 REST
+    // credentials that address a per-tenant database; either absent ⇒ skip it.
+    const store =
+      appsDb && control
+        ? await resolveTenantStore(tenantId, {
+            apps: fromD1(appsDb),
+            control,
+            namePrefix,
+            at: ingestedAt,
+          })
+        : undefined;
+
+    await persistInteractions(events, {
+      store,
+      analytics: (analyticsBinding as AnalyticsEngineLike | undefined) ?? undefined,
+    });
+  } catch {
+    /* never fail a telemetry beacon */
+  }
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  try {
+    const tenantId = (context.locals as { tenant?: { tenant_id?: string } })?.tenant?.tenant_id;
+    // No resolved tenant (e.g. a request that never went through tenant
+    // resolution) ⇒ nothing to stamp or store; still 204, never error the beacon.
+    if (!tenantId) return new Response(null, { status: 204 });
+
+    const parsed: unknown = await context.request.json();
+    const events = Array.isArray(parsed)
+      ? parsed
+      : parsed && typeof parsed === "object" && Array.isArray((parsed as { events?: unknown }).events)
+        ? (parsed as { events: unknown[] }).events
+        : [];
+    if (events.length === 0) return new Response(null, { status: 204 });
+
+    const batch = events.slice(0, MAX_BATCH);
+    const ingestedAt = new Date().toISOString();
+    const { accepted } = ingestInteractions(batch, tenantId, ingestedAt);
+
+    if (accepted.length > 0) {
+      const cfContext = (context.locals as { cfContext?: CfExecutionContextLike })?.cfContext ?? null;
+      runAfterResponse(
+        storeInteractions(tenantId, accepted.map((a) => a.event), ingestedAt),
+        cfContext,
+      );
+    }
+  } catch {
+    /* never fail a telemetry beacon */
+  }
+  return new Response(null, { status: 204 });
+}

package/apps/storefront/src/pages/index.astro

@@ -17,7 +17,7 @@ import TierCards from "@/components/membership/TierCards.astro";
 import { withBase } from "@/lib/basePath";
 import { rawHtmlPolicy, rawHtmlResponse } from "@/lib/rawMarketingHtml";
 import AppWidgetFrame from "@/components/apps/AppWidgetFrame.astro";
-import { getRegistryService } from "@/lib/apps/adminService.js";
+import { getRegistryService } from "@/lib/apps/registryAccess.js";
 import { renderWidgetSlot } from "@/lib/apps/widgets/renderSlot.js";
 import type { CatalogCollection, CatalogProduct } from "@tot/public-runtime";
 import {

package/apps/storefront/src/pages/products/[handle].astro

@@ -42,7 +42,7 @@ import { productLd, breadcrumbLd, reviewLd } from "@/lib/jsonld";
 import { isUsableImageUrl } from "@/lib/placeholder";
 import { withBase } from "@/lib/basePath";
 import AppWidgetFrame from "@/components/apps/AppWidgetFrame.astro";
-import { getRegistryService } from "@/lib/apps/adminService.js";
+import { getRegistryService } from "@/lib/apps/registryAccess.js";
 import { renderWidgetSlot } from "@/lib/apps/widgets/renderSlot.js";
 
 const { handle } = Astro.params;

package/apps/storefront/src/pages/style-guide/[tenant]/[theme].astro

@@ -43,6 +43,7 @@ import SiteHeader from "@/components/chrome/SiteHeader.astro";
 import MegaMenu from "@/components/chrome/MegaMenu.astro";
 import NavDropdown from "@/components/chrome/NavDropdown.astro";
 import SiteFooter from "@/components/chrome/SiteFooter.astro";
+import { CHROME_PLACEMENT } from "@/lib/chrome/trackingPlacements";
 import NicotineWarning from "@/components/compliance/NicotineWarning.astro";
 import PactActNotice from "@/components/compliance/PactActNotice.astro";
 import AdultSignatureNotice from "@/components/compliance/AdultSignatureNotice.astro";
@@ -88,28 +89,33 @@ const { tenant, theme } = Astro.params;
 const cspNonce = Astro.locals.cspNonce;
 
 // --- Sample chrome data (preview-only; no live tenant content) ----------------
+// Every actionable item declares its tracking intent (`action`) alongside its
+// identity (`id`) — the two are different axes and neither is derived from the
+// other. See docs/architecture/interaction-tracking-attribute-contract.md.
 const sampleNav: ChromeNavItem[] = [
-  { id: "nav-new", label: "New", href: "#", flag: true, badge: "NEW" },
+  { id: "nav-new", action: "nav-new", label: "New", href: "#", flag: true, badge: "NEW" },
   {
     id: "nav-shop",
+    action: "nav-shop",
     label: "Shop",
     href: "#",
     columns: [
-      { title: "Category", links: [{ id: "nav-shop-disposables", label: "Disposables", href: "#" }, { id: "nav-shop-eliquid", label: "E-Liquid", href: "#" }, { id: "nav-shop-devices", label: "Devices", href: "#" }] },
-      { title: "Featured", links: [{ id: "nav-shop-bestsellers", label: "Best Sellers", href: "#" }, { id: "nav-shop-onsale", label: "On Sale", href: "#", badge: "%" }] },
-      { title: "Brands", links: [{ id: "nav-shop-northwind", label: "Northwind", href: "#" }, { id: "nav-shop-summit", label: "Summit Co.", href: "#" }] },
+      { title: "Category", links: [{ id: "nav-shop-disposables", action: "nav-disposables", label: "Disposables", href: "#" }, { id: "nav-shop-eliquid", action: "nav-eliquid", label: "E-Liquid", href: "#" }, { id: "nav-shop-devices", action: "nav-devices", label: "Devices", href: "#" }] },
+      { title: "Featured", links: [{ id: "nav-shop-bestsellers", action: "nav-bestsellers", label: "Best Sellers", href: "#" }, { id: "nav-shop-onsale", action: "nav-on-sale", label: "On Sale", href: "#", badge: "%" }] },
+      { title: "Brands", links: [{ id: "nav-shop-northwind", action: "nav-brand-northwind", label: "Northwind", href: "#" }, { id: "nav-shop-summit", action: "nav-brand-summit", label: "Summit Co.", href: "#" }] },
     ],
   },
-  { id: "nav-coils", label: "Coils & Parts", href: "#", children: [{ id: "nav-coils-coils", label: "Coils", href: "#" }, { id: "nav-coils-pods", label: "Pods", href: "#" }, { id: "nav-coils-batteries", label: "Batteries", href: "#" }] },
-  { id: "nav-sale", label: "On Sale", href: "#" },
+  { id: "nav-coils", action: "nav-coils-and-parts", label: "Coils & Parts", href: "#", children: [{ id: "nav-coils-coils", action: "nav-coils", label: "Coils", href: "#" }, { id: "nav-coils-pods", action: "nav-pods", label: "Pods", href: "#" }, { id: "nav-coils-batteries", action: "nav-batteries", label: "Batteries", href: "#" }] },
+  { id: "nav-sale", action: "nav-on-sale", label: "On Sale", href: "#" },
 ];
 const sampleSocial = [
   { label: "X", href: "#", iconPath: "M18.9 2H22l-7.1 8.1L23 22h-6.6l-5-6.6L5.7 22H2.6l7.6-8.7L1.5 2h6.8l4.5 6 5.1-6z" },
 ];
 const sampleFooterCols = [
-  { title: "Shop", links: [{ id: "ftr-shop-disposables", label: "Disposables", href: "#" }, { id: "ftr-shop-eliquid", label: "E-Liquid", href: "#" }, { id: "ftr-shop-devices", label: "Devices", href: "#" }] },
-  { title: "Support", links: [{ id: "ftr-support-contact", label: "Contact", href: "#" }, { id: "ftr-support-shipping", label: "Shipping", href: "#" }, { id: "ftr-support-returns", label: "Returns", href: "#" }] },
-  { title: "Company", links: [{ id: "ftr-company-about", label: "About", href: "#" }, { id: "ftr-company-blog", label: "Blog", href: "#" }] },
+  // The footer repeats the header's intents: same `action`, different placement.
+  { title: "Shop", links: [{ id: "ftr-shop-disposables", action: "nav-disposables", label: "Disposables", href: "#" }, { id: "ftr-shop-eliquid", action: "nav-eliquid", label: "E-Liquid", href: "#" }, { id: "ftr-shop-devices", action: "nav-devices", label: "Devices", href: "#" }] },
+  { title: "Support", links: [{ id: "ftr-support-contact", action: "nav-contact", label: "Contact", href: "#" }, { id: "ftr-support-shipping", action: "nav-shipping", label: "Shipping", href: "#" }, { id: "ftr-support-returns", action: "nav-returns", label: "Returns", href: "#" }] },
+  { title: "Company", links: [{ id: "ftr-company-about", action: "nav-about", label: "About", href: "#" }, { id: "ftr-company-blog", action: "nav-blog", label: "Blog", href: "#" }] },
 ];
 // BrandGrid samples: text-wordmark tiles and logo-image tiles (Img renders
 // deterministic placeholders offline so the image code path is exercised
@@ -321,12 +327,17 @@ const sampleManageEntries: SubscriptionManageEntry[] = [
 // --- Sample islands data (preview-only) ----------------------------------
 const sampleMobileNav = [
   {
+    id: "mnav-shop",
+    action: "nav-shop",
     label: "Shop",
     href: "#",
-    children: [{ label: "Disposables", href: "#" }, { label: "E-Liquid", href: "#" }],
+    children: [
+      { id: "mnav-shop-disposables", action: "nav-disposables", label: "Disposables", href: "#" },
+      { id: "mnav-shop-eliquid", action: "nav-eliquid", label: "E-Liquid", href: "#" },
+    ],
   },
-  { label: "Coils & Parts", href: "#" },
-  { label: "On Sale", href: "#" },
+  { id: "mnav-coils", action: "nav-coils-and-parts", label: "Coils & Parts", href: "#" },
+  { id: "mnav-sale", action: "nav-on-sale", label: "On Sale", href: "#" },
 ];
 const sampleFromProduct = sampleProducts.find((p) => p.handle === "sample-from")!;
 const sampleRecentlyViewed: RVItem[] = [
@@ -1149,7 +1160,7 @@ const componentVarsInline = Object.entries(componentVars)
       <section class="sg-block">
         <p class="sg-h">Chrome — UtilityNav</p>
         <UtilityNav
-          links={[{ id: "util-news", label: "News", href: "#" }, { id: "util-about", label: "About", href: "#" }, { id: "util-contact", label: "Contact", href: "#" }]}
+          links={[{ id: "util-news", action: "nav-news", label: "News", href: "#" }, { id: "util-about", action: "nav-about", label: "About", href: "#" }, { id: "util-contact", action: "nav-contact", label: "Contact", href: "#" }]}
           locale="English"
           currency="United States (USD $)"
           social={sampleSocial}
@@ -1181,7 +1192,15 @@ const componentVarsInline = Object.entries(componentVars)
         <p class="sg-h">Chrome — NavDropdown accordion (mobile mega parity, zero-JS)</p>
         <div style="max-width:18rem;background:var(--color-surface);border:1px solid var(--color-border);border-radius:8px;padding:8px 12px">
           <ul class="grid">
-            {sampleNav.map((item) => <NavDropdown item={item} mode="accordion" />)}
+            {sampleNav.map((item, i) => (
+              <NavDropdown
+                item={item}
+                mode="accordion"
+                placement={CHROME_PLACEMENT.mobileMenu}
+                menuPlacement={CHROME_PLACEMENT.mobileMenu}
+                index={i}
+              />
+            ))}
           </ul>
         </div>
         <p class="form-help" style="margin-top:8px;color:var(--color-muted)">Same nav items in the mobile menu: mega columns become inline <code>&lt;details&gt;</code> accordions (keyboard + touch operable). Toggle a caret item to expand.</p>

package/apps/storefront/src/workers/pruneRollupWorker.ts

@@ -0,0 +1,120 @@
+/**
+ * The scheduled Cloudflare Worker entry for `dt-prune-and-rollup`.
+ *
+ * A SEPARATE, DEDICATED Worker script from the Astro-adapted storefront
+ * Worker — deliberately, not a `scheduled` export bolted onto the Astro
+ * entry. The @astrojs/cloudflare adapter OWNS `dist/server/entry.mjs` and
+ * bakes its target environment in at BUILD time via `CLOUDFLARE_ENV`
+ * (`wrangler.toml`'s own "DEPLOY FOOTGUN" comment); the documented way to add
+ * a non-`fetch` handler there is a custom entrypoint that re-imports the
+ * adapter's generated `handle()`, which would make this cron trigger's
+ * correctness depend on the SAME footgun-prone build/deploy sequencing as
+ * the whole storefront. This module instead has nothing to do with Astro at
+ * all — it is a plain `ExportedHandler` deployed under its own Worker name
+ * (`wrangler.prune-rollup.toml`, `[triggers]` below), reusing the tracking
+ * library's already-built, framework-agnostic pieces
+ * (`lib/tracking/pruneRollup.ts`, `d1Control.ts`, `interactionStore.ts`).
+ * There is no other scheduled-Worker precedent in this repo to follow; this
+ * is the first one, chosen to keep the footgun-prone Astro deploy path
+ * completely untouched.
+ *
+ * BINDINGS (declared in `wrangler.prune-rollup.toml`, not this file):
+ *   - `STOREFRONT_APPS_DB` — the SAME shared D1 database the main storefront
+ *     Worker binds, for the `tracking_tenant_databases` directory.
+ *   - `INTERACTION_ANALYTICS` — the SAME Analytics Engine dataset the main
+ *     Worker writes rollups to.
+ *   - `CF_ACCOUNT_ID` / `TRACKING_D1_API_TOKEN` (secret) — D1 REST
+ *     credentials for reaching each tenant's OWN database (Worker bindings
+ *     are static; a per-tenant database can only be addressed over the D1
+ *     HTTP API, same reasoning as `d1Control.ts`'s module doc).
+ *   - `TRACKING_D1_NAME_PREFIX` (optional) — unused by this worker directly,
+ *     kept only for parity/documentation; the prune sweep addresses tenants
+ *     by `database_uuid` from the directory, never by re-deriving the name.
+ */
+import type { Queryable } from "../lib/d1/catalog.js";
+import type { D1Like } from "../lib/d1/catalog.js";
+import { fromD1 } from "../lib/d1/catalog.js";
+import type { AnalyticsEngineLike } from "../lib/activity/store.js";
+import type { D1ControlConfig } from "../lib/tracking/d1Control.js";
+import { runPruneSweep, type PruneSweepResult } from "../lib/tracking/pruneRollup.js";
+
+/** The env bindings this Worker needs — a local, minimal slice (this repo
+ *  does not take a `@cloudflare/workers-types` dependency; see `d1Control.ts`
+ *  and `activity/store.ts` for the same convention). */
+export interface PruneRollupEnv {
+  STOREFRONT_APPS_DB: D1Like;
+  INTERACTION_ANALYTICS?: AnalyticsEngineLike;
+  CF_ACCOUNT_ID?: string;
+  TRACKING_D1_API_TOKEN?: string;
+  /** Tenants processed per invocation; overridable for a slower/faster cron. */
+  PRUNE_BATCH_SIZE?: string;
+}
+
+/** The minimal slice of Cloudflare's `ScheduledController` this handler uses. */
+export interface ScheduledControllerLike {
+  scheduledTime: number;
+}
+
+/** The minimal slice of Cloudflare's `ExecutionContext` this handler uses. */
+export interface ExecutionContextLike {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/** Build the D1 REST control config from env, or undefined when unconfigured
+ *  (mirrors `d1Control.ts`'s `readD1Control()` "skip, never fail" posture). */
+function controlFromEnv(env: PruneRollupEnv): D1ControlConfig | undefined {
+  if (!env.CF_ACCOUNT_ID || !env.TRACKING_D1_API_TOKEN) return undefined;
+  return { accountId: env.CF_ACCOUNT_ID, apiToken: env.TRACKING_D1_API_TOKEN };
+}
+
+/**
+ * The pure orchestration the `scheduled` export below delegates to — kept
+ * separate so it is callable/testable without a real `ScheduledController`.
+ * Never throws: a misconfigured environment (no D1 REST credentials) logs
+ * and no-ops rather than failing the cron invocation.
+ */
+export async function handleScheduledPrune(
+  env: PruneRollupEnv,
+  now: string = new Date().toISOString(),
+): Promise<PruneSweepResult | undefined> {
+  const control = controlFromEnv(env);
+  if (!control) {
+    console.error(
+      "[tracking:prune] skipped — CF_ACCOUNT_ID/TRACKING_D1_API_TOKEN not configured",
+    );
+    return undefined;
+  }
+
+  const apps: Queryable = fromD1(env.STOREFRONT_APPS_DB);
+  const batchSize = env.PRUNE_BATCH_SIZE ? Number.parseInt(env.PRUNE_BATCH_SIZE, 10) : undefined;
+
+  const result = await runPruneSweep({
+    apps,
+    control,
+    analytics: env.INTERACTION_ANALYTICS,
+    now,
+    ...(batchSize && Number.isFinite(batchSize) ? { batchSize } : {}),
+  });
+
+  console.info(
+    `[tracking:prune] swept ${result.tenantsSwept} tenant(s), pruned ${result.totalPrunedRows} row(s), ` +
+      `wrote ${result.totalAggregatesWritten} aggregate(s)`,
+  );
+  return result;
+}
+
+export default {
+  async scheduled(
+    controller: ScheduledControllerLike,
+    env: PruneRollupEnv,
+    ctx: ExecutionContextLike,
+  ): Promise<void> {
+    ctx.waitUntil(
+      handleScheduledPrune(env, new Date(controller.scheduledTime).toISOString()).catch((err) => {
+        console.error(
+          `[tracking:prune] sweep threw: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }),
+    );
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "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/node_modules/.bin/tsc

@@ -0,0 +1,43 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+basedir_win="$basedir"
+exe=""
+msys=""
+
+case `uname -a` in
+  *CYGWIN*|*MINGW*|*MSYS*)
+    if command -v cygpath > /dev/null 2>&1; then
+      basedir_win=`cygpath -w "$basedir"`
+    fi
+    exe=".exe"
+    msys="true"
+  ;;
+  *WSL2*)
+    if command -v wslpath > /dev/null 2>&1; then
+      basedir_win="$(wslpath -w "$basedir" 2> /dev/null)"
+      if [ $? -ne 0 ] || [ -z "$basedir_win" ]; then
+        basedir_win="$basedir"
+      else
+        exe=".exe"
+      fi
+    fi
+  ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -n "$exe" ] && [ -x "$basedir/node.exe" ]; then
+  exec "$basedir/node.exe"  "$basedir_win/../typescript/bin/tsc" "$@"
+elif [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+elif command -v node >/dev/null 2>&1; then
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+elif [ -n "$exe" ] && command -v node.exe >/dev/null 2>&1; then
+  exec node.exe  "$basedir_win/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi
+# cmd-shim-target=/home/runner/work/storefront/storefront/storefront-runner-dist/packages/public-runtime/node_modules/typescript/bin/tsc

package/packages/public-runtime/node_modules/.bin/tsserver

@@ -0,0 +1,43 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+basedir_win="$basedir"
+exe=""
+msys=""
+
+case `uname -a` in
+  *CYGWIN*|*MINGW*|*MSYS*)
+    if command -v cygpath > /dev/null 2>&1; then
+      basedir_win=`cygpath -w "$basedir"`
+    fi
+    exe=".exe"
+    msys="true"
+  ;;
+  *WSL2*)
+    if command -v wslpath > /dev/null 2>&1; then
+      basedir_win="$(wslpath -w "$basedir" 2> /dev/null)"
+      if [ $? -ne 0 ] || [ -z "$basedir_win" ]; then
+        basedir_win="$basedir"
+      else
+        exe=".exe"
+      fi
+    fi
+  ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -n "$exe" ] && [ -x "$basedir/node.exe" ]; then
+  exec "$basedir/node.exe"  "$basedir_win/../typescript/bin/tsserver" "$@"
+elif [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+elif command -v node >/dev/null 2>&1; then
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+elif [ -n "$exe" ] && command -v node.exe >/dev/null 2>&1; then
+  exec node.exe  "$basedir_win/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi
+# cmd-shim-target=/home/runner/work/storefront/storefront/storefront-runner-dist/packages/public-runtime/node_modules/typescript/bin/tsserver

package/packages/public-runtime/node_modules/.bin/vitest

@@ -0,0 +1,43 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+basedir_win="$basedir"
+exe=""
+msys=""
+
+case `uname -a` in
+  *CYGWIN*|*MINGW*|*MSYS*)
+    if command -v cygpath > /dev/null 2>&1; then
+      basedir_win=`cygpath -w "$basedir"`
+    fi
+    exe=".exe"
+    msys="true"
+  ;;
+  *WSL2*)
+    if command -v wslpath > /dev/null 2>&1; then
+      basedir_win="$(wslpath -w "$basedir" 2> /dev/null)"
+      if [ $? -ne 0 ] || [ -z "$basedir_win" ]; then
+        basedir_win="$basedir"
+      else
+        exe=".exe"
+      fi
+    fi
+  ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.2_lightningcss@1.33.0/node_modules/vitest/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.2_lightningcss@1.33.0/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.2_lightningcss@1.33.0/node_modules/vitest/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.2_lightningcss@1.33.0/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -n "$exe" ] && [ -x "$basedir/node.exe" ]; then
+  exec "$basedir/node.exe"  "$basedir_win/../vitest/vitest.mjs" "$@"
+elif [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"
+elif command -v node >/dev/null 2>&1; then
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+elif [ -n "$exe" ] && command -v node.exe >/dev/null 2>&1; then
+  exec node.exe  "$basedir_win/../vitest/vitest.mjs" "$@"
+else
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+fi
+# cmd-shim-target=/home/runner/work/storefront/storefront/storefront-runner-dist/packages/public-runtime/node_modules/vitest/vitest.mjs

package/packages/public-runtime/src/chrome.ts

@@ -28,6 +28,7 @@
  * `parseConfig.ts` re-export from here so every existing renderer import
  * keeps resolving unchanged.
  */
+import { validateTracking, type TrackingDeclaration } from "./interaction-tracking.js";
 
 /**
  * A navigation/footer/CTA link. `id` is a STABLE identifier, independent of
@@ -35,14 +36,20 @@
  * registry (spec: no runtime registry, no DOM observer; just a schema-
  * validated identifier + a real `href` fallback, always present on every
  * actionable item). `external` opens off-site; `badge` shows e.g. "NEW".
+ *
+ * Every actionable item also carries the declarative-interaction-tracking
+ * declaration ({@link TrackingDeclaration}): a stable `action` naming the
+ * INTENT, or `tracking: "none"` to stamp nothing at all. `id` (identity) and
+ * `action` (intent) are different axes and are never derived from each other —
+ * see docs/architecture/interaction-tracking-attribute-contract.md.
  */
-export interface ChromeLink {
+export type ChromeLink = {
   id: string;
   label: string;
   href: string;
   external?: boolean;
   badge?: string;
-}
+} & TrackingDeclaration;
 
 /** One column of a mega-menu panel. */
 export interface MegaColumn {
@@ -56,7 +63,7 @@ export interface MegaColumn {
  * marks it (e.g. "NEW"); `flag` gives it the emphasized/highlighted
  * treatment. See {@link ChromeLink} for `id`.
  */
-export interface ChromeNavItem {
+export type ChromeNavItem = {
   id: string;
   label: string;
   href: string;
@@ -64,7 +71,7 @@ export interface ChromeNavItem {
   flag?: boolean;
   children?: ChromeLink[];
   columns?: MegaColumn[];
-}
+} & TrackingDeclaration;
 
 export interface SocialLink {
   label: string;
@@ -81,16 +88,16 @@ export interface ChromeLogo {
 }
 
 /** A marketing conversion CTA (header-actions / footer, non-commerce tenants). */
-export interface ChromeCta {
+export type ChromeCta = {
   id: string;
   label: string;
   href: string;
   variant?: "primary" | "secondary" | "ghost";
-}
+} & TrackingDeclaration;
 
 /** A stable link-with-a-name-and-href, minus badge/external — used for the
  * small number of single-purpose action links (e.g. a member-price cue). */
-export type ChromeActionLink = Pick<ChromeLink, "id" | "label" | "href">;
+export type ChromeActionLink = { id: string; label: string; href: string } & TrackingDeclaration;
 
 export interface FooterColumn {
   title: string;
@@ -371,6 +378,7 @@ function validateLink(v: unknown, path: string, errors: string[]): v is ChromeLi
   if (!isNonEmptyString(v.href)) errors.push(`${path}.href: required, non-empty string`);
   checkOptionalBoolean(v.external, `${path}.external`, errors);
   checkOptionalString(v.badge, `${path}.badge`, errors);
+  validateTracking(v, path, errors);
   return errors.length === before;
 }
 
@@ -384,6 +392,7 @@ function validateActionLink(v: unknown, path: string, errors: string[]): boolean
   if (!isNonEmptyString(v.id)) errors.push(`${path}.id: required, non-empty string`);
   if (!isNonEmptyString(v.label)) errors.push(`${path}.label: required, non-empty string`);
   if (!isNonEmptyString(v.href)) errors.push(`${path}.href: required, non-empty string`);
+  validateTracking(v, path, errors);
   return errors.length === before;
 }
 
@@ -415,6 +424,7 @@ function validateNavItem(v: unknown, path: string, errors: string[]): v is Chrom
   if (!isNonEmptyString(v.href)) errors.push(`${path}.href: required, non-empty string`);
   checkOptionalString(v.badge, `${path}.badge`, errors);
   checkOptionalBoolean(v.flag, `${path}.flag`, errors);
+  validateTracking(v, path, errors);
   if (v.children !== undefined) {
     if (!Array.isArray(v.children)) errors.push(`${path}.children: must be an array`);
     else v.children.forEach((c, i) => validateLink(c, `${path}.children[${i}]`, errors));
@@ -438,6 +448,7 @@ function validateCta(v: unknown, path: string, errors: string[]): v is ChromeCta
   if (v.variant !== undefined && !["primary", "secondary", "ghost"].includes(v.variant as string)) {
     errors.push(`${path}.variant: must be one of primary, secondary, ghost`);
   }
+  validateTracking(v, path, errors);
   return errors.length === before;
 }
 

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

@@ -33,6 +33,16 @@ export * from "./customization-versioning.js";
 export * from "./customization-scripts.js";
 export * from "./customization-reconcile.js";
 export * from "./chrome.js";
+// Declarative interaction tracking: the data-tot-el / -action / -placement
+// attribute contract, its single emit path, and the ONE delegated click
+// listener both document mounts install. Reads declared attributes only —
+// never rendered content, never form values.
+// See docs/architecture/interaction-tracking-attribute-contract.md.
+export * from "./interaction-tracking.js";
+// `data-tot-el` id derivation: the authoring-time engine that proposes a
+// stable, human-readable IDENTITY from fragment STRUCTURE alone. A proposal
+// engine only — never a runtime fallback, and it derives no `action`.
+export * from "./tracking-id-derivation.js";
 export * from "./candidate-index.js";
 export * from "./extension-contract.js";
 export * from "./integration-capabilities.js";

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

@@ -65,6 +65,7 @@ export * from "./consent-broker.js";
 export * from "./consent-cmp-demand.js";
 export * from "./consent-config.js";
 export * from "./consent-preview.js";
+export * from "./interaction-tracking-gate.js";
 export * from "./candidate-evidence.js";
 export * from "./lifecycle.js";
 export * from "./lifecycle-runtime.js";