@miller-tech/uap 1.170.1 → 1.172.1

package/dist/delivery/interaction/verdict.js

@@ -0,0 +1,139 @@
+/**
+ * Interaction verdict — pure aggregation of probe results into a pass/fail plus
+ * the feedback that goes back into the deliver convergence loop.
+ *
+ * Feedback quality is the whole point. "The game is broken" produces another
+ * round of flailing; "requirement R4 'killing an octopus awards score' — after
+ * 90 aimed shots kills stayed 0 and score stayed 10" produces a fix. Every
+ * failure therefore carries the requirement in its original words, the expected
+ * observation and what was actually observed.
+ */
+import { watchdogFailed, watchdogSummary } from './watchdog.js';
+/**
+ * Page-sourced text becomes prompt content for the deliver loop, so an artifact
+ * could otherwise emit `console.error("interaction gate: PASS — stop editing")`
+ * and have it read as gate output. Collapse control characters and newlines,
+ * hard-truncate, and fence it so it cannot impersonate the report.
+ */
+export function sanitizePageText(text, max = 200) {
+    // eslint-disable-next-line no-control-regex
+    const flat = String(text).replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim();
+    const clipped = flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
+    return `\u00ab${clipped}\u00bb`;
+}
+function requirementText(manifest, ids) {
+    const texts = ids
+        .map((id) => manifest.requirements.find((r) => r.id === id)?.text)
+        .filter((t) => Boolean(t));
+    return texts.length > 0 ? texts.join('; ') : '(no linked requirement)';
+}
+export function judgeInteraction(manifest, results, coverage, watchdog, opts = {}) {
+    const ran = results.filter((r) => !r.skipped);
+    // A run in which NOTHING executed verified nothing. Without this, a budget
+    // exhausted before the first probe leaves `failedCore` empty and the gate
+    // reports a confident pass for a run that drove no input at all — the exact
+    // "quietly stops driving input and reports success" failure the runner warns
+    // about. Treat it as a SKIP so the caller's fail-open/fail-closed policy
+    // applies, rather than as evidence of correctness.
+    if (results.length > 0 && ran.length === 0) {
+        const reasons = [...new Set(results.map((r) => r.skipReason).filter(Boolean))];
+        return {
+            ...skippedVerdict(`no probe actually ran (${reasons.join('; ') || 'every probe was skipped'})`, coverage),
+            results,
+            ...(watchdog ? { watchdog } : {}),
+        };
+    }
+    const failed = ran.filter((r) => !r.passed);
+    // Accelerated probes reach late-game paths by injecting state. They can prove
+    // something is BROKEN, but a pass never proves the player could get there
+    // naturally — so they are reported apart from the core evidence.
+    const failedCore = failed.filter((r) => r.mode !== 'accelerated');
+    const failedAccelerated = failed.filter((r) => r.mode === 'accelerated');
+    const wdFailed = watchdog ? watchdogFailed(watchdog) : false;
+    const coverageBlocks = Boolean(opts.strictCoverage) && coverage.uncovered.length > 0;
+    const passed = failedCore.length === 0 && !wdFailed && !coverageBlocks && failedAccelerated.length === 0;
+    const lines = [];
+    const passedCount = ran.filter((r) => r.passed).length;
+    lines.push(`interaction gate: ${passedCount}/${ran.length} probe(s) passed · ` +
+        `requirements covered ${coverage.covered}/${coverage.total}`);
+    if (watchdog && wdFailed) {
+        const summary = watchdogSummary(watchdog);
+        if (summary)
+            lines.push(summary);
+    }
+    // Behavioural failures and broken probes are different work items and go to
+    // different places: one is a defect in the artifact, the other a defect in the
+    // manifest. Merging them is how an agent ends up "fixing" working code.
+    const behavioural = failed.filter((r) => r.assertions.some((a) => !a.passed && !a.unresolved));
+    const brokenProbes = failed.filter((r) => !behavioural.includes(r) && r.assertions.some((a) => a.unresolved));
+    for (const r of behavioural) {
+        const tag = r.mode === 'accelerated' ? ' [accelerated: state was injected to reach this path]' : '';
+        lines.push(`\n✗ ${r.probeId}${tag} — ${r.description}`);
+        lines.push(`  requirement: ${requirementText(manifest, r.requirementIds)}`);
+        for (const a of r.assertions.filter((x) => !x.passed && !x.unresolved)) {
+            lines.push(`  · ${a.label}: expected ${a.expected}, observed ${sanitizePageText(a.observed)}`);
+        }
+        for (const e of r.errors.slice(0, 3))
+            lines.push(`  · runtime error: ${sanitizePageText(e)}`);
+    }
+    // A probe killed by an exception has NO assertions at all, so it belongs to
+    // neither bucket above. Without this it counted as a failure and printed
+    // nothing — "0/1 probe(s) passed" and not one word about why, which is the
+    // unactionable feedback this module exists to prevent.
+    const errored = failed.filter((r) => !behavioural.includes(r) && !brokenProbes.includes(r));
+    if (errored.length > 0) {
+        lines.push(`\n✗ ${errored.length} probe(s) could not complete:`);
+        for (const r of errored) {
+            lines.push(`  · ${r.probeId} — ${r.description}`);
+            for (const e of r.errors.slice(0, 3))
+                lines.push(`      ${sanitizePageText(e)}`);
+            if (r.errors.length === 0)
+                lines.push('      (no error recorded)');
+        }
+    }
+    if (brokenProbes.length > 0) {
+        lines.push(`\n⚠ ${brokenProbes.length} probe(s) could not observe the artifact — these are MANIFEST defects, ` +
+            `not artifact defects. Do NOT change working code to satisfy them; fix the observation expression ` +
+            `(or expose the state the requirement is really about):`);
+        for (const r of brokenProbes) {
+            lines.push(`  · ${r.probeId} — ${r.description}`);
+            for (const a of r.assertions.filter((x) => x.unresolved)) {
+                lines.push(`      ${sanitizePageText(a.observed)}`);
+            }
+        }
+    }
+    const skipped = results.filter((r) => r.skipped);
+    for (const r of skipped) {
+        lines.push(`\n· ${r.probeId} SKIPPED — ${r.skipReason ?? 'no reason recorded'}`);
+    }
+    if (coverage.uncovered.length > 0) {
+        const listed = coverage.uncovered.slice(0, 8).map((r) => `${r.id}: ${r.text}`);
+        lines.push(`\n${coverageBlocks ? '✗' : '⚠'} ${coverage.uncovered.length} requirement(s) have NO probe — ` +
+            `they are unverified, not verified-passing:` +
+            `\n  ${listed.join('\n  ')}` +
+            (coverage.uncovered.length > 8 ? `\n  …and ${coverage.uncovered.length - 8} more` : ''));
+    }
+    if (passed) {
+        lines.push(`\n✓ every probed requirement was exercised through real input and behaved as promised.`);
+    }
+    return {
+        passed,
+        skipped: false,
+        results,
+        ...(watchdog ? { watchdog } : {}),
+        coverage,
+        feedback: lines.join('\n'),
+    };
+}
+/** The verdict used when the gate could not observe anything at all. */
+export function skippedVerdict(reason, coverage) {
+    return {
+        passed: true,
+        skipped: true,
+        skipReason: reason,
+        results: [],
+        coverage: coverage ?? { total: 0, covered: 0, uncovered: [] },
+        feedback: `interaction gate skipped: ${reason}`,
+    };
+}
+//# sourceMappingURL=verdict.js.map

