@hyperfixi/testing-framework 2.9.0 → 2.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixi/testing-framework",
-  "version": "2.9.0",
+  "version": "2.9.2",
   "description": "Cross-platform behavior testing suite for LokaScript applications",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -40,7 +40,8 @@
     "analyze-failures": "tsx src/multilingual/tools/analyze-failures.ts",
     "typecheck": "tsc --noEmit",
     "test:check": "VITEST_QUIET=1 bash ../../scripts/vitest-run.sh --reporter=dot",
-    "test:canonical": "FOREIGN_CANONICAL_VALIDITY=1 VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/canonical-validity.test.ts src/multilingual/foreign-canonical-validity.test.ts"
+    "test:canonical": "FOREIGN_CANONICAL_VALIDITY=1 VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/canonical-validity.test.ts src/multilingual/foreign-canonical-validity.test.ts",
+    "test:shipped-sources": "VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/shipped-sources-validity.test.ts"
   },
   "keywords": [
     "hyperscript",
@@ -56,10 +57,10 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "dependencies": {
-    "@hyperfixi/core": "^2.9.0",
-    "@hyperfixi/patterns-reference": "^2.9.0",
-    "@lokascript/i18n": "^2.9.0",
-    "@lokascript/semantic": "^2.9.0",
+    "@hyperfixi/core": "^2.9.2",
+    "@hyperfixi/patterns-reference": "^2.9.2",
+    "@lokascript/i18n": "^2.9.2",
+    "@lokascript/semantic": "^2.9.2",
     "diff": "^8.0.3",
     "esbuild": "^0.28.0",
     "happy-dom": "^20.10.6",

package/src/multilingual/canonical-validity.ts

@@ -15,8 +15,9 @@
  *
  * The FOREIGN-side sibling (foreign-canonical-validity.ts) is folded into
  * `multilingual/cli.ts`'s `--regression` gate as the R4 canonical-validity
- * ratchet. This en-side check remains vitest-only (its allowlist holds exactly
- * one entry, pick-text-range). The same loader recipe now also ships in the
+ * ratchet. This en-side check remains vitest-only; its allowlist is currently
+ * EMPTY (134/134 corpus references render valid — it formerly held one entry,
+ * pick-text-range). The same loader recipe now also ships in the
  * build-time `@hyperscript-tools/i18n` transpiler (`src/validate.ts`, CLI
  * `--check`, Eleventy `parseCheck`) to gate its ENGLISH side (input + foreign→
  * English output). Faithful foreign-OUTPUT gating still awaits the v2

package/src/multilingual/effect-signature.ts

@@ -0,0 +1,92 @@
+/**
+ * DOM effect signatures — shared by the R2 execution validator (corpus
+ * patterns vs the en reference) and the shipped-examples execution gate
+ * (shipped handlers vs the upstream engine).
+ *
+ * A signature is a before/after diff of every element's identity-relevant
+ * state: classes, attributes, inline style, and leaf text. Selectors, classes,
+ * and attribute names are code (not translated), so signatures are directly
+ * comparable across languages — and across engines, which is what makes the
+ * upstream-oracle comparison possible at all.
+ *
+ * Extracted verbatim from validators/execution-validator.ts (R2), which now
+ * imports from here. Any change to the serialization changes BOTH gates'
+ * signatures at once, deliberately: the two must never disagree about what a
+ * DOM effect is.
+ */
+
+/**
+ * Attributes that are ENGINE bookkeeping, not page behavior: hyperscript
+ * source (`_`), hyperfixi's processed-marker, show/hide display memo, and the
+ * shipped-examples harness's identity keys. Excluded from signatures so a
+ * cross-engine comparison measures what the handler DID to the page, not how
+ * each engine annotates its own work. For R2 this changed exactly one locked
+ * signature (`hide-with-transition`, which loses its data-original-display
+ * memo) and no fidelity numbers — translations are compared against a same-run
+ * en reference, so both sides drop the memo together.
+ */
+const ENGINE_ATTRS = new Set([
+  '_',
+  'data-hyperscript-powered',
+  'data-original-display',
+  'data-exec-key',
+]);
+
+/**
+ * Serialize the identity-relevant state of one element.
+ * Leaf text only — container text would duplicate every child mutation.
+ */
+export function serializeElement(el: Element): string {
+  const attrs = Array.from(el.attributes)
+    .filter(a => a.name !== 'class' && a.name !== 'style' && !ENGINE_ATTRS.has(a.name))
+    .map(a => `${a.name}=${a.value}`)
+    .sort()
+    .join(',');
+  const classes = Array.from(el.classList).sort().join(' ');
+  const style = (el as HTMLElement).getAttribute('style') ?? '';
+  const text =
+    el.childNodes.length === 0 || (el.childNodes.length === 1 && el.firstChild?.nodeType === 3)
+      ? (el.textContent ?? '')
+      : '';
+  return `cls[${classes}] attr[${attrs}] style[${style}] text[${text}]`;
+}
+
+/**
+ * Snapshot every element under <body>. <body> participates under its own
+ * stable key (body-targeted effects must be visible).
+ *
+ * Keying: `data-exec-key` when present (stamped by the shipped-examples
+ * harness BEFORE the engine runs, so the key is the element's IDENTITY — an
+ * engine inserting or removing one element cannot shift every later element's
+ * key, which flat indices did: one injected node turned a one-line diff into a
+ * whole-page churn storm). Elements without a key (added during the run, and
+ * the whole R2 corpus fixture, which is never stamped) fall back to `#id` /
+ * `tag[document-order-index]` — R2's original keying, byte-identical for its
+ * signatures.
+ */
+export function snapshot(document: Document): Map<string, string> {
+  const out = new Map<string, string>();
+  out.set('body', serializeElement(document.body));
+  document.body.querySelectorAll('*').forEach((el, i) => {
+    const execKey = el.getAttribute?.('data-exec-key');
+    const key = execKey
+      ? `${el.tagName.toLowerCase()}:${execKey}${el.id ? `#${el.id}` : ''}`
+      : el.id
+        ? `#${el.id}`
+        : `${el.tagName.toLowerCase()}[${i}]`;
+    out.set(key, serializeElement(el));
+  });
+  return out;
+}
+
+/** Sorted, stable list of per-element changes between two snapshots. */
+export function diffSnapshots(before: Map<string, string>, after: Map<string, string>): string[] {
+  const effects: string[] = [];
+  for (const [k, v] of after) {
+    const b = before.get(k);
+    if (b === undefined) effects.push(`+${k} ${v}`);
+    else if (b !== v) effects.push(`Δ${k} ${v}`);
+  }
+  for (const k of before.keys()) if (!after.has(k)) effects.push(`-${k}`);
+  return effects.sort();
+}

package/src/multilingual/shipped-examples-execution.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Shipped-examples execution gate (see shipped-examples-execution.ts for the
+ * why and the execution model).
+ *
+ * Executes every eligible `_="…"` handler shipped in `examples/**` on BOTH
+ * hyperfixi and the real `hyperscript.org` engine, in jsdom, and ratchets on
+ * divergence of their DOM effect signatures. Upstream is the behavioral
+ * oracle — the same role R4 gives it for validity. This is the gate that would
+ * have caught the #785 defect (a conditional body running unconditionally on a
+ * shipped page) on BEHAVIOR: every parse-level gate stayed green while it
+ * shipped.
+ *
+ * Assertions, matching the shipped-sources gate:
+ *   1. sanity — pages walked, handlers extracted, comparisons actually ran
+ *      (guards the silent-zero failure mode);
+ *   2. no NEW divergence appears outside the committed allowlist;
+ *   3. no allowlisted key has silently converged (stale entries must be
+ *      removed so the list only ever ratchets down).
+ *
+ * To update after an intentional change: re-run and regenerate
+ * `baselines/shipped-examples-execution.json` (the allowlist key embeds a
+ * source hash, so FIXING a handler changes its key and assertion 3 forces the
+ * entry's removal).
+ *
+ * Node-only (walks the repo, imports hyperscript.org off disk). The sweep
+ * swaps jsdom globals per handler execution — safe because vitest isolates
+ * test files per worker.
+ *
+ * @vitest-environment node
+ * The node environment is REQUIRED, not a preference: under the suite default
+ * (happy-dom) the DOM constructors already exist on globalThis, the harness's
+ * globals bootstrap refuses to overwrite what it does not own, and both
+ * engines then bind happy-dom's constructors — every instanceof against a
+ * jsdom element fails and every hyperfixi signature comes back empty
+ * (measured: 0 real matches under happy-dom vs 74 under node).
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { describe, it, expect, beforeAll } from 'vitest';
+import {
+  runShippedExamplesExecution,
+  triggerEventOf,
+  keyFor,
+  type ExecutionParityResult,
+} from './shipped-examples-execution';
+
+interface AllowlistDoc {
+  allowedDivergences: Array<{
+    key: string;
+    file: string;
+    event: string;
+    excerpt: string;
+    reason: string;
+  }>;
+}
+
+const baselinePath = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../baselines/shipped-examples-execution.json'
+);
+const allowlist = JSON.parse(readFileSync(baselinePath, 'utf8')) as AllowlistDoc;
+const allowed = new Set(allowlist.allowedDivergences.map(e => e.key));
+
+describe('shipped-examples execution gate', () => {
+  let result: ExecutionParityResult;
+
+  beforeAll(async () => {
+    result = await runShippedExamplesExecution();
+
+    // Visibility, not assertions: what the sweep could not compare, and why.
+    // A silently shrinking denominator is this gate's own blind spot.
+    const reasons = new Map<string, number>();
+    for (const s of result.skipped) {
+      const r = s.reason.split(':')[0] ?? s.reason;
+      reasons.set(r, (reasons.get(r) ?? 0) + 1);
+    }
+    const vacuous = result.compared.filter(c => c.vacuous).length;
+    console.log(
+      `[shipped-examples-execution] pages=${result.pages} handlers=${result.handlers} ` +
+        `compared=${result.compared.length} (vacuous=${vacuous}) skipped=${result.skipped.length}`
+    );
+    for (const [r, n] of [...reasons].sort((a, b) => b[1] - a[1])) {
+      console.log(`[shipped-examples-execution]   skip ×${n}: ${r}`);
+    }
+  }, 240_000);
+
+  it('walks pages and compares handlers (sanity: extraction and both engines working)', () => {
+    // Floors well below current values (55 / 333 / 162 / 74) but far above
+    // zero: a broken walk, extractor, or engine bootstrap fails loudly here
+    // instead of making assertions 2-3 vacuously pass.
+    expect(result.pages).toBeGreaterThan(40);
+    expect(result.handlers).toBeGreaterThan(250);
+    expect(result.compared.length).toBeGreaterThan(120);
+    // Vacuous (empty-vs-empty) pairs are NOT parity evidence — the floor is on
+    // real, non-empty signature matches.
+    const realMatches = result.compared.filter(c => c.match && !c.vacuous).length;
+    expect(realMatches).toBeGreaterThan(60);
+  });
+
+  it('has no NEW divergence from upstream outside the allowlist', () => {
+    const unexpected = result.compared.filter(c => !c.match && !allowed.has(c.key));
+    expect(
+      unexpected,
+      unexpected.length
+        ? `\nShipped handlers whose DOM effect DIVERGES from the hyperscript.org engine ` +
+            `(fix the behavior, or allowlist with a family reason):\n` +
+            unexpected
+              .map(
+                f =>
+                  `  [${f.key}]\n` +
+                  `      "${f.excerpt}"\n` +
+                  `      hyperfixi: ${JSON.stringify(f.hyperfixiEffects).slice(0, 300)}\n` +
+                  `      upstream : ${JSON.stringify(f.upstreamEffects).slice(0, 300)}`
+              )
+              .join('\n') +
+            `\n\nTriage guidance: an EMPTY hyperfixi signature with a non-empty upstream one usually\n` +
+            `means hyperfixi silently dropped behavior (the #785 class). The reverse often means a\n` +
+            `deliberate hyperfixi extension or a jsdom limitation on the upstream side — check the\n` +
+            `existing family reasons in baselines/shipped-examples-execution.json before adding a new one.`
+        : ''
+    ).toEqual([]);
+  });
+
+  it('has no stale allowlist entries (a now-converged handler must be removed so the list ratchets down)', () => {
+    const stillDiverging = new Set(result.compared.filter(c => !c.match).map(c => c.key));
+    const stale = allowlist.allowedDivergences.map(e => e.key).filter(k => !stillDiverging.has(k));
+    expect(
+      stale,
+      stale.length
+        ? `\nThese allowlisted handlers no longer diverge (fixed, or edited — the key embeds a\n` +
+            `source hash; or no longer eligible, in which case the coverage loss should be deliberate).\n` +
+            `Remove them from baselines/shipped-examples-execution.json:\n  ${stale.join('\n  ')}`
+        : ''
+    ).toEqual([]);
+  });
+});
+
+describe('harness pieces', () => {
+  it('extracts the trigger event from the leading on-clause', () => {
+    expect(triggerEventOf('on click add .a to me')).toBe('click');
+    expect(triggerEventOf('  on  every  click log me')).toBe('click');
+    expect(triggerEventOf("on keydown[key=='Escape'] from window hide .x")).toBe('keydown');
+    expect(triggerEventOf('on draggable:start add .drag')).toBe('draggable:start');
+    expect(triggerEventOf('on click or keyup toggle .a')).toBe('click');
+    expect(triggerEventOf('install Draggable')).toBeNull();
+    expect(triggerEventOf('init set x to 1')).toBeNull();
+  });
+
+  it('keys embed the source hash, so an edited handler changes key', () => {
+    const a = keyFor({ file: 'f.html', source: 'on click add .a', event: 'click' });
+    const b = keyFor({ file: 'f.html', source: 'on click add .b', event: 'click' });
+    expect(a).not.toBe(b);
+    expect(a).toMatch(/^f\.html::[0-9a-f]{10}::click$/);
+  });
+});

package/src/multilingual/shipped-examples-execution.ts

@@ -0,0 +1,499 @@
+/**
+ * Shipped-examples execution gate — upstream as the behavioral oracle
+ * -------------------------------------------------------------------
+ * Every parse-level gate in this repo went green while `native-dialog.html`
+ * shipped with a conditional body running unconditionally (#785), and again
+ * while five upstream-valid `if` shapes regressed on a PR branch (#786). The
+ * class they cannot see is BEHAVIOR: a handler that parses cleanly and then
+ * does the wrong thing on the page.
+ *
+ * This gate executes the handlers we actually ship. For each `_="…"` attribute
+ * in `examples/**`, the full page is loaded into two jsdom instances — one
+ * processed by hyperfixi (parse + a fresh Runtime with the element as context,
+ * the same shape the browser attribute processor uses), one by the real
+ * `hyperscript.org` engine (`processNode`) — the handler's trigger event is
+ * dispatched, and the resulting DOM effect signatures (../effect-signature.ts,
+ * shared with the R2 execution ratchet) are diffed against each other.
+ * Upstream plays the role R4 gives it for validity: the oracle. A divergence
+ * means hyperfixi's runtime behavior differs from upstream's ON A SHIPPED
+ * PAGE — exactly the #785/#786 failure mode, caught on behavior instead of by
+ * luck.
+ *
+ * ## Fair denominator (mirrors R4)
+ * A handler is only compared when BOTH engines accept its source: hyperfixi
+ * must compile it clean (`ok: true`, no recovered errors — recovering sources
+ * are the shipped-sources gate's business) and upstream must parse it (a
+ * hyperfixi-only extension has no oracle). It must also be deterministically
+ * executable in jsdom: triggered by a dispatchable event, free of network /
+ * timer / navigation constructs. Every exclusion is recorded with a reason —
+ * the skip list is part of the result, never silent (`no silent caps`).
+ *
+ * ## Execution model
+ * Per handler and engine: a FRESH jsdom of the whole page, every eligible
+ * handler installed (page-like — bubbling into sibling handlers stays real and
+ * symmetric), then ONLY the probed handler's event dispatched, with a
+ * before/after snapshot around it. See runHandlerOnEngine for why isolation is
+ * worth its cost.
+ *
+ * ## Node-only
+ * Imports the real `hyperscript.org` build off disk and swaps jsdom globals
+ * per handler execution (both engines resolve `document` lazily through
+ * globalThis — the same mechanism the R2 validator relies on). Cannot run in a
+ * browser suite, and under vitest REQUIRES the node environment (see the test
+ * file's docblock).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { JSDOM } from 'jsdom';
+import { snapshot, diffSnapshots } from './effect-signature';
+
+/** Repo root, from `packages/testing-framework/src/multilingual/`. */
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+
+/**
+ * Only `examples/**` — unlike the shipped-sources validity gate, execution
+ * needs the surrounding PAGE (the handler's selectors resolve against it), and
+ * doc snippets have none.
+ */
+const DEFAULT_ROOTS = ['examples'];
+
+/**
+ * Events the harness can dispatch deterministically. `on load` is excluded
+ * (fires through engine-specific initialization, not a dispatchable event);
+ * anything not listed is skipped with a reason.
+ */
+const SAFE_EVENTS = new Set([
+  'click',
+  'dblclick',
+  'mousedown',
+  'mouseup',
+  'mouseenter',
+  'mouseleave',
+  'mouseover',
+  'mouseout',
+  'pointerdown',
+  'pointerup',
+  'input',
+  'change',
+  'keydown',
+  'keyup',
+  'focus',
+  'blur',
+]);
+
+/**
+ * Constructs that make an execution nondeterministic in jsdom (network,
+ * timers, animation, navigation, module-level installs) — with, for each, the
+ * reason it is excluded. Matched against the whole source.
+ */
+const DISQUALIFIERS: Array<{ pattern: RegExp; reason: string }> = [
+  { pattern: /\bfetch\b/, reason: 'network (fetch)' },
+  { pattern: /\bwait\b/, reason: 'timers (wait)' },
+  { pattern: /\bsettle\b/, reason: 'animation settling' },
+  { pattern: /\btransition\b/, reason: 'animation (transition)' },
+  { pattern: /\brepeat\s+forever\b/, reason: 'unbounded loop' },
+  { pattern: /\bgo\s+to\s+url\b/i, reason: 'navigation' },
+  { pattern: /\binstall\s/, reason: 'behavior install (registries differ by design)' },
+  { pattern: /(^|\s)js(\s|\()/, reason: 'js interop block' },
+  { pattern: /\beventsource\b/i, reason: 'SSE' },
+  { pattern: /\bsocket\b/i, reason: 'WebSocket' },
+  { pattern: /\bnavigator\b/, reason: 'browser API jsdom does not implement' },
+  { pattern: /\bbeep!/, reason: 'debug construct' },
+  {
+    pattern: /\bnew Date\b|\bMath\.random\b|toLocaleTimeString|Date\.now/,
+    reason: 'nondeterministic value (time/random) — signatures would flake across the two runs',
+  },
+];
+
+/** A handler extracted from a shipped page. */
+export interface ShippedHandler {
+  /** Repo-relative path of the page. */
+  file: string;
+  /** Document-order index among the page's `[_]` elements — the element's identity across jsdom instances. */
+  index: number;
+  /** The hyperscript source. */
+  source: string;
+  /** The trigger event parsed from the leading `on` clause, when any. */
+  event: string | null;
+}
+
+export interface SkippedHandler extends ShippedHandler {
+  reason: string;
+}
+
+/** One compared handler: both engines ran it; signatures either match or not. */
+export interface ComparedHandler extends ShippedHandler {
+  /** Stable key: file + source hash + event. Fixing a source changes its key. */
+  key: string;
+  event: string;
+  hyperfixiEffects: string[];
+  upstreamEffects: string[];
+  match: boolean;
+  /**
+   * Both signatures empty. NOT evidence of parity — a genuinely effect-free
+   * handler (bare `halt`, a `log`) and a both-engines-broken handler look the
+   * same. Counted separately; never let vacuous pairs inflate the match count.
+   */
+  vacuous: boolean;
+  /** Single-line excerpt, for reading the baseline without opening the file. */
+  excerpt: string;
+}
+
+export interface ExecutionParityResult {
+  /** Pages walked. */
+  pages: number;
+  /** Handlers found (before eligibility). */
+  handlers: number;
+  /** Handlers executed on both engines. */
+  compared: ComparedHandler[];
+  /** Handlers excluded, each with its reason. */
+  skipped: SkippedHandler[];
+}
+
+/** Stable key for one handler execution. */
+export function keyFor(h: { file: string; source: string; event: string }): string {
+  const hash = createHash('sha1').update(h.source).digest('hex').slice(0, 10);
+  return `${h.file}::${hash}::${h.event}`;
+}
+
+/** First `on <event>` name, if the source is an event handler. */
+export function triggerEventOf(source: string): string | null {
+  // `on every click`, `on click[filter]`, `on click from #x`, `on click or keyup`
+  // all yield their first event name; modifiers/filters are dropped.
+  const m = source.match(/^\s*on\s+(?:every\s+)?([\w-]+(?::[\w-]+)?)/);
+  return m ? (m[1] ?? null) : null;
+}
+
+function walkHtml(dir: string, acc: string[] = []): string[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name.startsWith('.')) {
+      continue;
+    }
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkHtml(full, acc);
+    else if (entry.name.endsWith('.html')) acc.push(full);
+  }
+  return acc;
+}
+
+/** Extract the page's `[_]` handlers in document order. */
+export function extractHandlers(file: string, html: string): ShippedHandler[] {
+  const dom = new JSDOM(html);
+  const out: ShippedHandler[] = [];
+  dom.window.document.querySelectorAll('[_]').forEach((el: Element, index: number) => {
+    const source = el.getAttribute('_') ?? '';
+    out.push({ file, index, source, event: triggerEventOf(source) });
+  });
+  return out;
+}
+
+/** Minimal engine surfaces, injected by `initEngines`. */
+export interface Engines {
+  /** hyperfixi compile check (fair-denominator side 1). */
+  compileClean(source: string): boolean;
+  /** upstream parse check (fair-denominator side 2). Returns error strings; [] = valid. */
+  upstreamErrors(source: string): string[];
+  /** Install a handler on an element via hyperfixi (the public eval surface). */
+  hyperfixiInstall(source: string, el: Element): Promise<void>;
+  /** Install a handler on an element via the upstream engine. */
+  upstreamInstall(el: Element): void;
+}
+
+/**
+ * Keys this module has installed onto globalThis from a jsdom window. Tracked
+ * so every later `installGlobals` RE-points them at the new page's window —
+ * merely skipping keys that already exist left every DOM constructor
+ * (`HTMLElement`, `Element`, …) bound to the FIRST page forever, and both
+ * engines' `instanceof` checks then silently failed for later pages' elements
+ * (measured: upstream produced empty signatures for `on click put 'Hello' into
+ * #output` — the simplest possible handler — on every page after the first).
+ */
+const installedGlobalKeys = new Set<string>();
+
+/**
+ * Point the process globals at a page's jsdom (jsdom-global style: everything
+ * the window owns that node does not, plus the DOM-critical names node has
+ * opinions about). Both engines resolve `document` lazily through globalThis,
+ * so this is what "switching pages" means.
+ */
+export function installGlobals(dom: JSDOM): void {
+  const g = globalThis as Record<string, unknown>;
+  const win = dom.window as unknown as Record<string, unknown>;
+  for (const key of Object.getOwnPropertyNames(win)) {
+    if (key in globalThis && !installedGlobalKeys.has(key)) continue; // node's own — leave it
+    try {
+      g[key] = win[key];
+      installedGlobalKeys.add(key);
+    } catch {
+      /* read-only */
+    }
+  }
+  for (const key of ['window', 'document', 'Event', 'CustomEvent', 'navigator']) {
+    try {
+      Object.defineProperty(g, key, {
+        value: key === 'window' ? dom.window : win[key],
+        configurable: true,
+        writable: true,
+      });
+      installedGlobalKeys.add(key);
+    } catch {
+      /* read-only */
+    }
+  }
+}
+
+/**
+ * Errors thrown inside dispatched listeners surface as unhandled rejections
+ * (handlers are async) and would crash the sweep. Trapped, not asserted: a
+ * runtime error that damages behavior diverges in its effect signature, which
+ * is the comparison — same stance as the R2 validator.
+ */
+let rejectionTrapInstalled = false;
+function installRejectionTrap(): void {
+  if (rejectionTrapInstalled) return;
+  process.on('unhandledRejection', () => {
+    /* swallowed — the effect signature is the assertion */
+  });
+  rejectionTrapInstalled = true;
+}
+
+/**
+ * Load both engines ONCE, after bootstrapping jsdom globals (both packages
+ * touch DOM constructors at module evaluation). Callers then swap pages via
+ * `installGlobals`.
+ */
+export async function initEngines(): Promise<Engines> {
+  installRejectionTrap();
+  installGlobals(new JSDOM('<!doctype html><html><body></body></html>'));
+
+  // Install goes through parse + a FRESH Runtime per handler with the element
+  // as context — the same shape the browser attribute processor uses, and the
+  // same shape the R2 validator proved stable across per-page document swaps.
+  // (The api singleton `hyperscript.eval` binds document-dependent state at
+  // first use, which is correct in a browser — document identity never changes
+  // within a realm — but silently resolves later PAGES' selectors against the
+  // first page here. Measured: a two-page probe no-opped page 2's toggle.)
+  const core = (await import('@hyperfixi/core')) as unknown as {
+    hyperscript: {
+      compileSync(code: string): { ok: boolean; errors?: Array<{ message: string }> };
+    };
+    parse(code: string): { success: boolean; node?: unknown };
+    Runtime: new () => { execute(ast: unknown, ctx: unknown): Promise<unknown> };
+    createContext(el: HTMLElement): unknown;
+  };
+
+  const require = createRequire(import.meta.url);
+  const esm = path.join(path.dirname(require.resolve('hyperscript.org')), '_hyperscript.esm.js');
+  const hs = (await import(pathToFileURL(esm).href)).default as {
+    parse(src: string): { errors?: Array<{ message: string }> };
+    processNode(el: Node): void;
+  };
+
+  return {
+    compileClean(source) {
+      try {
+        const r = core.hyperscript.compileSync(source);
+        return r.ok && (r.errors ?? []).length === 0;
+      } catch {
+        return false;
+      }
+    },
+    upstreamErrors(source) {
+      try {
+        return (hs.parse(source)?.errors ?? []).map(e => e.message);
+      } catch (e) {
+        return ['threw: ' + (e as Error).message.split('\n')[0]];
+      }
+    },
+    async hyperfixiInstall(source, el) {
+      const parsed = core.parse(source);
+      if (!parsed.success || !parsed.node) {
+        throw new Error('parse failed at install (eligibility should have caught this)');
+      }
+      const runtime = new core.Runtime();
+      await runtime.execute(parsed.node, core.createContext(el as HTMLElement));
+    },
+    upstreamInstall(el) {
+      hs.processNode(el);
+    },
+  };
+}
+
+/** Drain micro/macrotasks after a dispatch (same window the R2 validator uses). */
+const SETTLE_MS = 20;
+const settle = () => new Promise(r => setTimeout(r, SETTLE_MS));
+
+/**
+ * Execute ONE handler on one engine, in ISOLATION: a fresh jsdom of the page,
+ * every eligible handler installed (as on a real page — bubbling into sibling
+ * handlers stays page-like and symmetric across engines), then ONLY the probed
+ * handler's event dispatched, with a before/after snapshot around it.
+ *
+ * Isolation is deliberate, and worth its jsdom-per-handler cost: a sequential
+ * dispatch-them-all model was measured amplifying ONE real divergence into a
+ * page's worth of cascades (upstream's inert element-`decrement` made the
+ * following `put 0 into #count` write 0-over-0 — invisible — so every later
+ * handler on the page diverged too), and letting double-failures hide as
+ * empty-vs-empty "matches". Fresh state per handler makes each comparison
+ * independently triageable.
+ *
+ * Runtime errors do not abort — the effect signature is the comparison, and an
+ * error that damages behavior diverges in its effects.
+ */
+async function runHandlerOnEngine(
+  html: string,
+  eligible: Array<ShippedHandler & { event: string }>,
+  target: ShippedHandler & { event: string },
+  install: (h: ShippedHandler & { event: string }, el: Element) => Promise<void> | void
+): Promise<string[]> {
+  // No pretendToBeVisual: nothing eligible needs rAF (animation constructs are
+  // disqualified), and its frame timer would keep node alive after the sweep.
+  const dom = new JSDOM(html);
+  try {
+    installGlobals(dom);
+    const doc = dom.window.document;
+    const els = doc.querySelectorAll('[_]');
+
+    // Stamp identity keys BEFORE anything runs: same page → same stamping on
+    // both engines, so snapshot keys are the element's identity and an
+    // engine-inserted node cannot shift them (see snapshot()).
+    doc.body
+      .querySelectorAll('*')
+      .forEach((el: Element, i: number) => el.setAttribute('data-exec-key', String(i)));
+
+    for (const h of eligible) {
+      const el = els[h.index];
+      if (!el) continue;
+      try {
+        await install(h, el);
+      } catch {
+        /* recorded via the empty signature */
+      }
+    }
+
+    const el = els[target.index];
+    if (!el) return ['<element not found>'];
+    if ((target.event === 'input' || target.event === 'change') && 'value' in el) {
+      (el as HTMLInputElement).value = 'test';
+    }
+    const before = snapshot(doc);
+    el.dispatchEvent(new dom.window.Event(target.event, { bubbles: true, cancelable: true }));
+    await settle();
+    return diffSnapshots(before, snapshot(doc));
+  } finally {
+    // Release the page's timers/listeners so the process can exit; the next
+    // page (or the caller's bootstrap dom) re-points the globals.
+    dom.window.close();
+  }
+}
+
+/**
+ * The sweep: walk `examples/**`, extract handlers, apply the fair-denominator
+ * filters (each skip reasoned), and execute every eligible handler on both
+ * engines.
+ */
+export async function runShippedExamplesExecution(opts?: {
+  roots?: string[];
+  repoRoot?: string;
+  engines?: Engines;
+}): Promise<ExecutionParityResult> {
+  const repoRoot = opts?.repoRoot ?? REPO_ROOT;
+  const roots = opts?.roots ?? DEFAULT_ROOTS;
+  const engines = opts?.engines ?? (await initEngines());
+
+  const compared: ComparedHandler[] = [];
+  const skipped: SkippedHandler[] = [];
+  let pages = 0;
+  let handlers = 0;
+
+  for (const root of roots) {
+    for (const full of walkHtml(path.join(repoRoot, root))) {
+      const rel = path.relative(repoRoot, full);
+      const html = fs.readFileSync(full, 'utf8');
+      const pageHandlers = extractHandlers(rel, html);
+      if (pageHandlers.length === 0) continue;
+      pages++;
+      handlers += pageHandlers.length;
+
+      const eligible: Array<ShippedHandler & { event: string }> = [];
+      for (const h of pageHandlers) {
+        if (!h.event) {
+          skipped.push({ ...h, reason: 'not an `on <event>` handler' });
+          continue;
+        }
+        if (!SAFE_EVENTS.has(h.event)) {
+          skipped.push({ ...h, reason: `event not dispatchable deterministically (${h.event})` });
+          continue;
+        }
+        const disq = DISQUALIFIERS.find(d => d.pattern.test(h.source));
+        if (disq) {
+          skipped.push({ ...h, reason: disq.reason });
+          continue;
+        }
+        if (!engines.compileClean(h.source)) {
+          skipped.push({
+            ...h,
+            reason: 'hyperfixi does not compile it clean (shipped-sources gate territory)',
+          });
+          continue;
+        }
+        const upstreamErrs = engines.upstreamErrors(h.source);
+        if (upstreamErrs.length > 0) {
+          skipped.push({ ...h, reason: `upstream rejects it (no oracle): ${upstreamErrs[0]}` });
+          continue;
+        }
+        eligible.push(h as ShippedHandler & { event: string });
+      }
+      if (eligible.length === 0) continue;
+
+      // Both engines log runtime errors to the console during dispatch
+      // (COMMAND FAILED etc.). That is expected data here — the effect
+      // signature carries the consequence — so silence the console for the
+      // engine runs only, restoring even on a throw.
+      const saved = {
+        log: console.log,
+        warn: console.warn,
+        error: console.error,
+        debug: console.debug,
+      };
+      const noop = () => {};
+      console.log = console.warn = console.error = console.debug = noop;
+      try {
+        for (const h of eligible) {
+          const ours = await runHandlerOnEngine(html, eligible, h, (hh, el) =>
+            engines.hyperfixiInstall(hh.source, el)
+          );
+          const theirs = await runHandlerOnEngine(html, eligible, h, (_hh, el) =>
+            engines.upstreamInstall(el)
+          );
+          compared.push({
+            ...h,
+            key: keyFor(h),
+            hyperfixiEffects: ours,
+            upstreamEffects: theirs,
+            match: JSON.stringify(ours) === JSON.stringify(theirs),
+            vacuous: ours.length === 0 && theirs.length === 0,
+            excerpt: h.source.replace(/\s+/g, ' ').trim().slice(0, 100),
+          });
+        }
+      } finally {
+        console.log = saved.log;
+        console.warn = saved.warn;
+        console.error = saved.error;
+        console.debug = saved.debug;
+      }
+    }
+  }
+
+  return { pages, handlers, compared, skipped };
+}

