From abe740cb696e252855df44b265f0c4b62c7dafaf Mon Sep 17 00:00:00 2001
From: thaisrocine <thais.almeidacc@gmail.com>
Date: Mon, 9 Nov 2026 15:17:28 -0300
Subject: [PATCH 1/4] feat(blocks): host the Deco Analytics tag's source

The tag's code moves to blocks so it is written in one place for every
consumer, while the standalone script stays a build artifact: decocms/analytics
bundles these entries and its collector Worker keeps serving /_dq/a.js to v7,
checkout and sites outside deco. Serving stays in the Worker because one purge
fixes the whole fleet; a script inlined into each site's build would need a
dependency bump per repo.

The move is byte-for-byte: built from this folder (and from the packed tarball)
with the esbuild the collector uses, all ten bundles hash identically to what
production serves today, so no site receives a different script.

Two things keep it that way. The folder's tsconfig.json sets strict and ships
with src, because without it esbuild drops the "use strict" every production
bundle opens with. Biome formats the folder but neither lints it nor organizes
its imports: reordering imports reordered the core bundle, and the lint fixes
rewrite size-tuned code. tag.test.ts bundles every entry and fails if anything
outside the folder reaches the tag.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                                     |   1 +
 biome.json                                    |   8 +
 knip.json                                     |   6 +-
 .../src/v8/analytics/runtime/globals.d.ts     |  36 +
 .../src/v8/analytics/runtime/modules/click.ts |  54 ++
 .../v8/analytics/runtime/modules/commerce.ts  |  71 ++
 .../v8/analytics/runtime/modules/consent.ts   | 150 ++++
 .../src/v8/analytics/runtime/modules/deco.ts  | 207 ++++++
 .../analytics/runtime/modules/engagement.ts   | 140 ++++
 .../v8/analytics/runtime/modules/errors.ts    | 217 ++++++
 .../v8/analytics/runtime/modules/heatmap.ts   | 360 +++++++++
 .../v8/analytics/runtime/modules/vitals.ts    | 126 ++++
 .../src/v8/analytics/runtime/src/guards.ts    |  70 ++
 .../src/v8/analytics/runtime/src/index.ts     | 606 +++++++++++++++
 .../src/v8/analytics/runtime/src/queue.ts     |  40 +
 .../src/v8/analytics/runtime/src/trim.ts      |  39 +
 .../v8/analytics/runtime/view/heat-core.ts    | 335 +++++++++
 .../src/v8/analytics/runtime/view/view.ts     | 596 +++++++++++++++
 .../blocks/src/v8/analytics/shared/anchor.ts  | 171 +++++
 .../src/v8/analytics/shared/contract.ts       | 691 ++++++++++++++++++
 packages/blocks/src/v8/analytics/tag.test.ts  |  93 +++
 .../blocks/src/v8/analytics/tsconfig.json     |  14 +
 22 files changed, 4030 insertions(+), 1 deletion(-)
 create mode 100644 packages/blocks/src/v8/analytics/runtime/globals.d.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/modules/click.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/modules/commerce.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/modules/consent.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/modules/deco.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/modules/engagement.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/modules/errors.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/modules/heatmap.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/modules/vitals.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/src/guards.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/src/index.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/src/queue.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/src/trim.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/view/heat-core.ts
 create mode 100644 packages/blocks/src/v8/analytics/runtime/view/view.ts
 create mode 100644 packages/blocks/src/v8/analytics/shared/anchor.ts
 create mode 100644 packages/blocks/src/v8/analytics/shared/contract.ts
 create mode 100644 packages/blocks/src/v8/analytics/tag.test.ts
 create mode 100644 packages/blocks/src/v8/analytics/tsconfig.json

