@dikshanty94/webnav 0.2.0

package/dist/recorder/replay.js

@@ -0,0 +1,401 @@
+// The replay engine: plays back a recorded StoredActionEffect[] against a live adapter,
+// auto-paced or step-by-step, pausing for missing creds / commit confirmation / drift.
+// Deps injected (adapter/creds/sleep) so tests drive it with fakes — mirrors live-record.ts.
+import { mkdirSync, copyFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseSnapshot } from '../playwright/snapshot.js';
+import { resolveByFingerprint } from '../playwright/fingerprint.js';
+import { didNavigate } from '../explorer/diff.js';
+import { COMMIT_WORDS } from '../explorer/draft.js';
+import { resolveEvent, descriptorName } from './live.js';
+export class ReplayController {
+    state;
+    nextResolve = null;
+    waitResolve = null;
+    aborted = false;
+    constructor(session, labels) {
+        this.state = { session, running: true, mode: 'auto', waiting: null, done: false,
+            steps: labels.map((l) => ({ seq: l.seq, label: l.label, status: 'pending', shot: null })) };
+    }
+    control(action) {
+        if (action === 'pause') {
+            this.state.mode = 'step';
+            return true;
+        }
+        if (action === 'resume') {
+            this.state.mode = 'auto';
+            this.nextResolve?.();
+            this.nextResolve = null;
+            return true;
+        }
+        if (action === 'next') {
+            this.nextResolve?.();
+            this.nextResolve = null;
+            return true;
+        }
+        if (action === 'abort') {
+            this.aborted = true;
+            this.state.waiting = null;
+            this.state.waitingLabel = undefined;
+            this.nextResolve?.();
+            this.nextResolve = null;
+            this.waitResolve?.('abort');
+            this.waitResolve = null;
+            return true;
+        }
+        return false;
+    }
+    supply(value, save) {
+        if (this.state.waiting !== 'value' || !this.waitResolve)
+            return false;
+        this.state.waiting = null;
+        const r = this.waitResolve;
+        this.waitResolve = null;
+        r({ value, save });
+        return true;
+    }
+    confirm(fire) {
+        if (this.state.waiting !== 'confirm' || !this.waitResolve)
+            return false;
+        this.state.waiting = null;
+        const r = this.waitResolve;
+        this.waitResolve = null;
+        r({ fire });
+        return true;
+    }
+    async gate(sleep, paceMs) {
+        if (this.aborted)
+            return 'abort';
+        if (this.state.mode === 'auto') {
+            await sleep(paceMs);
+            return this.aborted ? 'abort' : 'go';
+        }
+        await new Promise((r) => { this.nextResolve = r; });
+        return this.aborted ? 'abort' : 'go';
+    }
+    waitFor(kind, label) {
+        this.state.waiting = kind;
+        this.state.waitingLabel = label;
+        return new Promise((r) => { this.waitResolve = r; });
+    }
+}
+const normName = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Best-effort screenshot copy — decoration only, never fails the step. */
+function saveShot(shotsDir, src, seq) {
+    const name = `step-${seq}.png`;
+    try {
+        mkdirSync(shotsDir, { recursive: true });
+        copyFileSync(src, join(shotsDir, name));
+        return name;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runReplay(effects, ctl, deps) {
+    const sleep = deps.sleep ?? realSleep;
+    const paceMs = deps.paceMs ?? 1500;
+    const st = ctl.state;
+    const skipRest = (from) => {
+        for (let j = from; j < st.steps.length; j++) {
+            if (st.steps[j].status === 'running' || st.steps[j].status === 'pending')
+                st.steps[j].status = 'skipped';
+        }
+    };
+    try {
+        if (effects.length === 0) {
+            st.done = true;
+            st.running = false;
+            return st;
+        }
+        await deps.adapter.open(effects[0].fromUrl);
+        for (let i = 0; i < effects.length; i++) {
+            const e = effects[i];
+            const step = st.steps[i];
+            step.status = 'running';
+            const g = await ctl.gate(sleep, paceMs);
+            if (g === 'abort') {
+                skipRest(i);
+                break;
+            }
+            if (e.action === null) {
+                if (e.navigated) {
+                    await deps.adapter.goto(e.toUrl);
+                    step.status = 'jumped';
+                }
+                else {
+                    step.status = 'skipped';
+                }
+                continue; // no gate/screenshot for skipped/jumped null-action steps
+            }
+            const action = e.action;
+            let ref = action.ref ?? null;
+            let abortedHere = false;
+            if (action.elementFp) {
+                // Resolve with ONE human-assisted retry (plan semantics): the first miss pauses
+                // (step mode) so the human can fix the live page — dismiss a popup, let a render
+                // settle — and hit Next, which re-resolves THIS step. A second miss is final.
+                for (let attempt = 0; attempt < 2; attempt++) {
+                    const nodes = parseSnapshot(await deps.adapter.snapshot());
+                    ref = resolveByFingerprint(action.elementFp, nodes);
+                    if (ref || attempt === 1)
+                        break;
+                    step.status = 'fail';
+                    step.note = 'element not found — Next retries once';
+                    ctl.control('pause');
+                    const g2 = await ctl.gate(sleep, paceMs);
+                    if (g2 === 'abort') {
+                        abortedHere = true;
+                        break;
+                    }
+                    step.status = 'running';
+                    step.note = undefined;
+                }
+            }
+            if (abortedHere) {
+                skipRest(i);
+                break;
+            }
+            if (!ref) {
+                step.status = 'fail';
+                step.note = 'element not found';
+                ctl.control('pause');
+                continue;
+            }
+            if (action.role === 'textbox') {
+                const wantKey = normName(action.name ?? '');
+                const creds = deps.creds.get(deps.site);
+                let value;
+                for (const [k, v] of Object.entries(creds)) {
+                    if (normName(k) === wantKey) {
+                        value = v;
+                        break;
+                    }
+                }
+                // the RECORDED value is the flow's variable — use it when no stored cred
+                // overrides (creds are the operator's variable store; secrets were never
+                // recorded, so a password still asks unless creds cover it).
+                if (value === undefined && typeof action.value === 'string')
+                    value = action.value;
+                if (value === undefined) {
+                    const answer = await ctl.waitFor('value', action.name ?? step.label);
+                    if (answer === 'abort') {
+                        skipRest(i);
+                        break;
+                    }
+                    value = answer.value ?? '';
+                    if (answer.save)
+                        deps.creds.set(deps.site, { [wantKey]: value });
+                }
+                await deps.adapter.fill(ref, value);
+            }
+            else {
+                const label = action.name ?? step.label;
+                if (COMMIT_WORDS.test(label)) {
+                    const answer = await ctl.waitFor('confirm', label);
+                    if (answer === 'abort') {
+                        skipRest(i);
+                        break;
+                    }
+                    if (!answer.fire) {
+                        step.status = 'skipped';
+                        continue;
+                    }
+                }
+                await deps.adapter.click(ref);
+            }
+            if (e.navigated) {
+                const cur = await deps.adapter.currentUrl();
+                if (didNavigate(cur, e.toUrl)) {
+                    step.status = 'fail';
+                    step.note = 'landed elsewhere';
+                    ctl.control('pause');
+                    continue;
+                }
+            }
+            if (deps.shotsDir) {
+                const src = await deps.adapter.screenshot();
+                if (src)
+                    step.shot = saveShot(deps.shotsDir, src, e.seq);
+            }
+            step.status = 'ok';
+        }
+    }
+    catch (e) {
+        // Engine failure (browser would not open, adapter died mid-run): resolve with a
+        // terminal error state — a REJECTED replay promise killed the whole dashboard
+        // process once (unhandled rejection; live crash 2026-07-15). Never rethrow.
+        st.error = String(e.message ?? e);
+        skipRest(0);
+    }
+    finally {
+        st.done = true;
+        st.running = false;
+        await deps.adapter.close().catch(() => { }); // close on a never-opened session throws too
+    }
+    return st;
+}
+// --- Ledger replay: play the RAW event stream (including what assembly dropped) ---
+// "Exactly what was done, again": resolution is the SAME deterministic descriptor
+// matching recording used (resolveEvent) — never a stored selector, never a guess.
+// A capture miss replays as a visible failed step, so this runner doubles as a
+// capture-fidelity test (spec 2026-07-16).
+/** A ledger row as a resolvable LiveEvent: human rows ARE LiveEvents; agent rows
+ *  synthesize one from {role,name} (descriptorName reads ariaLabel first). */
+function asLiveEvent(e) {
+    const d = e.descriptor;
+    if (e.source === 'human')
+        return d;
+    return { seq: e.seq, kind: e.kind === 'type' ? 'input' : 'click', tagName: '',
+        url: String(d.url ?? ''), role: d.role ?? null,
+        ariaLabel: d.name ?? null, leafText: null, href: null,
+        placeholder: null, nameAttr: null, inputType: null };
+}
+/** The page URL an event acted on (agent navigate rows act FROM fromUrl). */
+function pageUrlOf(e) {
+    const d = e.descriptor;
+    return String((e.source === 'agent' && e.kind === 'navigate' ? d.fromUrl : d.url) ?? '');
+}
+export async function runLedgerReplay(events, ctl, deps) {
+    const sleep = deps.sleep ?? realSleep;
+    const paceMs = deps.paceMs ?? 1500;
+    const st = ctl.state;
+    const skipRest = (from) => {
+        for (let j = from; j < st.steps.length; j++) {
+            if (st.steps[j].status === 'running' || st.steps[j].status === 'pending')
+                st.steps[j].status = 'skipped';
+        }
+    };
+    try {
+        if (events.length === 0) {
+            return st;
+        }
+        const first = events[0];
+        await deps.adapter.open(first.source === 'agent' && first.kind === 'navigate'
+            ? String(first.descriptor.url) : pageUrlOf(first));
+        for (let i = 0; i < events.length; i++) {
+            const e = events[i];
+            const d = e.descriptor;
+            const step = st.steps[i];
+            step.status = 'running';
+            const g = await ctl.gate(sleep, paceMs);
+            if (g === 'abort') {
+                skipRest(i);
+                break;
+            }
+            // expected landing = the page the NEXT event acted on (judgment-free — the
+            // ledger's own urls encode the journey)
+            const nextUrl = i + 1 < events.length ? pageUrlOf(events[i + 1]) : null;
+            if (e.source === 'agent' && e.kind === 'navigate') {
+                await deps.adapter.goto(String(d.url));
+                step.status = 'jumped';
+                continue;
+            }
+            const lev = asLiveEvent(e);
+            // resolve with ONE human-assisted retry (same semantics as steps replay)
+            let ref = null;
+            let abortedHere = false;
+            for (let attempt = 0; attempt < 2; attempt++) {
+                const res = resolveEvent(lev, parseSnapshot(await deps.adapter.snapshot()));
+                ref = res && 'ref' in res ? res.ref : null; // candidates = ambiguous = no guess
+                if (ref || attempt === 1)
+                    break;
+                step.status = 'fail';
+                step.note = 'element not found — Next retries once';
+                ctl.control('pause');
+                const g2 = await ctl.gate(sleep, paceMs);
+                if (g2 === 'abort') {
+                    abortedHere = true;
+                    break;
+                }
+                step.status = 'running';
+                step.note = undefined;
+            }
+            if (abortedHere) {
+                skipRest(i);
+                break;
+            }
+            if (!ref) {
+                step.status = 'fail';
+                step.note = 'element not found';
+                ctl.control('pause');
+                continue;
+            }
+            const label = descriptorName(lev) ?? step.label;
+            if (e.kind === 'input' || e.kind === 'type') {
+                let value = typeof d.value === 'string' ? d.value : undefined; // human non-secret variable
+                if (value === undefined) {
+                    const wantKey = normName(label);
+                    for (const [k, v] of Object.entries(deps.creds.get(deps.site))) {
+                        if (normName(k) === wantKey) {
+                            value = v;
+                            break;
+                        }
+                    }
+                }
+                if (value === undefined) {
+                    const answer = await ctl.waitFor('value', label);
+                    if (answer === 'abort') {
+                        skipRest(i);
+                        break;
+                    }
+                    value = answer.value ?? '';
+                    if (answer.save)
+                        deps.creds.set(deps.site, { [normName(label)]: value });
+                }
+                await deps.adapter.fill(ref, value);
+            }
+            else if (e.kind === 'hover') {
+                await deps.adapter.hover(ref);
+            }
+            else {
+                if (COMMIT_WORDS.test(label)) {
+                    const answer = await ctl.waitFor('confirm', label);
+                    if (answer === 'abort') {
+                        skipRest(i);
+                        break;
+                    }
+                    if (!answer.fire) {
+                        step.status = 'skipped';
+                        continue;
+                    }
+                }
+                await deps.adapter.click(ref);
+            }
+            // inputs/hovers never navigate (assembleEffect's guarantee for input; hover is a
+            // same-page reveal) — a page change after one of these belongs to the FOLLOWING
+            // event, so skip the landing check here rather than false-failing this step.
+            if (nextUrl && e.kind !== 'input' && e.kind !== 'type' && e.kind !== 'hover' && didNavigate(pageUrlOf(e), nextUrl)) {
+                // bounded settle: a client-side redirect needs a beat before the url is real
+                let cur = await deps.adapter.currentUrl();
+                for (let w = 0; w < 3 && didNavigate(cur, nextUrl); w++) {
+                    await sleep(700);
+                    cur = await deps.adapter.currentUrl();
+                }
+                if (didNavigate(cur, nextUrl)) {
+                    step.status = 'fail';
+                    step.note = 'landed elsewhere';
+                    ctl.control('pause');
+                    continue;
+                }
+            }
+            if (deps.shotsDir) {
+                const src = await deps.adapter.screenshot();
+                if (src)
+                    step.shot = saveShot(deps.shotsDir, src, e.seq);
+            }
+            step.status = 'ok';
+        }
+    }
+    catch (e) {
+        st.error = String(e.message ?? e); // same never-reject contract as runReplay
+        skipRest(0);
+    }
+    finally {
+        st.done = true;
+        st.running = false;
+        await deps.adapter.close().catch(() => { });
+    }
+    return st;
+}

package/dist/recorder/review.d.ts

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process';
+import type { Coverage, LandingStructure } from './coverage.js';
+declare const run: typeof execFile.__promisify__;
+export interface ReviewStepInfo {
+    seq: number;
+    kind: string;
+    label: string;
+    value?: string;
+    capturedAt: number;
+}
+export interface ReviewFrame {
+    path: string;
+    atMs: number;
+}
+/** Parse ffmpeg showinfo stderr → the pts seconds of each selected frame (in order). */
+export declare function parseShowinfoTimes(stderr: string): number[];
+/** The audit task — shown to the operator in the dashboard and editable per run.
+ *  This is the GOAL: compare the video (frames) against the captured steps and
+ *  surface CAPTURE GAPS — visible changes with no recorded step. */
+export declare const DEFAULT_INSTRUCTIONS = "Your job \u2014 compare what the video SHOWS against what was CAPTURED:\n1. For each frame, say what user action most likely produced that screen state.\n2. CAPTURE GAPS: visible changes in the frames with NO captured step near that\n   timestamp (\u00B15s). These are recorder misses \u2014 the deliverable. Be specific:\n   what happened on screen, when, and what kind of event the recorder should\n   have caught (click / input / navigation / scroll / hover-menu ...).\n3. Steps with no visual correlate in any frame (possible over-capture or noise).\n4. A short verdict: is this recording complete enough to replay the user's\n   journey? What single capture improvement would help most?\n\nFormat as markdown with sections: Frames, Capture gaps, Uncorrelated steps, Verdict.\nBe concrete and terse. If the evidence is thin (few frames/steps), say so honestly.";
+export interface CaptureGap {
+    atMs?: number;
+    kind?: string;
+    whatHappened?: string;
+    shouldHaveCaptured?: string;
+}
+/** Tolerant extraction of the gap JSON from a review reply (may be wrapped in
+ *  prose/markdown). Returns [] on absence/parse failure (never throws). */
+export declare function parseGaps(text: string): CaptureGap[];
+/** The audit prompt. Pure — unit-tested; the spawn stays thin. */
+export declare function buildReviewPrompt(session: string, steps: ReviewStepInfo[], logLines: {
+    t: number;
+    line: string;
+}[], frames: ReviewFrame[], instructions?: string, structured?: boolean, knownDrops?: Coverage['dropped'], structure?: LandingStructure[]): string;
+export interface ReviewDeps {
+    videosDir: string;
+    outDir: string;
+    steps: ReviewStepInfo[];
+    logs: {
+        t: number;
+        line: string;
+    }[];
+    log: (line: string) => void;
+    claudeModel?: string;
+    instructions?: string;
+    maxFrames?: number;
+    structured?: boolean;
+    knownDrops?: Coverage['dropped'];
+    coverage?: Coverage;
+    structure?: LandingStructure[];
+    exec?: typeof run;
+}
+/** Extract scene-change frames from one take. Returns frames with ABSOLUTE wall-clock
+ *  times. The ts in take-<ts>.webm is the STOP/SAVE time (Date.now() at videoStop),
+ *  NOT the start — so the true start is reconstructed as stop − ffprobe duration,
+ *  and each frame's time is that true start + its pts offset. */
+/** The frame-selection expression. Web-UI tuned (live finding: a 10-min browsing
+ *  take yielded 4 frames at scene>0.08 — movie-cut thresholds miss typing/menus/
+ *  scroll): >2% change counts, a min-gap rate-limits bursts (a playing video would
+ *  otherwise eat the whole frame budget in seconds), and a HEARTBEAT guarantees
+ *  one frame per interval across the entire timeline even when nothing trips the
+ *  threshold — full coverage for the gap audit. Pure: unit-tested. */
+export declare function frameSelectExpr(durationS: number, maxFrames: number): {
+    expr: string;
+    minGapS: number;
+    heartbeatS: number;
+};
+export declare function extractFrames(takePath: string, takeStopMs: number, framesDir: string, maxFrames: number, exec: typeof run): Promise<ReviewFrame[]>;
+export declare function runSessionReview(session: string, deps: ReviewDeps): Promise<string | {
+    report: string;
+    gaps: CaptureGap[];
+}>;
+export {};

package/dist/recorder/review.js

@@ -0,0 +1,171 @@
+// Session review: audit what the recorder CAPTURED against what the video SHOWS.
+// Pipeline: ffmpeg scene-detection extracts a compact FRAME STRIP from each video
+// take (Claude cannot ingest video — stills at change-moments are the consumable
+// form, and better for gap-finding since each frame carries a timestamp to match
+// against step times) → a headless `claude -p` (Sonnet, per user decision; this is
+// a judgment task OUTSIDE webnav's zero-LLM runtime — it audits the tool, it is
+// not part of navigation) reads steps+logs+frames and reports capture gaps.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const run = promisify(execFile);
+/** Parse ffmpeg showinfo stderr → the pts seconds of each selected frame (in order). */
+export function parseShowinfoTimes(stderr) {
+    const out = [];
+    for (const m of stderr.matchAll(/pts_time:([\d.]+)/g))
+        out.push(Number(m[1]));
+    return out;
+}
+/** The audit task — shown to the operator in the dashboard and editable per run.
+ *  This is the GOAL: compare the video (frames) against the captured steps and
+ *  surface CAPTURE GAPS — visible changes with no recorded step. */
+export const DEFAULT_INSTRUCTIONS = `Your job — compare what the video SHOWS against what was CAPTURED:
+1. For each frame, say what user action most likely produced that screen state.
+2. CAPTURE GAPS: visible changes in the frames with NO captured step near that
+   timestamp (±5s). These are recorder misses — the deliverable. Be specific:
+   what happened on screen, when, and what kind of event the recorder should
+   have caught (click / input / navigation / scroll / hover-menu ...).
+3. Steps with no visual correlate in any frame (possible over-capture or noise).
+4. A short verdict: is this recording complete enough to replay the user's
+   journey? What single capture improvement would help most?
+
+Format as markdown with sections: Frames, Capture gaps, Uncorrelated steps, Verdict.
+Be concrete and terse. If the evidence is thin (few frames/steps), say so honestly.`;
+/** Append the structured-output instruction: return a JSON gap list the capture
+ *  loop can parse to judge convergence (zero gaps = complete). */
+const STRUCTURED_TAIL = `
+
+OUTPUT FORMAT (STRICT): after any brief reasoning, end your reply with ONE JSON
+object on its own, exactly:
+{"gaps":[{"atMs":<frame time ms>,"kind":"click|input|navigation|scroll|hover-menu|other","whatHappened":"...","shouldHaveCaptured":"..."}],"verdict":"..."}
+A gap = a visible change in the frames with NO captured step within ±5s. If capture
+is complete, return {"gaps":[],"verdict":"complete"}. Emit NOTHING after the JSON.`;
+/** Tolerant extraction of the gap JSON from a review reply (may be wrapped in
+ *  prose/markdown). Returns [] on absence/parse failure (never throws). */
+export function parseGaps(text) {
+    // last {...} block that parses and has a `gaps` array wins (the model ends with it)
+    const matches = text.match(/\{[\s\S]*\}/g);
+    if (!matches)
+        return [];
+    for (let i = matches.length - 1; i >= 0; i--) {
+        try {
+            const o = JSON.parse(matches[i]);
+            if (Array.isArray(o.gaps))
+                return o.gaps;
+        }
+        catch { /* try the next candidate */ }
+    }
+    return [];
+}
+/** The audit prompt. Pure — unit-tested; the spawn stays thin. */
+export function buildReviewPrompt(session, steps, logLines, frames, instructions, structured, knownDrops, structure) {
+    const t = (ms) => new Date(ms).toLocaleTimeString();
+    const stepTxt = steps.length
+        ? steps.map((s) => `- [${t(s.capturedAt)}] seq ${s.seq} ${s.kind}: ${s.label}${s.value !== undefined ? ` = "${s.value}"` : ''}`).join('\n')
+        : '(no steps captured)';
+    const logTxt = logLines.map((l) => `- [${t(l.t)}] ${l.line}`).join('\n') || '(no logs)';
+    const frameTxt = frames.map((f, i) => `- frame ${i + 1} at ${t(f.atMs)}: ${f.path}`).join('\n') || '(no frames extracted)';
+    const dropTxt = knownDrops?.length
+        ? `\nASSEMBLY DROPS (already known — measured deterministically; do NOT re-report these as gaps):\n${knownDrops.map((d) => `- seq ${d.seq} ${d.kind}: ${d.label ?? '(unlabeled)'} — ${d.reason}`).join('\n')}\n`
+        : '';
+    const structureTxt = structure?.length
+        ? `\nLANDING STRUCTURE (named vs NAMELESS interactive controls per page — many nameless controls = a sensor gap; compare against what the frames show):\n${structure.map((s) => `- ${s.url} — named: ${s.named}, nameless: ${s.nameless}`).join('\n')}\n`
+        : '';
+    return `You are auditing a browser-session RECORDER for capture gaps. A human browsed a website
+while our tool recorded their actions as "steps". We also have a screen video of the same
+session, from which scene-change frames were extracted (one image per visible change,
+each with its wall-clock timestamp).
+
+Session: ${session}
+
+CAPTURED STEPS (what our recorder saved):
+${stepTxt}
+
+RECORDER LOGS (including honest skips):
+${logTxt}
+
+VIDEO FRAMES (visible changes; READ each image file with the Read tool):
+${frameTxt}
+${dropTxt}${structureTxt}
+${instructions ?? DEFAULT_INSTRUCTIONS}${structured ? STRUCTURED_TAIL : ''}`;
+}
+/** Extract scene-change frames from one take. Returns frames with ABSOLUTE wall-clock
+ *  times. The ts in take-<ts>.webm is the STOP/SAVE time (Date.now() at videoStop),
+ *  NOT the start — so the true start is reconstructed as stop − ffprobe duration,
+ *  and each frame's time is that true start + its pts offset. */
+/** The frame-selection expression. Web-UI tuned (live finding: a 10-min browsing
+ *  take yielded 4 frames at scene>0.08 — movie-cut thresholds miss typing/menus/
+ *  scroll): >2% change counts, a min-gap rate-limits bursts (a playing video would
+ *  otherwise eat the whole frame budget in seconds), and a HEARTBEAT guarantees
+ *  one frame per interval across the entire timeline even when nothing trips the
+ *  threshold — full coverage for the gap audit. Pure: unit-tested. */
+export function frameSelectExpr(durationS, maxFrames) {
+    // budget ~25% of frames for scene-changes so bursts can't cut off tail coverage
+    const heartbeatS = Math.max(5, Math.ceil(durationS / Math.max(1, Math.floor(maxFrames * 0.75))));
+    const minGapS = Math.max(2, Math.floor(heartbeatS / 3));
+    const expr = `isnan(prev_selected_t)+(gt(scene\,0.02)+gte(t-prev_selected_t\,${heartbeatS}))*gte(t-prev_selected_t\,${minGapS})`;
+    return { expr, minGapS, heartbeatS };
+}
+export async function extractFrames(takePath, takeStopMs, framesDir, maxFrames, exec) {
+    mkdirSync(framesDir, { recursive: true });
+    let durationS = 0;
+    try {
+        const pr = await exec('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', takePath]);
+        durationS = Number(String(pr.stdout).trim()) || 0;
+    }
+    catch { /* unknown duration → trueStartMs falls back to takeStopMs (uncorrected, no worse than before) */ }
+    const trueStartMs = takeStopMs - Math.round(durationS * 1000);
+    const { expr } = frameSelectExpr(durationS, maxFrames);
+    const vf = `select='${expr}',showinfo,scale=800:-2`;
+    let stderr = '';
+    try {
+        const r = await exec('ffmpeg', ['-y', '-i', takePath, '-vf', vf, '-fps_mode', 'vfr',
+            '-frames:v', String(maxFrames), join(framesDir, 'f-%03d.png')], { maxBuffer: 32 * 1024 * 1024 });
+        stderr = r.stderr ?? '';
+    }
+    catch (e) {
+        // ffmpeg exits non-zero on some streams even after writing frames — keep what landed
+        stderr = e.stderr ?? '';
+    }
+    const times = parseShowinfoTimes(stderr);
+    const files = readdirSync(framesDir).filter((f) => f.endsWith('.png')).sort();
+    return files.map((f, i) => ({ path: join(framesDir, f), atMs: trueStartMs + Math.round((times[i] ?? 0) * 1000) }));
+}
+export async function runSessionReview(session, deps) {
+    const exec = deps.exec ?? run;
+    const maxFrames = deps.maxFrames ?? 20;
+    deps.log(`review: extracting frames for ${session}…`);
+    let takes = [];
+    try {
+        takes = readdirSync(deps.videosDir).filter((f) => f.endsWith('.webm')).sort();
+    }
+    catch { /* no videos */ }
+    const frames = [];
+    for (const take of takes) {
+        const stopMs = Number((/take-(\d+)\.webm/.exec(take) ?? [])[1] ?? 0);
+        const dir = join(deps.outDir, 'frames-' + take.replace(/\.webm$/, ''));
+        const got = await extractFrames(join(deps.videosDir, take), stopMs, dir, maxFrames, exec);
+        frames.push(...got);
+        deps.log(`review: ${got.length} change-frames from ${take}`);
+    }
+    const prompt = buildReviewPrompt(session, deps.steps, deps.logs, frames, deps.instructions, deps.structured, deps.knownDrops, deps.structure);
+    deps.log(`review: asking Claude (${deps.claudeModel ?? 'sonnet'}) — ${frames.length} frames, ${deps.steps.length} steps…`);
+    let report;
+    try {
+        const { stdout } = await exec('claude', ['-p', prompt, '--model', deps.claudeModel ?? 'sonnet', '--allowedTools', 'Read'], { maxBuffer: 32 * 1024 * 1024, timeout: 5 * 60_000 });
+        report = stdout.trim() || '(claude returned no output)';
+    }
+    catch (e) {
+        report = 'REVIEW FAILED: ' + String(e.message ?? e);
+    }
+    mkdirSync(deps.outDir, { recursive: true });
+    writeFileSync(join(deps.outDir, 'review.md'), report);
+    deps.log('review: done — report saved');
+    if (deps.structured) {
+        const gaps = parseGaps(report);
+        writeFileSync(join(deps.outDir, 'review.json'), JSON.stringify({ gaps, coverage: deps.coverage ?? null, structure: deps.structure ?? null }, null, 2));
+        return { report, gaps };
+    }
+    return report;
+}

package/dist/recorder/snapshot-dom.d.ts

@@ -0,0 +1,7 @@
+export interface SerializableNode {
+    role: string;
+    name: string | null;
+    url?: string | null;
+    children?: SerializableNode[];
+}
+export declare function serializeSnapshot(root: SerializableNode): string;

package/dist/recorder/snapshot-dom.js

@@ -0,0 +1,25 @@
+// src/recorder/snapshot-dom.ts
+// Serialize an accessibility tree to the playwright-parity snapshot text that
+// src/playwright/snapshot.ts::parseSnapshot reads. Pure + deterministic; the
+// in-repo test oracle for the extension's browser-side twin.
+// TWIN of webnav-extension/serialize.ts::serialize — MUST stay in sync (same
+// ~15-line algorithm, duplicated deliberately; see the ponytail note there).
+// Assign a sequential synthetic ref (e1, e2, …) to EVERY node in pre-order, so
+// even nameless icon nodes carry a bracketed attr and survive parseSnapshot
+// (which drops a line that has neither a quoted name nor a [attr]).
+export function serializeSnapshot(root) {
+    const lines = [];
+    let counter = 0;
+    const walk = (node, depth) => {
+        const ref = `e${++counter}`;
+        const indent = '  '.repeat(depth);
+        const namePart = node.name !== null ? ` "${node.name}"` : '';
+        lines.push(`${indent}${node.role}${namePart} [ref=${ref}]`);
+        if (node.url)
+            lines.push(`${indent}  /url: ${node.url}`);
+        for (const child of node.children ?? [])
+            walk(child, depth + 1);
+    };
+    walk(root, 0);
+    return lines.join('\n');
+}