package/src/multilingual/shipped-sources-validity.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Shipped-sources validity gate (see shipped-sources-validity.ts for the why).
+ *
+ * Compiles every hyperscript source we ship in `examples/` and the doc trees,
+ * and ratchets on the recovers-with-errors state (`ok: true` with a non-empty
+ * `errors`). Three assertions, matching the canonical-validity gates:
+ *   1. sanity — sources were actually found and mostly compile clean;
+ *   2. no NEW recovering source appears outside the committed allowlist;
+ *   3. no allowlisted key has silently become clean (stale entries must be
+ *      removed so the list only ever shrinks).
+ *
+ * To update after an intentional fix: re-run and rewrite
+ * `baselines/shipped-sources-validity.json`. Note the allowlist key embeds a
+ * hash of the source, so FIXING a source changes its key — the entry goes
+ * stale and assertion 3 makes removing it mandatory.
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { JSDOM } from 'jsdom';
+import { describe, it, expect, beforeAll } from 'vitest';
+import {
+  checkShippedSourcesValidity,
+  type ShippedSourcesResult,
+  type CompileForValidity,
+} from './shipped-sources-validity';
+
+interface AllowlistDoc {
+  allowedRecovered: Array<{
+    key: string;
+    file: string;
+    error: string;
+    upstream: string;
+    reason: string;
+  }>;
+}
+
+const baselinePath = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../baselines/shipped-sources-validity.json'
+);
+const allowlist = JSON.parse(readFileSync(baselinePath, 'utf8')) as AllowlistDoc;
+const allowed = new Set(allowlist.allowedRecovered.map(e => e.key));
+
+describe('shipped-sources validity gate', () => {
+  let result: ShippedSourcesResult;
+
+  beforeAll(async () => {
+    // Import core through its built entry, the same surface a consumer gets.
+    const core = (await import('@hyperfixi/core')) as unknown as {
+      hyperscript: { compileSync: CompileForValidity };
+    };
+    const dom = new JSDOM('<!doctype html><html><body></body></html>');
+    result = checkShippedSourcesValidity(
+      code => core.hyperscript.compileSync(code),
+      dom.window.document as unknown as Parameters<typeof checkShippedSourcesValidity>[1]
+    );
+  }, 120_000);
+
+  it('finds and compiles the shipped sources (sanity: trees walked, extraction working)', () => {
+    // Guards the silent-zero failure mode: a broken walk or extractor would
+    // make every other assertion vacuously pass.
+    expect(result.checked).toBeGreaterThan(100);
+    expect(result.clean).toBeGreaterThan(100);
+  });
+
+  it('has no NEW source that parses with recovered errors outside the allowlist', () => {
+    const unexpected = result.findings.filter(f => !allowed.has(f.key));
+    expect(
+      unexpected,
+      unexpected.length
+        ? `\nNew shipped sources that parse ok:true WITH errors (fix the source, or allowlist with a reason):\n` +
+            unexpected
+              .map(f => `  [${f.key}]\n      "${f.excerpt}"\n      -> ${f.error}`)
+              .join('\n') +
+            `\n\nAsk the real hyperscript.org engine for a second opinion before deciding:\n` +
+            `upstream REJECTING means the source is malformed; upstream ACCEPTING means this is a hyperfixi parser defect.\n` +
+            `See loadCanonicalParser() in canonical-validity.ts.`
+        : ''
+    ).toEqual([]);
+  });
+
+  it('has no stale allowlist entries (a now-clean source must be removed so the list ratchets down)', () => {
+    const stillFailing = new Set(result.findings.map(f => f.key));
+    const stale = allowlist.allowedRecovered.map(e => e.key).filter(key => !stillFailing.has(key));
+    expect(
+      stale,
+      stale.length
+        ? `\nThese allowlisted sources no longer recover-with-errors (fixed, or edited — the key embeds a source hash).\n` +
+            `Remove them from baselines/shipped-sources-validity.json:\n  ${stale.join('\n  ')}`
+        : ''
+    ).toEqual([]);
+  });
+});