diff --git a/CLAUDE.md b/CLAUDE.md
index 9d09ddf3..94712394 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -144,6 +144,7 @@ v7's pure helpers, for sites moved from v7: each one gives v7's output (latest 7
 
 ### Key boundaries
 
+- **The Deco Analytics tag's source lives in `src/v8/analytics/` (`runtime/`, `shared/`) and is not a package module**: no export, and nothing in the runtime imports it. decocms/analytics bundles each entry with esbuild into a standalone script that its collector Worker serves at `/_dq/a.js` to every site (v7, checkout and sites outside deco included); `AnalyticsScript` only renders the `<script>` tag. The folder's `tsconfig.json` ships with `src` and sets `strict`, so the consumer's bundles keep the `"use strict"` the production ones carry. Biome formats the folder but doesn't lint it or organize its imports: those fixes change the bytes every site is served (reordering imports reorders the bundle). `analytics/tag.test.ts` bundles every entry and holds that nothing outside the folder reaches it. Until decocms/analytics builds from this package, its own `runtime/` is what production serves: change both.
 - **The runtime never imports the protocol or the CLI.** `src/v8` modules import only each other (no Node built-ins, no React at runtime except `/analytics`); `src/v8/browserBundle.test.ts` proves it with a real esbuild bundle. The one exception is `#async-store` (package.json `imports`): its `node`/`workerd`/`bun`/`deno` condition loads `src/async/node.ts` (`AsyncLocalStorage` from `node:async_hooks`, so Workers need `nodejs_compat`), its `default` `src/async/default.ts` (a global `AsyncLocalStorage` if the runtime has one, else none). The CLI may import the protocol.
 - **Clients depend only on `@decocms/blocks`**, with no peers and no framework binding. A client takes settings as arguments (no env reads), never caches, has no hooks, converters or `"use client"` code: those belong in the site's platform template (`tests/upstream-clients.conformance.test.ts`).
 - **Platform helpers live in the platform's package, not in blocks.** Besides its client, an `apps-*` package may export pure helper subpaths that compose with `@decocms/blocks` (`@decocms/apps-vtex/image` and `@decocms/apps-shopify/image`: image URL providers for `createImageUrl`). Pure: no network, no React, no env reads, no runtime imports (`tests/upstream-helpers.guardrail.test.ts`, which also bundles each for a browser and workerd). The product owner's call: `@decocms/blocks` holds framework code only, nothing that knows VTEX, Shopify or another commerce platform. Bindings never depend on an `apps-*` package: sites wire the helper in.
diff --git a/biome.json b/biome.json
index 72a60cc5..efea8f66 100644
--- a/biome.json
+++ b/biome.json
@@ -43,6 +43,14 @@
     ]
   },
   "overrides": [
+    {
+      "includes": [
+        "packages/blocks/src/v8/analytics/runtime/**",
+        "packages/blocks/src/v8/analytics/shared/**"
+      ],
+      "linter": { "enabled": false },
+      "assist": { "enabled": false }
+    },
     {
       "includes": [
         "packages/apps-*/src/**",
diff --git a/knip.json b/knip.json
index 5c008b78..dd1bc460 100644
--- a/knip.json
+++ b/knip.json
@@ -46,7 +46,11 @@
       ],
       "entry": [
         "src/v8/cli/main.ts",
-        "src/v8/cli/__tests__/folderCdn.ts"
+        "src/v8/cli/__tests__/folderCdn.ts",
+        "src/v8/analytics/runtime/src/index.ts",
+        "src/v8/analytics/runtime/modules/*.ts",
+        "src/v8/analytics/runtime/view/*.ts",
+        "src/v8/analytics/shared/*.ts"
       ]
     },
     "packages/compat-v7": {
diff --git a/packages/blocks/src/v8/analytics/runtime/globals.d.ts b/packages/blocks/src/v8/analytics/runtime/globals.d.ts
new file mode 100644
index 00000000..9cf9f4d4
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/globals.d.ts
@@ -0,0 +1,36 @@
+// The seam optional modules attach through. Declared once, ambiently, so a module does
+// not have to redeclare `window` as `any` just to reach it — which is what commerce.ts
+// did, and it disabled every other type check in the file as a side effect.
+interface Window {
+  __dqRegister?: (
+    fn: (
+      enqueue: EnqueueFn,
+      api: Record<string, unknown>,
+      /** Register work to run just BEFORE the last flush of a page load. A module that
+       *  only knows its value at the end — scroll depth, the vitals, accumulated error
+       *  repeats — contributes here rather than spending a request of its own. */
+      onFinal: (hook: () => void) => void,
+      /** Register work to run when an SPA navigation changes the URL, BEFORE the new
+       *  `$pageview`, with the path being left. A per-view measurement closes its view here. */
+      onRoute: (hook: (prev: string) => void) => void,
+    ) => void,
+  ) => void;
+  __dq?: Record<string, unknown>;
+  __dqAllowAutomation?: boolean;
+  /** Set by `boot()` so a second copy of this bundle on the same page does nothing. Two
+   *  identical script tags both execute -- the browser reuses the cached resource, not the
+   *  execution -- and that is two pageviews for one page load. */
+  __dqBooted?: boolean;
+}
+
+type EnqueueFn = (
+  name: string,
+  props?: Record<string, string | number | boolean>,
+  extra?: Record<string, unknown>,
+  /** Send this event NOW instead of letting it batch. The module that owns an event is the
+   *  only thing that can judge what losing it costs, and core must not learn event names to
+   *  decide -- a name check in core put the word "purchase" in the bundle served to sites
+   *  that do not have the commerce module. Costs one request, so it is for events whose loss
+   *  is not recoverable from anything else: `purchase`, and so far nothing else. */
+  urgent?: boolean,
+) => void;
diff --git a/packages/blocks/src/v8/analytics/runtime/modules/click.ts b/packages/blocks/src/v8/analytics/runtime/modules/click.ts
new file mode 100644
index 00000000..ea4599e6
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/modules/click.ts
@@ -0,0 +1,54 @@
+/** A/B testing interaction capture: per-click telemetry for whichever elements a site
+ *  wants scored against an experiment variant.
+ *
+ *  Not tied to a specific experiment id in the payload -- `enqueue` already merges
+ *  `cfg.x` (the map `setExperiment` builds) into every event, so `exp` on this row is
+ *  free. Carrying it again here would duplicate a column this event already gets by
+ *  riding the same pipe as everything else.
+ *
+ *  `engagement.ts` already tracks outbound/download clicks unconditionally, because
+ *  those are a fixed, small vocabulary. Clicks in general are not: GA4 sends one event
+ *  per click with no cap, which is the shape this module exists to avoid repeating.
+ */
+import { LIMITS } from "../../shared/contract.ts";
+
+const CAPTURE_PHASE: Record<number, string> = {
+  1: "capturing",
+  2: "at_target",
+  3: "bubbling",
+};
+
+window.__dqRegister?.((enqueue) => {
+  // Same reasoning as engagement's outbound cap: an experiment CTA rage-clicked ten
+  // times is one fact about that click, not ten rows.
+  const MAX_CLICKS = 30;
+  let sent = 0;
+
+  addEventListener(
+    "click",
+    (event: MouseEvent) => {
+      if (sent >= MAX_CLICKS) return;
+      const el = event.target as Element | null;
+      if (!el) return;
+      sent++;
+
+      const classList = el.classList ? [...el.classList].slice(0, 5).join(" ") : "";
+
+      enqueue("experiment_click", {
+        capture_phase: CAPTURE_PHASE[event.eventPhase] ?? "none",
+        // Viewport, for reading `page_x`/`page_y` as a fraction of what the visitor could
+        // actually see -- document size, not screen size, is a separate question nobody
+        // asked here.
+        viewport_width: window.innerWidth || document.documentElement.clientWidth || 0,
+        viewport_height: window.innerHeight || document.documentElement.clientHeight || 0,
+        page_x: Math.round(event.pageX),
+        page_y: Math.round(event.pageY),
+        element_type: el.tagName?.toLowerCase() ?? "",
+        element_id: el.id ?? "",
+        element_class: classList.slice(0, LIMITS.valueLen),
+        is_trusted: event.isTrusted,
+      });
+    },
+    { capture: true, passive: true },
+  );
+});
diff --git a/packages/blocks/src/v8/analytics/runtime/modules/commerce.ts b/packages/blocks/src/v8/analytics/runtime/modules/commerce.ts
new file mode 100644
index 00000000..602e452a
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/modules/commerce.ts
@@ -0,0 +1,71 @@
+/** Commerce is a module, not core.
+ *
+ *  These helpers are sugar over `track`: `addToCart({...})` and
+ *  `track("add_to_cart", {...})` produce the identical event. Their value is type safety
+ *  and IDE discovery, which is a build-time concern — so the core has no reason to carry
+ *  them, and a site that never sells anything has no reason to download them.
+ *
+ *  Event names are GA4's, because the deco framework already emits those and existing
+ *  experiment queries already join on them. Whoever prescribes a different vocabulary
+ *  fragments the market rather than unifying it — Segment calls this `Product Added`. */
+type Primitive = string | number | boolean;
+type Props = Record<string, Primitive>;
+
+type Money = {
+  value?: number;
+  currency?: string;
+  items?: number;
+  itemIds?: string[];
+  props?: Props;
+};
+
+window.__dqRegister?.((enqueue, api: Record<string, unknown>) => {
+  const of =
+    (name: string) =>
+    (m: Money = {}) =>
+      enqueue(name, m.props, {
+        value: m.value,
+        currency: m.currency,
+        items_count: m.items,
+        item_ids: m.itemIds,
+      });
+
+  api.viewItemList = of("view_item_list");
+  api.selectItem = of("select_item");
+  api.viewItem = of("view_item");
+  api.addToCart = of("add_to_cart");
+  api.removeFromCart = of("remove_from_cart");
+  api.beginCheckout = of("begin_checkout");
+
+  /** transaction_id is what stops a purchase being counted twice when the customer
+   *  reloads the confirmation page — the most common e-commerce analytics bug, and one
+   *  that lands straight in reported revenue.
+   *
+   *  URGENT, the last argument. Core flushes the first event of a page load and then
+   *  batches until 50 events, `flushMs` (10s), or the page ending — the right trade for a
+   *  scroll depth and the wrong one for money. Most visits are shorter than ten seconds,
+   *  so a purchase in a short session rides entirely on a beacon fired while the page is
+   *  being torn down, and that beacon is what a slow device is worst at. Measured on the CI
+   *  runner, which is slower than a laptop and therefore closer to a real phone: a purchase
+   *  fired and the tab closed stored nothing, intermittently, while passing every time on a
+   *  laptop.
+   *
+   *  The cost is bounded by CONVERSIONS rather than by traffic — at most one extra request
+   *  per visit, on the small fraction of visits that convert. Deliberately not the other
+   *  six: an abandoned cart is a funnel number, and losing a funnel number is not losing
+   *  revenue. A cart that precedes a purchase in the same queue rides along anyway, because
+   *  a flush drains the queue rather than one event. */
+  api.purchase = (m: Money & { transactionId: string }) =>
+    enqueue(
+      "purchase",
+      m.props,
+      {
+        value: m.value,
+        currency: m.currency,
+        items_count: m.items,
+        item_ids: m.itemIds,
+        transaction_id: m.transactionId,
+      },
+      true,
+    );
+});
diff --git a/packages/blocks/src/v8/analytics/runtime/modules/consent.ts b/packages/blocks/src/v8/analytics/runtime/modules/consent.ts
new file mode 100644
index 00000000..0fceabe3
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/modules/consent.ts
@@ -0,0 +1,150 @@
+/** Consent, and the stable identifier it unlocks.
+ *
+ *  At tier 0 — the default, and what every site runs today — there is no consent to ask
+ *  for and nothing here does anything. Identity is an HMAC over a salt the Worker rotates
+ *  and deletes every day, which is what makes the collector cookieless and is the same
+ *  design Plausible ships. Its cost is that the same person is a new identifier tomorrow,
+ *  so retention cannot be measured at all.
+ *
+ *  Tier 1 buys that back, and only where a visitor has actually agreed. We deliberately do
+ *  NOT ship a banner: every serious storefront already runs a CMP — farmrio loads OneTrust,
+ *  898 KB of it — and a second prompt would ask the visitor twice while leaving it
+ *  ambiguous which consent governs. So this listens for the consent that already exists
+ *  and adds an explicit call for sites whose banner is homegrown.
+ *
+ *  Three sources, in the order a site is likely to have them:
+ *    1. `__dq.consent(true|false)` — explicit, and always wins
+ *    2. IAB TCF v2 `__tcfapi` — what OneTrust and Cookiebot expose
+ *    3. Google Consent Mode — `analytics_storage` on the dataLayer, for GTM sites
+ */
+
+const KEY = "_dq_cid";
+
+type Listener = (granted: boolean) => void;
+const listeners: Listener[] = [];
+let granted: boolean | null = null; // null = not yet known, which is not "no"
+
+/** A random identifier, not derived from anything about the visitor. It is a label the
+ *  browser carries, so it can be deleted by the visitor and is meaningless anywhere else.
+ *  The Worker hashes it with the site before storing, so the same browser is a different
+ *  identifier on each customer's site — without that we would have built the cross-client
+ *  identity graph that tier 0 exists to avoid. */
+function mint(): string {
+  const b = new Uint8Array(16);
+  (globalThis.crypto ?? ({} as Crypto)).getRandomValues?.(b);
+  return Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+}
+
+function store(): Storage | null {
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  } // blocked in some privacy modes
+}
+
+/** The stable id, or "" when there is no consent. Reading this never creates one: an id
+ *  minted before consent arrived is a persistent identifier set without permission, which
+ *  is the exact thing consent is being asked about. */
+export function clientId(): string {
+  if (granted !== true) return "";
+  const s = store();
+  if (!s) return "";
+  let v = "";
+  try {
+    v = s.getItem(KEY) ?? "";
+  } catch {
+    return "";
+  }
+  if (!v || v.length !== 32) {
+    v = mint();
+    try {
+      s.setItem(KEY, v);
+    } catch {
+      return "";
+    }
+  }
+  return v;
+}
+
+/** Withdrawal has to erase, not merely stop sending. A visitor who says no and still finds
+ *  the identifier in their browser was not given a choice, they were given a checkbox. */
+function forget() {
+  try {
+    store()?.removeItem(KEY);
+  } catch {
+    /* nothing to do about it */
+  }
+}
+
+export function setConsent(v: boolean) {
+  if (granted === v) return;
+  granted = v;
+  if (!v) forget();
+  for (const fn of listeners) {
+    try {
+      fn(v);
+    } catch {
+      /* one listener must not stop another */
+    }
+  }
+}
+
+export function onConsent(fn: Listener) {
+  listeners.push(fn);
+}
+export function consentKnown(): boolean {
+  return granted !== null;
+}
+
+/** Wires up whichever CMP is present. Safe to call when none is: every branch is guarded,
+ *  and a site with no banner simply never grants, which leaves it at tier 0. */
+export function watchConsent(w: any) {
+  // 1. Google Consent Mode. GTM sites push `['consent', 'update', {analytics_storage}]`,
+  //    and the state may already be on the dataLayer before we load.
+  const dl = w.dataLayer;
+  if (Array.isArray(dl)) {
+    const read = (a: any) => {
+      if (a?.[0] === "consent" && (a[1] === "update" || a[1] === "default") && a[2]) {
+        if (a[2].analytics_storage === "granted") setConsent(true);
+        else if (a[2].analytics_storage === "denied") setConsent(false);
+      }
+    };
+    for (const a of dl) read(a);
+    const push = dl.push.bind(dl);
+    dl.push = function (...args: any[]) {
+      try {
+        read(args[0]);
+      } catch {
+        /* keep GTM working */
+      }
+      return push(...args);
+    };
+  }
+
+  // 2. IAB TCF v2. Purpose 1 is "store and access information on a device", which is
+  //    exactly what an identifier in localStorage is — not purpose 8 (measurement), which
+  //    covers what we do with it once stored.
+  if (typeof w.__tcfapi === "function") {
+    try {
+      w.__tcfapi("addEventListener", 2, (data: any, ok: boolean) => {
+        if (!ok || !data) return;
+        if (data.eventStatus !== "tcloaded" && data.eventStatus !== "useractioncomplete") return;
+        setConsent(Boolean(data.purpose?.consents?.[1]));
+      });
+    } catch {
+      /* a CMP that throws is a CMP that has not granted */
+    }
+  }
+}
+
+// Registered like every other module: core exposes the hook, this fills it in. A site at
+// tier 0 downloads none of this — the same rule that keeps `commerce` off a blog.
+window.__dqRegister?.((_enqueue, api: Record<string, unknown>) => {
+  watchConsent(window as any);
+  (window as any).__dqCid = clientId;
+  // Overrides the core no-op, so a homegrown banner has something to call.
+  api.consent = (v: unknown) => setConsent(Boolean(v));
+});
+
+export const CONSENT_KEY = KEY;
diff --git a/packages/blocks/src/v8/analytics/runtime/modules/deco.ts b/packages/blocks/src/v8/analytics/runtime/modules/deco.ts
new file mode 100644
index 00000000..25e523b4
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/modules/deco.ts
@@ -0,0 +1,207 @@
+/** Adapter for deco storefronts.
+ *
+ *  Two jobs, both about not asking a site to instrument twice: read the experiment
+ *  assignment the origin already made, and forward the analytics events the framework
+ *  already dispatches.
+ *
+ *  It reads `deco_segment` rather than the event bus for flags because the cookie is set
+ *  by the origin before any script runs, so the assignment is on the very first event —
+ *  including the pageview. Waiting for the bus would attribute the landing pageview to no
+ *  variant, which is the one event an experiment most needs attributed.
+ */
+import { LIMITS, STOREFRONT_EXP } from "../../shared/contract.ts";
+
+type Props = Record<string, string | number | boolean>;
+
+window.__dqRegister?.((enqueue, api: Record<string, unknown>) => {
+  const setExperiment = api.setExperiment as ((k: string, v: string) => void) | undefined;
+
+  // ---- assignment, from the cookie the origin already set ---------------------
+  //
+  // deco_segment is base64 of URI-encoded JSON: { active: string[], inactiveDrawn: [] }.
+  // It carries flag NAMES and nothing else — see deco/runtime/middleware.ts, which writes
+  // it from `flag.value` as a boolean.
+  //
+  // So both lists matter. `inactiveDrawn` means "evaluated for this visitor and came out
+  // false", which IS the control group: recording only the active flags would leave an
+  // experiment with a treatment arm and no baseline to compare it against, and a
+  // conversion rate with nothing to compare it to is not a result.
+  try {
+    const raw = document.cookie
+      .split(";")
+      .map((c) => c.trim())
+      .find((c) => c.startsWith("deco_segment="));
+    if (raw) {
+      const json = JSON.parse(decodeURIComponent(atob(raw.slice("deco_segment=".length))));
+      const set = (name: string, variant: string) => {
+        // Experiment keys allow hyphens; anything else the Worker normalises and flags.
+        if (name && name.length <= LIMITS.expKeyLen) setExperiment?.(name, variant);
+      };
+      for (const name of json.active ?? []) set(String(name), "on");
+      for (const name of json.inactiveDrawn ?? []) set(String(name), "off");
+    }
+  } catch {
+    // A malformed cookie is a site problem, not a reason to stop collecting.
+  }
+
+  // ---- the side of a Fresh x TanStack split ------------------------------------
+  //
+  // `withABTesting` keeps the side in `_deco_bucket` as `<side>:<percent>` (`worker:50`), set at
+  // the edge before the document reaches the browser, so it too is on the first event. Recorded
+  // as the `storefront` experiment with the names the store Worker stamps on what it sends
+  // through `EdgeIngest` -- the two halves of the funnel only group together if they agree, and
+  // `STOREFRONT_EXP` is where they do. An unknown side is skipped rather than recorded raw: a
+  // third variant nobody emits at the edge would be a funnel with no ruler.
+  try {
+    const raw = document.cookie
+      .split(";")
+      .map((c) => c.trim())
+      .find((c) => c.startsWith(`${STOREFRONT_EXP.cookie}=`));
+    const side = raw
+      ? decodeURIComponent(raw.slice(STOREFRONT_EXP.cookie.length + 1)).split(":")[0]
+      : "";
+    const variant = STOREFRONT_EXP.variants[side];
+    if (variant) setExperiment?.(STOREFRONT_EXP.name, variant);
+  } catch {
+    // Same as above: a bad cookie costs the arm, never the collection.
+  }
+
+  // ---- events, from the bus the framework already has -------------------------
+  //
+  // deco dispatches commerce events in the Google Analytics shape. Mapped to our names
+  // rather than forwarded verbatim: `add_to_cart` here has a typed value column, and
+  // passing GA's nested `ecommerce.items` through as props would put money in a string.
+  const NAME_MAP: Record<string, string> = {
+    view_item: "view_item",
+    view_item_list: "view_item_list",
+    select_item: "select_item",
+    add_to_cart: "add_to_cart",
+    remove_from_cart: "remove_from_cart",
+    begin_checkout: "begin_checkout",
+    purchase: "purchase",
+    search: "$search",
+    view_promotion: "view_promotion",
+    select_promotion: "select_promotion",
+  };
+
+  /** A storefront can hand the bus its products in one of two shapes, and both are deco's.
+   *
+   *  `items` is the GA4 shape `mapProductToAnalyticsItem` builds. `products` is the schema.org
+   *  `Product` itself, which the `DECO` adapter of the Azzas tracking SDK expects and builds the
+   *  GA4 payload from on its own -- the FARM sends every commerce event that way. Reading only
+   *  `items` stored 94k `add_to_cart` from the FARM in five days with not one item id or value:
+   *  the event names arrived, so every panel looked instrumented, and nothing said which product.
+   *
+   *  The id follows `mapProductToAnalyticsItem`: `item_id` is `productID` (the SKU), so a site
+   *  sending either shape lands the same id in `item_ids`. `sku` is the fallback because the
+   *  lighter Product the FARM puts on shelf cards carries `sku` and no `productID`. */
+  const productId = (pr: any) => String(pr?.productID ?? pr?.sku ?? "");
+
+  /** Price of one unit off a schema.org `AggregateOffer`. `lowPrice` is the price the shopper
+   *  sees; the first offer is the fallback for the trimmed Product on shelf cards. */
+  const unitPrice = (pr: any): number | undefined => {
+    const o = pr?.offers;
+    const v = o?.lowPrice ?? o?.offers?.[0]?.price;
+    return typeof v === "number" ? v : undefined;
+  };
+
+  /** Events where `value` means money that moved. A `view_item_list` of 40 cards has no value:
+   *  summing the shelf would put a number in a revenue column that no shopper ever paid. */
+  const VALUED = new Set(["add_to_cart", "remove_from_cart", "begin_checkout", "purchase"]);
+
+  const money = (name: string, p: any) => {
+    const items = p?.items ?? p?.ecommerce?.items;
+    const products = Array.isArray(items) ? undefined : p?.products;
+    const out: Record<string, unknown> = {};
+    if (typeof p?.value === "number") out.value = p.value;
+    if (typeof p?.currency === "string") out.currency = p.currency;
+    if (Array.isArray(items)) {
+      out.items_count = items.length;
+      out.item_ids = items
+        .map((i: any) => String(i?.item_id ?? i?.id ?? ""))
+        .filter(Boolean)
+        .slice(0, LIMITS.itemIds);
+    } else if (Array.isArray(products)) {
+      out.items_count = products.length;
+      out.item_ids = products.map(productId).filter(Boolean).slice(0, LIMITS.itemIds);
+      // Only when the site did not say it, and only on events where a value is money.
+      if (out.value === undefined && VALUED.has(name)) {
+        let sum = 0;
+        let priced = 0;
+        for (const pr of products) {
+          const u = unitPrice(pr);
+          if (u === undefined) continue;
+          sum += u * (typeof pr?.quantity === "number" && pr.quantity > 0 ? pr.quantity : 1);
+          priced++;
+        }
+        // All or nothing: a cart of three with one unpriced item is not worth the two we
+        // could price, and a partial sum would look exactly like a real one.
+        if (priced && priced === products.length) out.value = Math.round(sum * 100) / 100;
+      }
+      const cur = products[0]?.offers?.priceCurrency;
+      if (out.currency === undefined && typeof cur === "string" && out.value !== undefined)
+        out.currency = cur;
+    }
+    if (typeof p?.transaction_id === "string") out.transaction_id = p.transaction_id;
+    return out;
+  };
+
+  /** Subscribe WHENEVER the bus shows up, not only if it is already there.
+   *
+   *  This was `window?.DECO?.events?.subscribe?.(…)` — one attempt, optional-chained, no retry —
+   *  and it lost every commerce event on a real site. React hoists `<script async>` into `<head>`
+   *  regardless of where the component sits in the tree: measured on igor-tanstack.deco.site,
+   *  our tag is at byte 200 and the inline block that defines `DECO.events` is at byte 1905, in
+   *  the body. So this ran first, found nothing, and never tried again. Two `view_promotion`
+   *  events fired and went nowhere, with no error and a page that looked perfectly instrumented.
+   *
+   *  NOTHING IS LOST BY ARRIVING LATE, which is what makes polling the right answer rather than
+   *  a patch: the bus keeps a `_q` and `subscribe` replays it to a new subscriber. So the only
+   *  requirement is to subscribe eventually.
+   *
+   *  Bounded at ten seconds. A page that has not defined the bus by then does not have one —
+   *  a site without the deco runtime is a normal thing, and an interval left running forever
+   *  would be this module's parting gift to every such page.
+   */
+  const onBus = (fn: (event: any) => void) => {
+    const w = (globalThis as any).window;
+    const now = w?.DECO?.events;
+    if (typeof now?.subscribe === "function") {
+      now.subscribe(fn);
+      return;
+    }
+    let tries = 0;
+    const iv = setInterval(() => {
+      const bus = (globalThis as any).window?.DECO?.events;
+      if (typeof bus?.subscribe === "function") {
+        clearInterval(iv);
+        bus.subscribe(fn);
+        return;
+      }
+      if (++tries >= 100) clearInterval(iv);
+    }, 100);
+  };
+
+  onBus((event: any) => {
+    if (!event?.name) return;
+
+    // The bus replays a synthetic "deco" event on subscribe, carrying the same flags the
+    // cookie already gave us. Ignored rather than mapped: it is not something a visitor
+    // did, and turning it into an event would put a row in the table for every page load
+    // that means nothing.
+    if (event.name === "deco") return;
+
+    const mapped = NAME_MAP[event.name];
+    if (!mapped) return; // unknown bus events are not forwarded blind
+
+    const p = event.params ?? {};
+    const props: Props = {};
+    // The schema.org shape carries the list on the product, not on the event.
+    const list = p.item_list_name ?? p.products?.[0]?.item_list_name;
+    if (typeof list === "string") props.list = list.slice(0, 200);
+    if (typeof p.search_term === "string")
+      props.term = p.search_term.trim().toLowerCase().slice(0, 200);
+
+    enqueue(mapped, props, money(event.name, p));
+  });
+});
diff --git a/packages/blocks/src/v8/analytics/runtime/modules/engagement.ts b/packages/blocks/src/v8/analytics/runtime/modules/engagement.ts
new file mode 100644
index 00000000..0c6452e6
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/modules/engagement.ts
@@ -0,0 +1,140 @@
+/** Enhanced measurement: the four things every site wants counted and nobody wants to
+ *  instrument by hand — how far people scroll, which links take them away, what they
+ *  download, and what they search for.
+ *
+ *  The reason this is a MODULE and not core: it is automatic, and automatic collection is
+ *  where an analytics SDK gets expensive without anyone deciding to spend. A blog does not
+ *  need outbound-click tracking and should not download the code for it.
+ *
+ *  Every counter here is bounded on purpose. GA4 fires a scroll event at each of four
+ *  thresholds, which is four events per page for one number; it sends an outbound event
+ *  per click including the same link clicked twice; and none of it is capped. At 400M
+ *  events a month those choices are the difference between a bill you planned and one you
+ *  did not.
+ */
+import { LIMITS } from "../../shared/contract.ts";
+
+window.__dqRegister?.((enqueue, _api: Record<string, unknown>, onFinal, onRoute) => {
+  // ---- scroll ---------------------------------------------------------------
+  // One event per page load carrying the DEEPEST point reached, not one per threshold
+  // crossed. Four events to communicate a single number is the shape GA4 chose, and the
+  // extra three carry no information the fourth does not.
+  let deepest = 0;
+  let scrollSent = false;
+
+  const depth = () => {
+    const doc = document.documentElement;
+    const viewport = window.innerHeight || doc.clientHeight || 0;
+    const total = Math.max(doc.scrollHeight, document.body?.scrollHeight ?? 0);
+    if (total <= viewport) return 100; // nothing to scroll: the page was fully seen
+    const seen = (window.scrollY || doc.scrollTop || 0) + viewport;
+    return Math.max(0, Math.min(100, Math.round((seen / total) * 100)));
+  };
+
+  // Passive: a scroll listener that can block scrolling is a listener that made the site
+  // worse to use, which is the one thing analytics must never do.
+  addEventListener(
+    "scroll",
+    () => {
+      const d = depth();
+      if (d > deepest) deepest = d;
+    },
+    { passive: true },
+  );
+
+  // `prev` is set when an SPA route closes the view: the path it was measured on goes with it,
+  // and the live document is already the next route's, so only what was tracked counts.
+  function sendScroll(prev?: string) {
+    if (scrollSent) return;
+    const d = prev ? deepest : Math.max(deepest, depth());
+    // Rounded to a bucket. The difference between 61% and 62% is noise, and storing it
+    // raw would put a hundred distinct values into a LowCardinality dictionary for no
+    // question anyone asks.
+    const bucket = Math.min(100, Math.round(d / 25) * 25);
+    scrollSent = true;
+    enqueue("$scroll", { depth: String(bucket) }, prev ? { path: prev } : undefined);
+  }
+
+  // ---- outbound links and downloads -----------------------------------------
+  const DOWNLOAD_EXT =
+    /\.(pdf|zip|rar|7z|gz|tar|csv|xlsx?|docx?|pptx?|txt|dmg|exe|pkg|apk|mp3|mp4|mov|avi|wav)($|\?)/i;
+
+  // Same link clicked twice in one page load is one fact, not two. Rage-clicking a slow
+  // link is the common case and it is exactly the case that would inflate the number.
+  const clicked = new Set<string>();
+  const MAX_CLICKS = 20;
+
+  addEventListener(
+    "click",
+    (e) => {
+      const el = (e.target as Element | null)?.closest?.("a[href]") as HTMLAnchorElement | null;
+      if (!el) return;
+
+      const href = el.href;
+      if (!href || href.startsWith("javascript:")) return;
+
+      let url: URL;
+      try {
+        url = new URL(href, location.href);
+      } catch {
+        return;
+      }
+      if (url.protocol !== "http:" && url.protocol !== "https:") return;
+
+      if (clicked.size >= MAX_CLICKS || clicked.has(href)) return;
+
+      const isDownload =
+        el.hasAttribute("download") || DOWNLOAD_EXT.test(url.pathname + url.search);
+      const isOutbound = url.host !== location.host;
+      if (!isDownload && !isOutbound) return;
+
+      clicked.add(href);
+      // The URL is the whole point of the event, so it gets the path budget rather than the
+      // value budget — a truncated destination answers nothing.
+      const target = (url.host + url.pathname).slice(0, LIMITS.pathLen);
+      enqueue(isDownload ? "$download" : "$outbound", { target });
+    },
+    { capture: true, passive: true },
+  );
+
+  // ---- site search ----------------------------------------------------------
+  // A closed list of parameter names, for the same reason the campaign vocabulary is
+  // closed: an open one lets any query string mint a dimension value. These are the ones
+  // that actually appear on storefronts.
+  const SEARCH_PARAMS = ["q", "s", "search", "query", "termo", "busca", "keyword"];
+
+  (function searchOnce() {
+    try {
+      const qs = new URLSearchParams(location.search);
+      for (const key of SEARCH_PARAMS) {
+        const term = qs.get(key);
+        if (!term) continue;
+        enqueue("$search", {
+          // Lowercased and trimmed so "Tenis", "tenis " and "tenis" are one term rather
+          // than three rows in a top-searches report.
+          term: term.trim().toLowerCase().slice(0, LIMITS.valueLen),
+          param: key,
+        });
+        return;
+      }
+    } catch {
+      /* a malformed query string is not worth breaking collection over */
+    }
+  })();
+
+  // ---- flush ----------------------------------------------------------------
+  // Scroll depth is only known when the visitor leaves. Core runs this immediately
+  // before its own last flush, so the event rides out with everything else instead of
+  // buying a request of its own — three modules each flushing cost three requests for
+  // what is one visit's worth of data.
+  onFinal(() => sendScroll());
+  // One `$scroll` per VIEW. Before this, an SPA's route 2 inherited route 1's depth and the
+  // whole visit sent a single event at the end, attributed to whichever path was last. A
+  // query-string change on the same path is the same view, as it is for core's pageview.
+  onRoute?.((prev) => {
+    if (prev === location.pathname) return;
+    sendScroll(prev);
+    deepest = 0;
+    scrollSent = false;
+  });
+});
diff --git a/packages/blocks/src/v8/analytics/runtime/modules/errors.ts b/packages/blocks/src/v8/analytics/runtime/modules/errors.ts
new file mode 100644
index 00000000..4ac108fc
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/modules/errors.ts
@@ -0,0 +1,217 @@
+/** Automatic error capture.
+ *
+ *  `captureException` in core only ever sees what a site already wrapped in try/catch,
+ *  which is the minority of what breaks. This module attaches the two listeners that
+ *  see the rest, and does the two things that separate an error product from an error
+ *  log: it gives every error a stable fingerprint so repeats group, and it collapses a
+ *  repeating error into one event with a count instead of one event per occurrence.
+ *
+ *  That second part is not an optimisation. A render loop throwing on every frame is
+ *  the normal shape of a bad deploy; without collapsing, one visitor's broken tab sends
+ *  thousands of events, the queue drops the rest of their session, and the bill and the
+ *  data are both wrong.
+ */
+import { LIMITS } from "../../shared/contract.ts";
+
+type Props = Record<string, string | number | boolean>;
+
+window.__dqRegister?.((enqueue, api: Record<string, unknown>, onFinal) => {
+  // Volatile parts of a message are what stop repeats grouping: ids, timestamps, URLs
+  // and offsets differ per occurrence while the fault is identical. Strip them before
+  // hashing, keep the original message on the event as a sample.
+  const stable = (msg: string) =>
+    msg
+      .replace(/https?:\/\/[^\s)'"]+/g, "<url>")
+      .replace(/\b[0-9a-f]{8,}\b/gi, "<hex>")
+      .replace(/\b\d[\d.,]*\b/g, "<n>")
+      .replace(/['"][^'"]{0,80}['"]/g, "<str>")
+      .slice(0, 200);
+
+  // A file path is the same fault whether it arrives absolute, with a cache-busting
+  // query, or with a hash fragment.
+  const cleanFile = (f: string) => {
+    if (!f) return "";
+    try {
+      const u = new URL(f, location.href);
+      return (u.origin === location.origin ? "" : u.origin) + u.pathname;
+    } catch {
+      return f.split("?")[0].split("#")[0];
+    }
+  };
+
+  // A URL in a message or a stack keeps its origin and path and loses its query and fragment:
+  // `fetch failed for /api/cart?email=...&token=...` is the fault, the values are a visitor's.
+  // A frame's trailing `:line:col` survives, since it is what points at the fault.
+  const noQuery = (s: string) =>
+    s.replace(
+      /([a-z][\w+.-]*:\/\/[^\s?#()'"]*)[?#][^\s()'"]*?(?=:\d+:\d+(?![^\s)])|[\s()'"]|$)/gi,
+      "$1",
+    );
+
+  // FNV-1a with a murmur3 finaliser. The finaliser matters: without it the low bits are
+  // just an XOR of the input's low bits, and near-identical inputs land in adjacent
+  // buckets rather than spread.
+  const fingerprint = (parts: string[]) => {
+    let h = 2166136261;
+    const s = parts.join("|");
+    for (let i = 0; i < s.length; i++) {
+      h ^= s.charCodeAt(i);
+      h = Math.imul(h, 16777619);
+    }
+    h = Math.imul(h ^ (h >>> 16), 2246822507);
+    h = Math.imul(h ^ (h >>> 13), 3266489909);
+    return ((h ^ (h >>> 16)) >>> 0).toString(36).padStart(7, "0");
+  };
+
+  // Seen this page load: fingerprint -> how many times since the last send. A repeating
+  // error increments rather than enqueues.
+  const seen = new Map<string, { n: number; sent: boolean }>();
+  // A hard ceiling on DISTINCT errors per page load. A loop that generates a new
+  // fingerprint each time (a message with an unstrippable varying part) would otherwise
+  // defeat the collapsing entirely, which is the failure mode this guard exists for.
+  const MAX_DISTINCT = 20;
+
+  // OURS = this origin, or a host the site declared as its own in `errorHosts` (served as `er`;
+  // a separate asset CDN, say). Everything else on a storefront is a vendor: a GTM tag, a pixel,
+  // a chat widget. Measured on FILA, New Balance and Umbro, 96-100% of `$error` was a
+  // cross-origin ResourceError -- a dead tag, a 403'd account, an ad blocker -- none of it
+  // actionable here, and between them 18-26% of every event those sites sent.
+  const ours = (u: string) => {
+    try {
+      const x = new URL(u, location.href);
+      return (
+        x.origin === location.origin || ((api.er as string[] | undefined) ?? []).includes(x.host)
+      );
+    } catch {
+      return false;
+    }
+  };
+
+  function report(
+    type: string,
+    message: string,
+    file: string,
+    line: number,
+    stack: string,
+    props?: Props,
+  ) {
+    // Read by the heatmap module: a click followed by an error within a second is an
+    // "error click". On the performance timeline, which is what the click is timed on.
+    // Only OUR faults flag it. Vendor tags boot on the storefront's first interaction, so their
+    // failures land right after the first click -- every header "error click" reproduced on
+    // FILA, New Balance and Umbro was one. The source is the file, else the first stack frame
+    // (a URL followed by :line:col, which a URL quoted in the message is not). "Script error."
+    // and a fault with no source cannot be attributed, so they do not flag.
+    const src = file || (/([a-z][\w+.-]*:\/\/[^\s()]+):\d+:\d+/i.exec(String(stack))?.[1] ?? "");
+    // Not the site's code at all: a script the BROWSER injected -- an in-app browser's bridge
+    // (`iabjs://`, Instagram/Facebook), an extension (`chrome-extension://`, `moz-extension://`,
+    // `safari-web-extension://`). Nothing the site ships can fix it, and it was the largest single
+    // fault on two storefronts after #27 (newbalance: 130 an hour, "Error invoking postMessage:
+    // Java object is gone").
+    if (/^[a-z][\w+.-]*:\/\//i.test(src) && !/^https?:/i.test(src)) return;
+    if (src && message !== "Script error." && ours(src))
+      (window as any).__dqLastErrorTs = performance.now();
+    const fp = fingerprint([type, stable(message), cleanFile(file), String(line)]);
+    const prev = seen.get(fp);
+    if (prev) {
+      prev.n++;
+      return;
+    } // already reported this page load
+    if (seen.size >= MAX_DISTINCT) return; // storm guard
+    seen.set(fp, { n: 1, sent: true });
+
+    enqueue("$error", props, {
+      error_type: (type || "Error").slice(0, 40),
+      error_fingerprint: fp,
+      error_message: noQuery(String(message ?? "")).slice(0, LIMITS.valueLen),
+      error_file: cleanFile(file).slice(0, LIMITS.pathLen),
+      error_line: Number(line) || 0,
+      error_count: 1,
+      error_stack: noQuery(String(stack ?? "")).slice(0, LIMITS.errorEventBytes),
+    });
+  }
+
+  // Repeats accumulated after the first report are sent once, at the end, as a single
+  // event carrying the count. One event per thousand occurrences, and the thousand is
+  // still visible.
+  function flushRepeats() {
+    let any = false;
+    for (const [fp, rec] of seen) {
+      if (rec.n <= 1) continue;
+      enqueue("$error", undefined, {
+        error_fingerprint: fp,
+        error_type: "repeat",
+        error_count: rec.n - 1,
+        error_message: "",
+      });
+      rec.n = 1;
+      any = true;
+    }
+    void any;
+  }
+  // Ordering, not a second request: core runs this BEFORE its final flush, so the
+  // repeats are in the queue when that flush happens. Enqueueing after it used to
+  // report eight occurrences as one; flushing again to compensate cost a request.
+  onFinal(flushRepeats);
+
+  addEventListener(
+    "error",
+    (e: any) => {
+      // A failed <img>/<script>/<link> also fires "error" on window, with no `error`
+      // object and the element as target. It is a real fault worth recording, but it is
+      // not an exception and must not be reported as one.
+      if (!e?.error && e?.target && e.target !== window) {
+        const el = e.target;
+        // `.href` on an SVG element is an SVGAnimatedString, NOT a string — so a failing
+        // `<use href="/sprite.svg#icon">` used to be reported as
+        // `/[object%20SVGAnimatedString]`, which names no resource and masks which sprite
+        // actually failed (seen live on a storefront whose icons are one `<use>` sprite).
+        // `.src` has the same shape on SVGScriptElement.
+        const raw = el.src || el.href || "";
+        const src: string = typeof raw === "string" ? raw : (raw.baseVal ?? "");
+        // A vendor's asset failing is the vendor's problem (see `ours`): dropped, not reported.
+        // Ours -- our chunks, our sprite, a declared `errorHosts` CDN -- is a real fault.
+        if (!src || !ours(src)) return;
+        report(
+          "ResourceError",
+          `failed to load ${el.tagName?.toLowerCase?.() ?? "resource"}`,
+          src,
+          0,
+          "",
+        );
+        return;
+      }
+      report(
+        e?.error?.name ?? "Error",
+        e?.message ?? String(e?.error ?? "error"),
+        e?.filename ?? "",
+        e?.lineno ?? 0,
+        e?.error?.stack ?? "",
+      );
+    },
+    true,
+  ); // capture phase: resource errors do not bubble
+
+  addEventListener("unhandledrejection", (e: any) => {
+    const r = e?.reason;
+    report(
+      r?.name ?? "UnhandledRejection",
+      r?.message ?? String(r ?? "rejected"),
+      r?.fileName ?? "",
+      r?.lineNumber ?? 0,
+      r?.stack ?? "",
+    );
+  });
+
+  // Same fingerprinting for the manual path, so an error caught by the site and the
+  // same error escaping uncaught land in one group rather than two.
+  api.captureException = (err: any, props?: Props) =>
+    report(
+      err?.name ?? "Error",
+      err?.message ?? String(err),
+      err?.fileName ?? "",
+      err?.lineNumber ?? 0,
+      err?.stack ?? "",
+      props,
+    );
+});
diff --git a/packages/blocks/src/v8/analytics/runtime/modules/heatmap.ts b/packages/blocks/src/v8/analytics/runtime/modules/heatmap.ts
new file mode 100644
index 00000000..eb1bf2ea
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/modules/heatmap.ts
@@ -0,0 +1,360 @@
+/** Heatmaps: where people click, how far they scroll and where their attention goes, as ONE
+ *  `$heatmap` event per page view.
+ *
+ *  Each view (a document load, or an SPA route change to a new path) gets a random `view_id`, kept
+ *  in memory only, so this works at tier 0 with no storage. Every emission is CUMULATIVE for its
+ *  view -- on `visibilitychange: hidden`, on `pagehide` and on route change -- and the warehouse
+ *  keeps the last one per view (`argMax(..., ts)`). That makes a lost early beacon harmless and a
+ *  page that is hidden and shown five times one view, not five.
+ *
+ *  It rides core's flushes, so it never spends a request of its own.
+ *
+ *  Costs on the visitor's main thread, all bounded:
+ *    - click (capture, passive): one getBoundingClientRect on the anchor, a parent walk with
+ *      getComputedStyle for the fixed/sticky flag, sibling counts. Read in the CAPTURE phase,
+ *      before the site's own handlers have mutated anything, so the layout read finds a clean
+ *      layout instead of forcing one. No serialisation.
+ *    - scroll (passive): at most one rAF per frame; `scrollHeight` at most once a second.
+ *    - sections: one IntersectionObserver, callbacks off the input path.
+ *  Every handler is wrapped: a failure here means "heatmap stopped", never "the page broke".
+ *
+ *  Never sent: text, input values, href/src, classes, coordinates of untrusted events.
+ */
+import { anchorOf, rootOf, pathOf, cyrb53, fsRootName } from "../../shared/anchor.ts";
+
+window.__dqRegister?.((enqueue, cfg: Record<string, any>, onFinal, onRoute) => {
+  const w = window as any,
+    d = document,
+    now = () => performance.now();
+  // Never runs where a visitor types who they are or pays.
+  const DENY = /^\/(checkout|account|login)(\/|$)|^\/(api\/io|pvt)\//i;
+
+  let on = false,
+    vid = "",
+    path = "",
+    t0 = 0,
+    last = 0,
+    input = 0,
+    vis = false,
+    raf = 0,
+    dhAt = 0;
+  let vw = 0,
+    vh = 0,
+    top = 0,
+    dh = 0,
+    sd = 0,
+    am = 0;
+  let roots: Map<string, number>,
+    at: number[],
+    ss: Map<number, number>,
+    seen: Set<number>,
+    clicks: any[][];
+  let burst: any,
+    known: WeakSet<Element>,
+    idxOf: WeakMap<Element, number>,
+    sent = "",
+    sentAm = 0;
+  // Clicks awaiting a dead-click verdict. ANY reaction clears all of them: one DOM mutation, a
+  // scroll, a route change or focus moving into a text field answers every click before it.
+  const pending = new Set<any>();
+  const react = () => {
+    pending.clear();
+    mo.disconnect();
+  };
+  const mo = new MutationObserver(react);
+
+  const idx = (id: string) => {
+    if (!id) return -1;
+    let i = roots.get(id);
+    if (i === undefined) {
+      if (roots.size >= 32) return -1;
+      roots.set(id, (i = roots.size));
+    }
+    return i;
+  };
+  const guard =
+    (f: (...a: any[]) => void) =>
+    (...a: any[]) => {
+      try {
+        f(...a);
+      } catch {
+        /* heatmap stops, page lives */
+      }
+    };
+  // Every listener goes through here: guarded, passive unless told otherwise.
+  const listen = (
+    t: string,
+    f: (e: any) => void,
+    o: AddEventListenerOptions = { passive: true },
+    on: EventTarget = w,
+  ) => on.addEventListener(t, guard(f), o);
+
+  // ---- time: active ms credited to the viewport position it was spent on --------------------
+  // Active = tab visible AND some input in the last 30 s, so an idle background tab does not
+  // paint the hero red. Time between two ticks is credited to where the viewport WAS.
+  const tick = () => {
+    const n = now(),
+      act = Math.min(n, input + 3e4) - last;
+    if (vis && act > 0 && dh) {
+      am += act;
+      for (
+        let i = Math.floor((top * 40) / dh),
+          e = Math.min(39, Math.floor(((top + vh - 1) * 40) / dh));
+        i <= e;
+        i++
+      )
+        at[i] = (at[i] || 0) + act;
+      for (const i of seen) ss.set(i, ss.get(i)! + act);
+    }
+    last = n;
+    vis = d.visibilityState == "visible";
+    vw = innerWidth;
+    vh = innerHeight;
+    top = scrollY;
+    if (n - dhAt > 1e3) {
+      const h = d.documentElement.scrollHeight;
+      dhAt = n;
+      if (h > dh) {
+        dh = h;
+        observe(d.body);
+      }
+    }
+    sd = Math.max(sd, dh ? Math.min(100, Math.round(((top + vh) * 100) / dh)) : 100);
+  };
+  const poke = () => {
+    const n = now();
+    if (on && n - input > 3e4) tick();
+    input = n;
+  };
+
+  // ---- sections: Deco sections and FastStore component roots, the same roots clicks use -----
+  const io = new IntersectionObserver(
+    guard((es: IntersectionObserverEntry[]) => {
+      if (!on) return;
+      tick();
+      for (const e of es) {
+        const i = idxOf.get(e.target)!;
+        if (i < 0) continue;
+        if (e.intersectionRatio >= 0.5 || e.intersectionRect.height >= 300) {
+          seen.add(i);
+          ss.set(i, ss.get(i) || 0);
+        } else seen.delete(i);
+      }
+    }),
+    { threshold: [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1] },
+  );
+  // Top-down to the first root on each branch: visits the page scaffolding, not the inside of
+  // every component. Re-run when the document grows, which is when lazy sections appear.
+  const observe = (p: Element, k = 0) => {
+    for (const c of p?.children ?? []) {
+      if (k++ > 3e3) return;
+      if (c.matches("section[data-manifest-key]") || fsRootName(c)) {
+        if (!known.has(c)) {
+          known.add(c);
+          idxOf.set(c, idx(rootOf(c)[1]));
+          io.observe(c);
+        }
+      } else observe(c, k);
+    }
+  };
+
+  // ---- view lifecycle -----------------------------------------------------------------------
+  const start = () => {
+    path = location.pathname;
+    // Sampled ONCE per view: per-event sampling overcounts visitors (2026-08-19).
+    on = cfg.h !== 0 && !DENY.test(path) && Math.random() < (cfg.hr ?? 1);
+    const r = crypto.getRandomValues(new Uint32Array(2));
+    vid = ((r[0] & 0x1fffff) * 4294967296 + r[1]).toString(36);
+    cfg.hv = on ? vid : ""; // read by vitals, for the INP A/B by view
+    t0 = last = input = now();
+    dhAt = -1e4;
+    dh = sd = am = 0;
+    burst = 0;
+    sent = "";
+    notes = [];
+    roots = new Map();
+    at = [];
+    ss = new Map();
+    seen = new Set();
+    clicks = [];
+    // Root indices are per view: an SPA view re-observes from scratch with a fresh dictionary.
+    io.disconnect();
+    known = new WeakSet();
+    idxOf = new WeakMap();
+    if (!on) return;
+    tick();
+    // An SPA view starts before its new DOM exists; look again once it has rendered.
+    setTimeout(
+      guard(() => {
+        if (on) {
+          tick();
+          dh = 0;
+          dhAt = -1e4;
+          tick();
+        }
+      }),
+      2e3,
+    );
+  };
+
+  const emit = () => {
+    if (!on || cfg.h === 0) return;
+    drain();
+    tick();
+    const a: number[] = [];
+    for (let i = 0; i < at.length; i++) a.push(Math.round((at[i] || 0) / 100));
+    const hm: any = {
+      v: 1,
+      id: vid,
+      vw,
+      vh,
+      dh,
+      sd,
+      am: Math.round(am),
+      at: a,
+      s: [...roots.keys()].map((k) => k.slice(0, 120)),
+      ss: [...ss].map(([i, ms]) => [i, Math.round(ms / 100)]),
+      // Copies: the queue serialises later, and a dead flag set after this must not edit a
+      // record already queued.
+      c: clicks.map((c) => c.slice()),
+    };
+    // Never over the contract's 4 KB for this event: shed the newest clicks first.
+    let j;
+    while ((j = JSON.stringify(hm)).length > 3800 && hm.c.length) hm.c.pop();
+    // Unchanged since the last emission -- `hidden` then `pagehide` on the way out -- is not
+    // sent again: core drains on each, and a second copy would cost a second beacon. "Unchanged"
+    // ignores the few ms of attention that tick between the two; a second of it is a change.
+    const { am: a0, at: a1, ss: a2, ...rest } = hm;
+    const sig = JSON.stringify(rest);
+    if (sig == sent && hm.am - sentAm < 1e3) return;
+    sent = sig;
+    sentAm = hm.am;
+    enqueue("$heatmap", undefined, { path, heatmap: hm });
+  };
+
+  // ---- clicks -------------------------------------------------------------------------------
+  // The listener only takes notes: target, coordinates, scroll, time. The hashing and the layout
+  // reads happen AFTER THE NEXT PAINT (rAF, then a task), so none of it is inside the interaction
+  // INP measures -- and a layout read there would force the layout the click's own :active
+  // styles just invalidated. A route change or the end of the view drains the notes first, so a
+  // click is never attributed to the next view.
+  const clamp = (v: number) => (v > 255 ? 255 : v > 0 ? v | 0 : 0);
+  let notes: any[] = [];
+  const drain = () => {
+    for (const r of notes.splice(0)) record(r);
+  };
+  const record = ([t, cx, cy, sy, n, kb, tok]: any[]) => {
+    if (!t.isConnected) return; // gone before we looked: no anchor to hash
+    const [a, inter] = anchorOf(t),
+      [root, id] = rootOf(a);
+    const el = cyrb53(id + "|" + pathOf(root, a)).toString(36);
+    const r = a.getBoundingClientRect(),
+      ds = scrollY - sy;
+    let f = (inter ? 16 : 0) | (kb ? 32 : 0);
+    for (let p: Element | null = a; p && p != d.body; p = p.parentElement) {
+      const pos = getComputedStyle(p).position;
+      if (pos == "fixed" || pos == "sticky") {
+        f |= 8;
+        break;
+      }
+    }
+    // Where the element was AT THE CLICK: a fixed one does not move with scroll, the rest moved
+    // up by however far the page scrolled since.
+    const top = f & 8 ? r.top : r.top + ds,
+      left = r.left;
+    // A keyboard "click" has no coordinates; it happened on the element, so use its centre.
+    const x = kb ? left + r.width / 2 : cx,
+      y = kb ? top + r.height / 2 : cy;
+    // Rage: 3+ clicks within 1 s, each within 30 px of the first. One record, n = count.
+    if (
+      burst &&
+      burst[0] == el &&
+      n - burst[1] < 1e3 &&
+      Math.hypot(x - burst[2], y - burst[3]) <= 30
+    ) {
+      const c = (tok.c = burst[4]);
+      if (c[7] < 255) c[7]++;
+      if (c[7] > 2) c[8] |= 1;
+      return;
+    }
+    if (clicks.length >= 40) return;
+    const c = (tok.c = [
+      idx(id),
+      el,
+      clamp(((x - left) * 256) / r.width),
+      clamp(((y - top) * 256) / r.height),
+      Math.min(1e3, Math.max(0, Math.round((x * 1e3) / innerWidth))),
+      Math.max(0, Math.round(f & 8 ? y : y + sy)),
+      Math.round(n - t0),
+      1,
+      f | tok.f,
+    ]);
+    clicks.push(c);
+    burst = [el, n, x, y, c];
+  };
+  listen(
+    "click",
+    (e: MouseEvent) => {
+      const t = e.target as Element;
+      // Untrusted clicks are not behaviour; ignored widgets and password fields are never recorded.
+      // A target that is not an Element throws in `closest`, which `guard` turns into "not recorded".
+      if (!on || cfg.h === 0 || !e.isTrusted || t.closest("[data-dq-ignore],input[type=password]"))
+        return;
+      const n = now(),
+        tok: any = { f: 0 };
+      if (!notes.length) requestAnimationFrame(() => setTimeout(guard(drain)));
+      notes.push([t, e.clientX, e.clientY, scrollY, n, e.detail === 0, tok]);
+      // Dead: nothing reacted within 1 s. Error: the errors module reported something in that second.
+      // Armed NOW, since the reaction is what follows the click. Focus moving onto a clicked button
+      // is not a reaction -- every button click does that.
+      if (!pending.size)
+        mo.observe(d, { subtree: true, childList: true, attributes: true, characterData: true });
+      pending.add(tok);
+      setTimeout(
+        guard(() => {
+          if (pending.delete(tok)) tok.f |= 2;
+          if (!pending.size) mo.disconnect();
+          if ((w.__dqLastErrorTs ?? -1) >= n) tok.f |= 4;
+          if (tok.c) tok.c[8] |= tok.f;
+        }),
+        1e3,
+      );
+    },
+    { capture: true, passive: true },
+  );
+
+  listen("scroll", () => {
+    poke();
+    react();
+    if (on && !raf)
+      raf = requestAnimationFrame(
+        guard(() => {
+          raf = 0;
+          on && tick();
+        }),
+      );
+  });
+  for (const t of ["pointerdown", "pointermove", "keydown", "touchstart"]) listen(t, poke);
+  listen("visibilitychange", () => on && tick(), {}, d);
+  // `matches` throws on a non-Element target; `guard` makes that a no-op.
+  listen(
+    "focusin",
+    (e: FocusEvent) =>
+      (e.target as Element).matches("input,textarea,select,[contenteditable]") && react(),
+    {},
+    d,
+  );
+  // A page restored from the back/forward cache is a new view; the old one was emitted on pagehide.
+  listen("pageshow", (e: PageTransitionEvent) => e.persisted && start());
+
+  onFinal(emit);
+  // Core calls this BEFORE the new route's $pageview. A query-string change on the same path
+  // (PLP filters) is not a new view, matching core's replaceState rule.
+  onRoute?.((prev: string) => {
+    if (prev == location.pathname) return;
+    react();
+    emit();
+    start();
+  });
+  start();
+});
diff --git a/packages/blocks/src/v8/analytics/runtime/modules/vitals.ts b/packages/blocks/src/v8/analytics/runtime/modules/vitals.ts
new file mode 100644
index 00000000..1d62685e
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/modules/vitals.ts
@@ -0,0 +1,126 @@
+/** Core Web Vitals, in one event on the way out.
+ *
+ *  Not five events, and not one per metric as they settle. Every vital is only final when
+ *  the page is: LCP can be replaced by a later element, CLS accumulates until the visitor
+ *  leaves, and INP is the worst interaction of the whole visit. Sending them early means
+ *  sending them wrong, and sending each separately means four extra rows carrying one
+ *  number each and repeating the same page, path and visitor.
+ *
+ *  Deliberately not the `web-vitals` library. It is ~2 KB for an attribution model we do
+ *  not use, and this is the part of the payload every visitor downloads.
+ */
+window.__dqRegister?.((enqueue, _api: Record<string, unknown>, onFinal) => {
+  let lcp: number | null = null;
+  let cls = 0;
+  let inp = 0;
+  let sent = false;
+  // The vitals are the DOCUMENT's: LCP, FCP and TTFB belong to the hard load, never to a later
+  // SPA route. They are sent on the way out, when `location` and the heatmap's view id already
+  // name whatever route the visitor ended on, so both are taken here, for the page being
+  // measured. The view id a microtask later, once the heatmap module (after this one in the
+  // bundle) has opened its first view.
+  const path = location.pathname;
+  let hv: unknown;
+  queueMicrotask(() => {
+    hv = _api.hv;
+  });
+
+  // The first moment the page was hidden. A tab opened in the BACKGROUND — ctrl+click
+  // from a listing, "open link in new tab" — keeps accruing largest-contentful-paint
+  // until it is first revealed, so its LCP measures how long the visitor took to look at
+  // the tab, not how long the content took to appear. Measured on a live storefront:
+  // per-page LCP of 152,858 ms and 151,296 ms on product pages (the ones opened from a
+  // listing, naturally) against a 936 ms p75 for the whole site — three samples are
+  // enough to make the per-page panel unreadable.
+  //
+  // Paint metrics that land after this point are therefore dropped. TTFB, CLS and INP
+  // are kept: none of them is distorted by the tab being hidden.
+  let firstHidden = document.visibilityState === "hidden" ? 0 : Infinity;
+  addEventListener(
+    "visibilitychange",
+    () => {
+      firstHidden = Math.min(firstHidden, performance.now());
+    },
+    { once: true },
+  );
+  const whileVisible = (v: number | null) => (v === null || v > firstHidden ? null : v);
+
+  const observe = (type: string, cb: (entries: any[]) => void, opts: any = {}) => {
+    try {
+      const po = new PerformanceObserver((list) => cb(list.getEntries()));
+      po.observe({ type, buffered: true, ...opts });
+      return po;
+    } catch {
+      return null;
+    } // an unsupported entry type must not break collection
+  };
+
+  // The LAST largest-contentful-paint wins: the browser reports a new one whenever a
+  // bigger element arrives, and only the final value is the metric.
+  observe("largest-contentful-paint", (es) => {
+    const last = es[es.length - 1];
+    if (last) lcp = last.startTime;
+  });
+
+  // CLS excludes shifts within 500ms of an interaction — a layout change the visitor
+  // asked for is not "unexpected", and counting it punishes responsive UI.
+  observe("layout-shift", (es) => {
+    for (const e of es) if (!e.hadRecentInput) cls += e.value;
+  });
+
+  // A true INP is the 98th percentile of interaction latencies. Keeping every interaction
+  // to compute that costs memory on a page that may run for an hour, so this is the worst
+  // one — which is INP exactly whenever a visit has fewer than fifty interactions, and an
+  // upper bound otherwise. The direction of the error is knowable, which is what matters.
+  observe(
+    "event",
+    (es) => {
+      for (const e of es) if (e.duration > inp) inp = e.duration;
+    },
+    { durationThreshold: 40 },
+  );
+
+  const paintOnce = (name: string): number | null => {
+    try {
+      const e = performance.getEntriesByName(name)[0] as PerformanceEntry | undefined;
+      return e ? e.startTime : null;
+    } catch {
+      return null;
+    }
+  };
+
+  const ttfb = (): number | null => {
+    try {
+      const nav = performance.getEntriesByType("navigation")[0] as
+        | PerformanceNavigationTiming
+        | undefined;
+      return nav ? nav.responseStart : null;
+    } catch {
+      return null;
+    }
+  };
+
+  function send() {
+    if (sent) return;
+    sent = true;
+    const fcp = paintOnce("first-contentful-paint");
+    const t = ttfb();
+    // Nothing observed at all means an unsupported browser, not a fast page. Sending a
+    // row of nulls would dilute every average with visits that were never measured.
+    if (lcp === null && fcp === null && t === null && cls === 0 && inp === 0) return;
+    enqueue("$vitals", undefined, {
+      path,
+      vital_lcp: whileVisible(lcp),
+      vital_inp: inp || null,
+      vital_cls: Math.round(cls * 10000) / 10000,
+      vital_ttfb: t,
+      vital_fcp: whileVisible(fcp),
+      // The heatmap module's view id when it sampled this view: the pilot's INP guardrail compares
+      // views with and without heatmap capture on the same site and days.
+      heatmap: hv ? { id: hv } : undefined,
+    });
+  }
+
+  // Every vital is only final when the page is, so this rides out on core's last flush.
+  onFinal(send);
+});
diff --git a/packages/blocks/src/v8/analytics/runtime/src/guards.ts b/packages/blocks/src/v8/analytics/runtime/src/guards.ts
new file mode 100644
index 00000000..ed7a5f28
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/src/guards.ts
@@ -0,0 +1,70 @@
+/** Reasons not to collect at all, evaluated once at boot.
+ *
+ *  Automation detection has a catch: Playwright sets navigator.webdriver, so it would
+ *  block our own end-to-end tests. `__dqAllowAutomation` is the escape hatch, and it is
+ *  why 2.8 does not fail for the wrong reason. */
+export function shouldSkip(w: typeof globalThis & Record<string, any>): string | null {
+  const nav = w.navigator;
+
+  if (!w.__dqAllowAutomation) {
+    if (nav?.webdriver) return "automation";
+    if (w._phantom || w.__nightmare || w.Cypress) return "automation";
+  }
+
+  try {
+    if (w.localStorage?.getItem("__dq_ignore") === "true") return "opt-out";
+  } catch {
+    /* storage can throw in private mode; not a reason to skip */
+  }
+
+  if (isLocal(w) && !w.__dq?.dev) return "local";
+
+  return null;
+}
+
+/** A development host. Not collected unless the site asks for it.
+ *
+ *  This was missing entirely, and on a fleet of storefronts built by agencies that is not
+ *  a small omission: every `npm run dev` against a client's site was writing into that
+ *  client's production numbers, indistinguishable from real traffic. Plausible ships a
+ *  separate script variant for the local case and OneDollarStats has `data-devmode`,
+ *  because both meet the same problem.
+ *
+ *  Opt in with `window.__dq.dev = true` before the script loads. */
+function isLocal(w: typeof globalThis & Record<string, any>): boolean {
+  const l = w.location;
+  if (!l) return false;
+  if (l.protocol === "file:") return true;
+  const h = String(l.hostname ?? "");
+  return (
+    h === "localhost" ||
+    h === "127.0.0.1" ||
+    h === "::1" ||
+    h === "[::1]" ||
+    h.endsWith(".local") ||
+    h.endsWith(".localhost") ||
+    // The private ranges a dev server binds to when someone tests from a phone.
+    /^10\./.test(h) ||
+    /^192\.168\./.test(h) ||
+    /^172\.(1[6-9]|2\d|3[01])\./.test(h)
+  );
+}
+
+/** A page prerendered by Chrome must not count until it becomes visible. Without this any
+ *  site with prefetch overcounts — which is the whole fleet. */
+export function whenVisible(doc: Document, fn: () => void): void {
+  if ((doc as any).prerendering) {
+    doc.addEventListener("prerenderingchange", () => fn(), { once: true });
+    return;
+  }
+  if ((doc.visibilityState as string) === "prerender") {
+    doc.addEventListener("visibilitychange", function onVis() {
+      if ((doc.visibilityState as string) !== "prerender") {
+        doc.removeEventListener("visibilitychange", onVis);
+        fn();
+      }
+    });
+    return;
+  }
+  fn();
+}
diff --git a/packages/blocks/src/v8/analytics/runtime/src/index.ts b/packages/blocks/src/v8/analytics/runtime/src/index.ts
new file mode 100644
index 00000000..65de5e07
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/src/index.ts
@@ -0,0 +1,606 @@
+import {
+  LIMITS,
+  WIRE,
+  CAMPAIGN_KEYS,
+  campaignKey,
+  isSampleable,
+  type Props,
+} from "../../shared/contract.ts";
+import { trimProps } from "./trim.ts";
+import { BoundedQueue, type QueuedEvent } from "./queue.ts";
+import { shouldSkip, whenVisible } from "./guards.ts";
+
+type Cfg = {
+  s: string; // site id
+  k?: string; // self-serve key, when not resolved from Host
+  r?: number; // sampling
+  tier?: 0 | 1; // 1 = a stable id is allowed, WITH consent
+  hash?: boolean; // the site routes on location.hash
+  dev?: boolean; // collect even on a development host
+  x?: Record<string, string>; // experiment map, injected by SSR
+  e?: string; // endpoint
+  q?: unknown[] | { push: (r: unknown) => void }; // stub queue; a live dispatcher after boot
+  killed?: boolean;
+  hr?: number; // heatmap module: per-view sampling rate
+  er?: string[]; // errors module: cross-origin hosts that count as ours
+  h?: number; // heatmap module: 0 = switched off by the server
+};
+
+const w = globalThis as typeof globalThis & Record<string, any>;
+const cfg: Cfg = w.__dq ?? (w.__dq = { s: "unknown" });
+/** Config carried on the script tag itself, read before anything else.
+ *
+ *  Instrumenting a real TanStack storefront found the hazard this exists for: the
+ *  framework hoisted `<script async src=".../_dq/a.js">` into `<head>`, ABOVE the inline
+ *  block that was supposed to configure it — measured at byte 190 against byte 1108. The
+ *  collector therefore ran with no `dev` flag, `shouldSkip` correctly saw a development
+ *  host, and boot returned early. The only symptom was silence, and `window.__dq` looked
+ *  half-built afterwards.
+ *
+ *  An attribute cannot lose that race: it is on the element that is executing. This is
+ *  why OneDollarStats carries `data-hostname` and `data-devmode` rather than expecting a
+ *  global to be there first, and it is the shape `<Stats />` (6.3) has to ship. */
+const tag = (() => {
+  try {
+    return (
+      (document.currentScript as HTMLScriptElement | null) ??
+      document.querySelector<HTMLScriptElement>('script[src*="/_dq/a.js"]')
+    );
+  } catch {
+    return null;
+  }
+})();
+const attr = (n: string) => tag?.dataset?.[n];
+
+/** Where beacons go.
+ *
+ *  Derived from the SCRIPT'S OWN src, not from a relative path. Instrumenting a real
+ *  storefront found why: the tag was loaded from our collector, the beacon used `/_dq/e`,
+ *  and a relative path resolves against the PAGE's origin — so every event was posted to
+ *  the shop's own server, which answered 200 with its homepage. Nothing reached the
+ *  collector and nothing reported an error, because a 200 is a 200.
+ *
+ *  A site on our CDN is unaffected, since both are the same origin; that is exactly why
+ *  this survived every local test. It breaks for every site that is NOT on our CDN — the
+ *  self-serve tier, which is the whole reason the `?k=` path exists.
+ *
+ *  An explicit `cfg.e` still wins, and the relative path remains the last resort. */
+const ENDPOINT = (() => {
+  if (cfg.e) return cfg.e;
+  try {
+    const src = tag?.src;
+    if (src) return new URL("/_dq/e", src).toString();
+  } catch {
+    /* a src we cannot parse is not a reason to fail to collect */
+  }
+  return "/_dq/e";
+})();
+
+const queue = new BoundedQueue();
+let superProps: Record<string, string> = {};
+let optedOut = false;
+/** Readable from config so it is on BEFORE boot. The skip reason — "local", "opt-out",
+ *  "automation" — is logged during boot, so a flag that can only be set by calling a
+ *  method afterwards cannot explain the one failure it exists for: nothing arrives and
+ *  there is no way to tell whether the tag is wrong, the site is wrong, or the host is
+ *  excluded. OneDollarStats reaches the same conclusion with `data-devmode`. */
+
+if (attr("dev") !== undefined)
+  (w as any).__dq = Object.assign((w as any).__dq ?? {}, { dev: attr("dev") !== "false" });
+if (attr("debug") !== undefined)
+  (w as any).__dq = Object.assign((w as any).__dq ?? {}, { debug: attr("debug") !== "false" });
+
+let skipped = false;
+let debugOn = Boolean((w as any).__dq?.debug);
+let timer: number | undefined;
+let firstSent = false;
+
+/** Run just before the last flush of a page load, so a module can add what it only knows
+ *  at the end without spending a request of its own. */
+const finalHooks: Array<() => void> = [];
+/** Run when an SPA navigation changes the URL, BEFORE the new `$pageview`, with the path that
+ *  is being left. A module measuring "this view" closes it here, so route 2 does not inherit
+ *  route 1's scroll depth -- which is exactly what `$scroll` did before this existed. */
+const routeHooks: Array<(prev: string) => void> = [];
+
+const log = (...a: unknown[]) => debugOn && console.log("[dq]", ...a);
+const uuidv7 = (): string => {
+  // Time-ordered so replay dedups by a key that also sorts, without pulling a dependency.
+  const t = Date.now();
+  const hex = t.toString(16).padStart(12, "0");
+  const r = crypto.getRandomValues(new Uint8Array(10));
+  const h = [...r].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-7${h.slice(0, 3)}-${(
+    (parseInt(h[3], 16) & 0x3) | 0x8
+  ).toString(16)}${h.slice(4, 7)}-${h.slice(7, 19)}`;
+};
+
+function enqueue(
+  rawName: unknown,
+  rawProps: unknown,
+  extra?: Record<string, unknown>,
+  urgent = false,
+) {
+  if (optedOut || cfg.killed) return;
+  // Only the tail is sheddable. `$` events carry every core metric and are bounded per
+  // pageview anyway, so exempting them costs almost no volume and keeps visitor counts,
+  // sessions and vitals exact at any rate.
+  if (
+    typeof cfg.r === "number" &&
+    cfg.r < 1 &&
+    isSampleable(String(rawName ?? "")) &&
+    Math.random() > cfg.r
+  )
+    return;
+
+  // Only the two violations that cost upload bytes are caught here; the Worker owns the
+  // rest, including the event name. Sending a name unnormalised costs nothing and saves
+  // 2.3 KB of normaliser in every visitor's download.
+  const trunc = new Set<string>();
+  const props = trimProps({ ...superProps, ...((rawProps as object) ?? {}) }, (f) => trunc.add(f));
+  const name = String(rawName ?? "").slice(0, LIMITS.nameLen * 2);
+
+  // Short keys on the wire. Field names are a double-digit share of a ~293 byte event, and
+  // the visitor pays that upload — often on mobile data. The Worker expands them, so
+  // nothing downstream ever sees the abbreviation.
+  const e: QueuedEvent = {
+    [WIRE.event_id]: uuidv7(),
+    [WIRE.ts]: new Date().toISOString(),
+    [WIRE.name]: name,
+    [WIRE.path]: location.pathname.slice(0, LIMITS.pathLen),
+    [WIRE.props]: props,
+  };
+  if (document.referrer) e[WIRE.referrer] = document.referrer.slice(0, LIMITS.refLen);
+  // On EVERY event of the page load, not just the landing pageview: an event fired
+  // after a client-side route change still belongs to the campaign that brought the
+  // visitor, and by then the query string is long gone.
+  if (hasCampaign) e[WIRE.utm] = campaign;
+  // Installed by the consent module, which only tier-1 sites download. Core asks; it does
+  // not know what consent is, the same way it does not know what a cart is.
+  const ci = (w as any).__dqCid?.();
+  if (ci) e[WIRE.client_id] = ci;
+  if (cfg.x && Object.keys(cfg.x).length) e[WIRE.exp] = cfg.x;
+
+  // Absent rather than empty: a key that is not sent costs nothing, while an empty one
+  // costs its own name on every event.
+  if (extra) {
+    for (const [k, v] of Object.entries(extra)) {
+      if (v === undefined || v === null || v === "") continue;
+      const short = (WIRE as Record<string, string>)[k];
+      e[short ?? k] = v;
+    }
+  }
+  if (trunc.size) e[WIRE._trunc] = [...trunc];
+
+  queue.push(e);
+  // The FIRST event of a page load goes immediately; everything after it batches.
+  //
+  // End-to-end latency measured 8.3s and none of it was the warehouse — ClickHouse answers
+  // in milliseconds. It was this queue: an event waits up to flushMs before anyone can see
+  // it, which makes a realtime view structurally impossible however fast the read side is.
+  //
+  // Flushing only the first costs ONE extra request per page load rather than one per
+  // event, so the batching that protects the collector is untouched — and the first event
+  // is the one realtime needs, because it is the pageview saying a visitor arrived.
+  if (!firstSent) {
+    firstSent = true;
+    flush();
+    return;
+  }
+
+  // Some events must not wait, and CORE DOES NOT DECIDE WHICH. This started as a name
+  // check here -- `name === "purchase"` -- which put the word "purchase" in the core
+  // bundle and broke the test asserting that a site without the commerce module does not
+  // download commerce vocabulary. That test was right: core does not know what a cart is,
+  // and the module that owns an event is the only thing that can judge what losing it
+  // costs. So urgency arrives as a parameter from the caller.
+  if (urgent) {
+    flush();
+    return;
+  }
+
+  log("queued", name, e);
+  if (queue.length >= LIMITS.eventsPerBatch) flush();
+}
+
+function applyCommand(cmd: Record<string, unknown> | null) {
+  if (!cmd) return;
+  if (cmd.k) {
+    cfg.killed = true;
+    log("killed by server");
+  }
+  if (typeof cmd.r === "number") {
+    cfg.r = cmd.r;
+    log("sampling ->", cmd.r);
+  }
+  // Module-level switch: `{h:0}` stops the heatmap module for the rest of the page load
+  // without touching core collection.
+  if ("h" in cmd) cfg.h = cmd.h as number;
+}
+
+const payload = (events: QueuedEvent[]) => JSON.stringify({ site: cfg.s, key: cfg.k, events });
+
+/** The last chance to deliver, so it does not get to fail quietly.
+ *
+ *  sendBeacon returns false more often than people expect: over the browser's beacon
+ *  queue limit, blocked by a connect-src CSP, or simply absent. Some privacy modes throw
+ *  instead of returning false. Either way the batch is still in hand, and keepalive fetch
+ *  survives unload too — so it is the fallback rather than the primary, which sendBeacon
+ *  remains because it is the more reliable of the two during teardown. */
+function sendFinal(body: string): void {
+  try {
+    const blob = new Blob([body], { type: "text/plain" });
+    if (navigator.sendBeacon && navigator.sendBeacon(ENDPOINT, blob)) {
+      log("final via sendBeacon", body.length);
+      return;
+    }
+    log("sendBeacon declined, falling back");
+  } catch (e) {
+    log("sendBeacon threw, falling back", e);
+  }
+
+  try {
+    fetch(ENDPOINT, {
+      method: "POST",
+      body,
+      keepalive: true,
+      headers: { "Content-Type": "text/plain" },
+    }).catch(() => {});
+    log("final via keepalive fetch", body.length);
+  } catch (e) {
+    log("both transports failed", e);
+  }
+}
+
+function flush(final = false) {
+  if (final) {
+    // Drain everything, not one batch. A tab closing with 120 events queued would
+    // otherwise deliver 50 and lose 70 — and nothing would report the loss.
+    let batch: QueuedEvent[];
+    while ((batch = queue.drain()).length) sendFinal(payload(batch));
+    return;
+  }
+
+  const batch = queue.drain();
+  if (!batch.length) return;
+
+  // text/plain avoids the CORS preflight: application/json cross-origin would trigger an
+  // OPTIONS before every beacon and double the request count.
+  fetch(ENDPOINT + (debugOn ? "?debug=1" : ""), {
+    method: "POST",
+    body: payload(batch),
+    keepalive: true,
+    headers: { "Content-Type": "text/plain" },
+  })
+    .then((r) => (r.status === 200 ? r.json() : null))
+    .then((cmd) => {
+      // With debug on the Worker echoes the flags it applied, so a developer sees what was
+      // rewritten without querying the warehouse — and without the client carrying the
+      // normaliser to find out.
+      const c = cmd as { _trunc?: string[] } | null;
+      if (c?._trunc && debugOn) console.warn("[dq] server adjusted:", c._trunc);
+      applyCommand(c as Record<string, unknown> | null);
+    })
+    .catch(() => {
+      /* losing a batch is not worth breaking the page over */
+    });
+}
+
+function pageview(props?: Props) {
+  enqueue("$pageview", props);
+}
+
+/** trimProps accepts primitives and returns them unchanged; superProps is the string map
+ *  every event spreads. Narrow here rather than widening superProps. */
+/** Campaign parameters live in the query string of the LANDING url and are gone by the
+ *  next navigation. Captured once at load and attached to every event in this page load.
+ *
+ *  Deliberately NOT persisted to storage: keeping them across page loads would need
+ *  device storage, which is the one thing that turns a cookieless collector into one
+ *  that needs a consent banner. Attribution across the visit is a server-side question
+ *  instead — the landing event carries the campaign, and a session inherits it from its
+ *  own first event. */
+const campaign: Record<string, string> = (() => {
+  const out: Record<string, string> = {};
+  try {
+    const q = new URLSearchParams(location.search);
+    for (const raw of CAMPAIGN_KEYS) {
+      const v = q.get(raw);
+      if (!v) continue;
+      const k = campaignKey(raw);
+      if (k) out[k] = v.slice(0, 200);
+    }
+  } catch {
+    /* a malformed query string is not worth breaking collection over */
+  }
+  return out;
+})();
+
+const hasCampaign = Object.keys(campaign).length > 0;
+
+const asStrings = (o: Record<string, unknown>): Record<string, string> => {
+  const out: Record<string, string> = {};
+  for (const k in o) out[k] = String(o[k]);
+  return out;
+};
+
+const api = {
+  track: (name: string, props?: Props) => enqueue(name, props),
+  pageview,
+  // trimProps, not sanitizeProps: the latter has never existed anywhere in the repo. A
+  // rename in "one payload contract" (f07c704) missed these two call sites; esbuild
+  // treats an unknown identifier as a runtime global rather than an error, and nothing
+  // typechecked — so two of the fourteen documented API methods have thrown
+  // ReferenceError ever since, silently, because no test called them.
+  //
+  // The no-op flag sink is deliberate: enqueue() re-trims { ...superProps, ...props } on
+  // every event, so anything worth flagging is flagged there with the event it affects.
+  // Flagging here as well would attribute it to whichever event happened to be next.
+  set: (p: Props) => {
+    superProps = { ...superProps, ...asStrings(trimProps(p, () => {})) };
+  },
+  setOnce: (p: Props) => {
+    const clean = asStrings(trimProps(p, () => {}));
+    for (const k in clean) if (!(k in superProps)) superProps[k] = clean[k];
+  },
+  unset: (keys: string[]) => {
+    for (const k of keys) delete superProps[k];
+  },
+  setExperiment: (id: string, variant: string) => {
+    cfg.x = { ...(cfg.x ?? {}), [id]: variant };
+  },
+  variant: (id: string) => cfg.x?.[id],
+  captureException: (err: unknown, props?: Props) => {
+    const e = err as Error;
+    enqueue("$error", props, {
+      error_type: e?.name ?? "Error",
+      error_message: String(e?.message ?? err).slice(0, LIMITS.valueLen),
+      error_stack: (e?.stack ?? "").slice(0, 8000),
+    });
+  },
+  optIn: () => {
+    optedOut = false;
+    try {
+      localStorage.removeItem("__dq_ignore");
+    } catch {}
+  },
+  optOut: () => {
+    optedOut = true;
+    try {
+      localStorage.setItem("__dq_ignore", "true");
+    } catch {}
+  },
+  hasOptedOut: () => optedOut,
+  /** Replaced by the consent module on a tier-1 site. Left as a no-op so a site that
+   *  calls it at tier 0 does not throw — declining consent that was never asked for is
+   *  not an error. */
+  consent: (_v: unknown) => {},
+  /** Send whatever is queued now. Useful before a hard navigation the SDK cannot see,
+   *  such as handing off to a payment provider. */
+  flush: () => flush(),
+  debug: (on = true) => {
+    debugOn = on;
+  },
+  reset: () => {
+    superProps = {};
+  },
+};
+
+/** The seam optional modules attach to. Core knows how to queue an event and nothing
+ *  about what the event means — a module can add named helpers on top without the core
+ *  learning what a cart is. */
+w.__dqRegister = (
+  fn: (
+    e: typeof enqueue,
+    api: Record<string, unknown>,
+    onFinal: (h: () => void) => void,
+    onRoute: (h: (prev: string) => void) => void,
+  ) => void,
+) => {
+  // A module must not install its helpers when collection is off. Found on a real
+  // storefront: with boot skipped, `window.__dq` carried `addToCart` and
+  // `captureException` from the modules while core's own `pageview` and `flush` were
+  // absent — a half-built object that invites a site to call into a runtime that will
+  // never send. Skipped means skipped, for everyone.
+  if (skipped) return;
+  try {
+    fn(
+      enqueue,
+      cfg as Record<string, unknown>,
+      (h) => {
+        finalHooks.push(h);
+      },
+      (h) => {
+        routeHooks.push(h);
+      },
+    );
+  } catch (err) {
+    log("module failed", err);
+  }
+};
+
+/** One call recorded by the stub, replayed against the real API.
+ *
+ *  Two shapes. `{ m, a }` is the official snippet's: a METHOD and its arguments, so a helper
+ *  called before boot (`viewItem`, `purchase`, `captureException`) arrives with its typed columns
+ *  -- value, currency, item_ids, transaction_id -- instead of being flattened into props or
+ *  dropped. Anything else is the original `track` stub's `[name, props]`, which keeps working.
+ *
+ *  `replaying` stops the one loop this can make: a method no module provided is still the stub,
+ *  and the stub pushes straight back here. That call is dropped, with a debug line saying why. */
+let replaying = false;
+function replay(r: unknown) {
+  if (!r || replaying) {
+    if (r) log("no such method; dropped", r);
+    return;
+  }
+  replaying = true;
+  try {
+    const rec = r as { m?: unknown; a?: ArrayLike<unknown> } & ArrayLike<unknown>;
+    if (typeof rec.m === "string") {
+      const fn = (cfg as Record<string, unknown>)[rec.m];
+      if (typeof fn === "function") fn(...Array.from(rec.a ?? []));
+      else log("no such method; dropped", rec.m);
+    } else {
+      enqueue(rec[0], rec[1]);
+    }
+  } catch (e) {
+    log("replay failed", e);
+  } finally {
+    replaying = false;
+  }
+}
+
+function boot() {
+  // ONCE PER PAGE, whatever put the tag there.
+  //
+  // Two identical `<script src>` tags both execute — the browser reuses the cached RESOURCE, not
+  // the execution — and measured, that is two `$pageview` events for one page load, doubling
+  // every number the page produces. It stopped being hypothetical when the TanStack framework
+  // started mounting the tag itself: any site that had already added it by hand now has both,
+  // and the duplicate arrives on a dependency bump rather than on a code change anyone reviews.
+  //
+  // The guard belongs HERE and not in either component, because the component can only know
+  // about itself. This covers every way a page ends up with two tags — two components, a
+  // component plus a hand-pasted snippet, a tag manager that injects a third.
+  //
+  // `w` rather than a module-level flag: two copies of this bundle are two module scopes, so a
+  // local `let` would be two separate flags, each false.
+  if (w.__dqBooted) {
+    log("already booted; this tag is a duplicate");
+    return;
+  }
+  w.__dqBooted = true;
+
+  // VIEW MODE: Studio framing this page to draw a heatmap over it. Nothing is collected -- no
+  // pageview, no module, no beacon -- and the overlay is a separate chunk that only this branch
+  // downloads; every other visitor pays for this test and nothing else. The chunk does the
+  // origin handshake: until an allow-listed parent speaks first, it does nothing at all.
+  if (/[?&]dq_view=1(&|$)/.test(location.search) && w.top !== w.self) {
+    skipped = true;
+    const s = document.createElement("script");
+    s.src = ENDPOINT.replace(/\/_dq\/e$/, "/_dq/v.js");
+    document.head.appendChild(s);
+    return;
+  }
+
+  const skip = shouldSkip(w);
+  if (skip) {
+    skipped = true;
+    log("not collecting:", skip);
+    return;
+  }
+
+  const stubbed = (cfg.q ?? []) as unknown[];
+  Object.assign(cfg, api);
+  // From here on the stub's queue is a live dispatcher, so a stub method a site captured before
+  // boot (or one no module replaced) still delivers instead of pushing into an array nobody reads.
+  cfg.q = { push: replay };
+  // A MICROTASK, because the commerce helpers do not exist yet: modules are appended after core
+  // in the same bundle and register when it finishes executing. Replaying here would find
+  // `viewItem` still pointing at the stub, which is exactly how a storefront that fires
+  // `view_item` before the script loads lost 94% of them.
+  queueMicrotask(() => {
+    for (const r of stubbed) replay(r);
+  });
+
+  whenVisible(document, () => pageview());
+
+  // SPA navigation. The framework serves full documents, but islands and client routers
+  // change the URL without one.
+  // One notion of "the URL changed", shared by every path that can change it.
+  //
+  // pushState, popstate and hashchange are not independent events: assigning
+  // `location.hash` fires hashchange AND popstate, so a hash-routed site counted every
+  // navigation twice — measured, five page views for what was three. Routing all three
+  // through here makes a repeat of the same URL a no-op, which also covers the router that
+  // calls pushState and then dispatches popstate itself.
+  //
+  // The hash is part of "the URL" only on a site that routes on it. Elsewhere a click on
+  // `#reviews` is an anchor -- and it still fires popstate, so leaving the fragment in the key
+  // counted every in-page jump as a page view even with `hash` off.
+  const here = () => location.pathname + location.search + (cfg.hash ? location.hash : "");
+  let lastUrl = here();
+  let lastPath = location.pathname;
+  const route = () => {
+    const prev = lastPath;
+    lastPath = location.pathname;
+    for (const fn of routeHooks) {
+      try {
+        fn(prev);
+      } catch {
+        /* one module must not stop another */
+      }
+    }
+  };
+  const navigated = () => {
+    const now = here();
+    if (now === lastUrl) return;
+    lastUrl = now;
+    route();
+    pageview();
+  };
+
+  const push = history.pushState;
+  if (push) {
+    history.pushState = function (this: History, ...a: any[]) {
+      push.apply(this, a as any);
+      navigated();
+    } as any;
+    addEventListener("popstate", navigated);
+  }
+
+  // replaceState was not patched at all, and routers use it constantly — canonical
+  // rewrites, redirects, writing filter state into the URL. Only a changed PATH counts
+  // here: a PLP rewriting its query string on every filter click is one page view, and
+  // firing on each would turn browsing into a traffic spike. This is deliberately stricter
+  // than `navigated`, which treats any URL change as a navigation.
+  const replace = history.replaceState;
+  if (replace) {
+    history.replaceState = function (this: History, ...a: any[]) {
+      const before = location.pathname;
+      replace.apply(this, a as any);
+      if (location.pathname !== before) {
+        lastUrl = here();
+        route();
+        pageview();
+      }
+    } as any;
+  }
+
+  // Hash routing, opt-in per site. NOT automatic: on an ordinary page `#secao` is an
+  // anchor, and counting those would inflate every long article and every FAQ. A site that
+  // routes on the hash declares it — which is how Plausible and OneDollarStats handle it
+  // too, each with a mode for the case.
+  if (cfg.hash) addEventListener("hashchange", navigated);
+
+  timer = setInterval(() => flush(), LIMITS.flushMs) as unknown as number;
+
+  // Both, on purpose. pagehide misses backgrounding on mobile, and visibilitychange
+  // misses some desktop closes; a page can also be restored from bfcache after either.
+  // Double-firing is harmless because a drained queue makes the second call a no-op.
+  // Modules that only know their value when the page ends — scroll depth, the vitals,
+  // the accumulated error repeats — contribute HERE, and then ONE flush carries all of
+  // it. Each of them used to call flush() itself, which produced four requests on the
+  // way out where one would do: the collector paying per module rather than per visit.
+  const onFinal = () => {
+    for (const fn of finalHooks) {
+      try {
+        fn();
+      } catch {
+        /* one module must not stop another */
+      }
+    }
+    flush(true);
+  };
+  addEventListener("pagehide", onFinal);
+  // On document, not window: visibilitychange is specified to fire at the Document. It
+  // does bubble, so a window listener happens to work in a real browser — but relying on
+  // that is fragile, and it silently does nothing for any dispatch that is not bubbling.
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") onFinal();
+  });
+}
+
+boot();
+export {};
diff --git a/packages/blocks/src/v8/analytics/runtime/src/queue.ts b/packages/blocks/src/v8/analytics/runtime/src/queue.ts
new file mode 100644
index 00000000..2f0f1625
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/src/queue.ts
@@ -0,0 +1,40 @@
+import { F_QUEUE_OVERFLOW, LIMITS, WIRE } from "../../shared/contract.ts";
+
+export type QueuedEvent = Record<string, unknown>;
+
+/** Bounded, because a page firing events in a loop must not grow memory in a customer's
+ *  browser without limit. Drops the oldest and marks the survivor, so the loss is visible
+ *  in the data rather than inferred from a gap. */
+export class BoundedQueue {
+  private items: QueuedEvent[] = [];
+
+  push(e: QueuedEvent): void {
+    if (this.items.length >= LIMITS.queueMax) {
+      this.items.shift();
+      const t = (e[WIRE._trunc] as string[] | undefined) ?? [];
+      if (!t.includes(F_QUEUE_OVERFLOW)) t.push(F_QUEUE_OVERFLOW);
+      e[WIRE._trunc] = t;
+    }
+    this.items.push(e);
+  }
+
+  /** Up to `eventsPerBatch` events AND `batchBytes` of them. Fifty `$error`s at 8 KB each is a
+   *  400 KB body: the collector answers 413, and keepalive or sendBeacon refuses it outright, so
+   *  the whole batch was lost. Always at least one event, so an oversize one cannot wedge the
+   *  queue; the collector judges it alone. */
+  drain(): QueuedEvent[] {
+    let n = 0,
+      bytes = 0;
+    const enc = new TextEncoder();
+    while (n < this.items.length && n < LIMITS.eventsPerBatch) {
+      bytes += enc.encode(JSON.stringify(this.items[n])).length + 1;
+      if (n && bytes > LIMITS.batchBytes) break;
+      n++;
+    }
+    return this.items.splice(0, n);
+  }
+
+  get length(): number {
+    return this.items.length;
+  }
+}
diff --git a/packages/blocks/src/v8/analytics/runtime/src/trim.ts b/packages/blocks/src/v8/analytics/runtime/src/trim.ts
new file mode 100644
index 00000000..199f87d7
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/src/trim.ts
@@ -0,0 +1,39 @@
+import { F_PROPS_COUNT, F_PROPS_LEN, F_PROPS_TYPE, LIMITS } from "../../shared/contract.ts";
+
+/** The client's share of the contract, kept to the two violations that actually cost
+ *  upload bytes: an oversized value and a non-primitive that would be serialised whole.
+ *
+ *  Everything else — charset, reserved names, currency, timestamps — is left to the
+ *  Worker. Shipping the full normaliser cost 2.3 KB minified in every visitor's download
+ *  to save bytes on payloads most sites never send, which is the wrong trade. The Worker
+ *  is the authority regardless, so the client's job is bandwidth, not correctness.
+ *
+ *  What a developer loses by not normalising here is visibility, and that comes back the
+ *  cheaper way: with `debug()` on, the collect response echoes the flags the Worker
+ *  applied. Zero bytes in the normal path, full feedback when someone is looking. */
+export function trimProps(input: unknown, flag: (f: string) => void): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!input || typeof input !== "object" || Array.isArray(input)) return out;
+
+  let n = 0;
+  for (const [k, v] of Object.entries(input as Record<string, unknown>)) {
+    if (n >= LIMITS.propKeys) {
+      flag(F_PROPS_COUNT);
+      break;
+    }
+    if (v === null || v === undefined) continue;
+
+    const t = typeof v;
+    if (t !== "string" && t !== "number" && t !== "boolean") {
+      flag(F_PROPS_TYPE);
+      continue;
+    }
+
+    out[k] =
+      t === "string" && (v as string).length > LIMITS.valueLen
+        ? (flag(F_PROPS_LEN), (v as string).slice(0, LIMITS.valueLen))
+        : v;
+    n++;
+  }
+  return out;
+}
diff --git a/packages/blocks/src/v8/analytics/runtime/view/heat-core.ts b/packages/blocks/src/v8/analytics/runtime/view/heat-core.ts
new file mode 100644
index 00000000..e1f05789
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/view/heat-core.ts
@@ -0,0 +1,335 @@
+// Ported verbatim from insights-mcp web/components/heat-core.ts (branch feat/page-heatmap, 3af7d86),
+// the PAGE_HEATMAP viewer, so the live-site overlay and the MCP App draw the same picture.
+// Change it there first, then copy it here: two heat maths that disagree are the failure to avoid.
+// One exception, owed upstream: `quantiles` (one typed sort, output identical to the old `quantile`)
+// landed here first, to keep each heatmap snapshot cheap on the store's main thread.
+/**
+ * Pure heatmap math for the page-heatmap viewer: device buckets, matching
+ * fallbacks, density field + Gaussian kernel, p99 normalisation, colour
+ * ramps, scroll reach and attention bands.
+ *
+ * Self-contained on purpose (no module-scope references): `heatCore.toString()`
+ * is injected into the snapshot iframe next to `anchorLib`, and the tests call
+ * `heatCore()` directly. Data in, numbers out — no DOM.
+ */
+export function heatCore() {
+  type Device = "desktop" | "tablet" | "mobile";
+  type Box = { x: number; y: number; w: number; h: number };
+  type Element = { sec: string; el: string; clicks: number; cells: [number, number][] };
+  type GridCell = { fixed: boolean; xb: number; yb: number; clicks: number };
+
+  /** Same rule as analytics_hm_device: layout follows the viewport, not the UA. */
+  function deviceOf(vw: number): Device | "" {
+    if (!vw) return "";
+    return vw < 768 ? "mobile" : vw < 1024 ? "tablet" : "desktop";
+  }
+
+  const DESKTOP_WIDTHS = [1280, 1366, 1440, 1536, 1920];
+
+  /** Width to render the snapshot at: the bucket's mean viewport snapped to a common screen. */
+  function renderWidth(device: Device, meanVw?: number | null): number {
+    if (device === "mobile") return 390;
+    if (device === "tablet")
+      return meanVw && meanVw >= 768 && meanVw < 1024 ? Math.round(meanVw) : 820;
+    if (!meanVw || meanVw < 1024) return 1440;
+    return DESKTOP_WIDTHS.reduce((a, b) => (Math.abs(b - meanVw) < Math.abs(a - meanVw) ? b : a));
+  }
+
+  /** Kernel radius in CSS px: a finger is wider than a cursor. */
+  const radiusFor = (device: Device) => (device === "desktop" ? 28 : 36);
+
+  /** Several quantiles of the positive values from ONE sort. A typed-array sort is native and
+   *  numeric (no comparator call per pair): a 1M-cell field sorts in ~0.2 s instead of ~0.65 s.
+   *  Float64 keeps the result exact for Float32 fields and plain numbers alike. */
+  function quantiles(values: ArrayLike<number>, qs: number[]): number[] {
+    const v = Float64Array.from(values)
+      .filter((x) => x > 0)
+      .sort();
+    return qs.map((q) => {
+      if (!v.length) return 0;
+      const pos = (v.length - 1) * q;
+      const lo = Math.floor(pos);
+      return v[lo] + (v[Math.min(lo + 1, v.length - 1)] - v[lo]) * (pos - lo);
+    });
+  }
+
+  function quantile(values: ArrayLike<number>, q: number): number {
+    return quantiles(values, [q])[0];
+  }
+
+  /** Cells per side of the position grid inside an element, as mv_hm_elements_daily stores it
+   *  (row * GRID + column). Must match the MV: migrations/2026_11_06_hm_cells_16. */
+  const GRID = 16;
+  /** The cell an element's clicks go to when the row has no cells: the one at its centre. */
+  const CENTER_CELL = (GRID / 2 - 1) * GRID + GRID / 2 - 1;
+  /** At most this many points per cell: bounds the work on the largest cells. */
+  const SPREAD = 8;
+
+  /** FNV-1a of an element's key: the seed its cells scatter from. */
+  function hash(key: string): number {
+    let h = 2166136261;
+    for (let i = 0; i < key.length; i++) h = Math.imul(h ^ key.charCodeAt(i), 16777619);
+    return h;
+  }
+  /** mulberry32 over a module-local state: no closure or array per cell. */
+  let rs = 0;
+  function rnd(): number {
+    rs = (rs + 0x6d2b79f5) | 0;
+    let t = Math.imul(rs ^ (rs >>> 15), 1 | rs);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  }
+
+  /**
+   * Places every element's clicks on the snapshot (design §6.3): on the
+   * element's own box when its anchor is found, else on its section box,
+   * else nowhere (the caller lists it and the coordinate grid covers it).
+   *
+   * A stored position is only "somewhere in this cell", so a cell's weight is spread over it.
+   * Where the blur (sigma = radius / 2) is wider than the cell, one point at its centre is
+   * already indistinguishable from the spread, and costs nothing extra -- most cells on mobile
+   * and on small elements. Wider cells (a full-width strip: 1400 / 16 = 87 px) get a few
+   * points, about one per sigma along each side, up to SPREAD, at seeded positions so a
+   * redraw does not move the heat. One centred point there drew a regular grid of blobs.
+   */
+  function place<E extends Element>(
+    elements: E[],
+    findEl: (sec: string, el: string) => Box | null,
+    findSec: (sec: string) => Box | null,
+    radius = 28,
+  ) {
+    const sigma = radius / 2;
+    const points: [number, number, number][] = [];
+    const sections = new Map<string, { box: Box; clicks: number }>();
+    const matched: E[] = [];
+    const missing: E[] = [];
+    let matchedClicks = 0;
+    let sectionClicks = 0;
+    let total = 0;
+    for (const e of elements) {
+      total += e.clicks;
+      const b = findEl(e.sec, e.el);
+      if (b && b.w > 0 && b.h > 0) {
+        matchedClicks += e.clicks;
+        matched.push(e);
+        const cells = e.cells.length ? e.cells : ([[CENTER_CELL, e.clicks]] as [number, number][]);
+        const sum = cells.reduce((s, [, n]) => s + n, 0) || 1;
+        const cw = b.w / GRID,
+          ch = b.h / GRID;
+        const per = Math.ceil(cw / sigma) * Math.ceil(ch / sigma); // points this cell size needs
+        const seed = per > 1 ? hash(`${e.sec}|${e.el}`) : 0;
+        for (const [c, n] of cells) {
+          // cells may be sampled-down counts: scale back to the element's click total
+          const w = (n / sum) * e.clicks;
+          const col = c % GRID,
+            row = (c - col) / GRID;
+          if (per === 1) {
+            points.push([b.x + (col + 0.5) * cw, b.y + (row + 0.5) * ch, w]);
+            continue;
+          }
+          const k = Math.max(1, Math.min(SPREAD, per, Math.round(n)));
+          rs = seed ^ Math.imul(c + 1, 0x9e3779b1);
+          for (let i = 0; i < k; i++)
+            points.push([b.x + (col + rnd()) * cw, b.y + (row + rnd()) * ch, w / k]);
+        }
+        continue;
+      }
+      const s = e.sec ? findSec(e.sec) : null;
+      if (s) {
+        sectionClicks += e.clicks;
+        const z = sections.get(e.sec) ?? { box: s, clicks: 0 };
+        z.clicks += e.clicks;
+        sections.set(e.sec, z);
+      }
+      missing.push(e);
+    }
+    return { points, sections, matched, missing, matchedClicks, sectionClicks, total };
+  }
+
+  /** Coordinate-grid fallback (xb = % of width, yb = 10 px rows; fixed rows sit in the top viewport). */
+  function gridPoints(grid: GridCell[], width: number): [number, number, number][] {
+    return grid.map((g) => [((g.xb + 0.5) / 100) * width, g.yb * 10 + 5, g.clicks]);
+  }
+
+  /** 1-D Gaussian weights for sigma (in cells), normalised to sum 1. */
+  function kernel(sigma: number): Float32Array {
+    const r = Math.max(1, Math.ceil(sigma * 3));
+    const k = new Float32Array(r * 2 + 1);
+    let sum = 0;
+    for (let i = -r; i <= r; i++) sum += k[i + r] = Math.exp(-(i * i) / (2 * sigma * sigma));
+    for (let i = 0; i < k.length; i++) k[i] /= sum;
+    return k;
+  }
+
+  /**
+   * Density field: points splatted into `cell`-px bins, then a separable
+   * Gaussian blur. A low-resolution field stretched by the browser stays
+   * smooth and avoids the canvas size limits a full-page canvas would hit.
+   */
+  function density(
+    points: [number, number, number][],
+    width: number,
+    height: number,
+    cell: number,
+    radius: number,
+  ) {
+    const cols = Math.max(1, Math.ceil(width / cell));
+    const rows = Math.max(1, Math.ceil(height / cell));
+    const a = new Float32Array(cols * rows);
+    for (const [x, y, w] of points) {
+      const cx = Math.floor(x / cell);
+      const cy = Math.floor(y / cell);
+      if (cx < 0 || cy < 0 || cx >= cols || cy >= rows || !(w > 0)) continue;
+      a[cy * cols + cx] += w;
+    }
+    const k = kernel(radius / cell / 2);
+    const r = (k.length - 1) / 2;
+    const b = new Float32Array(a.length);
+    for (let y = 0; y < rows; y++) {
+      const o = y * cols;
+      for (let x = 0; x < cols; x++) {
+        const v = a[o + x];
+        if (!v) continue;
+        for (let i = -r; i <= r; i++) {
+          const xx = x + i;
+          if (xx >= 0 && xx < cols) b[o + xx] += v * k[i + r];
+        }
+      }
+    }
+    a.fill(0);
+    for (let y = 0; y < rows; y++) {
+      for (let x = 0; x < cols; x++) {
+        const v = b[y * cols + x];
+        if (!v) continue;
+        for (let i = -r; i <= r; i++) {
+          const yy = y + i;
+          if (yy >= 0 && yy < rows) a[yy * cols + x] += v * k[i + r];
+        }
+      }
+    }
+    return { field: a, cols, rows };
+  }
+
+  /** Colour stops [t, r, g, b, alpha]; cold is transparent so the page stays readable. */
+  const RAMPS: Record<string, number[][]> = {
+    // Clarity-like: transparent → blue → cyan → green → yellow → orange → red
+    thermal: [
+      [0, 0, 40, 255, 0],
+      [0.08, 20, 70, 255, 0.28],
+      [0.25, 0, 185, 255, 0.5],
+      [0.45, 30, 220, 110, 0.62],
+      [0.65, 250, 232, 40, 0.74],
+      [0.82, 255, 140, 0, 0.82],
+      [1, 225, 18, 30, 0.9],
+    ],
+    // colour-blind safe alternative
+    inferno: [
+      [0, 0, 0, 4, 0],
+      [0.1, 40, 11, 84, 0.3],
+      [0.3, 101, 21, 110, 0.5],
+      [0.5, 159, 42, 99, 0.64],
+      [0.7, 212, 72, 66, 0.74],
+      [0.85, 245, 125, 21, 0.84],
+      [1, 252, 255, 164, 0.92],
+    ],
+  };
+
+  /** 256-entry RGBA lookup table for a ramp. */
+  function lut(name: string): Uint8ClampedArray {
+    const stops = RAMPS[name] ?? RAMPS.thermal;
+    const out = new Uint8ClampedArray(256 * 4);
+    for (let i = 0; i < 256; i++) {
+      const t = i / 255;
+      let j = 0;
+      while (j < stops.length - 2 && t > stops[j + 1][0]) j++;
+      const [t0, ...a] = stops[j];
+      const [t1, ...b] = stops[j + 1];
+      const f = t1 > t0 ? Math.min(1, Math.max(0, (t - t0) / (t1 - t0))) : 0;
+      for (let c = 0; c < 4; c++) out[i * 4 + c] = (a[c] + (b[c] - a[c]) * f) * (c === 3 ? 255 : 1);
+    }
+    return out;
+  }
+
+  /** CSS colour of a ramp at t (0..1), for legends and section chips. */
+  function rampCss(name: string, t: number, alpha?: number): string {
+    const l = lut(name);
+    const i = Math.round(Math.min(1, Math.max(0, t)) * 255) * 4;
+    return `rgba(${l[i]},${l[i + 1]},${l[i + 2]},${alpha ?? +(l[i + 3] / 255).toFixed(3)})`;
+  }
+
+  /**
+   * Field → RGBA pixels. Normalised to `max` (the p99 cell, so one hot CTA
+   * does not wash the page out); `log` compresses the long tail.
+   */
+  function colorize(
+    field: Float32Array,
+    max: number,
+    table: Uint8ClampedArray,
+    log = false,
+  ): Uint8ClampedArray {
+    const px = new Uint8ClampedArray(field.length * 4);
+    if (!(max > 0)) return px;
+    const lm = Math.log1p(max);
+    for (let i = 0; i < field.length; i++) {
+      const v = field[i];
+      if (!(v > 0)) continue;
+      const t = Math.min(1, log ? Math.log1p(v) / lm : v / max);
+      const j = Math.round(t * 255) * 4;
+      px[i * 4] = table[j];
+      px[i * 4 + 1] = table[j + 1];
+      px[i * 4 + 2] = table[j + 2];
+      px[i * 4 + 3] = table[j + 3];
+    }
+    return px;
+  }
+
+  /** Share of views whose deepest point reached each depth 0..100% (from the depth histogram). */
+  function reachCurve(depth: [number, number][], views?: number): Float32Array {
+    const hist = new Float64Array(101);
+    for (const [d, n] of depth) hist[Math.min(100, Math.max(0, Math.round(d)))] += n;
+    const total = views || hist.reduce((s, n) => s + n, 0);
+    const out = new Float32Array(101);
+    if (!total) return out;
+    let acc = 0;
+    for (let d = 100; d >= 0; d--) {
+      acc += hist[d];
+      out[d] = Math.min(1, acc / total);
+    }
+    out[0] = 1; // everyone sees the top of the page
+    return out;
+  }
+
+  /** Depth (0..100) where reach first drops below `share`. */
+  function depthAtReach(curve: Float32Array, share: number): number {
+    for (let d = 0; d <= 100; d++) if (curve[d] < share) return d;
+    return 100;
+  }
+
+  /** Attention: deciseconds per 2.5% band → 40 values. */
+  function attentionBands(attention: [number, number][]): Float32Array {
+    const out = new Float32Array(40);
+    for (const [b, ds] of attention) if (b >= 0 && b < 40) out[b] += ds;
+    return out;
+  }
+
+  return {
+    deviceOf,
+    renderWidth,
+    radiusFor,
+    quantile,
+    quantiles,
+    GRID,
+    place,
+    gridPoints,
+    kernel,
+    density,
+    lut,
+    rampCss,
+    colorize,
+    reachCurve,
+    depthAtReach,
+    attentionBands,
+  };
+}
+
+export type HeatCore = ReturnType<typeof heatCore>;
diff --git a/packages/blocks/src/v8/analytics/runtime/view/view.ts b/packages/blocks/src/v8/analytics/runtime/view/view.ts
new file mode 100644
index 00000000..39be64fd
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/runtime/view/view.ts
@@ -0,0 +1,596 @@
+/** View mode: the heatmap drawn over the LIVE site, inside Studio's iframe.
+ *
+ *  Loaded by core ONLY when the page is framed and its URL carries `dq_view=1` (core then
+ *  collects nothing at all: no pageview, no module, no beacon). A normal visitor never downloads
+ *  this file. Everything here runs on the site's own origin, so it can hash the live DOM with the
+ *  same `shared/anchor.ts` the runtime used on the click, measure boxes, and read element labels --
+ *  which go to the parent frame and nowhere else.
+ *
+ *  Trust: nothing is sent and nothing is accepted until a parent from the allow-list
+ *  (`https://*.decocms.com`, localhost for development) sends `init`. From then on that one
+ *  origin is pinned: every outgoing message is addressed to it, every incoming one must come from
+ *  it and from `window.parent`. Protocol, versioned: docs/RUNTIME_API.md -> "View mode".
+ *
+ *  The drawing is the insights-mcp PAGE_HEATMAP viewer's (heat-core.ts ported verbatim, heat-child
+ *  adapted from a static snapshot to a live page): Gaussian density with p99 normalisation, the
+ *  Térmica / Inferno ramps, scroll reach and fold lines, attention bands, section blocks.
+ */
+import { anchorHash } from "../../shared/anchor.ts";
+import { heatCore } from "./heat-core.ts";
+
+export const VIEW_PROTOCOL = 1;
+export const ALLOWED_PARENT =
+  /^(https:\/\/([a-z0-9-]+\.)*decocms\.com|http:\/\/(localhost|127\.0\.0\.1)(:\d+)?)$/;
+
+type Row = Record<string, unknown>;
+type Mode = "clicks" | "scroll" | "attention" | "sections";
+export interface ViewData {
+  mode: Mode;
+  /** hmElements rows as the read surface returns them; `clicks` may be replaced by the parent
+   *  with the weight of the selected click type (rage, dead, ...). */
+  elements: {
+    root: string;
+    el: string;
+    clicks: number | string;
+    cells?: Row | [number, number][];
+  }[];
+  grid?: { fixed: number | boolean; xb: number; yb: number; clicks: number | string }[];
+  /** hmScroll rows. */
+  depth?: { depth: number; views: number | string }[];
+  /** hmAttention rows. */
+  attention?: { band: number; ds: number | string }[];
+  /** hmSections rows. */
+  sections?: { root: string; reach_pct: number; avg_s: number; clicks?: number | string }[];
+  views?: number;
+  /** hmSummary.avg_fold (percent of the document). */
+  avgFold?: number | null;
+  scale?: number;
+  ramp?: "thermal" | "inferno";
+  opacity?: number;
+  log?: boolean;
+  radius?: number;
+  /** Share of grid clicks to paint for elements not on this page version (0 = none). */
+  gridShare?: number;
+}
+
+const H = heatCore();
+const n = (v: unknown) => Number(v) || 0;
+/** The read surface sends `el` in decimal (UInt64); the wire and anchor.ts use base36. */
+const dec = (el: string) => (/^\d+$/.test(el) ? el : String(parseInt(el, 36)));
+const norm = (s: string | null | undefined) => (s ?? "").replace(/\s+/g, " ").trim();
+
+export function startView(win: Window = window) {
+  const doc = win.document,
+    root = doc.documentElement;
+  let origin = "";
+  const post = (m: Row) => {
+    if (origin) win.parent.postMessage({ dq: "hm", v: VIEW_PROTOCOL, ...m }, origin);
+  };
+
+  const css = doc.createElement("style");
+  css.textContent = `
+  dialog, [role=dialog], [aria-modal=true] { display: none !important; }
+  *, *::before, *::after { animation-duration: 0s !important; animation-delay: 0s !important; animation-iteration-count: 1 !important; transition: none !important; }
+  html { cursor: crosshair; }
+  .__hm { position: absolute; left: 0; top: 0; z-index: 2147483000; pointer-events: none; overflow: hidden; }
+  .__heat, .__wash { position: absolute; left: 0; top: 0; display: none; opacity: var(--op, .85); }
+  .__wash { width: 100%; height: 100%; mix-blend-mode: multiply; }
+  .__marks { position: absolute; inset: 0; }
+  .__line { position: absolute; left: 0; right: 0; height: 0; border-top: 2px dashed rgba(17,20,24,.85); }
+  .__line span { position: absolute; right: 12px; top: -13px; font: 600 12px/1 system-ui, -apple-system, "Segoe UI", sans-serif;
+    color: #fff; background: rgba(17,20,24,.88); padding: 6px 9px; border-radius: 999px; white-space: nowrap; }
+  .__line.__fold { border-top-color: #fff; box-shadow: 0 0 0 1px rgba(17,20,24,.5); }
+  .__line.__fold span { left: 12px; right: auto; background: #fff; color: #111418; box-shadow: 0 2px 10px rgba(0,0,0,.25); }
+  .__zone { position: absolute; box-sizing: border-box; border: 1.5px dashed rgba(17,20,24,.38); border-radius: 6px; }
+  .__zone span { position: absolute; right: 8px; top: 8px; font: 600 11.5px/1.2 system-ui, -apple-system, "Segoe UI", sans-serif; color: #fff;
+    background: rgba(17,20,24,.78); padding: 5px 9px; border-radius: 999px; white-space: nowrap; }
+  .__block { position: absolute; left: 0; right: 0; box-sizing: border-box; border: 3px solid var(--c); background: var(--f); }
+  .__block div { position: absolute; left: 10px; top: 10px; display: flex; flex-wrap: wrap; gap: 4px 12px; align-items: baseline;
+    font: 500 13.5px/1.25 system-ui, -apple-system, "Segoe UI", sans-serif; color: #111418; background: rgba(255,255,255,.94);
+    padding: 7px 11px; border-radius: 8px; box-shadow: 0 2px 12px rgba(0,0,0,.18); max-width: calc(100% - 20px); }
+  .__block div b { font-weight: 700; }
+  .__hl { position: absolute; display: none; box-sizing: border-box; border: 2px solid #fff; border-radius: 6px;
+    box-shadow: 0 0 0 2px #111418, 0 0 0 9999px rgba(17,20,24,.18); }`;
+  const mk = (cls: string, tag = "div") => {
+    const e = doc.createElement(tag);
+    e.className = cls;
+    return e;
+  };
+  const layer = mk("__hm"),
+    canvas = mk("__heat", "canvas") as HTMLCanvasElement,
+    wash = mk("__wash"),
+    marks = mk("__marks"),
+    hl = mk("__hl");
+  for (const c of [canvas, wash, marks, hl]) layer.appendChild(c);
+  const ours = (x: Node | null) => !!x && (x === layer || layer.contains(x) || x === css);
+
+  let data: ViewData | null = null;
+  let index = new Map<string, Element>(); // `${root}|${el decimal}` -> live element
+  let roots = new Map<string, Element>(); // root identity -> live element
+  let keyOf = new WeakMap<Element, string>(); // element -> key, for hover
+  let active: string | null = null,
+    hoverKey: string | null = null,
+    want = new Set<string>();
+  let docW = 0,
+    docH = 0;
+  let blocks: { key: string; y: number; h: number }[] = [];
+
+  /** Hash every element of the live page: any element can be an anchor (a click on plain text
+   *  anchors on its target). Re-run on every snapshot, so it describes the page the heat is on. */
+  function reindex() {
+    index = new Map();
+    roots = new Map();
+    keyOf = new WeakMap();
+    for (const el of Array.from(doc.body.querySelectorAll("*"))) {
+      if (ours(el)) continue;
+      const h = anchorHash(el);
+      const k = `${h.root}|${parseInt(h.el, 36)}`;
+      if (!index.has(k)) index.set(k, el);
+      keyOf.set(el, k);
+      if (h.rootEl && !roots.has(h.root)) roots.set(h.root, h.rootEl);
+    }
+  }
+
+  const box = (el: Element | null | undefined) => {
+    if (!el) return null;
+    const r = el.getBoundingClientRect();
+    if (r.width < 2 || r.height < 2) return null;
+    const x = r.left + win.scrollX;
+    if (x >= docW - 1 || x + r.width <= 1) return null; // off-canvas slide / drawer
+    const cs = win.getComputedStyle(el);
+    if (cs.visibility === "hidden" || cs.opacity === "0") return null;
+    return { x, y: r.top + win.scrollY, w: r.width, h: r.height };
+  };
+
+  /** What a person would call the element. Read here, sent to the parent only. */
+  function labelOf(el: Element): string {
+    const a = norm(
+      el.getAttribute("aria-label") ?? el.getAttribute("alt") ?? el.getAttribute("title"),
+    );
+    if (a) return a.slice(0, 60);
+    const t = norm((el as HTMLElement).innerText ?? el.textContent);
+    if (t) return t.length > 48 ? `${t.slice(0, 46)}…` : t;
+    const img = el.querySelector("img[alt], [aria-label]");
+    const inner = norm(img?.getAttribute("alt") ?? img?.getAttribute("aria-label"));
+    if (inner) return inner.slice(0, 60);
+    const href = el.getAttribute("href");
+    if (href) {
+      try {
+        const u = new URL(href, doc.baseURI);
+        return u.pathname === "/"
+          ? "Link para a home"
+          : `Link para ${decodeURIComponent(u.pathname)}`;
+      } catch {
+        /* fall through */
+      }
+    }
+    return el.tagName === "IMG" ? "Imagem" : `<${el.tagName.toLowerCase()}>`;
+  }
+  const rootName = (r: string) => {
+    if (!r) return "Página";
+    if (r.startsWith("#")) return r;
+    const i = r.lastIndexOf("#"),
+      ord = Number(r.slice(i + 1)),
+      p = r.slice(0, i);
+    const base = p.startsWith("fs:")
+      ? p
+          .slice(3)
+          .replace(/-/g, " ")
+          .replace(/^./, (c) => c.toUpperCase())
+      : (p.split("/").pop() ?? p).replace(/\.tsx?$/, "");
+    return ord > 0 ? `${base} ${ord + 1}` : base;
+  };
+
+  function line(y: number, text: string, kind: string) {
+    const d = mk(`__line __${kind}`);
+    d.style.top = `${y}px`;
+    const s = doc.createElement("span");
+    s.textContent = text;
+    d.appendChild(s);
+    marks.appendChild(d);
+  }
+  function bands(values: ArrayLike<number>, ramp: string) {
+    const stops: string[] = [];
+    for (let i = 0; i < values.length; i++) {
+      stops.push(
+        `${H.rampCss(ramp, values[i], 0.16 + 0.44 * values[i])} ${(((i + 0.5) / values.length) * 100).toFixed(2)}%`,
+      );
+    }
+    wash.style.background = `linear-gradient(to bottom, ${stops.join(",")})`;
+    wash.style.display = "block";
+  }
+
+  function draw() {
+    if (!data || !origin) return;
+    if (!layer.isConnected) root.appendChild(layer);
+    if (!css.isConnected) (doc.head ?? root).appendChild(css);
+    const d = data,
+      ramp = d.ramp ?? "thermal",
+      views = Math.max(1, n(d.views));
+    docW = root.clientWidth;
+    docH = Math.max(doc.body.scrollHeight, root.scrollHeight);
+    layer.style.width = `${docW}px`;
+    layer.style.height = `${docH}px`;
+    layer.style.setProperty("--op", String(d.opacity ?? 0.85));
+    marks.textContent = "";
+    canvas.style.display = "none";
+    wash.style.display = "none";
+
+    const els = d.elements.map((e) => {
+      const cells = Array.isArray(e.cells)
+        ? e.cells
+        : Object.entries(e.cells ?? {}).map(([c, v]) => [Number(c), n(v)] as [number, number]);
+      return {
+        key: `${e.root}|${dec(String(e.el))}`,
+        sec: e.root,
+        el: dec(String(e.el)),
+        clicks: n(e.clicks),
+        cells,
+      };
+    });
+    const radius = d.radius ?? H.radiusFor(H.deviceOf(win.innerWidth) || "desktop");
+    const placed = H.place(
+      els,
+      (sec, el) => box(index.get(`${sec}|${el}`)),
+      (sec) => box(roots.get(sec)),
+      radius,
+    );
+    const reach = H.reachCurve(
+      (d.depth ?? []).map((r) => [n(r.depth), n(r.views)]),
+      views,
+    );
+    let legend: number[] = [];
+
+    if (d.mode === "clicks") {
+      const grid = d.grid ?? [];
+      const gridTotal = grid.reduce((s, g) => s + n(g.clicks), 0);
+      const missing = placed.total - placed.matchedClicks - placed.sectionClicks;
+      // ponytail: grid scaled by the unplaced share, not per-click exclusion (same as the viewer).
+      const share = gridTotal > 0 ? Math.min(1, (missing / gridTotal) * (d.gridShare ?? 1)) : 0;
+      const gp =
+        share > 0
+          ? H.gridPoints(
+              grid.map((g) => ({ fixed: !!g.fixed, xb: g.xb, yb: g.yb, clicks: n(g.clicks) })),
+              docW,
+            ).map(([x, y, w]) => [x, y, w * share] as [number, number, number])
+          : [];
+      const cell = Math.max(3, Math.ceil(docH / 30000));
+      const cur = H.density([...placed.points, ...gp], docW, docH, cell, radius);
+      canvas.width = cur.cols;
+      canvas.height = cur.rows;
+      canvas.style.width = `${cur.cols * cell}px`;
+      canvas.style.height = `${cur.rows * cell}px`;
+      // One sort for the p99 normalisation and the legend, not four.
+      const q = H.quantiles(cur.field, [0.5, 0.9, 0.99]);
+      const px = H.colorize(cur.field, q[2], H.lut(ramp), !!d.log);
+      canvas
+        .getContext("2d")!
+        .putImageData(
+          new ImageData(px as unknown as Uint8ClampedArray<ArrayBuffer>, cur.cols, cur.rows),
+          0,
+          0,
+        );
+      canvas.style.display = "block";
+      const area = (Math.PI * (radius / 2) ** 2 * 2) / (cell * cell);
+      legend = q.map((v) => v * area);
+      for (const [sec, z] of placed.sections) {
+        const zone = mk("__zone");
+        zone.style.cssText = `left:${z.box.x}px;top:${z.box.y}px;width:${z.box.w}px;height:${z.box.h}px`;
+        const chip = doc.createElement("span");
+        chip.textContent = `${Math.round(z.clicks * (d.scale ?? 1)).toLocaleString("pt-BR")} cliques em itens escondidos ou que mudaram`;
+        zone.appendChild(chip);
+        zone.dataset.key = `sec:${sec}`;
+        marks.appendChild(zone);
+      }
+    } else if (d.mode === "scroll") {
+      bands(
+        Array.from({ length: 100 }, (_, i) => reach[i]),
+        ramp,
+      );
+      if (d.avgFold)
+        line((d.avgFold / 100) * docH, `Dobra média, ${Math.round(d.avgFold)}% da página`, "fold");
+      for (const s of [0.75, 0.5, 0.25]) {
+        const at = H.depthAtReach(reach, s);
+        if (at < 100) line((at / 100) * docH, `${Math.round(s * 100)}% chegaram até aqui`, "reach");
+      }
+    } else if (d.mode === "attention") {
+      const b = H.attentionBands((d.attention ?? []).map((r) => [n(r.band), n(r.ds)]));
+      const max = Math.max(...b) || 1;
+      bands(
+        Array.from(b, (v) => v / max),
+        ramp,
+      );
+      legend = [max / 10 / views];
+    }
+
+    // Blocks: every Deco section / FastStore component root on this page, with what the read
+    // surface knows about it.
+    const stats = new Map((d.sections ?? []).map((s) => [s.root, s]));
+    const clicksBy = new Map<string, number>();
+    for (const e of els) clicksBy.set(e.sec, (clicksBy.get(e.sec) ?? 0) + e.clicks);
+    const out = [...roots]
+      .filter(([k]) => k && !k.startsWith("#"))
+      .flatMap(([key, el]) => {
+        const b = box(el);
+        if (!b) return [];
+        const s = stats.get(key);
+        return [
+          {
+            key,
+            name: rootName(key),
+            heading: norm(el.querySelector("h1, h2, h3")?.textContent).slice(0, 60),
+            y: b.y,
+            h: b.h,
+            clicks: clicksBy.get(key) ?? 0,
+            reach: s
+              ? n(s.reach_pct) / 100
+              : d.depth?.length
+                ? reach[Math.min(100, Math.floor((b.y / docH) * 100))]
+                : null,
+            seconds: s ? n(s.avg_s) : null,
+          },
+        ];
+      })
+      .sort((a, b) => a.y - b.y);
+    blocks = out.map(({ key, y, h }) => ({ key, y, h }));
+    if (d.mode === "sections") {
+      const maxC = Math.max(1, ...out.map((b) => b.clicks));
+      for (const b of out) {
+        const z = mk("__block"),
+          t = b.clicks / maxC;
+        z.dataset.key = `blk:${b.key}`;
+        z.style.cssText = `top:${b.y}px;height:${b.h}px;--c:${H.rampCss(ramp, 0.15 + 0.85 * t, 1)};--f:${H.rampCss(ramp, 0.15 + 0.85 * t, 0.08 + 0.2 * t)}`;
+        const chip = doc.createElement("div");
+        const parts = [
+          b.name,
+          `${Math.round(b.clicks * (d.scale ?? 1)).toLocaleString("pt-BR")} cliques`,
+        ];
+        if (b.reach != null) parts.push(`${Math.round(b.reach * 100)}% viram`);
+        if (b.seconds != null) parts.push(`${b.seconds.toFixed(1)} s em média`);
+        for (const p of parts) {
+          const s = doc.createElement(p === b.name ? "b" : "span");
+          s.textContent = p;
+          chip.appendChild(s);
+        }
+        z.appendChild(chip);
+        marks.appendChild(z);
+      }
+    }
+
+    paint(false);
+    const items = els.map((e) => {
+      const node = index.get(e.key),
+        b = box(node);
+      return {
+        key: e.key,
+        label: node ? labelOf(node) : "",
+        found: b ? "el" : placed.sections.has(e.sec) ? "sec" : "none",
+        y: b ? b.y : (placed.sections.get(e.sec)?.box.y ?? -1),
+        h: b ? b.h : 0,
+      };
+    });
+    post({
+      t: "placed",
+      items,
+      blocks: out,
+      height: docH,
+      width: docW,
+      legend,
+      stats: {
+        matched: placed.matchedClicks,
+        inSection: placed.sectionClicks,
+        total: placed.total,
+        matchRate: placed.total ? placed.matchedClicks / placed.total : null,
+      },
+    });
+  }
+
+  const boxOfKey = (key: string) => {
+    if (key.startsWith("blk:")) {
+      const b = blocks.find((x) => `blk:${x.key}` === key);
+      return b ? { x: 0, y: b.y, w: docW, h: b.h } : null;
+    }
+    return box(index.get(key));
+  };
+  function paint(scroll: boolean) {
+    const k = hoverKey ?? active,
+      b = k ? boxOfKey(k) : null;
+    if (!b) {
+      hl.style.display = "none";
+      return;
+    }
+    hl.style.cssText = `display:block;left:${b.x - 3}px;top:${b.y - 3}px;width:${b.w + 6}px;height:${b.h + 6}px`;
+    if (scroll) win.scrollTo({ top: Math.max(0, b.y - win.innerHeight / 3), behavior: "smooth" });
+  }
+
+  // ---- the print: the heat is drawn once and stays put -------------------------------------
+  // Redrawing it against the live DOM on every scroll frame and every mutation (carousels, lazy
+  // images) kept the store's main thread busy and made the page stutter. So the heat is a snapshot:
+  // hash the page, place, paint, and leave it. It is taken again only when what it shows changes:
+  // new data from the parent, a new width, a page that grew or shrank once it went quiet, and when
+  // someone comes back to the tab. In between the page stays live underneath (it scrolls, carousels
+  // turn, links hover); the heat does not follow it.
+  //
+  // There is deliberately NO clock. A periodic retake brings no new numbers -- the print redraws
+  // the page as it is NOW, and fresher figures only ever arrive as `data` -- so all it could do was
+  // spend a full re-hash and draw on the store's page at an arbitrary moment. Its one real job is
+  // healing drift (a carousel moved, a section swapped), and `visibilitychange` does that job
+  // better: it costs nothing while nobody is looking and fires exactly when someone looks again.
+  const QUIET_MS = 1000;
+  let timer = 0,
+    quiet = 0,
+    snapW = 0,
+    snapH = 0;
+  const snap = () => {
+    win.clearTimeout(timer);
+    timer = 0;
+    if (!data) return;
+    reindex();
+    draw();
+    snapW = docW;
+    snapH = docH;
+  };
+  const soon = () => {
+    if (!timer) timer = win.setTimeout(snap, 250);
+  };
+  /** Cleared with the overlay: a frame nobody is looking at holds no timer at all. This is the
+   *  store's own page, and the tab can be left framed for a working day. */
+  const stop = () => {
+    win.clearTimeout(timer);
+    timer = 0;
+    win.clearTimeout(quiet);
+    quiet = 0;
+    snapW = snapH = 0;
+  };
+  /** A height change is acted on only after QUIET_MS without one, and never mid-scroll: lazy
+   *  content arrives in bursts, and one snapshot after it settles is the one worth taking. */
+  const settle = () => {
+    win.clearTimeout(quiet);
+    quiet = win.setTimeout(() => {
+      quiet = 0;
+      if (data && Math.max(doc.body.scrollHeight, root.scrollHeight) !== snapH) soon();
+    }, QUIET_MS);
+  };
+  new ResizeObserver(settle).observe(doc.body);
+  win.addEventListener(
+    "resize",
+    () => {
+      if (data && root.clientWidth !== snapW) soon();
+    },
+    { passive: true },
+  );
+  win.addEventListener(
+    "scroll",
+    () => {
+      post({ t: "scroll", top: win.scrollY, vh: win.innerHeight, dh: docH });
+      if (quiet) settle();
+    },
+    { passive: true },
+  );
+  // Back to the tab after it was elsewhere: whatever the page did meanwhile, the print is redrawn
+  // over it before anyone reads it.
+  doc.addEventListener("visibilitychange", () => {
+    if (data && doc.visibilityState === "visible") soon();
+  });
+
+  // ---- hover and select: the page is a picture, nothing navigates -----------------------------
+  let mraf = 0;
+  doc.addEventListener(
+    "mousemove",
+    (ev) => {
+      if (mraf || !data) return;
+      mraf = win.requestAnimationFrame(() => {
+        mraf = 0;
+        const y = ev.clientY + win.scrollY;
+        if (data!.mode === "scroll" || data!.mode === "attention") {
+          post({
+            t: "hover",
+            key: null,
+            x: ev.clientX,
+            y: ev.clientY,
+            pct: docH ? Math.min(1, y / docH) : 0,
+          });
+          return;
+        }
+        let key: string | null = null;
+        if (data!.mode === "sections") {
+          const b = blocks.find((x) => y >= x.y && y <= x.y + x.h);
+          key = b ? `blk:${b.key}` : null;
+        } else {
+          for (
+            let el = doc.elementFromPoint(ev.clientX, ev.clientY);
+            el && el !== doc.body && !key;
+            el = el.parentElement
+          ) {
+            const k = keyOf.get(el);
+            if (k && want.has(k)) key = k;
+          }
+        }
+        if (key === hoverKey) return;
+        hoverKey = key;
+        paint(false);
+        const el = key && !key.startsWith("blk:") ? index.get(key) : null;
+        post({ t: "hover", key, label: el ? labelOf(el) : null, x: ev.clientX, y: ev.clientY });
+      });
+    },
+    { passive: true },
+  );
+  doc.addEventListener("mouseleave", () => {
+    hoverKey = null;
+    paint(false);
+    post({ t: "hover", key: null });
+  });
+  const block = (ev: Event) => {
+    ev.preventDefault();
+    ev.stopPropagation();
+  };
+  doc.addEventListener(
+    "click",
+    (ev) => {
+      block(ev);
+      if (hoverKey) post({ t: "select", key: hoverKey });
+    },
+    true,
+  );
+  doc.addEventListener("submit", block, true);
+  doc.addEventListener("auxclick", block, true);
+
+  // ---- the protocol ---------------------------------------------------------------------------
+  win.addEventListener("message", (e: MessageEvent) => {
+    if (e.source !== win.parent || !e.data || e.data.dq !== "hm") return;
+    if (!origin) {
+      // The handshake: the first message must be `init` from an allowed origin. It pins that origin.
+      if (e.data.t !== "init" || !ALLOWED_PARENT.test(e.origin)) return;
+      origin = e.origin;
+      reindex();
+      post({
+        t: "ready",
+        protocol: VIEW_PROTOCOL,
+        url: win.location.href,
+        title: doc.title,
+        width: root.clientWidth,
+        height: Math.max(doc.body.scrollHeight, root.scrollHeight),
+        anchors: index.size,
+      });
+      return;
+    }
+    if (e.origin !== origin) return;
+    const m = e.data;
+    if (m.t === "init")
+      post({
+        t: "ready",
+        protocol: VIEW_PROTOCOL,
+        url: win.location.href,
+        title: doc.title,
+        width: root.clientWidth,
+        height: docH,
+        anchors: index.size,
+      });
+    else if (m.t === "data" && m.d) {
+      data = m.d as ViewData;
+      want = new Set(data.elements.map((x) => `${x.root}|${dec(String(x.el))}`));
+      soon();
+    } else if (m.t === "highlight") {
+      active = typeof m.key === "string" ? m.key : null;
+      paint(!!m.scroll);
+    } else if (m.t === "scrollTo") {
+      const b = typeof m.key === "string" ? boxOfKey(m.key) : null;
+      win.scrollTo({
+        top: b ? Math.max(0, b.y - win.innerHeight / 3) : n(m.y),
+        behavior: "smooth",
+      });
+    } else if (m.t === "clear") {
+      data = null;
+      stop();
+      layer.remove();
+      css.remove();
+    }
+  });
+  // Exposed for tests only: the hash this view computes for an element, same as the runtime's.
+  (win as any).__dqViewKey = (el: Element) => {
+    const h = anchorHash(el);
+    return `${h.root}|${parseInt(h.el, 36)}`;
+  };
+}
+
+startView();
diff --git a/packages/blocks/src/v8/analytics/shared/anchor.ts b/packages/blocks/src/v8/analytics/shared/anchor.ts
new file mode 100644
index 00000000..ecd3ad37
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/shared/anchor.ts
@@ -0,0 +1,171 @@
+/** Element anchors for heatmaps: the ONE definition of "which element was clicked", shared by
+ *  the browser runtime (`runtime/modules/heatmap.ts`) and the viewer that paints the heat on a
+ *  server-rendered snapshot (insights-mcp vendors this file verbatim).
+ *
+ *  Both sides must produce the same hash for the same element, so this file is self-contained:
+ *  no imports, no globals beyond the DOM node it is handed, nothing that differs between a
+ *  visitor's browser and a sandboxed iframe. `tests/fixtures/anchor-vectors.json` pins the output;
+ *  a change to anything below that moves a vector is a breaking change for every heatmap already
+ *  collected, so it bumps ANCHOR_VERSION and ships in both repos at once.
+ *
+ *  The algorithm, exactly:
+ *
+ *  1. ANCHOR. From the click target, walk up at most 6 elements (target included) and take the
+ *     first that matches ACTIONABLE (interactive = true). If none does, repeat the walk and take
+ *     the first element carrying a `data-fs-*` attribute that is not a page wrapper, stopping at a
+ *     Deco section (interactive = false). Else the target.
+ *     A click on the <span> inside "Comprar" counts for the button, which is what a reader expects.
+ *
+ *  2. ROOT, the first that applies:
+ *     a. the nearest `section[data-manifest-key]` (Deco CMS section, self included):
+ *        identity `<manifest key>#<ordinal among sections with the same key, document order>`;
+ *     b. the OUTERMOST element on the anchor's ancestor chain (self included, `body` excluded)
+ *        carrying a `data-fs-*` attribute whose component name is not a page wrapper (WRAPPER):
+ *        identity `fs:<name>#<ordinal among elements carrying that attribute>`. Outermost, not
+ *        nearest: measured on FILA, New Balance and Umbro (2026-10-26), none of which render a
+ *        single `data-manifest-key` section, the outermost FastStore component is the
+ *        section-sized one (`hero-slideshow`, `tabbed-product-shelf`, `desktop-header`), while the
+ *        nearest is a product card or a link whose ordinal shifts as lazy content loads;
+ *     c. the nearest ancestor-or-self with an `id` that does not look generated (BAD_ID):
+ *        identity `#<id>`;
+ *     d. `body`: identity "" (the wire sends section index -1).
+ *     `<name>` is the attribute name without `data-fs-`. A `data-fs-*` attribute is chosen as the
+ *     alphabetically FIRST one on the element, so attribute order never matters.
+ *
+ *  3. PATH from root (exclusive) to anchor (inclusive), root first, segments joined by `>`:
+ *     `<localName>` + (`[<first data-fs-* attribute name>]` if any) + `:` + nth-of-type (1-based).
+ *     Example: `div:2>article[data-fs-product-card]:3>a:1`. Empty when the anchor is the root.
+ *     Classes, text, href, src and non-root ids are excluded on purpose: classes churn on every
+ *     Tailwind deploy, and text/href are PII and change daily.
+ *
+ *  4. HASH: `cyrb53(identity + "|" + path)`, a 53-bit integer (exact in a JS number and in JSON),
+ *     sent as base36. Collision odds at ~5,000 clickable elements per page: about 1e-9.
+ */
+export const ANCHOR_VERSION = 1;
+
+export const ACTIONABLE =
+  "a,button,input,select,textarea,label,summary,[role=button],[role=link],[role=tab]," +
+  '[role=menuitem],[role=option],[role=checkbox],[tabindex]:not([tabindex="-1"])';
+
+/** FastStore component names that wrap a whole page rather than one part of it. Umbro's home is
+ *  `data-fs-home` around every block; taking it as the root would put the whole page in one
+ *  "section". */
+export const WRAPPER = /^(home|page|layout|content|main|root|wrapper|container|region|grid)$/;
+
+/** Ids minted by a framework or a counter: different on every render, so useless as a root. */
+export const BAD_ID = /\d{4,}|^:r|^radix-|^headlessui-|[0-9a-f]{8}|react-aria|[:«»]/;
+
+/** cyrb53 (bryc, public domain): a fast 53-bit string hash with good avalanche. */
+export function cyrb53(s: string, seed = 0): number {
+  let h1 = 0xdeadbeef ^ seed,
+    h2 = 0x41c6ce57 ^ seed;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+}
+
+/** The alphabetically first `data-fs-*` attribute name on an element, or "". */
+export function fsAttr(e: Element): string {
+  let m = "";
+  for (const n of e.getAttributeNames()) if (n.startsWith("data-fs-") && (!m || n < m)) m = n;
+  return m;
+}
+
+/** Step 1. Returns the anchor and whether it is interactive. */
+export function anchorOf(t: Element): [Element, boolean] {
+  let e: Element | null = t;
+  for (let i = 0; e && i < 6; e = e.parentElement, i++) if (e.matches(ACTIONABLE)) return [e, true];
+  // Never a page wrapper, and never across a Deco section: an <h2> clicked inside a section must
+  // not anchor on the `data-fs-home` that wraps every section of the page.
+  e = t;
+  for (
+    let i = 0;
+    e && i < 6 && !e.matches("section[data-manifest-key]");
+    e = e.parentElement, i++
+  ) {
+    const f = fsAttr(e);
+    if (f && !WRAPPER.test(f.slice(8))) return [e, false];
+  }
+  return [t, false];
+}
+
+const ordinal = (list: NodeListOf<Element>, e: Element, same: (x: Element) => boolean) => {
+  let n = 0;
+  for (const x of list) {
+    if (x === e) return n;
+    if (same(x)) n++;
+  }
+  return n;
+};
+
+/** A FastStore component root by step 2b, or "" — exported so a viewer can enumerate roots. */
+export function fsRootName(e: Element): string {
+  const a = fsAttr(e);
+  return a && !WRAPPER.test(a.slice(8)) && /^[a-z0-9-]+$/.test(a) ? a : "";
+}
+
+/** Step 2. Returns the root element (null for body) and its identity. */
+export function rootOf(a: Element): [Element | null, string] {
+  const d = a.ownerDocument;
+  const s = a.closest("section[data-manifest-key]");
+  if (s) {
+    const k = s.getAttribute("data-manifest-key")!;
+    return [
+      s,
+      k +
+        "#" +
+        ordinal(
+          d.querySelectorAll("section[data-manifest-key]"),
+          s,
+          (x) => x.getAttribute("data-manifest-key") === k,
+        ),
+    ];
+  }
+  let fs: Element | null = null,
+    name = "";
+  for (let e: Element | null = a; e && e !== d.body; e = e.parentElement) {
+    const n = fsRootName(e);
+    if (n) {
+      fs = e;
+      name = n;
+    }
+  }
+  if (fs)
+    return [
+      fs,
+      "fs:" + name.slice(8) + "#" + ordinal(d.querySelectorAll("[" + name + "]"), fs, () => true),
+    ];
+  for (let e: Element | null = a; e && e !== d.body; e = e.parentElement) {
+    if (e.id && !BAD_ID.test(e.id)) return [e, "#" + e.id];
+  }
+  return [null, ""];
+}
+
+/** Step 3. */
+export function pathOf(root: Element | null, a: Element): string {
+  const out: string[] = [];
+  for (
+    let e: Element | null = a, i = 0;
+    e && e !== root && e !== e.ownerDocument.body && i < 64;
+    e = e.parentElement, i++
+  ) {
+    let n = 1;
+    for (let s = e.previousElementSibling; s; s = s.previousElementSibling)
+      if (s.localName === e.localName) n++;
+    const f = fsAttr(e);
+    out.push(e.localName + (f ? "[" + f + "]" : "") + ":" + n);
+  }
+  return out.reverse().join(">");
+}
+
+/** Steps 2-4 for an element already chosen as anchor: what the wire carries and what a viewer
+ *  matches on. `root` is the identity string ("" = body), `el` the base36 hash. */
+export function anchorHash(a: Element): { root: string; el: string; rootEl: Element | null } {
+  const [rootEl, root] = rootOf(a);
+  return { root, el: cyrb53(root + "|" + pathOf(rootEl, a)).toString(36), rootEl };
+}
diff --git a/packages/blocks/src/v8/analytics/shared/contract.ts b/packages/blocks/src/v8/analytics/shared/contract.ts
new file mode 100644
index 00000000..f4fc2ea1
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/shared/contract.ts
@@ -0,0 +1,691 @@
+/** The payload contract — one definition, imported by the runtime and by the Worker.
+ *
+ *  It lived in two files with duplicated constants, which is the reliable way to end up
+ *  with a client truncating at 200 and a server truncating at 250. The runtime applies
+ *  these rules to save bandwidth; the Worker applies them because the endpoint is public
+ *  and the client is by definition untrusted. Same rules, different reasons.
+ *
+ *  Fields deliberately do NOT share one charset. Applying a single rule everywhere is the
+ *  mistake: `plp-ranking` is a frozen experiment key owned by another team and contains a
+ *  hyphen, and an order id from a customer's OMS is opaque and case-sensitive. Normalising
+ *  those would break a join and an invoice respectively.
+ */
+
+export const LIMITS = {
+  requestBytes: 64 * 1024,
+  // What the runtime puts in ONE request, under `requestBytes` with room for the envelope. Also
+  // under the browser's 64 KB keepalive/beacon quota, so a final flush is never refused whole.
+  batchBytes: 56 * 1024,
+  eventsPerBatch: 50,
+  eventBytes: 1024,
+  errorEventBytes: 8 * 1024,
+  // `$heatmap`: one event per page view carrying its clicks, scroll and attention. Measured
+  // ~450-500 B for a typical storefront view; the client sheds its newest clicks to stay
+  // under 3,800 B, so this is a ceiling the runtime never reaches on its own.
+  heatmapEventBytes: 4 * 1024,
+  hmClicks: 40, // click records per view (a rage burst is ONE record with a count)
+  hmRoots: 32, // root dictionary entries per view
+  hmBands: 40, // attention bands, 2.5% of the document each
+  hmRootLen: 120, // a root identity: manifest key + ordinal, or fs:<component>#n
+  queueMax: 200,
+
+  // GA4's limit. Anything valid there is valid here, so a migration does not hit a new
+  // ceiling on arrival.
+  nameLen: 40,
+  propKeys: 24, // GA4 allows 25
+  keyLen: 40,
+  valueLen: 200,
+
+  expEntries: 8,
+  expKeyLen: 60,
+  pathLen: 512,
+  refLen: 256,
+  itemIds: 20,
+  itemIdLen: 64,
+  transactionIdLen: 64, // order ids run longer than a prop key
+  flushMs: 10_000,
+} as const;
+
+/** `_trunc` is `LowCardinality(String)`. A free-text flag would rebuild the cardinality
+ *  problem inside the column that exists to detect it, so the vocabulary is closed —
+ *  and small, which keeps its dictionary at a handful of entries for the whole fleet. */
+/** Flags are namespaced by the field they concern. `value.type` was ambiguous: there is
+ *  also a column called `value` holding money, so a reader could not tell whether the flag
+ *  meant "a prop was the wrong type" or "the amount would not parse". Now `props.*` is
+ *  about the props map and `amount.*` is about money.
+ *
+ *  The four the client needs are exported individually as well as in the map below.
+ *  esbuild cannot tree-shake a single property off an object it sees referenced, so
+ *  `FLAGS.propsCount` drags all twenty-one strings into the browser bundle. Naming them
+ *  separately keeps the client at the four it uses. */
+export const F_PROPS_COUNT = "props.count";
+export const F_PROPS_TYPE = "props.type";
+export const F_PROPS_LEN = "props.len";
+export const F_QUEUE_OVERFLOW = "queue.overflow";
+/** More events arrived in one request than `eventsPerBatch` allows. The surplus is discarded
+ *  and the survivors carry this, so the loss is visible in the warehouse rather than inferred
+ *  from a gap — the same contract `queue.overflow` makes on the client. */
+export const F_BATCH_OVERFLOW = "batch.overflow";
+
+export const FLAGS = {
+  nameEmpty: "name.empty",
+  nameCharset: "name.charset",
+  nameLen: "name.len",
+  nameReserved: "name.reserved",
+  keyCharset: "key.charset",
+  keyLen: "key.len",
+  propsCount: F_PROPS_COUNT,
+  propsType: F_PROPS_TYPE,
+  propsLen: F_PROPS_LEN,
+  propsControl: "props.control",
+  expCount: "exp.count",
+  expCharset: "exp.charset",
+  currencyInvalid: "currency.invalid",
+  amountType: "amount.type",
+  pathLen: "path.len",
+  refLen: "referrer.len",
+  itemIdsCount: "item_ids.count",
+  tsSkew: "ts.skew",
+  queueOverflow: F_QUEUE_OVERFLOW,
+  eventSize: "event.size",
+  // The sender's id was absent or not a UUID, so the Worker minted one. Recorded rather
+  // than silent because it costs the event its only dedup key: `uniqExact(event_id)` can
+  // no longer collapse a retry of the same event, and a number that quietly counts a
+  // retry twice is worse than one that says why.
+  eventIdMinted: "event_id.minted",
+  // Tier 0 identity for this row was built from a DERIVED salt because the day's stored one was
+  // missing — a cron that did not run. Derived from YESTERDAY's random salt, not from any
+  // secret, so the day is recomputable only until that salt expires from KV (around 03:10 UTC
+  // the following day), and then by nobody. Recorded rather than silent: "which days were recomputable,
+  // and for how long" has to be answerable from the warehouse. Rows written before 2026-10-27
+  // carry the same flag for a salt derived from `SALT_SECRET`/`VISITOR_SECRET`.
+  saltDerived: "salt.derived",
+  // Neither today's nor yesterday's salt was in KV, so this isolate minted a random salt for
+  // the day and holds it only in memory. Unrecomputable by anyone, and that costs counting:
+  // a visitor whose requests reach two isolates is two visitor_ids that day. Recorded so a
+  // fragmented day's unique counts are known to be inflated rather than trusted.
+  saltEphemeral: "salt.ephemeral",
+  // A tier 1 site sent a consented client id and there was no VISITOR_SECRET to hash it with,
+  // so this row fell back to tier 0 identity. Recorded because the failure is otherwise
+  // INVISIBLE AND EXPENSIVE: the site keeps collecting, every number looks right, and the one
+  // thing consent was collected to enable -- following the same person across days -- silently
+  // does not happen. The remedy is a deploy, so it has to be findable in the warehouse.
+  consentNoSecret: "consent.no_secret",
+  // DEPRECATED, never stamped any more. It meant "`SALT_SECRET` is unset, so tier 0's fallback
+  // would derive from `VISITOR_SECRET`". Tier 0 no longer has a secret at all (#13), so the
+  // state it described cannot exist. Declared still because rows written before 2026-10-27
+  // carry it, and this is where the `_trunc` vocabulary is closed.
+  saltSecretUnsplit: "salt.unsplit",
+  originMismatch: "origin.mismatch",
+  // An event or a prop key the site never declared. Recorded, never rejected: a taxonomy
+  // that drops data punishes the analyst for the developer's mistake, and the whole
+  // point of a registry is to make drift VISIBLE, not to lose the drifted data.
+  nameUnregistered: "name.unregistered",
+  propsUnregistered: "props.unregistered",
+  // The only two flags no collected event ever carries: they are written by `ops/backfill.mjs`
+  // on rows imported from the vendor we are replacing, and the Worker never sets them.
+  //
+  // They live here anyway, because this is where the `_trunc` vocabulary is CLOSED. A value in
+  // that column that is not declared here is off-contract, and the reason the vocabulary is
+  // closed at all -- keeping a LowCardinality dictionary at a handful of entries -- does not
+  // care which process wrote the row.
+  //
+  // `import.vendor` is provenance. `site_id_source = 'import'` already says a row was not
+  // collected; it does not say by whom, and the day a second vendor or a customer CSV arrives,
+  // "not host and not tag" identifies nothing.
+  //
+  // `import.day_grain` is a warning about the row's TIME. The vendor cannot report hours --
+  // `time:hour` collapses to a single bucket on their side -- so every imported event of a day
+  // sits at 00:00 of that day, and any hourly panel over an imported window is a midnight spike
+  // and nothing else. We do not synthesise a diurnal curve to make that chart look reasonable:
+  // an invented shape is worse than an absent one, because only the absent one is discoverable.
+  // This flag is how it is discovered.
+  //
+  // NEITHER IS A TRUST BOUNDARY. `flagSink` carries a payload's prior `_trunc` through without
+  // checking it against this list, so any browser can post either string -- as it already could
+  // before they were named here. The mark billing reads is `site_id_source`, which the Worker
+  // resolves and the payload cannot influence. These two are for a human reading a row.
+  // `$heatmap` only. `hm.len`: an array or a value was capped to its LIMITS bound. `hm.shape`:
+  // something was the wrong type or out of range and was DROPPED -- a click with no valid anchor
+  // hash, a section index pointing nowhere, a missing view id. Two flags rather than one per
+  // field, for the reason the vocabulary is closed at all.
+  hmLen: "hm.len",
+  hmShape: "hm.shape",
+  // `edge_events` only. The store's Worker called `EdgeIngest.write` without a bot score, so the
+  // row carries 99, the same "unknown, keep it" default a request without `cf.botManagement`
+  // gets on `workers.dev`. Marked because an RPC call carries no `request.cf` of its own: the
+  // score exists only if the caller forwarded it, and a funnel with bots quietly left in has to
+  // be findable.
+  edgeNoBotScore: "edge.no_bot_score",
+  importVendor: "import.vendor",
+  importDayGrain: "import.day_grain",
+} as const;
+
+export type Flag = (typeof FLAGS)[keyof typeof FLAGS];
+export type Primitive = string | number | boolean;
+export type Props = Record<string, Primitive>;
+
+/** Platform events. Anything else arriving with a `$` is a site reaching into a namespace
+ *  that is not its own: the prefix is stripped and the attempt recorded. */
+/** Platform events. Anything else arriving with a `$` is a site reaching into a namespace
+ *  that is not its own: the prefix is stripped and the attempt recorded.
+ *
+ *  The engagement four are reserved for the same reason as the rest — they are generated
+ *  by our module, not by the site, so a registry must not ask a site to declare them and
+ *  a site must not be able to forge them. */
+export const RESERVED_NAMES = [
+  "$pageview",
+  "$error",
+  "$vitals",
+  "$exposure",
+  "$scroll",
+  "$outbound",
+  "$download",
+  "$search",
+  // One per sampled page view, from the heatmap module. Reserved for the same two reasons as
+  // the engagement four, and the second matters more here: sampling is decided per VIEW by the
+  // module (`heatmapRate`), so the per-event valve must never touch it.
+  "$heatmap",
+] as const;
+
+/** Whether the sampling valve is allowed to drop this event.
+ *
+ *  Sampling used to apply to EVERYTHING, `$pageview` included, and that is not what anyone
+ *  else does: GA4 samples in the REPORT when a query exceeds its quota, never at
+ *  collection, and Plausible does not sample at all. Dropping pageviews also produced the
+ *  worst possible arithmetic — a visitor with k events survives a rate r with probability
+ *  1-(1-r)^k, so a nominal 10% sample kept ~50% of visitors while keeping exactly 10% of
+ *  events, a five-fold overcount of uniques.
+ *
+ *  The collector's own `$` events are exempt, and that dissolves the problem rather than
+ *  mitigating it: every visit carries a `$pageview`, so if pageviews never drop then
+ *  visitor counts are exact at any rate. They are also bounded per pageview by
+ *  construction — one pageview, one vitals, one scroll, errors already collapsed into
+ *  `error_count` — so exempting them sheds almost no volume.
+ *
+ *  What floods a site is custom events: `track()` in a render loop is the emergency this
+ *  valve exists for, and it is the only thing the valve now touches. */
+export function isSampleable(name: string): boolean {
+  return !name.startsWith("$");
+}
+
+/** What the store's own Worker may write through `EdgeIngest`, and the props each one carries.
+ *
+ *  A CLOSED vocabulary, unlike the tag's. The edge is ours: these are the requests a store
+ *  Worker sees on both sides of a Fresh x TanStack split, emitted by one wrapper rather than by
+ *  each site's code, and that sameness is the whole reason they can be a ruler for an A/B test
+ *  between two codebases. A name outside this list is refused and counted; a prop outside it is
+ *  kept and flagged `props.unregistered`, like the site registry does.
+ *
+ *  They land in `edge_events`, never in `raw_events` (D20), so no panel, rollup or session
+ *  built on the tag ever counts a checkout API call as a page view. */
+export const EDGE_EVENTS = {
+  /** One per HTML document, on both sides of the split. `og` is the orderGroup on the order
+   *  confirmation (`/checkout/orderPlaced?og=`): it links a VTEX order to the visit that saw it.
+   *  `sc` is the sales channel of the request; `cart` the hashed orderForm on checkout documents. */
+  $edge_page: ["page", "status", "prefetch", "cache", "ttfb_ms", "og", "sc", "cart", "fetch_site"],
+  /** One per call to the VTEX checkout API. `step` includes `gatewayCallback`. The cart shape
+   *  (`qty` .. `items_value`, `payment`, `coupon`) is read from the orderForm that `shippingData`
+   *  and `paymentData` return; `error` is the VTEX code and message on a status >= 400. */
+  checkout_step: [
+    "step",
+    "status",
+    "cart",
+    "payment",
+    "coupon",
+    "shipping_paid",
+    "items",
+    "referer",
+    "error",
+    "ms",
+    "from_checkout",
+    "qty",
+    "lines",
+    "sellers",
+    "packages",
+    "shipping",
+    "items_value",
+  ],
+  /** One per call that changes the cart outside the checkout: `add`, `remove`, `update`,
+   *  `coupon`, `simulate`. The route differs per side (v7's invoke route on Fresh, the TanStack
+   *  invoke route), and the store Worker maps both to this. */
+  cart_action: ["action", "status", "cart", "items"],
+  /** What the shopper is paying and why, beside `checkout_step` on `shippingData` and
+   *  `paymentData`: discounts, promotions, the orderForm's messages, unavailable items, gifts,
+   *  who VTEX thinks the shopper is, and what the payment POST asked for. */
+  checkout_summary: [
+    "step",
+    "status",
+    "cart",
+    "value",
+    "items_value",
+    "discounts",
+    "shipping",
+    "qty",
+    "lines",
+    "promos",
+    "promo_hash",
+    "promo_names",
+    "messages",
+    "message_count",
+    "unavailable",
+    "selectable_gifts",
+    "gift_items",
+    "priced_items",
+    "utm_source",
+    "coupon",
+    "tags",
+    "channels",
+    "pay_systems",
+    "installments",
+    "pay_value",
+    "logged_in",
+    "can_edit",
+    "email",
+    "profile_id",
+    "saved_cards",
+    "saved_addresses",
+    "cookies",
+  ],
+  /** The checkout page's own beacon, forwarded by the store Worker: JS errors, the step the
+   *  shopper is on, the click on "place order" (`kind = buy`) and what followed it, the messages
+   *  on screen, the exit. `kind` is the beacon's, `msg`/`aux`/`n` its three fields. */
+  checkout_js: ["kind", "msg", "aux", "n", "cart"],
+} as const satisfies Record<string, readonly string[]>;
+
+export type EdgeEventName = keyof typeof EDGE_EVENTS;
+/** Props per edge event. Above the tag's `propKeys` because the vocabulary is closed and ours:
+ *  `checkout_summary` carries 32 fields, and packing them into fewer keys would trade a query on
+ *  a column for a parse of a string. */
+export const EDGE_PROP_KEYS = 40;
+/** Size budget per edge event, for the same reason: the tag's 1 KB is a budget for a visitor's
+ *  upload on mobile data, and an edge event never travels over one. */
+export const EDGE_EVENT_BYTES = 4096;
+export const EDGE_EVENT_NAMES = Object.keys(EDGE_EVENTS) as EdgeEventName[];
+
+/** The side of a Fresh x TanStack split, as an experiment.
+ *
+ *  `withABTesting` (decocms/blocks, compat-v7) keeps the side in the `_deco_bucket` cookie as
+ *  `<side>:<percent>`. The runtime's deco adapter reads it into `exp`, and the store Worker
+ *  stamps the same pair on what it sends through `EdgeIngest`, so both halves of the funnel
+ *  group by one experiment with one pair of variant names. Changing a value here without
+ *  changing the store side splits the funnel in two. */
+export const STOREFRONT_EXP = {
+  cookie: "_deco_bucket",
+  name: "storefront",
+  variants: { worker: "tanstack", fallback: "fresh" } as Record<string, string>,
+} as const;
+
+/** The campaign parameters worth a typed column, and nothing else. `utm` is a Map with
+ *  LowCardinality keys: an open vocabulary is exactly how that becomes a cardinality
+ *  problem, since anything appending `utm_<random>` to a URL would mint a key forever.
+ *  The five UTM parameters are the standard set; `gclid` and `fbclid` are here because
+ *  they are what actually arrives from paid traffic and are otherwise lost. */
+export const CAMPAIGN_KEYS = [
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_term",
+  "utm_content",
+  "gclid",
+  "fbclid",
+] as const;
+
+/** Strip the `utm_` prefix on the way in: the column is already called `utm`, so storing
+ *  `utm_source` spends five characters per row per key restating it. */
+export const campaignKey = (raw: string): string | null => {
+  const k = raw.trim().toLowerCase();
+  // Accepts BOTH the raw form and the already-stripped one, because this runs twice:
+  // once in the browser reading the query string, and again in the Worker over whatever
+  // arrived. Accepting only `utm_source` meant the Worker dropped everything the runtime
+  // had correctly shortened to `source`, and only `gclid` survived — it has no prefix to
+  // strip. The endpoint is public anyway, so it has to handle either shape regardless of
+  // what our own runtime happens to send.
+  if ((CAMPAIGN_KEYS as readonly string[]).includes(k)) {
+    return k.startsWith("utm_") ? k.slice(4) : k;
+  }
+  return (CAMPAIGN_KEYS as readonly string[]).includes("utm_" + k) ? k : null;
+};
+
+/** Short keys on the wire, full names in the column. At 452M events a month, field names
+ *  are a double-digit percentage of a 293-byte event — and the browser pays that upload on
+ *  mobile data. Plausible does the same for the same reason. The Worker expands them, so
+ *  nothing downstream ever sees the abbreviation. */
+/** What a minted self-serve key looks like: a prefix and 22 URL-safe characters, the same
+ *  shape the visitor hash uses.
+ *
+ *  It lives in the CONTRACT rather than in the Worker's config module because it is one:
+ *  whoever mints keys and whoever reads them have to agree, and those will not be the same
+ *  codebase (D9). Deliberately NOT a secret — Plausible puts the equivalent in the script's
+ *  filename, OneDollarStats uses the hostname itself, and a public identifier is the only
+ *  thing a browser tag can carry. That is exactly why a key-sourced site is recorded as
+ *  `tag` and never billed from. Checking the shape is a BOUND, not authentication: without
+ *  it, any string of any length from any visitor becomes a KV read we pay for. */
+export const KEY_SHAPE = /^dq_[A-Za-z0-9_-]{22}$/;
+
+export const WIRE = {
+  event_id: "i",
+  /** A stable per-browser identifier, present ONLY on a tier-1 site whose visitor has
+   *  granted consent. Absent otherwise, which is the whole point: at tier 0 there is
+   *  nothing to send, and the Worker derives identity from a salt it rotates and forgets
+   *  daily. Never stored as sent — the Worker hashes it with the site so the same browser
+   *  is a different identifier on every customer's site. */
+  client_id: "ci",
+  ts: "t",
+  name: "n",
+  path: "p",
+  referrer: "r",
+  exp: "x",
+  props: "d",
+  value: "v",
+  currency: "c",
+  items_count: "q",
+  item_ids: "s",
+  transaction_id: "o",
+  error_type: "et",
+  error_message: "em",
+  error_file: "ef",
+  error_line: "el",
+  error_stack: "es",
+  error_fingerprint: "eg",
+  error_count: "ec",
+  utm: "u",
+  // Core Web Vitals go in typed columns rather than props: they are numbers that get
+  // averaged, bucketed and compared against thresholds, and a Map value would have to be
+  // parsed on every read. Nullable, because a metric that never fired must be absent
+  // rather than zero — a page nobody interacted with has no INP, and recording 0 would
+  // put it in the "good" bucket.
+  vital_lcp: "vl",
+  vital_inp: "vi",
+  vital_cls: "vc",
+  vital_ttfb: "vt",
+  vital_fcp: "vf",
+  // The heatmap module's per-view object. Expanded by the Worker into typed `hm_*` columns,
+  // never stored as sent. Shape in docs/PAYLOAD_CONTRACT.md.
+  heatmap: "hm",
+  _trunc: "_",
+} as const;
+
+const KEY_OK = /^[a-z][a-z0-9_]*$/;
+const EXP_OK = /^[a-z0-9][a-z0-9_-]*$/; // hyphens: `plp-ranking`, `model-b`
+const CONTROL = /[\x00-\x1F\x7F]/g;
+const ISO4217 = /^[A-Z]{3}$/;
+
+export type Sink = (f: Flag) => void;
+
+/** snake_case, letter-initial, no spaces. The name becomes a panel label and a grouping
+ *  key, so case and punctuation fragment one event across variants of itself — and a
+ *  fragmented name also inflates the `LowCardinality` dictionary it lives in.
+ *
+ *  Normalising is right. Doing it silently is not: two names collapsing into one is
+ *  something the sender has to be able to see. */
+export function normalizeName(
+  input: unknown,
+  flag: Sink,
+  reserved: readonly string[] = RESERVED_NAMES,
+): string {
+  const raw = String(input ?? "").trim();
+  if (!raw) {
+    flag(FLAGS.nameEmpty);
+    return "unnamed";
+  }
+
+  if (raw.startsWith("$")) {
+    if (reserved.includes(raw)) return raw;
+    flag(FLAGS.nameReserved);
+    return normalizeName(raw.slice(1), flag, reserved);
+  }
+
+  let n = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, "_")
+    .replace(/_{2,}/g, "_")
+    .replace(/^_+|_+$/g, "");
+  if (!n) {
+    flag(FLAGS.nameEmpty);
+    return "unnamed";
+  }
+  if (!/^[a-z]/.test(n)) n = "e_" + n;
+  if (n !== raw) flag(FLAGS.nameCharset);
+  if (n.length > LIMITS.nameLen) {
+    n = n.slice(0, LIMITS.nameLen).replace(/_+$/, "");
+    flag(FLAGS.nameLen);
+  }
+  return n;
+}
+
+function normalizeKey(input: string, flag: Sink): string | null {
+  let k = input
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, "_")
+    .replace(/_{2,}/g, "_")
+    .replace(/^_+|_+$/g, "");
+  if (!k) return null;
+  if (!/^[a-z]/.test(k)) k = "p_" + k;
+  if (k !== input) flag(FLAGS.keyCharset);
+  if (k.length > LIMITS.keyLen) {
+    k = k.slice(0, LIMITS.keyLen).replace(/_+$/, "");
+    flag(FLAGS.keyLen);
+  }
+  return KEY_OK.test(k) ? k : null;
+}
+
+/** Control characters are replaced rather than truncated around: a newline inside a value
+ *  breaks line-oriented reads of the same data downstream, and a tab breaks TSV. */
+export function normalizeProps(
+  input: unknown,
+  flag: Sink,
+  maxKeys: number = LIMITS.propKeys,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!input || typeof input !== "object" || Array.isArray(input)) return out;
+
+  let n = 0;
+  for (const [rawKey, rawValue] of Object.entries(input as Record<string, unknown>)) {
+    if (n >= maxKeys) {
+      flag(FLAGS.propsCount);
+      break;
+    }
+    if (rawValue === null || rawValue === undefined) continue;
+
+    const t = typeof rawValue;
+    if (t !== "string" && t !== "number" && t !== "boolean") {
+      flag(FLAGS.propsType);
+      continue;
+    }
+
+    const key = normalizeKey(rawKey, flag);
+    if (!key) {
+      flag(FLAGS.keyCharset);
+      continue;
+    }
+
+    let v = String(rawValue);
+    const stripped = v.replace(CONTROL, " ");
+    if (stripped !== v) {
+      v = stripped;
+      flag(FLAGS.propsControl);
+    }
+    if (v.length > LIMITS.valueLen) {
+      v = v.slice(0, LIMITS.valueLen);
+      flag(FLAGS.propsLen);
+    }
+
+    out[key] = v;
+    n++;
+  }
+  return out;
+}
+
+/** Case and hyphens preserved: these keys are a frozen contract owned elsewhere, and
+ *  rewriting `plp-ranking` into `plp_ranking` would silently break the join they exist
+ *  for. Invalid keys are dropped rather than coerced, for the same reason. */
+export function normalizeExp(input: unknown, flag: Sink): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!input || typeof input !== "object" || Array.isArray(input)) return out;
+
+  let n = 0;
+  for (const [k, v] of Object.entries(input as Record<string, unknown>)) {
+    if (n >= LIMITS.expEntries) {
+      flag(FLAGS.expCount);
+      break;
+    }
+    const key = String(k).slice(0, LIMITS.expKeyLen);
+    const val = String(v ?? "").slice(0, LIMITS.expKeyLen);
+    if (!EXP_OK.test(key) || !EXP_OK.test(val)) {
+      flag(FLAGS.expCharset);
+      continue;
+    }
+    out[key] = val;
+    n++;
+  }
+  return out;
+}
+
+/** ISO 4217, three letters. Anything else is emptied and flagged: a half-valid currency on
+ *  a revenue row is worse than a missing one. */
+export function normalizeCurrency(input: unknown, flag: Sink): string {
+  const c = String(input ?? "")
+    .trim()
+    .toUpperCase();
+  if (!c) return "";
+  if (!ISO4217.test(c)) {
+    flag(FLAGS.currencyInvalid);
+    return "";
+  }
+  return c;
+}
+
+/** Unparseable becomes null and is flagged, never coerced to zero. A silent zero in a
+ *  revenue report is a wrong number; a null is a missing one, and only one of those gets
+ *  noticed. */
+export function normalizeAmount(input: unknown, flag: Sink): number | null {
+  if (input === null || input === undefined || input === "") return null;
+  const n = Number(input);
+  if (!Number.isFinite(n)) {
+    flag(FLAGS.amountType);
+    return null;
+  }
+  return n;
+}
+
+/** Opaque and case-sensitive: it comes from the customer's order system, and it is what
+ *  stops a reloaded confirmation page counting a sale twice. Only control bytes go. */
+/** Canonical UUID form, which is what the `event_id` column accepts. Not a version check:
+ *  a v4 from the runtime, a v7 from a server-side sender and a caller's own id are all
+ *  fine, and refusing one of them would be inventing a contract nobody agreed to. */
+const UUID_SHAPE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+/** An id that ClickHouse will accept, minted when the sender did not supply a usable one.
+ *
+ *  This closes a hole that cost whole batches. `event_id` is a `UUID` column, and an absent
+ *  id normalised to `""` -- which fails to parse, and a JSONEachRow INSERT fails as ONE
+ *  statement. So a single event without an id destroyed every event in the same request,
+ *  the sender got its 204, and the only trace was `events_lost`. Measured: one event with
+ *  no `i` field, ClickHouse code 27, `inserted: 0`, `eventsLost: 1`.
+ *
+ *  Our own runtime always sends one, which is exactly why this went unnoticed -- but the
+ *  endpoint is public, and a server-side sender or a third-party SDK writing the lean
+ *  version of our contract is not a hypothetical. `sanitize.ts` promises never to "reject a
+ *  batch because one event is bad", and this is the one place it silently did. */
+export function normalizeEventId(input: unknown, flag: Sink): string {
+  const v = normalizeOpaque(input, 36);
+  if (UUID_SHAPE.test(v)) return v;
+  flag(FLAGS.eventIdMinted);
+  return crypto.randomUUID();
+}
+
+export function normalizeOpaque(input: unknown, max: number): string {
+  return String(input ?? "")
+    .replace(CONTROL, "")
+    .slice(0, max);
+}
+
+export function normalizeItemIds(input: unknown, flag: Sink): string[] {
+  if (!Array.isArray(input)) return [];
+  if (input.length > LIMITS.itemIds) flag(FLAGS.itemIdsCount);
+  return input
+    .slice(0, LIMITS.itemIds)
+    .map((v) => normalizeOpaque(v, LIMITS.itemIdLen))
+    .filter(Boolean);
+}
+
+/** ClickHouse `DateTime64` in JSONEachRow wants `YYYY-MM-DD hh:mm:ss.mmm` — a `T` or a `Z`
+ *  is a parse error, and a parse error rejects the whole batch rather than the row.
+ *  Client clocks are wrong often enough that anything more than a day out is treated as
+ *  skew and replaced, so one bad clock cannot poison a partition. */
+/** The window is ASYMMETRIC, and that is the whole point.
+ *
+ *  A timestamp in the past is ordinary: a beacon queued while the visitor was offline, a
+ *  tab restored hours later, a phone that reconnects on the train. Up to a day of that is
+ *  legitimate and gets kept.
+ *
+ *  A timestamp in the FUTURE never is. An event cannot be received before it happened, so
+ *  a future ts is always a wrong client clock — and browser clocks are wrong constantly.
+ *  Accepting them symmetrically, as this did, means a visitor whose clock is twenty
+ *  minutes fast pins their events to the top of the realtime feed and inflates "visitors
+ *  now" until the world catches up. One skewed device could make the live view useless.
+ *
+ *  Sixty seconds of forward tolerance covers ordinary jitter between the client's clock
+ *  and ours; past that the event is stamped with receipt time and flagged, because the
+ *  ORDER of a visitor's events is still worth preserving even when their clock is not.
+ */
+const PAST_TOLERANCE_MS = 86_400_000; // a day
+const FUTURE_TOLERANCE_MS = 60_000; // clock jitter, nothing more
+
+export function normalizeTs(input: unknown, flag: Sink): string {
+  const now = Date.now();
+  const t = Date.parse(String(input ?? ""));
+  if (!Number.isFinite(t) || now - t > PAST_TOLERANCE_MS || t - now > FUTURE_TOLERANCE_MS) {
+    flag(FLAGS.tsSkew);
+    return new Date(now).toISOString().replace("T", " ").replace("Z", "");
+  }
+  return new Date(t).toISOString().replace("T", " ").replace("Z", "");
+}
+
+/** Deduped and sorted, so two events that hit the same limits produce a byte-identical
+ *  array — which is what lets the column compress instead of merely storing. */
+export function flagSink(initial: readonly string[] = []) {
+  const set = new Set<string>(initial);
+  return {
+    flag: ((f: Flag) => {
+      set.add(f);
+    }) as Sink,
+    list: (): string[] => [...set].sort(),
+  };
+}
+
+/** The config fields the SERVED BUNDLE is built from — and nothing else.
+ *
+ *  Purging on every config write would throw away the fleet's cache for changes that do not move
+ *  a single byte of the script. `domains` is only ever read server-side, to cross-check an Origin
+ *  against a declared key; `schema` drives validation in the Worker; `goals` belongs to the read
+ *  side. None of them reach the browser.
+ *
+ *  Kept here, next to the wire contract, because it is exactly that: a promise about what the
+ *  bundle depends on. When `serveScript` starts reading another field, it goes in this list, and
+ *  the test that compares the two catches it if it does not. */
+export const BUNDLE_FIELDS = [
+  "id",
+  "sampling",
+  "tier",
+  "hash",
+  "modules",
+  "heatmapRate",
+  "errorHosts",
+] as const;
+
+/** A stable fingerprint of just those fields, for deciding whether a write needs a purge.
+ *  Key order is fixed rather than whatever `JSON.stringify` produces from an object literal,
+ *  since two configs equal in content must not differ here by the order someone typed them. */
+export function bundleFingerprint(cfg: Record<string, unknown> | null | undefined): string {
+  if (!cfg) return "";
+  return JSON.stringify(
+    BUNDLE_FIELDS.map((f) => {
+      const v = cfg[f];
+      // Module ORDER does not change the bundle -- they are concatenated from a fixed map -- so
+      // a reorder must not look like a change.
+      return Array.isArray(v) ? [...v].map(String).sort() : (v ?? null);
+    }),
+  );
+}
diff --git a/packages/blocks/src/v8/analytics/tag.test.ts b/packages/blocks/src/v8/analytics/tag.test.ts
new file mode 100644
index 00000000..c9deb369
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/tag.test.ts
@@ -0,0 +1,93 @@
+// @vitest-environment node
+/**
+ * The Deco Analytics tag's source (`runtime/`, `shared/`). It is not a package
+ * module: decocms/analytics bundles each entry below into a standalone script
+ * and its Worker serves them at `/_dq/a.js`, the way it does today for v7,
+ * checkout and sites outside deco. These tests pin what that build relies on.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, it } from "vitest";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const v8 = dirname(here);
+// Shell out to the esbuild binary: its JS API trips over Vitest's realm isolation.
+const esbuildBin = join(here, "../../../../../node_modules/.bin/esbuild");
+const out = mkdtempSync(join(tmpdir(), "dq-tag-"));
+afterAll(() => rmSync(out, { recursive: true, force: true }));
+
+/** Every script the Worker composes a site's bundle from, as decocms/analytics builds them. */
+const ENTRIES = [
+  "runtime/src/index.ts",
+  "runtime/modules/click.ts",
+  "runtime/modules/commerce.ts",
+  "runtime/modules/consent.ts",
+  "runtime/modules/deco.ts",
+  "runtime/modules/engagement.ts",
+  "runtime/modules/errors.ts",
+  "runtime/modules/heatmap.ts",
+  "runtime/modules/vitals.ts",
+  "runtime/view/view.ts",
+];
+
+function bundle(entry: string): { code: string; inputs: string[] } {
+  const file = join(out, entry.replaceAll("/", "_"));
+  execFileSync(
+    esbuildBin,
+    [
+      join(here, entry),
+      "--bundle",
+      "--format=iife",
+      "--minify",
+      "--target=es2020",
+      `--outfile=${file}.js`,
+      `--metafile=${file}.json`,
+    ],
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  const inputs = Object.keys(JSON.parse(readFileSync(`${file}.json`, "utf-8")).inputs);
+  return { code: readFileSync(`${file}.js`, "utf-8"), inputs };
+}
+
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) return name === "__fixtures__" ? [] : sourceFiles(path);
+    return /\.tsx?$/.test(name) && !/\.test\.tsx?$/.test(name) ? [path] : [];
+  });
+}
+
+describe("the Deco Analytics tag", () => {
+  it.each(ENTRIES)("%s bundles into one self-contained strict-mode script", (entry) => {
+    const { code } = bundle(entry);
+    // The production bundles open with this directive. It comes from `strict` in this
+    // folder's tsconfig.json, which ships with `src`, so the consumer's build emits it
+    // without a tsconfig of its own. Losing it changes every bundle's bytes and runs the
+    // tag in sloppy mode.
+    expect(code.startsWith('"use strict";(()=>{')).toBe(true);
+    expect(code).not.toMatch(/\bimport\s*[({"']|\brequire\(|node:/);
+  });
+
+  it.each(ENTRIES)("%s pulls in nothing from outside the tag's folder", (entry) => {
+    // The tag runs on every page of every site; the CMS runtime and React must never
+    // reach it through a stray import.
+    const outside = bundle(entry)
+      .inputs.map((input) => relative(here, join(process.cwd(), input)))
+      .filter((input) => input.startsWith(".."));
+    expect(outside).toEqual([]);
+  });
+
+  it("the CMS runtime imports nothing from the tag's source", () => {
+    const tag = `${sep}analytics${sep}`;
+    const offenders = sourceFiles(v8)
+      .filter((file) => !file.includes(tag))
+      .filter((file) =>
+        /from\s+["'][^"']*analytics\/(runtime|shared)\//.test(readFileSync(file, "utf-8")),
+      )
+      .map((file) => relative(v8, file));
+    expect(offenders).toEqual([]);
+  });
+});
diff --git a/packages/blocks/src/v8/analytics/tsconfig.json b/packages/blocks/src/v8/analytics/tsconfig.json
new file mode 100644
index 00000000..3a344f8c
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": []
+  },
+  "include": ["runtime/**/*.ts", "shared/**/*.ts"]
+}

From 2b366a87be835d729c8b97852ad4d47511fa002f Mon Sep 17 00:00:00 2001
From: thaisrocine <thais.almeidacc@gmail.com>
Date: Mon, 9 Nov 2026 19:46:58 -0300
Subject: [PATCH 2/4] feat(blocks): run the Deco Analytics client natively on
 v8

A v8 site should not need the external tag to collect. startAnalytics(), on
the new @decocms/blocks/analytics/client subpath, runs the same files the
collector bundles into /_dq/a.js: it fills window.__dq with the fields the
collector writes ahead of the tag, imports core, then each module in order.
Identification, the queue, the transport and the automatic collection keep one
implementation, and the standalone build is untouched.

Order matters because every module registers on load through __dqRegister, and
core replays the page's stub in a microtask that a module in its own chunk
misses. So the client holds the stub back and replays it once every module is
in. It does nothing on the server and never rejects, so a failure stops
analytics and nothing else. Events go to /_dq/e on the page's own host, which
keeps the site resolved from Host.

commerce.ts and vitals.ts gain an empty export so they can be imported as
modules; the ten bundles still hash to decocms/analytics' tag.lock.json.
client.test.ts checks that a page view and a click reach the collector exactly
as they do from the standalone bundle.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                                     |   3 +-
 packages/blocks/package.json                  |   5 +
 .../src/v8/analytics/client.server.test.ts    |   9 +
 .../blocks/src/v8/analytics/client.test.ts    | 172 ++++++++++++++++++
 packages/blocks/src/v8/analytics/client.ts    | 110 +++++++++++
 .../v8/analytics/runtime/modules/commerce.ts  |   2 +
 .../v8/analytics/runtime/modules/vitals.ts    |   2 +
 7 files changed, 302 insertions(+), 1 deletion(-)
 create mode 100644 packages/blocks/src/v8/analytics/client.server.test.ts
 create mode 100644 packages/blocks/src/v8/analytics/client.test.ts
 create mode 100644 packages/blocks/src/v8/analytics/client.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index 94712394..2365b5fc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -85,6 +85,7 @@ Each export is built from the source file below (`dist/<same path>.js`, see abov
 |---|---|
 | `@decocms/blocks` | `src/index.ts` — the v8 runtime API only (`createCMS`, `currentClient`, `matchRoute`, `remoteLoader`, `parseDraftPointer`, `Blocks`, `Lazy`, …; a client is `cms.client({ version, visitor, date, experiments, campaigns })`, with `forRelease()`/`forDraft(p)` as shortcuts; the preview helpers are `cms.readVersion` (→ `{ version, date?, experiments?, campaigns? }`, spread into `cms.client`; `cms.draftPointer` is its `version` alone)/`cms.draftCookie`, since they check the preview hosts (the current release's `previewHosts`, which Studio writes into the release metadata, plus `createCMS({ preview: { hosts } })`; every host while a site has published no list, or with no `site` and no `preview.hosts`); `parseVersion` is the same reading without the host check, for the bindings), re-exported from `src/v8/index.ts` as one explicit `export { … } from "./v8/index.ts"` block (a conformance test parses that form) |
 | `@decocms/blocks/analytics` | `src/v8/analytics.ts` — `AnalyticsScript`, `track` |
+| `@decocms/blocks/analytics/client` | `src/v8/analytics/client.ts` — `startAnalytics(options)`: the Deco Analytics client for a v8 site, without the external tag. Importing it touches nothing; in the browser it fills `window.__dq` with the fields the collector writes ahead of `/_dq/a.js`, imports core and then each module named in `options.modules` (one chunk each, so a site downloads only what it starts), and replays what the page queued once every module registered. Resolves to the client's API, or null on the server, when collection is off for the visitor, when anything failed (it never rejects), or the tag's API when the tag booted first. Events go to `/_dq/e` on the page's own host by default, so the collector resolves the site from `Host`. `client.test.ts` holds that its events equal the standalone tag's |
 | `@decocms/blocks/experiments` | `src/v8/experiments.ts` — who is in which A/B test, pure and isomorphic (no React, no `node:`, no CMS runtime, no module state, no environment reads): `assign(experiments, visitor)` → `{ [name]: boolean }`, `newVisitor`, `parseVisitor`, `serializeVisitor`, `readVisitor(request)` → `{ visitor, cookie }` (the web helper; `cookie` only when the visitor had no id), and the types `Visitor`, `Experiments`, `Assignments` (`experiments.test.ts` pins the runtime names). Nothing calls them for you: the app reads the visitor and passes it to `cms.client({ visitor })`, and the built-in `split-traffic` calls `assign`. A decision is arithmetic (`roll = murmur3_32("name:id") % 10000 / 100`, in when it is under the rounded percentage), so one visitor id serves every test and raising a percentage only adds people. The hash, the roll and the id live in the internal `src/v8/bucketing.ts` (not exported; the tests import it by path). `Visitor` is v7's `deco_segment` (same fields and encoding) plus an `id`, written once when it has none; v7's stored assignments are honoured while their `pct` holds (a missing or `-1` `pct` included), never rewritten. Changing the hash or the pinned vectors in `experiments.test.ts` moves every visitor already allocated: never a test to update |
 | `@decocms/blocks/fetch` | `src/v8/fetch.ts` — `createInstrumentedFetch` |
 | `@decocms/blocks/image` | `src/v8/image.ts` — the Deco image CDN's URLs (`decoCdn`), `createImageUrl`, `srcSet`, `parseSrcSet`, `preloadLink` and the generic `ImageProvider` type. Platform-neutral only: no commerce platform's URLs, hosts or detection here (a platform's provider lives in its client package, e.g. `@decocms/apps-vtex/image`). Pure functions, no React, no module state: a site builds one `ImageUrl`; the bindings render it |
@@ -144,7 +145,7 @@ v7's pure helpers, for sites moved from v7: each one gives v7's output (latest 7
 
 ### Key boundaries
 
-- **The Deco Analytics tag's source lives in `src/v8/analytics/` (`runtime/`, `shared/`) and is not a package module**: no export, and nothing in the runtime imports it. decocms/analytics bundles each entry with esbuild into a standalone script that its collector Worker serves at `/_dq/a.js` to every site (v7, checkout and sites outside deco included); `AnalyticsScript` only renders the `<script>` tag. The folder's `tsconfig.json` ships with `src` and sets `strict`, so the consumer's bundles keep the `"use strict"` the production ones carry. Biome formats the folder but doesn't lint it or organize its imports: those fixes change the bytes every site is served (reordering imports reorders the bundle). `analytics/tag.test.ts` bundles every entry and holds that nothing outside the folder reaches it. Until decocms/analytics builds from this package, its own `runtime/` is what production serves: change both.
+- **The Deco Analytics client's source lives in `src/v8/analytics/` (`runtime/`, `shared/`), one implementation for two consumers.** decocms/analytics bundles each entry with esbuild into a standalone script that its collector Worker serves at `/_dq/a.js` to every site (v7, checkout and sites outside deco included), and `AnalyticsScript` renders that `<script>` tag; a v8 site can instead run the same files through `@decocms/blocks/analytics/client` (`client.ts`, the only export). Nothing in the CMS runtime imports them. The files under `runtime/` and `shared/` are scripts first: each runs on load, which is what the standalone needs, so the client imports them in order rather than calling into them. The folder's `tsconfig.json` ships with `src` and sets `strict`, so the consumer's bundles keep the `"use strict"` the production ones carry. Biome formats the folder but doesn't lint it or organize its imports: those fixes change the bytes every site is served (reordering imports reorders the bundle). `analytics/tag.test.ts` bundles every entry and holds that nothing outside the folder reaches it. Until decocms/analytics builds from this package, its own `runtime/` is what production serves: change both.
 - **The runtime never imports the protocol or the CLI.** `src/v8` modules import only each other (no Node built-ins, no React at runtime except `/analytics`); `src/v8/browserBundle.test.ts` proves it with a real esbuild bundle. The one exception is `#async-store` (package.json `imports`): its `node`/`workerd`/`bun`/`deno` condition loads `src/async/node.ts` (`AsyncLocalStorage` from `node:async_hooks`, so Workers need `nodejs_compat`), its `default` `src/async/default.ts` (a global `AsyncLocalStorage` if the runtime has one, else none). The CLI may import the protocol.
 - **Clients depend only on `@decocms/blocks`**, with no peers and no framework binding. A client takes settings as arguments (no env reads), never caches, has no hooks, converters or `"use client"` code: those belong in the site's platform template (`tests/upstream-clients.conformance.test.ts`).
 - **Platform helpers live in the platform's package, not in blocks.** Besides its client, an `apps-*` package may export pure helper subpaths that compose with `@decocms/blocks` (`@decocms/apps-vtex/image` and `@decocms/apps-shopify/image`: image URL providers for `createImageUrl`). Pure: no network, no React, no env reads, no runtime imports (`tests/upstream-helpers.guardrail.test.ts`, which also bundles each for a browser and workerd). The product owner's call: `@decocms/blocks` holds framework code only, nothing that knows VTEX, Shopify or another commerce platform. Bindings never depend on an `apps-*` package: sites wire the helper in.
diff --git a/packages/blocks/package.json b/packages/blocks/package.json
index 9bb1fe17..abb3fd85 100644
--- a/packages/blocks/package.json
+++ b/packages/blocks/package.json
@@ -67,6 +67,11 @@
 			"source": "./src/v8/analytics.ts",
 			"default": "./dist/v8/analytics.js"
 		},
+		"./analytics/client": {
+			"types": "./dist/v8/analytics/client.d.ts",
+			"source": "./src/v8/analytics/client.ts",
+			"default": "./dist/v8/analytics/client.js"
+		},
 		"./cli": {
 			"types": "./dist/v8/cli/index.d.ts",
 			"source": "./src/v8/cli/index.ts",
diff --git a/packages/blocks/src/v8/analytics/client.server.test.ts b/packages/blocks/src/v8/analytics/client.server.test.ts
new file mode 100644
index 00000000..7effda4b
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/client.server.test.ts
@@ -0,0 +1,9 @@
+// @vitest-environment node
+/** On the server, `@decocms/blocks/analytics/client` imports cleanly and does nothing. */
+import { expect, it } from "vitest";
+import { startAnalytics } from "./client.ts";
+
+it("importing and starting it on the server touch no browser API", async () => {
+  expect(await startAnalytics({ modules: ["click", "heatmap"] })).toBeNull();
+  expect((globalThis as Record<string, unknown>).__dq).toBeUndefined();
+});
diff --git a/packages/blocks/src/v8/analytics/client.test.ts b/packages/blocks/src/v8/analytics/client.test.ts
new file mode 100644
index 00000000..fed2bc5c
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/client.test.ts
@@ -0,0 +1,172 @@
+// @vitest-environment jsdom
+/**
+ * `@decocms/blocks/analytics/client`: a v8 site running the Deco Analytics client
+ * without the external tag. It must collect what the tag collects, by itself, and
+ * send it to the collector in the same wire format, because both run the same files.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { JSDOM } from "jsdom";
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { WIRE } from "./shared/contract.ts";
+
+type Event = Record<string, unknown>;
+type Api = Record<string, (...args: any[]) => unknown>;
+type Post = { url: string; body: { site: string; key?: string; events: Event[] } };
+
+const here = dirname(fileURLToPath(import.meta.url));
+const w = window as unknown as Record<string, any>;
+let posts: Post[] = [];
+
+const events = () => posts.flatMap((p) => p.body.events);
+const names = () => events().map((e) => e[WIRE.name]);
+
+/** A fresh page: the client's globals gone and a fresh copy of every module. */
+beforeEach(() => {
+  vi.resetModules();
+  for (const k of ["__dq", "__dqBooted", "__dqRegister", "__dqCid"]) delete w[k];
+  posts = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string, init: RequestInit) => {
+      posts.push({ url: String(url), body: JSON.parse(String(init.body)) });
+      return new Response(null, { status: 204 });
+    }),
+  );
+});
+afterEach(() => vi.unstubAllGlobals());
+
+const start = async (options: Record<string, unknown> = {}) => {
+  const { startAnalytics } = await import("./client.ts");
+  // `dev`: jsdom's page is on localhost, which the client rightly skips otherwise.
+  return (await startAnalytics({ dev: true, ...options })) as Api | null;
+};
+
+describe("startAnalytics", () => {
+  it("collects a page view by itself and sends it to /_dq/e on the page's own host", async () => {
+    const api = await start();
+    expect(typeof api?.track).toBe("function");
+    expect(posts).toHaveLength(1);
+    // Relative, so the collector resolves the site from this page's Host (rule 1).
+    expect(posts[0].url).toBe("/_dq/e");
+    expect(posts[0].body.events[0]).toMatchObject({
+      [WIRE.name]: "$pageview",
+      [WIRE.path]: location.pathname,
+    });
+  });
+
+  it("counts a client-side navigation as a page view, with no track() call", async () => {
+    const api = await start();
+    history.pushState({}, "", "/category/shoes");
+    api!.flush();
+    expect(
+      events()
+        .filter((e) => e[WIRE.name] === "$pageview")
+        .map((e) => e[WIRE.path]),
+    ).toEqual(["/", "/category/shoes"]);
+    history.pushState({}, "", "/");
+  });
+
+  it("loads the modules it is given, after core, and they collect by themselves", async () => {
+    const api = await start({ modules: ["click", "commerce"] });
+    document.body.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    api!.addToCart({ value: 10, currency: "BRL", itemIds: ["sku-1"] });
+    api!.flush();
+    expect(names()).toEqual(["$pageview", "experiment_click", "add_to_cart"]);
+    expect(events()[2]).toMatchObject({ [WIRE.value]: 10, [WIRE.currency]: "BRL" });
+  });
+
+  it("delivers a helper the page queued before it started, once that helper's module is in", async () => {
+    w.__dq = { q: [{ m: "addToCart", a: [{ value: 5 }] }] };
+    const api = await start({ modules: ["commerce"] });
+    api!.flush();
+    expect(names()).toEqual(["$pageview", "add_to_cart"]);
+  });
+
+  it("passes the site's settings to core the way the collector's bundle does", async () => {
+    await start({ key: "dq_SiteKey000000000000000", endpoint: "https://collector.example/_dq/e" });
+    expect(posts[0].url).toBe("https://collector.example/_dq/e");
+    expect(posts[0].body.key).toBe("dq_SiteKey000000000000000");
+  });
+
+  it("leaves the external tag alone when it booted first: one client per page", async () => {
+    const track = vi.fn();
+    w.__dqBooted = true;
+    w.__dq = { track };
+    const api = await start({ modules: ["click"] });
+    expect(api?.track).toBe(track);
+    expect(posts).toEqual([]);
+  });
+
+  it("collects nothing, and loads no module, when collection is off for this visitor", async () => {
+    const { startAnalytics } = await import("./client.ts");
+    // A development host without `dev`: the same skip the tag applies.
+    expect(await startAnalytics({ modules: ["click"] })).toBeNull();
+    document.body.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(posts).toEqual([]);
+    expect(w.__dq.track).toBeUndefined();
+  });
+});
+
+describe("the same events as the standalone tag", () => {
+  const out = mkdtempSync(join(tmpdir(), "dq-client-"));
+  afterAll(() => rmSync(out, { recursive: true, force: true }));
+  const esbuildBin = join(here, "../../../../../node_modules/.bin/esbuild");
+
+  /** The bundle decocms/analytics serves as `/_dq/a.js` for a site with `click`: core, then the module. */
+  function standalone(): string {
+    return ["runtime/src/index.ts", "runtime/modules/click.ts"]
+      .map((entry) => {
+        const file = join(out, entry.replaceAll("/", "_"));
+        execFileSync(esbuildBin, [
+          join(here, entry),
+          "--bundle",
+          "--format=iife",
+          "--minify",
+          "--target=es2020",
+          `--outfile=${file}.js`,
+          "--log-level=warning",
+        ]);
+        return readFileSync(`${file}.js`, "utf-8");
+      })
+      .join("\n");
+  }
+
+  /** The keys of each event, the values that don't vary by run (`event_id`, `ts`) left out. */
+  const shape = (es: Event[]) =>
+    es.map((e) => {
+      const { [WIRE.event_id]: _id, [WIRE.ts]: _ts, ...rest } = e;
+      return rest;
+    });
+
+  it("a page view and a click reach the collector identically from either", async () => {
+    const api = await start({ modules: ["click"] });
+    document.body.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    api!.flush();
+    const native = posts.map((p) => ({ ...p.body, events: shape(p.body.events) }));
+
+    const dom = new JSDOM("<!doctype html><body></body>", {
+      url: location.href,
+      runScripts: "outside-only",
+      pretendToBeVisual: true,
+    });
+    const tagPosts: Post["body"][] = [];
+    dom.window.fetch = (async (_url: string, init: RequestInit) => {
+      tagPosts.push(JSON.parse(String(init.body)));
+      return new Response(null, { status: 204 });
+    }) as never;
+    dom.window.eval(`window.__dq={s:"unknown",e:"/_dq/e",r:1,tier:0,dev:true};${standalone()}`);
+    dom.window.document.body.dispatchEvent(new dom.window.MouseEvent("click", { bubbles: true }));
+    dom.window.__dq.flush();
+    dom.window.close();
+
+    expect(native).toEqual(tagPosts.map((b) => ({ ...b, events: shape(b.events) })));
+    expect(native.flatMap((b) => b.events).map((e) => e[WIRE.name])).toEqual([
+      "$pageview",
+      "experiment_click",
+    ]);
+  });
+});
diff --git a/packages/blocks/src/v8/analytics/client.ts b/packages/blocks/src/v8/analytics/client.ts
new file mode 100644
index 00000000..61ec4378
--- /dev/null
+++ b/packages/blocks/src/v8/analytics/client.ts
@@ -0,0 +1,110 @@
+/**
+ * `@decocms/blocks/analytics/client`: the Deco Analytics client for a v8 site,
+ * without the external tag. It runs the same files decocms/analytics bundles
+ * into `/_dq/a.js` (core, then each module), so identification, the queue,
+ * the transport and the automatic collection have one implementation for both.
+ *
+ * Importing this module does nothing: no DOM access, safe on the server.
+ * `startAnalytics()` does the work in the browser and never rejects, so a
+ * failure is "analytics stopped", never "the page broke".
+ */
+
+/** The optional modules, by the names the collector's site config uses. */
+export type AnalyticsModule =
+  | "click"
+  | "commerce"
+  | "consent"
+  | "deco"
+  | "engagement"
+  | "errors"
+  | "heatmap"
+  | "vitals";
+
+export interface AnalyticsClientOptions {
+  /** Modules to load after core, in this order. Default none: core alone collects page views. */
+  modules?: AnalyticsModule[];
+  /**
+   * Where events go. Default `/_dq/e` on the page's own host, which is what makes the
+   * collector resolve the site from the `Host` header, the only resolution billing trusts.
+   */
+  endpoint?: string;
+  /** The site's declared key, for a host the collector can't resolve. Its events are `tag`-grade. */
+  key?: string;
+  /** Share of sheddable events to keep, 0 to 1. Core events (`$…`) are always kept. */
+  sampling?: number;
+  /** 1 lets the consent module keep a stable id once the visitor consents. Default 0. */
+  tier?: 0 | 1;
+  /** The site routes on `location.hash`, so a hash change is a page view. */
+  hash?: boolean;
+  /** Collect on a development host too (localhost, private ranges). */
+  dev?: boolean;
+  /** Heatmap module: share of page views it samples, 0 to 1. */
+  heatmapRate?: number;
+  /** Errors module: cross-origin script hosts that count as the site's own. */
+  errorHosts?: string[];
+}
+
+/** One loader per file, so a bundler splits each module into its own chunk. */
+const MODULES: Record<AnalyticsModule, () => Promise<unknown>> = {
+  click: () => import("./runtime/modules/click.ts"),
+  commerce: () => import("./runtime/modules/commerce.ts"),
+  consent: () => import("./runtime/modules/consent.ts"),
+  deco: () => import("./runtime/modules/deco.ts"),
+  engagement: () => import("./runtime/modules/engagement.ts"),
+  errors: () => import("./runtime/modules/errors.ts"),
+  heatmap: () => import("./runtime/modules/heatmap.ts"),
+  vitals: () => import("./runtime/modules/vitals.ts"),
+};
+
+/**
+ * Starts collection in the browser: the page view now and on every client-side
+ * navigation, plus whatever the modules collect. Call it once, after the page is
+ * interactive; nothing visual should wait on it. Resolves to the client's API
+ * (`track`, `pageview`, the modules' helpers such as `addToCart`), or null on the
+ * server, when collection is off for this visitor (automation, opt-out, a
+ * development host) or when anything failed.
+ *
+ * If the external tag already booted on this page, it is left alone and its API
+ * is returned: one client per page, whichever came first.
+ */
+export async function startAnalytics(
+  options: AnalyticsClientOptions = {},
+): Promise<Record<string, unknown> | null> {
+  if (typeof window === "undefined") return null;
+  const w = window as unknown as Record<string, any>;
+  try {
+    if (w.__dqBooted) return typeof w.__dq?.track === "function" ? w.__dq : null;
+
+    // The same fields the collector writes ahead of `/_dq/a.js`, and the same precedence: what
+    // the page already set on `window.__dq` wins. `q` is held back and replayed below, once
+    // every module has registered: core replays its stub in a microtask, and a module in its
+    // own chunk arrives later than that, so a helper queued before boot would be dropped.
+    const page = (w.__dq ?? {}) as Record<string, unknown>;
+    const queued = Array.isArray(page.q) ? [...page.q] : [];
+    w.__dq = Object.assign(
+      {
+        s: "unknown",
+        e: options.endpoint ?? "/_dq/e",
+        r: options.sampling ?? 1,
+        tier: options.tier ?? 0,
+        ...(options.hash ? { hash: 1 } : {}),
+        ...(options.dev ? { dev: true } : {}),
+        ...(options.key ? { k: options.key } : {}),
+        ...(options.heatmapRate !== undefined ? { hr: options.heatmapRate } : {}),
+        ...(options.errorHosts?.length ? { er: options.errorHosts } : {}),
+      },
+      page,
+      { q: [] },
+    );
+
+    await import("./runtime/src/index.ts");
+    // Core assigns its API only when it collects; skipped means skipped, modules included.
+    if (typeof w.__dq.track !== "function") return null;
+
+    for (const name of new Set(options.modules ?? [])) await MODULES[name]?.();
+    for (const r of queued) w.__dq.q?.push?.(r);
+    return w.__dq;
+  } catch {
+    return null;
+  }
+}
diff --git a/packages/blocks/src/v8/analytics/runtime/modules/commerce.ts b/packages/blocks/src/v8/analytics/runtime/modules/commerce.ts
index 602e452a..bafec365 100644
--- a/packages/blocks/src/v8/analytics/runtime/modules/commerce.ts
+++ b/packages/blocks/src/v8/analytics/runtime/modules/commerce.ts
@@ -69,3 +69,5 @@ window.__dqRegister?.((enqueue, api: Record<string, unknown>) => {
       true,
     );
 });
+
+export {};
diff --git a/packages/blocks/src/v8/analytics/runtime/modules/vitals.ts b/packages/blocks/src/v8/analytics/runtime/modules/vitals.ts
index 1d62685e..59fcd505 100644
--- a/packages/blocks/src/v8/analytics/runtime/modules/vitals.ts
+++ b/packages/blocks/src/v8/analytics/runtime/modules/vitals.ts
@@ -124,3 +124,5 @@ window.__dqRegister?.((enqueue, _api: Record<string, unknown>, onFinal) => {
   // Every vital is only final when the page is, so this rides out on core's last flush.
   onFinal(send);
 });
+
+export {};

From 5180df5f1381a193b6ee51d39c539beb318bd6e0 Mon Sep 17 00:00:00 2001
From: thaisrocine <thais.almeidacc@gmail.com>
Date: Tue, 10 Nov 2026 11:28:54 -0300
Subject: [PATCH 3/4] docs(blocks): a release does not reach the Deco Analytics
 tag by itself

decocms/analytics pins @decocms/blocks at an exact version, so a change to the
client's source reaches /_dq/a.js only when someone bumps it there and its
e2e passes. Agreed with @tlgimenes to keep that step manual for now; written
here so an agent releasing a change to the client knows the second half.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 2365b5fc..b7727927 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -145,7 +145,8 @@ v7's pure helpers, for sites moved from v7: each one gives v7's output (latest 7
 
 ### Key boundaries
 
-- **The Deco Analytics client's source lives in `src/v8/analytics/` (`runtime/`, `shared/`), one implementation for two consumers.** decocms/analytics bundles each entry with esbuild into a standalone script that its collector Worker serves at `/_dq/a.js` to every site (v7, checkout and sites outside deco included), and `AnalyticsScript` renders that `<script>` tag; a v8 site can instead run the same files through `@decocms/blocks/analytics/client` (`client.ts`, the only export). Nothing in the CMS runtime imports them. The files under `runtime/` and `shared/` are scripts first: each runs on load, which is what the standalone needs, so the client imports them in order rather than calling into them. The folder's `tsconfig.json` ships with `src` and sets `strict`, so the consumer's bundles keep the `"use strict"` the production ones carry. Biome formats the folder but doesn't lint it or organize its imports: those fixes change the bytes every site is served (reordering imports reorders the bundle). `analytics/tag.test.ts` bundles every entry and holds that nothing outside the folder reaches it. Until decocms/analytics builds from this package, its own `runtime/` is what production serves: change both.
+- **The Deco Analytics client's source lives in `src/v8/analytics/` (`runtime/`, `shared/`), one implementation for two consumers.** decocms/analytics bundles each entry with esbuild into a standalone script that its collector Worker serves at `/_dq/a.js` to every site (v7, checkout and sites outside deco included), and `AnalyticsScript` renders that `<script>` tag; a v8 site can instead run the same files through `@decocms/blocks/analytics/client` (`client.ts`, the only export). Nothing in the CMS runtime imports them. The files under `runtime/` and `shared/` are scripts first: each runs on load, which is what the standalone needs, so the client imports them in order rather than calling into them. The folder's `tsconfig.json` ships with `src` and sets `strict`, so the consumer's bundles keep the `"use strict"` the production ones carry. Biome formats the folder but doesn't lint it or organize its imports: those fixes change the bytes every site is served (reordering imports reorders the bundle). `analytics/tag.test.ts` bundles every entry and holds that nothing outside the folder reaches it..
+- **A blocks release does not reach the standalone tag by itself.** Publishing `@decocms/blocks` changes nothing in `/_dq/a.js`: decocms/analytics pins blocks at an exact version and its Worker serves what it built from that. After a release that changes anything under `src/v8/analytics/runtime/` or `shared/`, open a PR in decocms/analytics that bumps `@decocms/blocks` to that exact version and runs `npm run tag:lock`; its CI checks the bundles against the lock and runs the e2e, and the merge deploys. Say in that PR which bundles changed and why, since every site loads them. A v8 site on `@decocms/blocks/analytics/client` gets the change with its own next bump and deploy. Until decocms/analytics builds from this package (task 3.7 of its execution plan), its own `runtime/` is what production serves: make the same change there instead.
 - **The runtime never imports the protocol or the CLI.** `src/v8` modules import only each other (no Node built-ins, no React at runtime except `/analytics`); `src/v8/browserBundle.test.ts` proves it with a real esbuild bundle. The one exception is `#async-store` (package.json `imports`): its `node`/`workerd`/`bun`/`deno` condition loads `src/async/node.ts` (`AsyncLocalStorage` from `node:async_hooks`, so Workers need `nodejs_compat`), its `default` `src/async/default.ts` (a global `AsyncLocalStorage` if the runtime has one, else none). The CLI may import the protocol.
 - **Clients depend only on `@decocms/blocks`**, with no peers and no framework binding. A client takes settings as arguments (no env reads), never caches, has no hooks, converters or `"use client"` code: those belong in the site's platform template (`tests/upstream-clients.conformance.test.ts`).
 - **Platform helpers live in the platform's package, not in blocks.** Besides its client, an `apps-*` package may export pure helper subpaths that compose with `@decocms/blocks` (`@decocms/apps-vtex/image` and `@decocms/apps-shopify/image`: image URL providers for `createImageUrl`). Pure: no network, no React, no env reads, no runtime imports (`tests/upstream-helpers.guardrail.test.ts`, which also bundles each for a browser and workerd). The product owner's call: `@decocms/blocks` holds framework code only, nothing that knows VTEX, Shopify or another commerce platform. Bindings never depend on an `apps-*` package: sites wire the helper in.

From ef66c14e222b604a93a01e4753d1ee3f202d5232 Mon Sep 17 00:00:00 2001
From: thaisrocine <thais.almeidacc@gmail.com>
Date: Tue, 10 Nov 2026 11:29:04 -0300
Subject: [PATCH 4/4] docs(blocks): fix a doubled period

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index b7727927..45865911 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -145,7 +145,7 @@ v7's pure helpers, for sites moved from v7: each one gives v7's output (latest 7
 
 ### Key boundaries
 
-- **The Deco Analytics client's source lives in `src/v8/analytics/` (`runtime/`, `shared/`), one implementation for two consumers.** decocms/analytics bundles each entry with esbuild into a standalone script that its collector Worker serves at `/_dq/a.js` to every site (v7, checkout and sites outside deco included), and `AnalyticsScript` renders that `<script>` tag; a v8 site can instead run the same files through `@decocms/blocks/analytics/client` (`client.ts`, the only export). Nothing in the CMS runtime imports them. The files under `runtime/` and `shared/` are scripts first: each runs on load, which is what the standalone needs, so the client imports them in order rather than calling into them. The folder's `tsconfig.json` ships with `src` and sets `strict`, so the consumer's bundles keep the `"use strict"` the production ones carry. Biome formats the folder but doesn't lint it or organize its imports: those fixes change the bytes every site is served (reordering imports reorders the bundle). `analytics/tag.test.ts` bundles every entry and holds that nothing outside the folder reaches it..
+- **The Deco Analytics client's source lives in `src/v8/analytics/` (`runtime/`, `shared/`), one implementation for two consumers.** decocms/analytics bundles each entry with esbuild into a standalone script that its collector Worker serves at `/_dq/a.js` to every site (v7, checkout and sites outside deco included), and `AnalyticsScript` renders that `<script>` tag; a v8 site can instead run the same files through `@decocms/blocks/analytics/client` (`client.ts`, the only export). Nothing in the CMS runtime imports them. The files under `runtime/` and `shared/` are scripts first: each runs on load, which is what the standalone needs, so the client imports them in order rather than calling into them. The folder's `tsconfig.json` ships with `src` and sets `strict`, so the consumer's bundles keep the `"use strict"` the production ones carry. Biome formats the folder but doesn't lint it or organize its imports: those fixes change the bytes every site is served (reordering imports reorders the bundle). `analytics/tag.test.ts` bundles every entry and holds that nothing outside the folder reaches it.
 - **A blocks release does not reach the standalone tag by itself.** Publishing `@decocms/blocks` changes nothing in `/_dq/a.js`: decocms/analytics pins blocks at an exact version and its Worker serves what it built from that. After a release that changes anything under `src/v8/analytics/runtime/` or `shared/`, open a PR in decocms/analytics that bumps `@decocms/blocks` to that exact version and runs `npm run tag:lock`; its CI checks the bundles against the lock and runs the e2e, and the merge deploys. Say in that PR which bundles changed and why, since every site loads them. A v8 site on `@decocms/blocks/analytics/client` gets the change with its own next bump and deploy. Until decocms/analytics builds from this package (task 3.7 of its execution plan), its own `runtime/` is what production serves: make the same change there instead.
 - **The runtime never imports the protocol or the CLI.** `src/v8` modules import only each other (no Node built-ins, no React at runtime except `/analytics`); `src/v8/browserBundle.test.ts` proves it with a real esbuild bundle. The one exception is `#async-store` (package.json `imports`): its `node`/`workerd`/`bun`/`deno` condition loads `src/async/node.ts` (`AsyncLocalStorage` from `node:async_hooks`, so Workers need `nodejs_compat`), its `default` `src/async/default.ts` (a global `AsyncLocalStorage` if the runtime has one, else none). The CLI may import the protocol.
 - **Clients depend only on `@decocms/blocks`**, with no peers and no framework binding. A client takes settings as arguments (no env reads), never caches, has no hooks, converters or `"use client"` code: those belong in the site's platform template (`tests/upstream-clients.conformance.test.ts`).