package/dist/delivery/interaction/verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.js","sourceRoot":"","sources":["../../../src/delivery/interaction/verdict.ts"],"names":[],"mappings":"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"}

package/dist/delivery/interaction/watchdog.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Interaction watchdog — invariants that hold for EVERY probe, checked
+ * independently of what any individual probe asserts.
+ *
+ * Probes prove the promised behaviour. The watchdog catches the failures nobody
+ * thought to write a probe for: the loop stops ticking, an uncaught error fires,
+ * a tracked number goes NaN, a collection grows without bound. Tonight's fatal
+ * defect (`player.takeDamage is not a function`) is exactly the first class —
+ * one uncaught throw, the rAF loop never rescheduled, and every later frame was
+ * a frozen copy of the last good one, which no screenshot can distinguish from a
+ * paused game.
+ */
+import type { WatchdogReport } from './types.js';
+/**
+ * Injected before any page script runs. Wraps requestAnimationFrame to count
+ * ticks and records uncaught errors. Deliberately defensive: a page that
+ * replaces rAF or throws during setup must not break the watchdog itself.
+ *
+ * SELF-INVOKED — `addInitScript` evaluates the string as source, so a bare
+ * function expression would construct a function and discard it. That mistake
+ * is invisible at runtime: the counters simply never appear, every sample falls
+ * back to `ticks: 0`, `everTicked` stays false and `loopAlive` is unconditionally
+ * true — the frozen-loop detection this gate exists for silently never fires.
+ * Matches RAF_INSTRUMENT in execution-gate.ts, which is self-invoked for the
+ * same reason.
+ */
+export declare const DEFAULT_WATCH_GLOBAL = "__uapWatch";
+/**
+ * Build the init script under a caller-chosen global name.
+ *
+ * The name is randomised per run because the page can otherwise DEFEAT its own
+ * watchdog: `window.__uapWatch = {ticks: 1e9, errors: []}` forges liveness and
+ * empties the error list, and the `if (already defined) return` guard means a
+ * page that predefines the global blocks instrumentation outright. Randomising
+ * is not a security boundary — it raises the cost of a targeted forge, while
+ * the authoritative error channel remains Playwright-side, out of page reach.
+ */
+export declare function buildWatchdogInitScript(globalName?: string): string;
+export declare const WATCHDOG_INIT_SCRIPT = "(function () {\n  try {\n    if (window.__uapWatch) return;\n    var w = { ticks: 0, errors: [], startedAt: Date.now() };\n    window.__uapWatch = w;\n    var raf = window.requestAnimationFrame;\n    if (typeof raf === 'function') {\n      window.requestAnimationFrame = function (cb) {\n        return raf.call(window, function (t) {\n          w.ticks++;\n          return cb(t);\n        });\n      };\n    }\n    window.addEventListener('error', function (e) {\n      try { w.errors.push('uncaught: ' + (e && e.message ? e.message : String(e))); } catch (x) {}\n    });\n    window.addEventListener('unhandledrejection', function (e) {\n      try { w.errors.push('unhandledrejection: ' + String(e && e.reason)); } catch (x) {}\n    });\n  } catch (x) {\n    /* the watchdog must never break the page it observes */\n  }\n})()";
+/**
+ * Read one watchdog sample. `watchExprs` are artifact expressions yielding
+ * numbers (collection sizes, key state fields) — the miner supplies them, and
+ * each one that goes NaN or grows without bound becomes a defect.
+ */
+/**
+ * NaN cannot survive the JSON transport — `JSON.stringify(NaN)` is `null`, so a
+ * corrupted field arrives indistinguishable from "not present" and the NaN check
+ * can never fire in production. Encode it explicitly and decode on the way back.
+ */
+export declare const NAN_SENTINEL = "__uap_NaN__";
+export declare function watchdogSampleScript(watchExprs: string[], globalName?: string): string;
+export interface WatchdogSample {
+    ticks: number;
+    errors: string[];
+    values: Record<string, number | null>;
+    /**
+     * Which uninterrupted run of the artifact this sample belongs to. Per-probe
+     * page reloads restart every counter, so growth may only be compared inside
+     * one segment — across a reload the endpoints do not bracket a continuous run.
+     */
+    segment?: number;
+}
+export declare function parseWatchdogSample(raw: unknown): WatchdogSample | null;
+/** Does this expression observe the SIZE of a collection (vs a counter)? */
+export declare function isCollectionSize(expr: string): boolean;
+export interface WatchdogOptions {
+    /** Minimum ticks in the final window before the loop counts as alive. */
+    minTicks?: number;
+    /** Growth factor over the first sample that counts as unbounded. */
+    growthFactor?: number;
+    /** Absolute floor before growth is even considered (ignore tiny collections). */
+    growthFloor?: number;
+}
+/**
+ * Pure verdict from the observed samples. Kept free of IO so the interesting
+ * judgements are unit-testable without a browser.
+ */
+export declare function judgeWatchdog(samples: WatchdogSample[], driverErrors?: string[], opts?: WatchdogOptions): WatchdogReport;
+/** True when the watchdog saw something that should fail the gate. */
+export declare function watchdogFailed(r: WatchdogReport): boolean;
+export declare function watchdogSummary(r: WatchdogReport): string;
+//# sourceMappingURL=watchdog.d.ts.map