package/src/multilingual/shipped-sources-validity.ts

@@ -0,0 +1,194 @@
+/**
+ * Shipped-sources validity gate
+ * -----------------------------
+ * Every hyperscript source we ship in `examples/` and the doc trees, parsed
+ * with hyperfixi, must not land in the *recovers-with-errors* state:
+ * `ok === true` with a non-empty `errors`.
+ *
+ * That state is the blind spot this gate exists for. The parser is
+ * deliberately resilient — it recovers from some malformed input and returns a
+ * usable-but-degraded AST plus diagnostics — so genuinely broken sources
+ * neither throw nor report `ok: false`. Nothing in the existing suites looks at
+ * the combination, which is how five malformed examples shipped undetected
+ * (an `if` with no `end`, a `put` with no target, `{id}` where `${id}` was
+ * meant, and a `*--css-var` neither engine supports). The same sweep is what
+ * caught the `send`-vs-`trigger` divergence and the `parseTriggerCommand` hang
+ * in #780, neither of which was reachable from the existing tests.
+ *
+ * Deliberately NOT gated: `ok === false`. That is a much larger and mostly
+ * legitimate class — non-English sources (which need the multilingual path,
+ * not `compileSync`), plugin syntax whose feature is not installed, and
+ * intentionally-broken "this does not work" doc snippets. Gating it would
+ * drown the signal. A source that fails outright is also loud; one that
+ * silently recovers is not, and that asymmetry is the whole point.
+ *
+ * Node-only: the second-opinion path needs `loadCanonicalParser()`, which
+ * imports the real `hyperscript.org` build off disk. Cannot run in a browser
+ * suite.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { extractHyperscriptFromMarkup } from '@hyperfixi/patterns-reference';
+
+/** Repo root, from `packages/testing-framework/src/multilingual/`. */
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+
+/** Trees whose hyperscript we ship to users. */
+const DEFAULT_ROOTS = ['examples', 'docs', 'packages/core/docs'];
+
+/**
+ * Paths excluded from the sweep, each with the reason it is not a shipped
+ * source. Keep this list short and justified — every entry is coverage lost.
+ */
+const EXCLUDED = [
+  {
+    match: (rel: string) => rel.includes(`${path.sep}archive${path.sep}`),
+    reason: 'historical phase/summary docs, not shipped guidance',
+  },
+];
+
+export interface ShippedSource {
+  /** Repo-relative path of the file the source came from. */
+  file: string;
+  /** How it was extracted, for triage. */
+  kind: 'html-attribute' | 'markdown-html-block';
+  /** The hyperscript source itself. */
+  source: string;
+}
+
+export interface ShippedSourceFinding extends ShippedSource {
+  /** Stable allowlist key: file plus a hash of the source. */
+  key: string;
+  /** First hyperfixi diagnostic. */
+  error: string;
+  /** Single-line excerpt, for reading the baseline without opening the file. */
+  excerpt: string;
+}
+
+export interface ShippedSourcesResult {
+  /** Sources extracted and compiled. */
+  checked: number;
+  /** Sources that compiled with no diagnostics. */
+  clean: number;
+  /** Sources in the recovers-with-errors state. */
+  findings: ShippedSourceFinding[];
+}
+
+/** Minimal shape of `hyperscript.compileSync`, injected so this stays testable. */
+export type CompileForValidity = (code: string) => {
+  ok: boolean;
+  errors?: Array<{ message: string }>;
+};
+
+/**
+ * A stable key for an individual snippet.
+ *
+ * Hashing the source (rather than using its index in the file) means the key
+ * survives reordering, and — the point — CHANGES when the snippet is fixed, so
+ * a stale allowlist entry cannot silently keep covering a source that has been
+ * edited. The stale-entry test turns that into a hard failure.
+ */
+function keyFor(file: string, source: string): string {
+  return `${file}::${createHash('sha1').update(source).digest('hex').slice(0, 10)}`;
+}
+
+function walk(dir: string, acc: string[] = []): string[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name.startsWith('.')) {
+      continue;
+    }
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, acc);
+    else if (/\.(html|md)$/.test(entry.name)) acc.push(full);
+  }
+  return acc;
+}
+
+/**
+ * Collect every hyperscript source we ship.
+ *
+ * HTML files contribute their `_=` / `hx-live` attributes and
+ * `<script type="text/hyperscript">` bodies, read through the DOM (see
+ * `extractHyperscriptFromMarkup` for why not a regex). Markdown contributes
+ * the same, extracted from its fenced ```html blocks.
+ *
+ * Bare fenced ```hyperscript blocks are deliberately NOT collected: in this
+ * repo they are overwhelmingly syntax *notation* rather than code
+ * (`send <event> to <target>`, `copy <source> as <format>`), which no parser
+ * can accept and which it would be wrong to demand parses. The sources that
+ * actually run on a page are the attributes.
+ */
+export function collectShippedSources(
+  doc: Parameters<typeof extractHyperscriptFromMarkup>[0],
+  opts?: { roots?: string[]; repoRoot?: string }
+): ShippedSource[] {
+  const repoRoot = opts?.repoRoot ?? REPO_ROOT;
+  const roots = opts?.roots ?? DEFAULT_ROOTS;
+  const out: ShippedSource[] = [];
+
+  for (const root of roots) {
+    for (const full of walk(path.join(repoRoot, root))) {
+      const rel = path.relative(repoRoot, full);
+      if (EXCLUDED.some(e => e.match(rel))) continue;
+      const text = fs.readFileSync(full, 'utf8');
+
+      if (full.endsWith('.html')) {
+        for (const source of extractHyperscriptFromMarkup(doc, text).snippets) {
+          out.push({ file: rel, kind: 'html-attribute', source });
+        }
+      } else {
+        for (const block of text.matchAll(/```html\n([\s\S]*?)```/g)) {
+          for (const source of extractHyperscriptFromMarkup(doc, block[1] ?? '').snippets) {
+            out.push({ file: rel, kind: 'markdown-html-block', source });
+          }
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Compile every shipped source and report the ones that recovered with errors.
+ */
+export function checkShippedSourcesValidity(
+  compile: CompileForValidity,
+  doc: Parameters<typeof extractHyperscriptFromMarkup>[0],
+  opts?: { roots?: string[]; repoRoot?: string }
+): ShippedSourcesResult {
+  const sources = collectShippedSources(doc, opts);
+  const findings: ShippedSourceFinding[] = [];
+  let clean = 0;
+
+  for (const s of sources) {
+    let result: ReturnType<CompileForValidity>;
+    try {
+      result = compile(s.source);
+    } catch {
+      // A throw is the loud failure mode, not this gate's business.
+      continue;
+    }
+    const errors = result.errors ?? [];
+    if (result.ok && errors.length > 0) {
+      findings.push({
+        ...s,
+        key: keyFor(s.file, s.source),
+        error: errors[0]?.message ?? 'recovered with errors',
+        excerpt: s.source.replace(/\s+/g, ' ').trim().slice(0, 100),
+      });
+    } else if (result.ok) {
+      clean++;
+    }
+  }
+
+  return { checked: sources.length, clean, findings };
+}

package/src/multilingual/validators/execution-validator.test.ts

@@ -339,8 +339,10 @@ describe('R2 execution validator (lock)', () => {
     // The three wave-9 additions. Each en reference must produce a non-empty,
     // deterministic signature against the existing fixture. The `*opacity`
     // hide/show STRATEGIES are synchronous (no timer): hide writes display:none
-    // + a data-original-display marker on #btn; show adds the visibility class
-    // on #modal. chained-access-possessive-dot writes the parent (.card) display.
+    // on #btn (its data-original-display memo is engine bookkeeping, excluded
+    // from signatures since the shared effect-signature module — see
+    // ENGINE_ATTRS there); show adds the visibility class on #modal.
+    // chained-access-possessive-dot writes the parent (.card) display.
     const cases: ReadonlyArray<[string, string, string[]]> = [
       [
         'chained-access-possessive-dot',
@@ -350,7 +352,7 @@ describe('R2 execution validator (lock)', () => {
       [
         'hide-with-transition',
         'on click hide me with *opacity',
-        ['Δ#btn cls[] attr[data-original-display=,id=btn] style[display: none;] text[Click]'],
+        ['Δ#btn cls[] attr[id=btn] style[display: none;] text[Click]'],
       ],
       [
         'show-with-transition',

package/src/multilingual/validators/execution-validator.ts

@@ -31,6 +31,7 @@ import { JSDOM } from 'jsdom';
 import { parseSemantic, buildAST } from '@lokascript/semantic';
 import { getAllPatterns, getTranslationsByLanguage } from '@hyperfixi/patterns-reference';
 import type { LanguageCode } from '../types';
+import { snapshot, diffSnapshots } from '../effect-signature';
 
 /**
  * The curated execution subset: simple, deterministic, fixture-friendly
@@ -287,53 +288,12 @@ export interface ExecutionResult {
   executionFidelity?: number;
 }
 
-/**
- * Serialize the identity-relevant state of every element under <body>.
- * Keyed by #id when present, else tag[document-order-index]; the fixture is
- * identical across languages, so keys are comparable.
- */
-function serializeElement(el: Element): string {
-  const attrs = Array.from(el.attributes)
-    .filter(a => a.name !== 'class' && a.name !== 'style')
-    .map(a => `${a.name}=${a.value}`)
-    .sort()
-    .join(',');
-  const classes = Array.from(el.classList).sort().join(' ');
-  const style = (el as HTMLElement).getAttribute('style') ?? '';
-  // Leaf text only — container text would duplicate every child mutation.
-  const text =
-    el.childNodes.length === 0 || (el.childNodes.length === 1 && el.firstChild?.nodeType === 3)
-      ? (el.textContent ?? '')
-      : '';
-  return `cls[${classes}] attr[${attrs}] style[${style}] text[${text}]`;
-}
-
-function snapshot(document: Document): Map<string, string> {
-  const out = new Map<string, string>();
-  // body participates under its own stable key: body-targeted effects
-  // (`add .modal-open to body`, modal-open/modal-close-button) must be
-  // visible in the signature now that the runtime resolves `body`. Before
-  // wave 3b these writes fell back to `me` (visible by accident); a correct
-  // body write was invisible and a dropped one unscoreable.
-  out.set('body', serializeElement(document.body));
-  document.body.querySelectorAll('*').forEach((el, i) => {
-    const key = el.id ? `#${el.id}` : `${el.tagName.toLowerCase()}[${i}]`;
-    out.set(key, serializeElement(el));
-  });
-  return out;
-}
-
-/** Sorted, stable list of per-element changes between two snapshots. */
-function diffSnapshots(before: Map<string, string>, after: Map<string, string>): string[] {
-  const effects: string[] = [];
-  for (const [k, v] of after) {
-    const b = before.get(k);
-    if (b === undefined) effects.push(`+${k} ${v}`);
-    else if (b !== v) effects.push(`Δ${k} ${v}`);
-  }
-  for (const k of before.keys()) if (!after.has(k)) effects.push(`-${k}`);
-  return effects.sort();
-}
+// Effect-signature machinery (serializeElement/snapshot/diffSnapshots) moved to
+// ../effect-signature.ts (imported at the top), shared with the
+// shipped-examples execution gate so the two can never disagree about what a
+// DOM effect is. Notes that used to live on the local copies (leaf-text-only
+// rationale; body's own stable key, added in wave 3b when the runtime learned
+// to resolve `body`) moved with them.
 
 /** How long to let the dispatched handler settle (ms). The subset contains no
  * waits/transitions/fetches, so this only needs to drain micro/macrotasks. */