@dikshanty94/webnav 0.2.0

package/dist/recorder/hover-probe.js

@@ -0,0 +1,100 @@
+// X2 — hover / right-click reveal probe (spec 2026-07-16 §2). A hover mega-menu or a
+// context menu appears in NO settled snapshot and declares no trigger, so the map
+// honestly omits a site's primary nav. This opt-in pass, over the CURRENT page of a
+// live recording session, hovers (or right-clicks) each STRUCTURAL candidate, diffs
+// the reveal, and records an ActionEffect the draft already turns into a reveal
+// affordance (draftFromEffects is diff-driven — the `hover`/`rightClick` markers only
+// name the kind; the reveal decision is behavioral).
+//
+// REVEAL ONLY: the probe never clicks anything INSIDE a revealed menu (commit rule #2).
+import { parseSnapshot } from '../playwright/snapshot.js';
+import { diffSnapshots } from '../explorer/diff.js';
+import { settleSnapshot } from '../router/browse.js';
+// Landmark roles whose named interactive descendants are primary-nav triggers worth probing.
+const LANDMARK_ROLES = new Set(['banner', 'navigation']);
+// Roles that are a real interactive control (so "named interactive inside a landmark" is honest).
+const INTERACTIVE_ROLES = new Set(['button', 'link', 'menuitem', 'tab', 'combobox', 'checkbox', 'radio', 'switch']);
+const HASPOPUP_RE = /\[aria-haspopup(?:=|\])/;
+// Nearest-lower-depth ancestor walk (the insideOverlay idiom in infer.ts): is node `idx`
+// inside a banner/navigation landmark subtree? Depth = leading-space count, so an ancestor
+// is any earlier node at a strictly smaller depth.
+function insideLandmark(nodes, idx) {
+    let cur = nodes[idx].depth;
+    for (let i = idx - 1; i >= 0; i--) {
+        if (nodes[i].depth < cur) {
+            if (LANDMARK_ROLES.has(nodes[i].role))
+                return true;
+            cur = nodes[i].depth;
+        }
+    }
+    return false;
+}
+/** STRUCTURAL, judgment-free candidate selection: nodes with aria-haspopup, menuitems, and
+ *  named interactive nodes inside a banner/navigation landmark. Requires a ref (can only hover
+ *  a resolvable element), deduped by ref, capped (default 12). Zero cost on a page with none. */
+export function hoverCandidates(nodes, limit = 12) {
+    const out = [];
+    const seen = new Set();
+    for (let i = 0; i < nodes.length; i++) {
+        const n = nodes[i];
+        if (!n.ref || seen.has(n.ref))
+            continue;
+        const isCandidate = HASPOPUP_RE.test(n.raw) // declares a popup
+            || n.role === 'menuitem' // a menu entry (may open a submenu)
+            || (!!n.name && INTERACTIVE_ROLES.has(n.role) && insideLandmark(nodes, i)); // primary-nav trigger
+        if (!isCandidate)
+            continue;
+        seen.add(n.ref);
+        out.push(n);
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+/** Probe the CURRENT page: per candidate, take a baseline snapshot, hover (or right-click),
+ *  settle, diff; a non-empty ADDED diff records a reveal effect + a ledger event. Between
+ *  candidates we press Escape to dismiss the just-opened overlay so reveals don't stack
+ *  (Escape is the honest neutralizer — a re-hover of some "neutral" node is itself a guess
+ *  at what's neutral; Escape closes menus/popovers without moving the pointer anywhere real). */
+export async function runHoverProbe(deps) {
+    const { adapter, store, sessionId, rightClick, log } = deps;
+    const baseline = await adapter.snapshot();
+    const url = await adapter.currentUrl();
+    const candidates = hoverCandidates(parseSnapshot(baseline), deps.limit);
+    const kind = rightClick ? 'right-click' : 'hover';
+    log(`${kind}-probe: ${candidates.length} candidate(s) on ${url}`);
+    let revealed = 0;
+    for (const c of candidates) {
+        const ref = c.ref;
+        // Ledger the intent BEFORE acting (same discipline as the agent-session hover branch):
+        // a probe that fails to reveal still leaves an honest trace of what we tried.
+        const led = store.appendEvent(sessionId, {
+            source: 'agent', kind,
+            descriptor: { cmd: kind, ref, role: c.role, name: c.name, url },
+        });
+        const from = await adapter.snapshot(); // re-baseline per candidate (a prior Escape may have changed the page)
+        if (rightClick)
+            await adapter.rightClick(ref);
+        else
+            await adapter.hover(ref);
+        const to = await settleSnapshot(() => adapter.snapshot());
+        const diff = diffSnapshots(parseSnapshot(from), parseSnapshot(to));
+        if (diff.added.length > 0) {
+            const action = { role: c.role, name: c.name, ref, ...(rightClick ? { rightClick: true } : { hover: true }) };
+            const seq = store.appendActionEffect(sessionId, {
+                fromUrl: url, fromSnapshot: from, action, toUrl: url, toSnapshot: to, navigated: false, diff,
+            });
+            if (led != null && seq != null)
+                store.stampEvent(sessionId, led, 'step:' + seq);
+            revealed++;
+            log(`  ${kind} ${c.name ?? ref}: +${diff.added.length} node(s) → reveal`);
+        }
+        else {
+            // honest no-op: a candidate that reveals nothing records no affordance.
+            if (led != null)
+                store.stampEvent(sessionId, led, 'dropped:no-reveal');
+        }
+        await adapter.press('Escape').catch(() => { }); // neutralize so the next candidate's diff is clean
+    }
+    return { probed: candidates.length, revealed };
+}

package/dist/recorder/ingest.d.ts

@@ -0,0 +1,39 @@
+import http from 'node:http';
+import { type SnapNode } from '../playwright/snapshot.js';
+import { type AXNode } from '../playwright/ax-adapter.js';
+import type { ActionEffect } from '../mapstore/record.js';
+import { RecordStore } from '../mapstore/record.js';
+export interface RawStep {
+    fromUrl: string;
+    fromSnapshot: string;
+    toUrl: string;
+    toSnapshot: string;
+    ref: string | null;
+    navigated?: boolean;
+}
+export interface IngestBody {
+    sessionId: string;
+    steps: RawStep[];
+}
+export interface RawAXStep {
+    fromUrl: string;
+    fromAX: AXNode[];
+    toUrl: string;
+    toAX: AXNode[];
+    clickedRef?: string | null;
+    tMs?: number;
+}
+export interface IngestAXBody {
+    sessionId: string;
+    steps: RawAXStep[];
+}
+/** Shared reconstruction core: fingerprint the clicked node + diff the landing,
+ *  independent of what produced the SnapNode[] (playwright YAML or adapted AX).
+ *  NOTE: do not add exact-string URL equality here — CDP gives browser-resolved
+ *  absolute URLs, playwright gives raw hrefs; didNavigate already compares
+ *  host+pathname only, which both producers satisfy. */
+export declare function reconstructEffectFromNodes(fromNodes: SnapNode[], toNodes: SnapNode[], fromUrl: string, toUrl: string, clickedRef: string | null): ActionEffect;
+export declare function reconstructEffect(step: RawStep): ActionEffect;
+export declare function ingest(body: IngestBody, store: RecordStore): number;
+export declare function ingestAX(body: IngestAXBody, store: RecordStore): number;
+export declare function serveIngest(port: number, store: RecordStore): http.Server;

package/dist/recorder/ingest.js

@@ -0,0 +1,138 @@
+// Server-side ingest: turn raw recorded browser steps into stored ActionEffects.
+// The extension stays dumb — fingerprint + diff are reconstructed here from the
+// snapshots, reusing tested code (recoverFingerprint, diffSnapshots).
+import http from 'node:http';
+import { parseSnapshot } from '../playwright/snapshot.js';
+import { recoverFingerprint } from '../playwright/fingerprint.js';
+import { diffSnapshots, didNavigate } from '../explorer/diff.js';
+import { adaptAXTree } from '../playwright/ax-adapter.js';
+/** SnapNode[] → playwright-ish snapshot text, using each node's own `.raw` line
+ *  re-indented by `.depth`. This is the inverse of parseSnapshot, so AX-sourced
+ *  effects store the same text format DOM-walk effects do (draft.ts/coverage.ts
+ *  re-parse fromSnapshot/toSnapshot downstream regardless of producer). */
+function serializeNodes(nodes) {
+    return nodes.map((n) => ' '.repeat(n.depth) + n.raw).join('\n');
+}
+/** Shared reconstruction core: fingerprint the clicked node + diff the landing,
+ *  independent of what produced the SnapNode[] (playwright YAML or adapted AX).
+ *  NOTE: do not add exact-string URL equality here — CDP gives browser-resolved
+ *  absolute URLs, playwright gives raw hrefs; didNavigate already compares
+ *  host+pathname only, which both producers satisfy. */
+export function reconstructEffectFromNodes(fromNodes, toNodes, fromUrl, toUrl, clickedRef) {
+    let action = null;
+    if (clickedRef) {
+        const node = fromNodes.find((n) => n.ref === clickedRef) ?? null;
+        action = {
+            role: node?.role ?? '', name: node?.name ?? null, ref: clickedRef,
+            elementFp: recoverFingerprint(fromNodes, clickedRef),
+        };
+    }
+    return {
+        fromUrl, fromSnapshot: serializeNodes(fromNodes),
+        action,
+        toUrl, toSnapshot: serializeNodes(toNodes),
+        navigated: didNavigate(fromUrl, toUrl),
+        diff: diffSnapshots(fromNodes, toNodes),
+    };
+}
+export function reconstructEffect(step) {
+    const fromNodes = parseSnapshot(step.fromSnapshot);
+    const toNodes = parseSnapshot(step.toSnapshot);
+    const fx = reconstructEffectFromNodes(fromNodes, toNodes, step.fromUrl, step.toUrl, step.ref);
+    // parseSnapshot's own text is already canonical — keep the original bytes rather
+    // than the re-serialized (equivalent but not byte-identical) form.
+    return { ...fx, fromSnapshot: step.fromSnapshot, toSnapshot: step.toSnapshot };
+}
+export function ingest(body, store) {
+    store.clearSession(body.sessionId); // re-ingest into the same session replaces, never appends duplicates
+    store.start(body.sessionId);
+    let n = 0;
+    for (const step of body.steps) {
+        store.appendActionEffect(body.sessionId, reconstructEffect(step));
+        n++;
+    }
+    store.stop(body.sessionId);
+    return n;
+}
+export function ingestAX(body, store) {
+    store.clearSession(body.sessionId);
+    store.start(body.sessionId);
+    let n = 0;
+    for (const step of body.steps) {
+        const fromNodes = adaptAXTree(step.fromAX);
+        const toNodes = adaptAXTree(step.toAX);
+        const fx = reconstructEffectFromNodes(fromNodes, toNodes, step.fromUrl, step.toUrl, step.clickedRef ?? null);
+        // Per-step wall-clock time (from the extension). Without it every step got the single
+        // flush-time Date.now(), so the dashboard showed them all at the same second.
+        const tMs = step.tMs;
+        // Ledger event so the Raw pane isn't empty for extension runs: each recorded step IS
+        // one event, captured as a step (1:1, no drops in the AX path). kind = navigate when the
+        // step changed page, else action; descriptor carries the acted element's identity.
+        const kind = fx.navigated ? 'navigate' : 'action';
+        const descriptor = fx.action
+            ? { role: fx.action.role, name: fx.action.name, url: fx.toUrl }
+            : { url: fx.toUrl };
+        const evSeq = store.appendEvent(body.sessionId, { source: 'agent', kind, descriptor, t: tMs }, tMs);
+        const stepSeq = store.appendActionEffect(body.sessionId, fx, tMs);
+        if (evSeq != null && stepSeq != null)
+            store.stampEvent(body.sessionId, evSeq, 'step:' + stepSeq);
+        n++;
+    }
+    store.stop(body.sessionId);
+    return n;
+}
+// Localhost-only receiver: the webnav-extension Chrome extension POSTs recorded
+// steps here; they land in webnav.db as ActionEffects via `ingest`, identical
+// to agent-recorded ones. No auth — localhost-only, no secrets in transit
+// beyond the map itself.
+// note: this is still the live `webnav dev ingest` verb (src/cli.ts), a separate
+// surface from agent-serve's own /ingest-ax mount. Its only in-extension caller was
+// the Phase-1 popup, removed 2026-07-19 (see webnav-extension/README.md) — the
+// wildcard CORS here is unrelated to that removal and is left as-is (out of scope).
+export function serveIngest(port, store) {
+    const server = http.createServer((req, res) => {
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Headers', 'content-type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204).end();
+            return;
+        }
+        if (req.method !== 'POST' || (req.url !== '/ingest' && req.url !== '/ingest-ax')) {
+            res.writeHead(404).end();
+            return;
+        }
+        const isAX = req.url === '/ingest-ax';
+        let raw = '';
+        // ponytail: 50MB cap — bounds an unbounded body on this long-running receiver
+        // (precedent: dashboard/server.ts). Generous because a session carries full
+        // per-step page snapshots; raise if real recordings exceed it.
+        req.on('data', (c) => { raw += c; if (raw.length > 50_000_000)
+            req.destroy(); });
+        req.on('end', () => {
+            try {
+                if (isAX) {
+                    const body = JSON.parse(raw);
+                    if (!body.sessionId || !Array.isArray(body.steps))
+                        throw new Error('sessionId and steps[] required');
+                    const appended = ingestAX(body, store);
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true, appended }));
+                }
+                else {
+                    const body = JSON.parse(raw);
+                    if (!body.sessionId || !Array.isArray(body.steps))
+                        throw new Error('sessionId and steps[] required');
+                    const appended = ingest(body, store);
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true, appended }));
+                }
+            }
+            catch (e) {
+                res.writeHead(400, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: false, error: String(e) }));
+            }
+        });
+    });
+    server.listen(port, '127.0.0.1');
+    return server;
+}

