fast-replay 0.1.0

package/dist/recorder/reaction.js

@@ -0,0 +1,65 @@
+const MAX_CONSOLE_TEXT = 500;
+export function collectReactions(context) {
+    const network = [];
+    const console_ = [];
+    const inFlight = new Map();
+    const onRequest = (request) => {
+        const entry = {
+            kind: 'network',
+            method: request.method(),
+            url: request.url(),
+            startedAt: Date.now(),
+            settledAt: null,
+            status: null,
+            failed: false,
+        };
+        inFlight.set(request, entry);
+        network.push(entry);
+    };
+    const settle = (request, status, failed) => {
+        const entry = inFlight.get(request);
+        if (!entry)
+            return;
+        entry.settledAt = Date.now();
+        entry.status = status;
+        entry.failed = failed;
+        inFlight.delete(request);
+    };
+    const onResponse = (response) => {
+        const status = response.status();
+        settle(response.request(), status, status >= 400);
+    };
+    const onRequestFailed = (request) => {
+        // Navigations the user aborts are noise, not evidence of a bug.
+        const aborted = request.failure()?.errorText === 'net::ERR_ABORTED';
+        settle(request, null, !aborted);
+    };
+    const onConsole = (msg) => {
+        if (msg.type() !== 'error')
+            return;
+        console_.push({ kind: 'console', text: msg.text().slice(0, MAX_CONSOLE_TEXT), t: Date.now() });
+    };
+    // Context-level uncaught page exceptions arrive as WebError, not Error.
+    const onWebError = (webError) => {
+        const err = webError.error();
+        const text = `${err.name}: ${err.message}`;
+        console_.push({ kind: 'console', text: text.slice(0, MAX_CONSOLE_TEXT), t: Date.now() });
+    };
+    context.on('request', onRequest);
+    context.on('response', onResponse);
+    context.on('requestfailed', onRequestFailed);
+    context.on('console', onConsole);
+    context.on('weberror', onWebError);
+    return {
+        network,
+        console: console_,
+        detach() {
+            context.off('request', onRequest);
+            context.off('response', onResponse);
+            context.off('requestfailed', onRequestFailed);
+            context.off('console', onConsole);
+            context.off('weberror', onWebError);
+        },
+    };
+}
+//# sourceMappingURL=reaction.js.map

package/dist/recorder/reaction.js.map

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

package/dist/recorder/types.d.ts

@@ -0,0 +1,62 @@
+import type { Action, Author } from '../ir/schema.js';
+/** Selector + semantic info resolved in the page, while the element is still live. */
+export interface CapturedTarget {
+    candidates: string[];
+    semantic: string;
+}
+/** A user action, as captured in the page. */
+export interface RawActionEvent {
+    kind: 'action';
+    action: Action;
+    value: string | null;
+    target: CapturedTarget | null;
+    /** Date.now() at capture time. */
+    t: number;
+    author: Author;
+}
+/** A batch of DOM changes summarized as selectors that appeared or disappeared. */
+export interface RawDomEvent {
+    kind: 'dom';
+    appeared: string[];
+    gone: string[];
+    t: number;
+}
+export type PageEvent = RawActionEvent | RawDomEvent;
+export interface RawNavigationEvent {
+    kind: 'navigation';
+    url: string;
+    t: number;
+}
+export interface RawNetworkEvent {
+    kind: 'network';
+    method: string;
+    url: string;
+    /** When the request was issued. */
+    startedAt: number;
+    /** When it settled (response or failure). Null while still in flight. */
+    settledAt: number | null;
+    status: number | null;
+    failed: boolean;
+}
+export interface RawConsoleEvent {
+    kind: 'console';
+    text: string;
+    t: number;
+}
+export type RawEvent = RawActionEvent | RawDomEvent | RawNavigationEvent | RawNetworkEvent | RawConsoleEvent;
+/** Everything a recording session collected, in capture order per channel. */
+export interface RecordingTrace {
+    actions: RawActionEvent[];
+    dom: RawDomEvent[];
+    navigations: RawNavigationEvent[];
+    network: RawNetworkEvent[];
+    console: RawConsoleEvent[];
+    startedAt: number;
+    endedAt: number;
+    baseUrl: string;
+    startPath: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+}

package/dist/recorder/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/recorder/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/recorder/types.ts"],"names":[],"mappings":""}