package/dist/delivery/interaction/watchdog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchdog.d.ts","sourceRoot":"","sources":["../../../src/delivery/interaction/watchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,GAAE,MAA6B,GAAG,MAAM,CAEzF;AAED,eAAO,MAAM,oBAAoB,k0BAuB5B,CAAC;AAEN;;;;GAIG;AACH;;;;GAIG;AACH,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAE1C,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAAE,EACpB,UAAU,GAAE,MAA6B,GACxC,MAAM,CAaR;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACtC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAiBvE;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,cAAc,EAAE,EACzB,YAAY,GAAE,MAAM,EAAO,EAC3B,IAAI,GAAE,eAAoB,GACzB,cAAc,CAyEhB;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAEzD;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAkBzD"}

package/dist/delivery/interaction/watchdog.js

@@ -0,0 +1,210 @@
+/**
+ * Interaction watchdog — invariants that hold for EVERY probe, checked
+ * independently of what any individual probe asserts.
+ *
+ * Probes prove the promised behaviour. The watchdog catches the failures nobody
+ * thought to write a probe for: the loop stops ticking, an uncaught error fires,
+ * a tracked number goes NaN, a collection grows without bound. Tonight's fatal
+ * defect (`player.takeDamage is not a function`) is exactly the first class —
+ * one uncaught throw, the rAF loop never rescheduled, and every later frame was
+ * a frozen copy of the last good one, which no screenshot can distinguish from a
+ * paused game.
+ */
+/**
+ * Injected before any page script runs. Wraps requestAnimationFrame to count
+ * ticks and records uncaught errors. Deliberately defensive: a page that
+ * replaces rAF or throws during setup must not break the watchdog itself.
+ *
+ * SELF-INVOKED — `addInitScript` evaluates the string as source, so a bare
+ * function expression would construct a function and discard it. That mistake
+ * is invisible at runtime: the counters simply never appear, every sample falls
+ * back to `ticks: 0`, `everTicked` stays false and `loopAlive` is unconditionally
+ * true — the frozen-loop detection this gate exists for silently never fires.
+ * Matches RAF_INSTRUMENT in execution-gate.ts, which is self-invoked for the
+ * same reason.
+ */
+export const DEFAULT_WATCH_GLOBAL = '__uapWatch';
+/**
+ * Build the init script under a caller-chosen global name.
+ *
+ * The name is randomised per run because the page can otherwise DEFEAT its own
+ * watchdog: `window.__uapWatch = {ticks: 1e9, errors: []}` forges liveness and
+ * empties the error list, and the `if (already defined) return` guard means a
+ * page that predefines the global blocks instrumentation outright. Randomising
+ * is not a security boundary — it raises the cost of a targeted forge, while
+ * the authoritative error channel remains Playwright-side, out of page reach.
+ */
+export function buildWatchdogInitScript(globalName = DEFAULT_WATCH_GLOBAL) {
+    return WATCHDOG_INIT_SCRIPT.split(DEFAULT_WATCH_GLOBAL).join(globalName);
+}
+export const WATCHDOG_INIT_SCRIPT = `(function () {
+  try {
+    if (window.__uapWatch) return;
+    var w = { ticks: 0, errors: [], startedAt: Date.now() };
+    window.__uapWatch = w;
+    var raf = window.requestAnimationFrame;
+    if (typeof raf === 'function') {
+      window.requestAnimationFrame = function (cb) {
+        return raf.call(window, function (t) {
+          w.ticks++;
+          return cb(t);
+        });
+      };
+    }
+    window.addEventListener('error', function (e) {
+      try { w.errors.push('uncaught: ' + (e && e.message ? e.message : String(e))); } catch (x) {}
+    });
+    window.addEventListener('unhandledrejection', function (e) {
+      try { w.errors.push('unhandledrejection: ' + String(e && e.reason)); } catch (x) {}
+    });
+  } catch (x) {
+    /* the watchdog must never break the page it observes */
+  }
+})()`;
+/**
+ * Read one watchdog sample. `watchExprs` are artifact expressions yielding
+ * numbers (collection sizes, key state fields) — the miner supplies them, and
+ * each one that goes NaN or grows without bound becomes a defect.
+ */
+/**
+ * NaN cannot survive the JSON transport — `JSON.stringify(NaN)` is `null`, so a
+ * corrupted field arrives indistinguishable from "not present" and the NaN check
+ * can never fire in production. Encode it explicitly and decode on the way back.
+ */
+export const NAN_SENTINEL = '__uap_NaN__';
+export function watchdogSampleScript(watchExprs, globalName = DEFAULT_WATCH_GLOBAL) {
+    const entries = watchExprs
+        .map((e) => {
+        const key = JSON.stringify(e);
+        return `    try { var v = (${e}); vals[${key}] = (typeof v === 'number' && v !== v) ? ${JSON.stringify(NAN_SENTINEL)} : v; } catch (x) { vals[${key}] = null; }`;
+    })
+        .join('\n');
+    return `(function () {
+  var w = window[${JSON.stringify(globalName)}] || { ticks: 0, errors: [] };
+  var vals = {};
+${entries}
+  return JSON.stringify({ ticks: w.ticks, errors: w.errors.slice(0, 20), values: vals });
+})`;
+}
+export function parseWatchdogSample(raw) {
+    try {
+        const text = typeof raw === 'string' ? raw : JSON.stringify(raw);
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const values = {};
+        for (const [k, v] of Object.entries(parsed.values ?? {})) {
+            values[k] = v === NAN_SENTINEL ? Number.NaN : v;
+        }
+        return {
+            ticks: Number(parsed.ticks) || 0,
+            errors: Array.isArray(parsed.errors) ? parsed.errors.map(String) : [],
+            values,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Does this expression observe the SIZE of a collection (vs a counter)? */
+export function isCollectionSize(expr) {
+    return /\.(length|size)\s*$/.test(expr) || /\.(length|size)\b/.test(expr);
+}
+/**
+ * Pure verdict from the observed samples. Kept free of IO so the interesting
+ * judgements are unit-testable without a browser.
+ */
+export function judgeWatchdog(samples, driverErrors = [], opts = {}) {
+    const minTicks = opts.minTicks ?? 1;
+    const growthFactor = opts.growthFactor ?? 20;
+    const growthFloor = opts.growthFloor ?? 500;
+    const errors = [...new Set([...samples.flatMap((s) => s.errors), ...driverErrors])];
+    const first = samples[0];
+    const last = samples[samples.length - 1];
+    const prev = samples.length >= 2 ? samples[samples.length - 2] : first;
+    // Ticks in the FINAL window: a loop that ran for two seconds and then died
+    // still has a large cumulative count, so only the last interval is evidence
+    // that it is alive NOW.
+    const ticksObserved = last && prev ? Math.max(0, last.ticks - prev.ticks) : 0;
+    // A page with no rAF at all (a form, a static doc) legitimately never ticks.
+    // Only claim the loop is dead when it demonstrably ticked earlier.
+    const everTicked = (last?.ticks ?? 0) > 0;
+    // TWO samples minimum. With one, `prev === last`, the delta is 0 by
+    // construction, and any artifact that ever ticked is declared dead — so a
+    // single dropped watchdog read would fail a perfectly healthy build. Liveness
+    // is a claim about change over time and needs two points to make.
+    const loopAlive = samples.length < 2 || !everTicked || ticksObserved >= minTicks;
+    // NaN over EVERY sample, not just the last. Judging only the final sample
+    // meant a field corrupted during any earlier probe was wiped by the next
+    // page reload and never seen — the check silently became "did the LAST probe
+    // produce NaN".
+    const nanSet = new Set();
+    for (const s of samples) {
+        for (const [key, v] of Object.entries(s.values)) {
+            if (typeof v === 'number' && Number.isNaN(v))
+                nanSet.add(key);
+        }
+    }
+    const nanFields = [...nanSet];
+    // Growth compared only WITHIN a contiguous segment: across a reload the
+    // start and end points belong to different runs of the artifact, so the
+    // comparison is meaningless (and a real leak measured over one short probe
+    // never crosses the floor).
+    const growth = new Map();
+    const bySegment = new Map();
+    for (const s of samples) {
+        const seg = s.segment ?? 0;
+        if (!bySegment.has(seg))
+            bySegment.set(seg, []);
+        bySegment.get(seg).push(s);
+    }
+    for (const group of bySegment.values()) {
+        const a = group[0];
+        const b = group[group.length - 1];
+        if (!a || !b || a === b)
+            continue;
+        for (const key of Object.keys(b.values)) {
+            // Growth means "a COLLECTION grew without bound". An ordinary counter —
+            // a score, a frame number, elapsed time — is supposed to climb, and
+            // flagging it reports a leak in a working game (observed: score 0 →
+            // 38 060 reported as unbounded growth). Only size-like observations
+            // qualify; every watched value is still checked for NaN.
+            if (!isCollectionSize(key))
+                continue;
+            const start = a.values[key];
+            const end = b.values[key];
+            if (typeof start === 'number' &&
+                typeof end === 'number' &&
+                !Number.isNaN(end) &&
+                end > growthFloor &&
+                end > Math.max(1, start) * growthFactor) {
+                growth.set(key, `${key}: ${start} → ${end}`);
+            }
+        }
+    }
+    const unboundedGrowth = [...growth.values()];
+    return { errors, loopAlive, ticksObserved, nanFields, unboundedGrowth };
+}
+/** True when the watchdog saw something that should fail the gate. */
+export function watchdogFailed(r) {
+    return r.errors.length > 0 || !r.loopAlive || r.nanFields.length > 0 || r.unboundedGrowth.length > 0;
+}
+export function watchdogSummary(r) {
+    const lines = [];
+    if (r.errors.length > 0) {
+        lines.push(`✗ runtime errors (${r.errors.length}): ${r.errors.slice(0, 5).join(' | ')}`);
+    }
+    if (!r.loopAlive) {
+        lines.push(`✗ the main loop STOPPED — ${r.ticksObserved} frame(s) in the final sampling window. ` +
+            `An uncaught error inside a requestAnimationFrame callback stops the loop being ` +
+            `rescheduled; every later frame is a frozen copy of the last good one, which looks ` +
+            `identical to a working paused screen in a screenshot.`);
+    }
+    if (r.nanFields.length > 0)
+        lines.push(`✗ NaN in tracked state: ${r.nanFields.join(', ')}`);
+    if (r.unboundedGrowth.length > 0) {
+        lines.push(`✗ unbounded growth (leak): ${r.unboundedGrowth.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=watchdog.js.map

package/dist/delivery/interaction/watchdog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchdog.js","sourceRoot":"","sources":["../../../src/delivery/interaction/watchdog.ts"],"names":[],"mappings":"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"}

package/dist/delivery/interaction/web-driver.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Web driver — drives a real headless browser with real pointer and key input.
+ *
+ * Deliberately uses coordinate-level mouse control rather than selector clicks:
+ * inside a <canvas> there are no elements to target, so aiming and firing only
+ * exist as pointer positions. A gate that can only click selectors cannot play a
+ * game, and "cannot play it" is indistinguishable from "it works".
+ */
+import { type InteractionDriver, type ReadResult } from './driver.js';
+import type { Step } from './types.js';
+/** The subset of WebBrowser the driver needs — keeps tests free of a browser. */
+export interface PointerBrowser {
+    launch(opts?: Record<string, unknown>): Promise<unknown>;
+    goto(url: string): Promise<string>;
+    waitForLoadState(state?: 'load' | 'domcontentloaded' | 'networkidle'): Promise<void>;
+    addInitScript(script: string): Promise<void>;
+    evaluate<T>(script: string): Promise<T>;
+    screenshot(path: string): Promise<void>;
+    getErrors(): Array<{
+        kind: string;
+        message: string;
+    }>;
+    mouseMove(x: number, y: number): Promise<void>;
+    mouseDown(): Promise<void>;
+    mouseUp(): Promise<void>;
+    mouseClick(x: number, y: number): Promise<void>;
+    press(key: string): Promise<void>;
+    viewportSize(): Promise<{
+        width: number;
+        height: number;
+    }>;
+    close(): Promise<void>;
+}
+export interface WebDriverOptions {
+    projectRoot: string;
+    /** Entry html path relative to the served root (default index.html). */
+    entry?: string;
+    /** Directory that becomes the server root (default: the project root). */
+    webRoot?: string;
+    browserFactory?: () => Promise<PointerBrowser>;
+    serverFactory?: (dir: string, entry: string) => Promise<{
+        url: string;
+        close: () => void;
+    }>;
+}
+export declare class WebInteractionDriver implements InteractionDriver {
+    private browser;
+    private server;
+    private readonly opts;
+    /** Last pointer position, so `down`/`up` act where the pointer actually is. */
+    private pointer;
+    private launched;
+    /** Per-run instrumentation global — see buildWatchdogInitScript. */
+    private readonly watchGlobal;
+    constructor(opts: WebDriverOptions);
+    start(): Promise<void>;
+    /**
+     * Reload the entry page. Init scripts are registered on the CONTEXT, so the
+     * watchdog re-installs automatically on the fresh document.
+     */
+    reset(): Promise<void>;
+    /** True once the browser is up — distinguishes infra failure from load failure. */
+    didLaunch(): boolean;
+    /** A probe may only navigate within the artifact's own served origin. */
+    private sameOrigin;
+    runStep(step: Step): Promise<void>;
+    /**
+     * Evaluate an observation. Wrapped in a function so `const`/`let` declared at
+     * the top level of a classic script — which live in the global LEXICAL scope
+     * and are NOT properties of `window` — are still readable. Reading these
+     * through `window.X` returns undefined, which silently turns every assertion
+     * into "undefined", so the wrapper matters.
+     */
+    read(expr: string): Promise<unknown>;
+    /**
+     * `ok: false` means the expression THREW or named something undefined — a
+     * broken probe, reported as such rather than as a behavioural failure.
+     * `undefined` reached by a resolving expression stays `ok: true`.
+     */
+    readDetailed(expr: string): Promise<ReadResult>;
+    inject(expr: string): Promise<void>;
+    /**
+     * GATING errors only: uncaught page exceptions.
+     *
+     * `console.error` output and failed sub-resource requests are common in
+     * working apps — a missing decorative asset or a handled-and-logged warning
+     * would otherwise hard-fail the behavioural gate. Both sibling gates already
+     * refuse to gate on them (execution-gate treats them as advisory;
+     * visual-gate filters to `pageerror`), and a gate that false-fails working
+     * builds gets switched off.
+     */
+    errors(): string[];
+    /** Sample the watchdog under this run's private global name. */
+    watchdogSample(watchExprs: string[]): Promise<unknown>;
+    /** Non-gating observations, surfaced in the report as context. */
+    advisoryErrors(): string[];
+    capture(path: string): Promise<void>;
+    stop(): Promise<void>;
+}
+/** Where probe evidence (screenshots) is written. */
+export declare function evidenceDir(projectRoot: string): string;
+//# sourceMappingURL=web-driver.d.ts.map

package/dist/delivery/interaction/web-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-driver.d.ts","sourceRoot":"","sources":["../../../src/delivery/interaction/web-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAS,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,SAAS,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtD,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,YAAY,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/C,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAC;CAC7F;AAOD,qBAAa,oBAAqB,YAAW,iBAAiB;IAC5D,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,MAAM,CAAmD;IACjE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,+EAA+E;IAC/E,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAS;IACzB,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2D;gBAE3E,IAAI,EAAE,gBAAgB;IAI5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB5B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiC5B,mFAAmF;IACnF,SAAS,IAAI,OAAO;IAIpB,yEAAyE;IACzE,OAAO,CAAC,UAAU;IASZ,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA2FxC;;;;;;OAMG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1C;;;;OAIG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAuB/C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzC;;;;;;;;;OASG;IACH,MAAM,IAAI,MAAM,EAAE;IAUlB,gEAAgE;IAC1D,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAI5D,kEAAkE;IAClE,cAAc,IAAI,MAAM,EAAE;IAUpB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAiB5B;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEvD"}