package/dist/recorder/live-record.d.ts

@@ -0,0 +1,41 @@
+import type { ActionEffect } from '../mapstore/record.js';
+export interface LiveRecordDeps {
+    adapter: {
+        evalJs(f: string, ref?: string): Promise<string>;
+        snapshot(): Promise<string>;
+        currentUrl(): Promise<string>;
+        close(): Promise<unknown>;
+    };
+    store: {
+        isActive(s: string): boolean;
+        appendActionEffect(s: string, fx: ActionEffect, nowMs?: number): number | null;
+        appendEvent(s: string, ev: {
+            t?: number;
+            source: 'human' | 'agent';
+            kind: string;
+            descriptor: Record<string, unknown>;
+        }): number | null;
+        stampEvent(s: string, seq: number, disposition: string): void;
+        start(s: string): unknown;
+        stop(s: string): void;
+    };
+    sessionId: string;
+    intervalMs: number;
+    log: (line: string) => void;
+    isStopped: () => boolean;
+    sleep?: (ms: number) => Promise<void>;
+    tickExtras?: {
+        port?: number;
+        session?: string;
+    };
+    onEvent?: (type: 'step' | 'sessions') => void;
+    onToggle?: (recording: boolean) => void;
+    onEnd?: (reason: 'closed' | 'stopped') => void;
+    onBeforeClose?: () => Promise<void> | void;
+    browserAlive?: () => boolean;
+    armed?: boolean;
+}
+export declare function runLiveRecord(deps: LiveRecordDeps): Promise<{
+    appended: number;
+    ticks: number;
+}>;