package/dist/replayer/artifacts.d.ts

@@ -0,0 +1,25 @@
+import type { Page } from 'playwright';
+import { type ReproPaths } from '../ir/io.js';
+import type { RawConsoleEvent, RawNetworkEvent } from '../recorder/types.js';
+export interface FailureContext {
+    stepId: string;
+    stepIndex: number;
+    semantic: string;
+    expected: string;
+    observed: string;
+    /** Only network activity since the previous step, so the log stays readable. */
+    networkSince: RawNetworkEvent[];
+    consoleErrors: RawConsoleEvent[];
+}
+export interface WrittenArtifacts {
+    dir: string;
+    screenshot: string | null;
+    consoleLog: string;
+    networkLog: string;
+    summary: string;
+}
+/**
+ * Everything a human (or an agent reading the MCP response) needs to understand
+ * a failure without re-running anything.
+ */
+export declare function writeFailureArtifacts(page: Page | null, paths: ReproPaths, failure: FailureContext): Promise<WrittenArtifacts>;

package/dist/replayer/artifacts.js

@@ -0,0 +1,58 @@
+import { mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { writeFileAtomic } from '../ir/io.js';
+const CONSOLE_TAIL = 50;
+/**
+ * Everything a human (or an agent reading the MCP response) needs to understand
+ * a failure without re-running anything.
+ */
+export async function writeFailureArtifacts(page, paths, failure) {
+    // Stale artifacts from an earlier run are worse than none.
+    await rm(paths.artifactsDir, { recursive: true, force: true });
+    await mkdir(paths.artifactsDir, { recursive: true });
+    const screenshot = path.join(paths.artifactsDir, 'screenshot.png');
+    let screenshotPath = null;
+    if (page && !page.isClosed()) {
+        try {
+            await page.screenshot({ path: screenshot, fullPage: true });
+            screenshotPath = screenshot;
+        }
+        catch {
+            // A crashed or navigating page cannot be captured; the rest still helps.
+        }
+    }
+    const consoleLog = path.join(paths.artifactsDir, 'console.log');
+    const tail = failure.consoleErrors.slice(-CONSOLE_TAIL);
+    await writeFileAtomic(consoleLog, tail.length
+        ? `${tail.map((c) => `[${new Date(c.t).toISOString()}] ${c.text}`).join('\n')}\n`
+        : 'No console errors captured.\n');
+    const networkLog = path.join(paths.artifactsDir, 'network.log');
+    await writeFileAtomic(networkLog, failure.networkSince.length
+        ? `${failure.networkSince
+            .map((n) => {
+            const status = n.failed ? `FAILED(${n.status ?? 'aborted'})` : (n.status ?? 'pending');
+            const ms = n.settledAt ? `${n.settledAt - n.startedAt}ms` : 'in-flight';
+            return `${n.method} ${n.url} -> ${status} (${ms})`;
+        })
+            .join('\n')}\n`
+        : 'No network activity since the previous step.\n');
+    const summary = path.join(paths.artifactsDir, 'failure.json');
+    await writeFileAtomic(summary, `${JSON.stringify({
+        stepId: failure.stepId,
+        stepIndex: failure.stepIndex,
+        semantic: failure.semantic,
+        expected: failure.expected,
+        observed: failure.observed,
+        screenshot: screenshotPath,
+        consoleLog,
+        networkLog,
+    }, null, 2)}\n`);
+    return {
+        dir: paths.artifactsDir,
+        screenshot: screenshotPath,
+        consoleLog,
+        networkLog,
+        summary,
+    };
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/replayer/artifacts.js.map

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

package/dist/replayer/invariants.d.ts

@@ -0,0 +1,26 @@
+import type { NetworkWait, Repro } from '../ir/schema.js';
+import type { RawConsoleEvent, RawNetworkEvent } from '../recorder/types.js';
+/**
+ * Every endpoint the recording actually exercised. Failed-request checking is
+ * scoped to these: a third-party analytics beacon 404-ing is noise, and letting
+ * it fail a repro would make the tool untrustworthy within a day.
+ */
+export declare function recordedPatterns(repro: Repro): NetworkWait[];
+export interface InvariantViolation {
+    invariant: 'noConsoleErrors' | 'noFailedRequests';
+    detail: string;
+}
+/**
+ * Did the specific bug this repro captured happen again?
+ *
+ * Deliberately narrow: it looks for the exact evidence recorded at authoring
+ * time, not for "any console error". An app that always logs a benign warning
+ * would otherwise never pass --expect-fixed, and a tool that cries wolf gets
+ * turned off.
+ */
+/** Does this repro record anything that could tell us the bug came back? */
+export declare function hasBugSignature(repro: Repro): boolean;
+/** Has the author stated what must be true once it is fixed? */
+export declare function hasFixCriterion(repro: Repro): boolean;
+export declare function checkBugRecurred(repro: Repro, network: RawNetworkEvent[], consoleErrors: RawConsoleEvent[], baseUrl: string): string[];
+export declare function checkInvariants(repro: Repro, network: RawNetworkEvent[], consoleErrors: RawConsoleEvent[], baseUrl: string): InvariantViolation[];

package/dist/replayer/invariants.js

@@ -0,0 +1,109 @@
+import { matchesUrlPattern } from '../compiler/normalize.js';
+import { isAmbientConsoleError, isIncidentalRequest } from '../noise.js';
+/**
+ * Every endpoint the recording actually exercised. Failed-request checking is
+ * scoped to these: a third-party analytics beacon 404-ing is noise, and letting
+ * it fail a repro would make the tool untrustworthy within a day.
+ */
+export function recordedPatterns(repro) {
+    const all = [];
+    for (const step of repro.steps)
+        all.push(...(step.waitAfter.network ?? []));
+    all.push(...(repro.assertion.finalState.network ?? []));
+    for (const f of repro.assertion.observedAtRecord?.failedRequests ?? []) {
+        all.push({ urlPattern: f.urlPattern, method: f.method });
+    }
+    const seen = new Set();
+    return all.filter((n) => {
+        const key = `${n.method} ${n.urlPattern}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Did the specific bug this repro captured happen again?
+ *
+ * Deliberately narrow: it looks for the exact evidence recorded at authoring
+ * time, not for "any console error". An app that always logs a benign warning
+ * would otherwise never pass --expect-fixed, and a tool that cries wolf gets
+ * turned off.
+ */
+/** Does this repro record anything that could tell us the bug came back? */
+export function hasBugSignature(repro) {
+    const observed = repro.assertion.observedAtRecord;
+    return Boolean(observed && (observed.consoleErrors.length || observed.failedRequests.length));
+}
+/** Has the author stated what must be true once it is fixed? */
+export function hasFixCriterion(repro) {
+    const expected = repro.assertion.expectedWhenFixed;
+    return Boolean(expected && (expected.domAppeared?.length || expected.domGone?.length));
+}
+export function checkBugRecurred(repro, network, consoleErrors, baseUrl) {
+    const observed = repro.assertion.observedAtRecord;
+    if (!observed)
+        return [];
+    const recurred = [];
+    const normalize = (s) => s.replace(/\s+/g, ' ').trim();
+    const baseline = observed.ambientConsoleErrors ?? [];
+    const live = consoleErrors
+        .filter((c) => !isAmbientConsoleError(c.text))
+        .filter((c) => !baseline.some((b) => c.text.startsWith(b.slice(0, 60))))
+        .map((c) => normalize(c.text));
+    for (const recorded of observed.consoleErrors) {
+        // Compare on a prefix: stack frames and ids drift between runs, the
+        // message that identifies the bug does not.
+        const needle = normalize(recorded).slice(0, 80);
+        if (needle && live.some((l) => l.includes(needle))) {
+            recurred.push(`console error recurred: ${recorded}`);
+        }
+    }
+    for (const recorded of observed.failedRequests) {
+        const again = network.some((n) => n.failed &&
+            n.method.toUpperCase() === recorded.method.toUpperCase() &&
+            matchesUrlPattern(n.url, recorded.urlPattern, baseUrl));
+        if (again) {
+            recurred.push(`request failed again: ${recorded.method} ${recorded.urlPattern} -> ${recorded.status ?? 'aborted'}`);
+        }
+    }
+    return recurred;
+}
+export function checkInvariants(repro, network, consoleErrors, baseUrl) {
+    const violations = [];
+    if (repro.assertion.invariants.noConsoleErrors) {
+        // Same filter the compiler used. Without it the invariant is inferred from
+        // filtered output but enforced against raw output, so ambient CORS and
+        // connection errors fail every replay of a perfectly healthy app.
+        const baseline = repro.assertion.observedAtRecord?.ambientConsoleErrors ?? [];
+        const seenAtRecord = (text) => baseline.some((b) => b === text || text.startsWith(b.slice(0, 60)));
+        for (const err of consoleErrors) {
+            if (isAmbientConsoleError(err.text) || seenAtRecord(err.text))
+                continue;
+            violations.push({ invariant: 'noConsoleErrors', detail: err.text });
+        }
+    }
+    if (repro.assertion.invariants.noFailedRequests) {
+        const patterns = recordedPatterns(repro);
+        for (const n of network) {
+            // An aborted request is a cancellation — a navigation, an unmount, a
+            // user moving on — not a server failure. Counting it made a same-host
+            // telemetry beacon fail every replay, and host rules cannot catch that
+            // because it is served from the app's own API origin.
+            if (!n.failed || n.status === null || n.status < 400)
+                continue;
+            if (isIncidentalRequest(n.url))
+                continue;
+            const inScope = patterns.some((p) => p.method.toUpperCase() === n.method.toUpperCase() &&
+                matchesUrlPattern(n.url, p.urlPattern, baseUrl));
+            if (!inScope)
+                continue;
+            violations.push({
+                invariant: 'noFailedRequests',
+                detail: `${n.method} ${n.url} -> ${n.status ?? 'aborted'}`,
+            });
+        }
+    }
+    return violations;
+}
+//# sourceMappingURL=invariants.js.map

package/dist/replayer/invariants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants.js","sourceRoot":"","sources":["../../src/replayer/invariants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIzE;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAY;IAC3C,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;IAC5E,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;IACxD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,gBAAgB,EAAE,cAAc,IAAI,EAAE,EAAE,CAAC;QACvE,GAAG,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACtB,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;QAC1C,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAOD;;;;;;;GAOG;AACH,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAAC,KAAY;IAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,gBAAgB,CAAC;IAClD,OAAO,OAAO,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,IAAI,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;AAChG,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,eAAe,CAAC,KAAY;IAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,iBAAiB,CAAC;IACnD,OAAO,OAAO,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AACzF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,KAAY,EACZ,OAA0B,EAC1B,aAAgC,EAChC,OAAe;IAEf,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,gBAAgB,CAAC;IAClD,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,MAAM,SAAS,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACvE,MAAM,QAAQ,GAAG,QAAQ,CAAC,oBAAoB,IAAI,EAAE,CAAC;IACrD,MAAM,IAAI,GAAG,aAAa;SACvB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;SAC7C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;SACvE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACjC,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC;QAC9C,oEAAoE;QACpE,4CAA4C;QAC5C,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAChD,IAAI,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;YACnD,QAAQ,CAAC,IAAI,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CACxB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE;YACxD,iBAAiB,CAAC,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CACzD,CAAC;QACF,IAAI,KAAK,EAAE,CAAC;YACV,QAAQ,CAAC,IAAI,CACX,yBAAyB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,OAAO,QAAQ,CAAC,MAAM,IAAI,SAAS,EAAE,CACrG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,KAAY,EACZ,OAA0B,EAC1B,aAAgC,EAChC,OAAe;IAEf,MAAM,UAAU,GAAyB,EAAE,CAAC;IAE5C,IAAI,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,eAAe,EAAE,CAAC;QAC/C,2EAA2E;QAC3E,uEAAuE;QACvE,kEAAkE;QAClE,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,gBAAgB,EAAE,oBAAoB,IAAI,EAAE,CAAC;QAC9E,MAAM,YAAY,GAAG,CAAC,IAAY,EAAW,EAAE,CAC7C,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QACtE,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;YAChC,IAAI,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YACxE,UAAU,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,IAAI,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC;QAChD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,qEAAqE;YACrE,sEAAsE;YACtE,uEAAuE;YACvE,sDAAsD;YACtD,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,GAAG,GAAG;gBAAE,SAAS;YAC/D,IAAI,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC;gBAAE,SAAS;YACzC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAC3B,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE;gBACjD,iBAAiB,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,CAClD,CAAC;YACF,IAAI,CAAC,OAAO;gBAAE,SAAS;YACvB,UAAU,CAAC,IAAI,CAAC;gBACd,SAAS,EAAE,kBAAkB;gBAC7B,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,MAAM,IAAI,SAAS,EAAE;aAC3D,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/replayer/resolve.d.ts

@@ -0,0 +1,35 @@
+import type { Locator, Page } from 'playwright';
+import type { Target } from '../ir/schema.js';
+export interface ResolveTimeouts {
+    /** The recorded best guess deserves a real chance before we move on. */
+    first: number;
+    /** Fallbacks are cheap probes; a long timeout here just burns wall-clock. */
+    subsequent: number;
+}
+export declare const DEFAULT_RESOLVE_TIMEOUTS: ResolveTimeouts;
+export interface Resolved {
+    locator: Locator;
+    selector: string;
+    /** Index into target.candidates, so callers can report degraded resolution. */
+    candidateIndex: number;
+}
+export declare class TargetResolutionError extends Error {
+    readonly target: Target;
+    readonly attempts: {
+        selector: string;
+        error: string;
+    }[];
+    constructor(target: Target, attempts: {
+        selector: string;
+        error: string;
+    }[]);
+}
+/**
+ * Try each recorded selector in priority order. Phase 0 deliberately does NOT
+ * heal: exhausting the candidates is a hard failure, reported with the semantic
+ * description so a human knows what the step meant.
+ *
+ * `onExhausted` is the seam Phase 1's LLM re-grounding plugs into — it may
+ * return a replacement selector, and the caller patches the IR.
+ */
+export declare function resolveTarget(page: Page, target: Target, timeouts?: ResolveTimeouts, onExhausted?: (target: Target, page: Page) => Promise<string | null>): Promise<Resolved>;

package/dist/replayer/resolve.js

@@ -0,0 +1,50 @@
+export const DEFAULT_RESOLVE_TIMEOUTS = { first: 800, subsequent: 400 };
+export class TargetResolutionError extends Error {
+    target;
+    attempts;
+    constructor(target, attempts) {
+        super(`Could not find ${target.semantic}`);
+        this.target = target;
+        this.attempts = attempts;
+        this.name = 'TargetResolutionError';
+    }
+}
+/**
+ * Try each recorded selector in priority order. Phase 0 deliberately does NOT
+ * heal: exhausting the candidates is a hard failure, reported with the semantic
+ * description so a human knows what the step meant.
+ *
+ * `onExhausted` is the seam Phase 1's LLM re-grounding plugs into — it may
+ * return a replacement selector, and the caller patches the IR.
+ */
+export async function resolveTarget(page, target, timeouts = DEFAULT_RESOLVE_TIMEOUTS, onExhausted) {
+    const attempts = [];
+    for (let i = 0; i < target.candidates.length; i++) {
+        const selector = target.candidates[i];
+        if (!selector)
+            continue;
+        const timeout = i === 0 ? timeouts.first : timeouts.subsequent;
+        try {
+            const locator = page.locator(selector).first();
+            await locator.waitFor({ state: 'visible', timeout });
+            return { locator, selector, candidateIndex: i };
+        }
+        catch (err) {
+            attempts.push({ selector, error: firstLine(err) });
+        }
+    }
+    if (onExhausted) {
+        const healed = await onExhausted(target, page);
+        if (healed) {
+            const locator = page.locator(healed).first();
+            await locator.waitFor({ state: 'visible', timeout: timeouts.first });
+            return { locator, selector: healed, candidateIndex: -1 };
+        }
+    }
+    throw new TargetResolutionError(target, attempts);
+}
+function firstLine(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.split('\n')[0] ?? msg;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/replayer/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/replayer/resolve.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,wBAAwB,GAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;AASzF,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAEnC;IACA;IAFX,YACW,MAAc,EACd,QAA+C;QAExD,KAAK,CAAC,kBAAkB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAHlC,WAAM,GAAN,MAAM,CAAQ;QACd,aAAQ,GAAR,QAAQ,CAAuC;QAGxD,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAU,EACV,MAAc,EACd,WAA4B,wBAAwB,EACpD,WAAoE;IAEpE,MAAM,QAAQ,GAA0C,EAAE,CAAC;IAE3D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ;YAAE,SAAS;QACxB,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC/D,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,CAAC;YAC/C,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;YACrD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC;QAClD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC/C,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;YAC7C,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;YACrE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,EAAE,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,MAAM,IAAI,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,SAAS,CAAC,GAAY;IAC7B,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;AACnC,CAAC"}

package/dist/replayer/run.d.ts

@@ -0,0 +1,104 @@
+import type { Browser, Page } from 'playwright';
+import type { Repro, Target } from '../ir/schema.js';
+import { type WrittenArtifacts } from './artifacts.js';
+import { type InvariantViolation } from './invariants.js';
+import { type ResolveTimeouts } from './resolve.js';
+export interface StepTiming {
+    id: string;
+    action: string;
+    semantic: string;
+    /** Time to resolve the target and perform the action. */
+    actMs: number;
+    /** Time spent waiting for the recorded reaction. */
+    waitMs: number;
+    totalMs: number;
+    /** >0 means the preferred selector failed and a fallback was used. */
+    candidateIndex: number;
+}
+export interface RunFailure {
+    stepId: string;
+    stepIndex: number;
+    semantic: string;
+    expected: string;
+    observed: string;
+    /**
+     * `assertion` — the app was driven successfully and the verdict is about the
+     * bug. `infrastructure` — the harness could not drive the app at all, so it
+     * says nothing about whether the bug is fixed. Reporting the second as
+     * "NOT FIXED" sends people chasing a bug they already fixed.
+     */
+    kind: 'assertion' | 'infrastructure';
+    artifacts: WrittenArtifacts | null;
+}
+export interface RunResult {
+    name: string;
+    passed: boolean;
+    durationMs: number;
+    /** Total steps in the IR — `timings` only covers the ones that ran. */
+    totalSteps: number;
+    /** Which polarity this run asserted. */
+    expectFixed: boolean;
+    /** Non-fatal observations, e.g. reactions that changed after a fix. */
+    notes: string[];
+    /** Path to the end-state screenshot, when one was requested. */
+    finalScreenshot: string | null;
+    timings: StepTiming[];
+    failure: RunFailure | null;
+    invariantViolations: InvariantViolation[];
+}
+export interface RunOptions {
+    headed?: boolean;
+    baseUrl?: string;
+    root?: string;
+    resolveTimeouts?: ResolveTimeouts;
+    /**
+     * Capture the end state even when the run passes.
+     *
+     * The CLI leaves this off to stay fast. The MCP server turns it on: its whole
+     * job is to hand the browser's visual state to a model, and "it passed" is a
+     * far weaker signal to a reader than seeing the resulting page.
+     */
+    captureFinalScreenshot?: boolean;
+    /**
+     * Verification mode: pass when the flow still walks and the recorded bug
+     * does NOT happen again.
+     *
+     * The default polarity asserts the opposite — that the bug still reproduces —
+     * which is what you want to confirm a fresh repro is sound, but backwards
+     * while you are fixing something. Under --expect-fixed a step's recorded
+     * reaction becomes a note rather than a failure: after a real fix the app is
+     * *supposed* to react differently.
+     */
+    expectFixed?: boolean;
+    /**
+     * Called when every selector candidate for a step failed. Returning a
+     * selector lets replay continue — the seam for Phase 1's LLM re-grounding.
+     * Phase 0 never supplies one.
+     */
+    onStepFailure?: (target: Target, page: Page) => Promise<string | null>;
+    /** Replay against a persistent Chromium profile (e.g. to reuse a login). */
+    profileDir?: string | null;
+    /**
+     * Multiply every recorded `waitAfter.timeoutMs`.
+     *
+     * Timeouts are derived from what the recording observed, which is wrong when
+     * replay runs somewhere slower than the machine that recorded — a cold dev
+     * server, CI, a heavier dataset. Without this the only fix was hand-editing
+     * every step in the IR.
+     */
+    timeoutScale?: number;
+    /**
+     * Reuse a running browser across runs. Saves the launch and, more usefully,
+     * keeps V8's code cache warm so a large app boots far faster on replay two
+     * onward. Each run still gets its own context.
+     */
+    browser?: Browser | null;
+    /**
+     * Shell command run before the browser opens, to reset state the flow mutates.
+     *
+     * Deliberately NOT a field in the IR: a repro file is something you download,
+     * hand-edit and share, and one that can execute commands is a liability.
+     */
+    setupCommand?: string | null;
+}
+export declare function runRepro(repro: Repro, options?: RunOptions): Promise<RunResult>;