package/dist/recorder/live-record.js

@@ -0,0 +1,255 @@
+// The live-record poll loop: drain the injected listener's queue, keep a rolling
+// buffer of REAL a11y snapshots, pair events to ticks, append ActionEffects.
+// Deps injected so tests drive it with a scripted fake adapter.
+//
+// TICK ECONOMY (live finding: every playwright-cli call is a child-process spawn,
+// ~300-500ms each, SERIALIZED through the daemon — several per tick made the overlay
+// lag seconds behind): a tick is currentUrl + ONE combined TICK_JS eval (install +
+// mode-paint + drain in a single JS turn); the EXPENSIVE snapshot runs only when
+// something happened (events drained / URL changed / pendings waiting / no baseline).
+import { TICK_JS, resolveEvent, fromTickFor, chooseToTick, assembleEffect, } from './live.js';
+import { parseSnapshot } from '../playwright/snapshot.js';
+import { parseEvalResult } from '../router/browse.js';
+import { classifyReadiness } from '../router/readiness.js';
+import { didNavigate, diffSnapshots } from '../explorer/diff.js';
+export async function runLiveRecord(deps) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const ticks = [];
+    const pending = [];
+    let appended = 0;
+    let errStreak = 0;
+    let undrainStreak = 0;
+    let endReason = 'stopped';
+    let sawRealPage = false;
+    let blankStreak = 0;
+    try {
+        while (!deps.isStopped() && (deps.armed ? true : deps.store.isActive(deps.sessionId))) {
+            if (deps.browserAlive && !deps.browserAlive()) {
+                deps.log('browser window closed — ending session');
+                endReason = 'closed';
+                break;
+            }
+            // 1. where are we? (cheap; also our browser-liveness probe)
+            let url;
+            try {
+                url = await deps.adapter.currentUrl();
+                // NOTE: do NOT reset errStreak here — currentUrl succeeding every tick while
+                // snapshot keeps throwing would pin the streak at 1 forever (found as a
+                // microtask-starved infinite loop that hung vitest unkillably). The streak
+                // resets only on a successful SNAPSHOT below.
+            }
+            catch (e) {
+                if (deps.isStopped() || (!deps.armed && !deps.store.isActive(deps.sessionId)))
+                    break;
+                if (++errStreak >= 5) {
+                    deps.log('browser gone — ending');
+                    break;
+                }
+                deps.log(`tick error (retrying): ${String(e).split('\n')[0]}`);
+                await sleep(deps.intervalMs);
+                continue;
+            }
+            // 2+3+4 in ONE eval: install-if-needed, paint the badge for the CURRENT mode
+            // (a fresh doc's badge is born correct — no grey blip), drain the queue.
+            // Junk (unparseable) output means the page/window is truly gone — the daemon
+            // would resurrect the browser on further evals, so a sustained streak ends
+            // the session instead of spamming.
+            const modeBefore = deps.store.isActive(deps.sessionId);
+            const raw = parseEvalResult(await deps.adapter.evalJs(TICK_JS(modeBefore, deps.tickExtras)).catch(() => 'JUNK'));
+            let events = [];
+            let tickRes = {};
+            try {
+                tickRes = JSON.parse(raw);
+                events = tickRes.queue ?? [];
+                undrainStreak = 0;
+            }
+            catch {
+                // Threshold is deliberately generous: DRAIN_JS is in-page try/catch-safe, so an
+                // ALIVE page never produces junk — but the eval itself can fail transiently
+                // mid-navigation. Only a sustained streak (~2.4s at 300ms) means the window is
+                // really gone (live finding: 3 fired during a plain page load and closed the
+                // armed window out from under the user).
+                if (++undrainStreak === 1)
+                    deps.log('skip: undrainable batch');
+                if (undrainStreak >= 8) {
+                    deps.log('browser window closed — ending session');
+                    endReason = 'closed';
+                    break;
+                }
+                await sleep(100); // transient (mid-navigation): retry fast so the badge returns sooner
+                continue;
+            }
+            // RESURRECTION DETECTOR (live finding: closing the window makes the daemon
+            // RELAUNCH it as a fresh about:blank on our next eval — where evals succeed,
+            // so the junk-based close detection never fires and the window "keeps opening
+            // again and again"). Signature: we had a real page, now it's about:blank in a
+            // freshly-installed doc. Two consecutive ticks (~400ms) to ride out rare
+            // auth-flow blank bounces; then end the session (finally closes the daemon
+            // session, which stops the resurrection for good).
+            // (installed is NOT part of the streak condition: the second tick on the same
+            // resurrected blank doc reports installed=false and would reset the streak.)
+            const isBlank = !url || url === 'about:blank';
+            if (sawRealPage && isBlank) {
+                if (++blankStreak >= 2) {
+                    deps.log('browser window closed — ending session');
+                    endReason = 'closed';
+                    break;
+                }
+            }
+            else {
+                blankStreak = 0;
+                if (!isBlank)
+                    sawRealPage = true;
+            }
+            const toggles = events.filter((e) => e.kind === 'toggle');
+            let data = events.filter((e) => e.kind !== 'toggle');
+            for (const tg of toggles) {
+                const cur = deps.store.isActive(deps.sessionId);
+                const next = typeof tg.desired === 'boolean' ? tg.desired : !cur;
+                if (next === cur)
+                    continue; // idempotent: a repeated 'stop' is a no-op, never a restart
+                if (next)
+                    deps.store.start(deps.sessionId);
+                else
+                    deps.store.stop(deps.sessionId);
+                deps.log('recording ' + (next ? 'STARTED' : 'STOPPED') + ' (pill via queue): ' + deps.sessionId);
+                deps.onToggle?.(next);
+                deps.onEvent?.('sessions');
+            }
+            // ARMED = capturing nothing: drop data events entirely. Without this the loop
+            // processed them and logged 'recorded …' while the store silently no-opped —
+            // the log claimed captures that never persisted (live confusion).
+            if (!deps.store.isActive(deps.sessionId))
+                data = [];
+            for (const ev of data)
+                pending.push({
+                    ev, drainIdx: ticks.length, waits: 0,
+                    // ledger the raw event NOW — before pairing can lose it (spec 2026-07-16)
+                    ledgerSeq: deps.store.appendEvent(deps.sessionId, {
+                        t: ev.t, source: 'human', kind: ev.kind, descriptor: ev
+                    }),
+                });
+            // (a toggle's visual flip already happened optimistically in-page; the next
+            // tick's TICK_JS paint carries the server truth.)
+            // 5. snapshot only when it can matter (the expensive call).
+            const urlChanged = ticks.length === 0 || didNavigate(ticks[ticks.length - 1].url, url)
+                || ticks[ticks.length - 1].url !== url;
+            if (data.length || pending.length || urlChanged) {
+                let snap;
+                try {
+                    snap = await deps.adapter.snapshot();
+                    errStreak = 0;
+                }
+                catch (e) {
+                    if (deps.isStopped() || (!deps.armed && !deps.store.isActive(deps.sessionId)))
+                        break;
+                    if (++errStreak >= 5) {
+                        deps.log('browser gone — ending');
+                        break;
+                    }
+                    deps.log(`tick error (retrying): ${String(e).split('\n')[0]}`);
+                    await sleep(deps.intervalMs);
+                    continue;
+                }
+                if (classifyReadiness(snap) !== 'loading')
+                    ticks.push({ url, snapshot: snap });
+                else
+                    ticks.push(ticks[ticks.length - 1] ?? { url, snapshot: snap }); // never archive a loading shell
+            }
+            // 6. pair pended events to ticks (unchanged semantics).
+            // Snapshot the later-click facts BEFORE the loop splices pending: computed inside,
+            // an already-processed (spliced) click stops counting as "later" for its same-batch
+            // input, and the input then pairs with the click's landing tick (final-review #1).
+            const clicks = pending.filter((q) => q.ev.kind === 'click')
+                .map((q) => ({ drainIdx: q.drainIdx, seq: q.ev.seq }));
+            for (let i = pending.length - 1; i >= 0; i--) {
+                const p = pending[i];
+                const hasLaterClick = clicks.some((c) => c.drainIdx > p.drainIdx || (c.drainIdx === p.drainIdx && c.seq > p.ev.seq));
+                let to = chooseToTick(p.drainIdx, ticks, hasLaterClick);
+                if (to === -1 && ++p.waits < 3)
+                    continue; // wait for the lookahead tick
+                if (to === -1)
+                    to = Math.min(p.drainIdx, ticks.length - 1); // give up waiting → same tick
+                let fromIdx = fromTickFor(p.ev, ticks, p.drainIdx - 1);
+                if (fromIdx === -1 && !didNavigate(ticks[Math.min(p.drainIdx, ticks.length - 1)].url, p.ev.url)) {
+                    fromIdx = Math.min(p.drainIdx, ticks.length - 1);
+                }
+                pending.splice(i, 1);
+                if (fromIdx === -1) {
+                    if (p.ledgerSeq != null)
+                        deps.store.stampEvent(deps.sessionId, p.ledgerSeq, 'dropped:no-from-page');
+                    deps.log(`skip: no from-page for seq ${p.ev.seq}`);
+                    continue;
+                }
+                const res = resolveEvent(p.ev, parseSnapshot(ticks[fromIdx].snapshot));
+                let ref = res && 'ref' in res ? res.ref : null;
+                if (res && 'candidates' in res && !didNavigate(url, p.ev.url)) {
+                    for (const c of res.candidates) { // ref-scoped probe (same doc only)
+                        const hit = parseEvalResult(await deps.adapter.evalJs('(el) => el.dataset.webnavHit || null', c).catch(() => 'null'));
+                        if (hit === String(p.ev.seq)) {
+                            ref = c;
+                            break;
+                        }
+                    }
+                }
+                let fx = assembleEffect(p.ev, ref, ticks[fromIdx], ticks[to]);
+                // An unresolved same-page click is normally dropped as noise (honest —
+                // never a guessed ref, per the identical-siblings-escalate rule). But a
+                // dropdown-item click that visibly CHANGED the page (e.g. a chart-type
+                // switch) is real signal, not noise — take ONE fresh snapshot and diff it
+                // against the from-tick; a genuine change gets recorded as evidence
+                // (action:null, same shape as the unresolved-NAVIGATED-click branch)
+                // instead of silently lost.
+                if (!fx && p.ev.kind === 'click' && deps.store.isActive(deps.sessionId)) {
+                    const freshSnap = await deps.adapter.snapshot().catch(() => null);
+                    if (freshSnap) {
+                        const diff = diffSnapshots(parseSnapshot(ticks[fromIdx].snapshot), parseSnapshot(freshSnap));
+                        if (diff.added.length || diff.removed.length) {
+                            fx = {
+                                fromUrl: ticks[fromIdx].url, fromSnapshot: ticks[fromIdx].snapshot,
+                                action: null, toUrl: url, toSnapshot: freshSnap,
+                                navigated: false, diff,
+                            };
+                        }
+                    }
+                }
+                if (fx) {
+                    // stamp the step with when the human ACTED, not when this slow loop got to it
+                    const stepSeq = deps.store.appendActionEffect(deps.sessionId, fx, p.ev.t);
+                    if (p.ledgerSeq != null && stepSeq != null)
+                        deps.store.stampEvent(deps.sessionId, p.ledgerSeq, 'step:' + stepSeq);
+                    appended++;
+                    deps.onEvent?.('step');
+                    const lag = p.ev.t && Date.now() - p.ev.t > 2000
+                        ? ` (at ${new Date(p.ev.t).toLocaleTimeString()})` : '';
+                    if (fx.action)
+                        deps.log(`recorded ${fx.navigated ? 'nav' : fx.action.role}: ${fx.action.name ?? fx.toUrl}${lag}`);
+                    else
+                        deps.log(`recorded unresolved same-page change (action:null): ${fx.toUrl}${lag}`);
+                }
+                else {
+                    if (p.ledgerSeq != null)
+                        deps.store.stampEvent(deps.sessionId, p.ledgerSeq, 'dropped:unresolved-same-page');
+                    deps.log(`skip: unresolved same-page click seq ${p.ev.seq}`);
+                }
+            }
+            // A fresh document just got its badge+listener via this tick's install; tick
+            // again immediately so the paint/queue gap after a navigation stays minimal.
+            if (!tickRes.installed)
+                await sleep(deps.intervalMs);
+        }
+    }
+    finally {
+        // pre-close hook: stop video / flush WHILE the session is still open — after
+        // adapter.close() the session is gone and playwright-cli video-stop saves nothing.
+        if (deps.onBeforeClose) {
+            try {
+                await deps.onBeforeClose();
+            }
+            catch { /* */ }
+        }
+        await deps.adapter.close().catch(() => { }); // graceful close request
+        deps.onEnd?.(endReason);
+    }
+    return { appended, ticks: ticks.length };
+}

package/dist/recorder/live.d.ts

@@ -0,0 +1,53 @@
+import type { SnapNode } from '../playwright/snapshot.js';
+import type { ActionEffect } from '../mapstore/record.js';
+export interface LiveEvent {
+    seq: number;
+    kind: 'click' | 'input' | 'toggle';
+    url: string;
+    tagName: string;
+    desired?: boolean;
+    t?: number;
+    role?: string | null;
+    ariaLabel?: string | null;
+    leafText?: string | null;
+    href?: string | null;
+    placeholder?: string | null;
+    nameAttr?: string | null;
+    inputType?: string | null;
+    value?: string | null;
+}
+export declare const INSTALLER_JS = "() => {\n  // Recording indicator: red inset border + \"REC\" pill. Placed BEFORE the\n  // idempotence guard so the every-tick eval self-heals it if an SPA re-render\n  // wipes it. pointer-events:none = never intercepts the user's clicks;\n  // aria-hidden = never appears in the a11y snapshots we record.\n  if (!document.getElementById('__webnav_rec_badge')) {\n    const d = document.createElement('div');\n    d.id = '__webnav_rec_badge';\n    d.setAttribute('aria-hidden', 'true');\n    d.style.cssText = 'position:fixed;inset:0;z-index:2147483647;pointer-events:none;box-shadow:inset 0 0 0 4px #e5484d;';\n    const p = document.createElement('button');\n    p.style.cssText = 'position:absolute;top:10px;left:50%;transform:translateX(-50%);background:#e5484d;color:#fff;font:700 11px/1 -apple-system,sans-serif;padding:6px 12px;border-radius:999px;pointer-events:auto;cursor:pointer;border:0;';\n    p.textContent = '\\u23FA record';\n    // A focusable element inside an aria-hidden container is STILL exposed by the\n    // a11y tree (aria-hidden on an ancestor doesn't suppress a focusable descendant) \u2014\n    // the wrapper div's aria-hidden alone does not hide this button from snapshots.\n    // Make the pill itself a11y-invisible too. Doesn't touch pointer-events/onclick.\n    p.setAttribute('aria-hidden', 'true');\n    p.setAttribute('tabindex', '-1');\n    d.appendChild(p);\n    (document.body || document.documentElement).appendChild(d);\n  }\n  if (document.documentElement.dataset.webnavInstalled) return 'already';\n  document.documentElement.dataset.webnavInstalled = '1';\n  // Keep the journey in THIS tab: a new tab escapes the recorder (one driven page).\n  // Standard recorder trick: _blank links open same-tab; window.open redirects inline.\n  // ponytail: OAuth-style popups get redirected into the tab \u2014 acceptable for v1.\n  document.addEventListener('click', (ev) => {\n    const t = ev.target;\n    if (t instanceof Element) {\n      const a = t.closest('a[target]');\n      if (a && a.getAttribute('target') !== '_self') a.setAttribute('target', '_self');\n    }\n  }, true);\n  window.open = (u) => { if (u) location.href = String(u); return null; };\n  const push = (e) => {\n    try {\n      const q = JSON.parse(sessionStorage.getItem('__webnav_evq') || '[]');\n      const seq = (Number(sessionStorage.getItem('__webnav_seq')) || 0) + 1;\n      sessionStorage.setItem('__webnav_seq', String(seq));\n      q.push(Object.assign({ seq, t: Date.now(), url: location.href }, e));\n      sessionStorage.setItem('__webnav_evq', JSON.stringify(q));\n      return seq;\n    } catch { return 0; }   // storage-denied page (opaque origin): drop, never explode\n  };\n  const badgeBtn = document.querySelector('#__webnav_rec_badge button');\n  if (badgeBtn) badgeBtn.onclick = () => {\n    // OPTIMISTIC flip: paint the new state NOW (the server's truth repaints next tick).\n    // (4-line paint duplicated from TICK_JS's painter \u2014 worlds are isolated, DOM isn't.)\n    const on = document.documentElement.dataset.webnavRec === '1';\n    const desired = !on;\n    document.documentElement.dataset.webnavRec = desired ? '1' : '0';\n    document.documentElement.dataset.webnavPinT = String(Date.now());   // pin: stale ticks must not undo this\n    const d0 = document.getElementById('__webnav_rec_badge');\n    if (d0) { d0.style.boxShadow = 'inset 0 0 0 4px ' + (desired ? '#e5484d' : '#8b93a3');\n      const b0 = d0.querySelector('button');\n      if (b0) { b0.style.background = desired ? '#e5484d' : '#8b93a3'; b0.textContent = desired ? '\\u25CF REC \\u2014 stop' : '\\u23FA record'; } }\n    // REALTIME: POST the DESIRED state straight to the dashboard server (idempotent \u2014\n    // a flip could double-toggle if visual state was stale; desired-state can't).\n    // Chrome exempts 127.0.0.1 from mixed-content blocking, so this works from https\n    // pages too. Fetch failure (strict CSP, no dashboard) \u2192 queue for the loop.\n    const port = document.documentElement.dataset.webnavPort;\n    const sess = document.documentElement.dataset.webnavSession;\n    if (port && sess) {\n      fetch('http://127.0.0.1:' + port + '/api/recordings/' + encodeURIComponent(sess) + '/toggle',\n        { method: 'POST', keepalive: true, headers: { 'content-type': 'application/json' },\n          body: JSON.stringify({ recording: desired }) }).catch(() => push({ kind: 'toggle', desired }));\n    } else { push({ kind: 'toggle', desired }); }\n  };\n  // Click RIPPLE: a brief expanding ring at the click point, painted only while\n  // recording \u2014 so the session VIDEO shows WHERE each click landed (the review\n  // agent reads frames; a ripple pins the action location). pointer-events:none\n  // (never intercepts), aria-hidden (never in the a11y snapshots we record), and\n  // it deliberately CREATES a visible change at click time, which biases the\n  // scene-change frame extractor toward selecting a frame at each click.\n  const ripple = (x, y) => {\n    const r = document.createElement('div');\n    r.setAttribute('aria-hidden', 'true');\n    r.style.cssText = 'position:fixed;left:' + (x - 22) + 'px;top:' + (y - 22) + 'px;width:44px;height:44px;border-radius:50%;border:3px solid #e5484d;background:rgba(229,72,77,.3);z-index:2147483646;pointer-events:none;transform:scale(.4);opacity:1;transition:transform .5s ease-out,opacity .7s ease-out;';\n    (document.body || document.documentElement).appendChild(r);\n    requestAnimationFrame(() => { r.style.transform = 'scale(1.7)'; r.style.opacity = '0'; });\n    setTimeout(() => r.remove(), 800);\n  };\n  // POINTER DOT: a persistent cursor marker that follows the mouse, so the session\n  // VIDEO shows WHERE the agent/human is pointing \u2014 essential for hover-revealed menus\n  // (a hover has no click ripple, so without this you can't see what's being hovered).\n  // Agent hovers go through playwright's real mouse \u2192 dispatch mousemove \u2192 this moves.\n  // One reused element (not per-move), pointer-events:none, aria-hidden (never in the\n  // a11y snapshot). Only visible while recording (the frame extractor still keys on the\n  // bigger scene changes; the dot is a small always-on locator, not a scene-change bait).\n  const pointer = () => {\n    let el = document.getElementById('__webnav_ptr');\n    if (!el) {\n      el = document.createElement('div');\n      el.id = '__webnav_ptr';\n      el.setAttribute('aria-hidden', 'true');\n      el.style.cssText = 'position:fixed;left:0;top:0;width:18px;height:18px;margin:-9px 0 0 -9px;border-radius:50%;border:2px solid #e5484d;background:rgba(229,72,77,.25);box-shadow:0 0 0 2px rgba(255,255,255,.6);z-index:2147483645;pointer-events:none;transition:left .2s ease-out,top .2s ease-out;display:none;';\n      (document.body || document.documentElement).appendChild(el);\n    }\n    return el;\n  };\n  document.addEventListener('mousemove', (ev) => {\n    const el = pointer();\n    const on = document.documentElement.dataset.webnavRec === '1';\n    el.style.display = on ? 'block' : 'none';\n    el.style.left = ev.clientX + 'px';\n    el.style.top = ev.clientY + 'px';\n  }, true);\n  // ownText/nearestLabel: a role-bearing wrapper (e.g. a chart's role=\"toolbar\"\n  // holding BOTH a legend and a dropdown) passes the old takeText check and its\n  // whole-subtree textContent bled the legend's text onto a dropdown click. These\n  // walk up from the ACTUAL click target (not the broad interactive ancestor) and\n  // stop at the first element with its own direct text \u2014 never a subtree scrape.\n  // Only used as the FALLBACK for broad containers \u2014 see leafLabel below.\n  function ownText(node) {\n    let s = '';\n    for (const c of node.childNodes) if (c.nodeType === 3) s += c.textContent;\n    return s.trim();\n  }\n  function nearestLabel(start) {\n    let n = start, depth = 0;\n    while (n && depth < 4) {\n      const al = n.getAttribute && n.getAttribute('aria-label');\n      if (al && al.trim()) return al.trim().slice(0, 80);\n      const ot = ownText(n);\n      if (ot) return ot.slice(0, 80);\n      n = n.parentElement; depth++;\n    }\n    return null;\n  }\n  // A genuine LEAF control's full textContent IS its label (safe \u2014 it has no\n  // unrelated siblings to bleed in). A BROAD container (toolbar/menu/list/...\n  // or no role) is not a single control, so its textContent bleeds siblings \u2014\n  // fall back to nearestLabel from the real click target instead.\n  var LEAF_TAGS = ['a','button','input','select','textarea','summary','label'];\n  var LEAF_ROLES = ['button','link','menuitem','option','tab','checkbox','radio',\n    'switch','menuitemcheckbox','menuitemradio','treeitem'];\n  function leafLabel(el, t, matched) {\n    var role = el.getAttribute && el.getAttribute('role');\n    var isLeaf = matched && (LEAF_TAGS.indexOf(el.tagName.toLowerCase()) >= 0 ||\n      (role && LEAF_ROLES.indexOf(role) >= 0));\n    if (isLeaf) {\n      var al = el.getAttribute && el.getAttribute('aria-label');\n      if (al && al.trim()) return al.trim().slice(0, 80);\n      return (el.textContent || '').trim().slice(0, 80) || null;\n    }\n    // el is a broad/unrecognized container, or closest() matched nothing\n    // (matched===false, el fell back to t) \u2014 either way not a single control.\n    return nearestLabel(t);\n  }\n  document.addEventListener('click', (ev) => {\n    const t = ev.target;\n    if (!(t instanceof Element)) return;\n    if (t.closest('#__webnav_rec_badge')) return;   // our own overlay is never a recorded click\n    if (document.documentElement.dataset.webnavRec === '1') ripple(ev.clientX, ev.clientY);\n    const closestEl = t.closest('a,button,[role],input,select,textarea,summary,label');\n    const el = closestEl || t;\n    const tag = el.tagName.toLowerCase();\n    const isBtnInput = el instanceof HTMLInputElement && ['submit','button','reset'].indexOf(el.type) >= 0;\n    const seq = push({\n      kind: 'click', tagName: tag,\n      role: el.getAttribute('role'), ariaLabel: el.getAttribute('aria-label'),\n      leafText: isBtnInput ? (el.value || null) : leafLabel(el, t, !!closestEl),\n      href: el instanceof HTMLAnchorElement ? el.href : null,\n      placeholder: el.getAttribute('placeholder'), nameAttr: el.getAttribute('name'),\n      inputType: el instanceof HTMLInputElement ? el.type : null,\n    });\n    if (el instanceof HTMLElement) el.dataset.webnavHit = String(seq);\n  }, true);\n  document.addEventListener('change', (ev) => {\n    const el = ev.target;\n    if (!(el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement)) return;\n    // SECRET RULE (refined): record the supplied VALUE as a flow variable for\n    // non-secret fields; password / cc-* autocomplete fields are NEVER captured.\n    // The guard must cover: multi-token autocomplete ('billing cc-number'), the\n    // password-manager tokens (current-password/new-password/one-time-code), and\n    // show-password toggles (type flips to text but autocomplete stays) \u2014 final\n    // pre-merge review finding.\n    const ac = (el.autocomplete || '');\n    const secret = el instanceof HTMLInputElement &&\n      (el.type === 'password' || /(^|s)(cc-|current-password|new-password|one-time-code)/.test(ac));\n    let value = null;\n    if (!secret) {\n      if (el instanceof HTMLInputElement && (el.type === 'checkbox' || el.type === 'radio')) value = el.checked ? 'true' : 'false';\n      else value = String(el.value ?? '').slice(0, 200);\n    }\n    push({ kind: 'input', tagName: el.tagName.toLowerCase(), role: el.getAttribute('role'),\n      ariaLabel: el.getAttribute('aria-label'), leafText: null, href: null,\n      placeholder: el.getAttribute('placeholder'), nameAttr: el.getAttribute('name'),\n      inputType: el instanceof HTMLInputElement ? el.type : null, value });\n  }, true);\n  return 'installed';\n}";
+export declare const MODE_JS: (recording: boolean) => string;
+export declare const DRAIN_JS = "() => {\n  try {\n    const q = sessionStorage.getItem('__webnav_evq') || '[]';\n    sessionStorage.removeItem('__webnav_evq');\n    return q;\n  } catch { return '[]'; }\n}";
+export declare const TICK_JS: (recording: boolean, extras?: {
+    port?: number;
+    session?: string;
+}) => string;
+export declare function descriptorRole(ev: LiveEvent): string | null;
+export declare function descriptorName(ev: LiveEvent): string | null;
+export type Resolution = {
+    ref: string;
+} | {
+    candidates: string[];
+} | null;
+/** Resolve a descriptor against a REAL playwright snapshot. Strict: no role/name
+ *  → null; unique role+name → ref; multiple + href → match the link target
+ *  (host+path); still multiple → candidates (the loop may probe them); else null. */
+export declare function resolveEvent(ev: LiveEvent, nodes: SnapNode[]): Resolution;
+export interface Tick {
+    url: string;
+    snapshot: string;
+}
+/** Latest tick ≤ uptoIdx on the same page as the event (query/hash ignored). */
+export declare function fromTickFor(ev: LiveEvent, ticks: Tick[], uptoIdx: number): number;
+/** Which tick is the event's landing? -1 = wait (need the lookahead tick).
+ *  A navigation often lands AFTER the drain tick; the one-tick lookahead
+ *  attributes it — unless a later click was drained, which then owns it.
+ *  ponytail: bursts inside one interval can misattribute; interval default
+ *  500ms makes that rare for deliberate QA clicking. */
+export declare function chooseToTick(drainIdx: number, ticks: Tick[], hasLaterClick: boolean): number;
+/** Build the ActionEffect. Unresolved same-page CLICKS are dropped (noise);
+ *  unresolved NAVIGATED clicks still emit with action:null (the draft's
+ *  link-scan + cross-link mesh recover link edges); inputs always emit —
+ *  the field identity powers the draft's login/credentials linkage. */
+export declare function assembleEffect(ev: LiveEvent, ref: string | null, from: Tick, to: Tick): ActionEffect | null;