@dikshanty94/webnav 0.2.0

package/dist/playwright/video.d.ts

@@ -0,0 +1,13 @@
+export interface VideoAdapter {
+    videoStart(): Promise<void>;
+    videoStop(filename: string): Promise<boolean>;
+}
+export interface VideoSyncDeps {
+    videosRoot: string;
+    log: (line: string) => void;
+    onSaved?: () => void;
+    now?: () => number;
+}
+/** Make a stateful videoSync(session, recording) bound to one adapter+deps.
+ *  Returns the closure the caller invokes on each record-state change. */
+export declare function makeVideoSync(getAdapter: () => VideoAdapter | null, deps: VideoSyncDeps): (session: string, recording: boolean) => void;

package/dist/playwright/video.js

@@ -0,0 +1,32 @@
+// Per-recording video capture, shared by BOTH the human live-record loop and the
+// agent `use navigate` path. A "take" is one Record→Stop span → one
+// ~/.webnav/recordings/<session>/take-<ts>.webm. Idempotent per span (a start
+// while already recording, or a stop while already stopped, is a no-op).
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** Make a stateful videoSync(session, recording) bound to one adapter+deps.
+ *  Returns the closure the caller invokes on each record-state change. */
+export function makeVideoSync(getAdapter, deps) {
+    const now = deps.now ?? (() => Date.now());
+    let videoOn = false;
+    return (session, recording) => {
+        const adapter = getAdapter();
+        if (recording && !videoOn && adapter) {
+            videoOn = true;
+            void adapter.videoStart().then(() => deps.log('video: recording started'), () => deps.log('video: START FAILED'));
+        }
+        else if (!recording && videoOn && adapter) {
+            videoOn = false;
+            const dir = join(deps.videosRoot, session);
+            try {
+                mkdirSync(dir, { recursive: true });
+            }
+            catch { /* decoration */ }
+            const file = join(dir, 'take-' + now() + '.webm');
+            void adapter.videoStop(file).then((ok) => {
+                deps.log(ok ? 'video: saved ' + file : 'video: SAVE FAILED (' + file + ')');
+                deps.onSaved?.();
+            });
+        }
+    };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,49 @@
+import type { TokenSavings } from './router/tokens.js';
+import type { Affordance } from './mapstore/types.js';
+export interface Candidate {
+    id: string;
+    url: string;
+    signals: Record<string, unknown>;
+}
+export interface EvidenceBundle {
+    goal: string;
+    query: string;
+    candidates: Candidate[];
+    cost: {
+        playwright_calls: number;
+        savings: TokenSavings;
+    };
+    snapshot?: string;
+    repertoire?: Affordance[];
+}
+export type RecallResponse = {
+    status: 'done';
+    evidence: EvidenceBundle;
+    halted?: 'commit-point';
+} | {
+    status: 'needs-navigation';
+    at: number;
+    semanticStep: string;
+    snapshot: string;
+    question: string;
+} | {
+    status: 'needs-classification';
+    action: string;
+    snapshot: string;
+    at?: number;
+} | {
+    status: 'needs-auth';
+    at: number;
+    profile: string;
+    site: string;
+    loginUrl: string;
+} | {
+    status: 'checkpoint';
+    at: number;
+    state: string;
+    snapshot: string;
+    repertoire: Affordance[];
+} | {
+    status: 'failed';
+    reason: string;
+};

package/dist/protocol.js

@@ -0,0 +1,3 @@
+// The call-and-response protocol between the calling agent and webnav.
+// webnav NEVER reasons; whenever a decision is needed, it hands back to the agent.
+export {};

package/dist/recorder/agent-session.d.ts

@@ -0,0 +1,59 @@
+import type { ActionEffect } from '../mapstore/record.js';
+export declare const OVERLAY_ON_JS: string;
+export interface AgentSessionCmd {
+    cmd: 'navigate' | 'snapshot' | 'click' | 'type' | 'hover' | 'eval' | 'quit';
+    url?: string;
+    ref?: string;
+    text?: string;
+    js?: string;
+}
+export declare const NAME_PROBE_JS = "(el) => {\n  // Defense in depth: even if a page's a11y snapshot exposes our own REC-overlay\n  // pill (a focusable element inside an aria-hidden container isn't reliably\n  // suppressed), never let the probe mint a name for it \u2014 that could mint a\n  // bogus overlay affordance into the map (wrong-map class).\n  if (el.closest && el.closest('#__webnav_rec_badge')) return '';\n  const ATTRS = ['aria-label','title','data-tooltip-content','data-tooltip','data-title','data-original-title','data-tip','aria-description'];\n  const g = (n) => { if (!n || !n.getAttribute) return ''; for (const a of ATTRS) { const v = n.getAttribute(a); if (v && v.trim()) return v.trim(); } return ''; };\n  let s = g(el);\n  if (!s) { const t = el.querySelector && el.querySelector('svg title, title'); if (t) s = (t.textContent || '').trim(); }\n  if (!s && el.getAttribute) { const lb = el.getAttribute('aria-labelledby'); if (lb) { const r = el.ownerDocument.getElementById(lb); if (r) s = (r.textContent || '').trim(); } }\n  if (!s) { let n = el.parentElement, d = 0; while (n && d < 2 && !s) { s = g(n); n = n.parentElement; d++; } }\n  // Last resort \u2014 the element's OWN text content. A label-less control whose text IS its\n  // label: a sortable column header 'Name', or a date-range button reading 'Last 7 Days\n  // (CD) : 02 Jul 2026 - 08 Jul 2026 UTC'. SINGLE-LINE only (no newline) so we never scrape\n  // a whole multi-row card (the leaf-vs-container rule from live.ts); the length cap is\n  // generous (120) because real button labels can be long \u2014 the final slice(0,80) still\n  // bounds what we store.\n  if (!s) { const own = (el.textContent || '').trim(); if (own && own.length <= 120 && !/\\n/.test(own)) s = own; }\n  return (s || '').trim().slice(0, 80);\n}";
+/** Pick the best label for a recorded action: the recovered accessible name if present,
+ *  else the DOM-probed attribute label (tooltip/aria), else null. REJECTS a probe result
+ *  that's actually a playwright-cli error blob (a stale-ref eval returns "### Error …" as
+ *  a string — that must never be stored as the element's name). Pure — unit-tested. */
+export declare function enrichName(recoveredName: string | null, probed: string | null | undefined): string | null;
+export interface AgentSessionDeps {
+    sessionId: string;
+    adapter: {
+        open(url: string): Promise<unknown>;
+        goto(url: string): Promise<unknown>;
+        snapshot(): Promise<string>;
+        currentUrl(): Promise<string>;
+        fill(ref: string, text: string): Promise<unknown>;
+        act(ref: string): Promise<unknown>;
+        hover(ref: string): Promise<unknown>;
+        evalJs(js: string, ref?: string): Promise<string>;
+        close(): Promise<unknown>;
+    };
+    store: {
+        isActive(s: string): boolean;
+        appendActionEffect(s: string, fx: ActionEffect): 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;
+    };
+    recover: (snapshot: string, ref: string) => {
+        action: {
+            role: string;
+            name: string | null;
+            ref: string;
+            elementFp?: unknown;
+        };
+    };
+    readLine: () => Promise<string | null>;
+    write: (line: string) => void;
+    notify: (kind: 'step' | 'sessions' | 'log', line?: string) => void;
+    startVideo: () => Promise<void>;
+    stopVideo: () => Promise<string | null>;
+    startUrl: string;
+}
+/** Run the interactive loop until quit/EOF. Returns a summary. */
+export declare function runAgentSession(deps: AgentSessionDeps): Promise<{
+    steps: number;
+    video: string | null;
+}>;

package/dist/recorder/agent-session.js

@@ -0,0 +1,230 @@
+// The interactive long-lived agent session loop. ONE process owns the browser
+// start-to-finish: it opens, starts video + recording, then reads JSON-line
+// commands on stdin, executes each against the SAME open browser, and writes one
+// JSON result line per command. On quit/EOF it stops video (saves the take),
+// stops recording, and closes the browser. This is the ONLY shape that lets video
+// span the whole session (playwright-cli video is bound to one process) AND leaks
+// nothing (the process closes its own browser on exit).
+//
+// Pure core: deps injected (adapter, store, io, notify, video) so it's unit-tested
+// with scripted stdin + a fake adapter — no real browser.
+import { runActionRecorded, parseEvalResult, settleSnapshot, probeLanding } from '../router/browse.js';
+import { diffSnapshots } from '../explorer/diff.js';
+import { parseSnapshot } from '../playwright/snapshot.js';
+import { INSTALLER_JS, MODE_JS } from './live.js';
+// Paint the same REC overlay the human live-recorder uses, so an agent session's
+// video also shows a recording indicator + click ripples (agent clicks go through
+// playwright's real .click(), which dispatches a trusted DOM click event — that
+// bubbles to INSTALLER_JS's document click listener exactly like a human click, so
+// the existing ripple painter fires with NO extra eval needed here). Composed as one
+// eval (install-if-missing, then paint recording=on) — mirrors TICK_JS in live.ts.
+// Best-effort: a CSP page that blocks eval must not break navigation/recording.
+export const OVERLAY_ON_JS = `() => { (${INSTALLER_JS})(); return (${MODE_JS(true)})(); }`;
+// A ref-scoped DOM read (playwright-cli `eval "(element)=>…" <ref>`) to recover a
+// human-meaningful label for a NAMELESS control (icon-only buttons: expand chevron,
+// favorite star, duplicate — their label lives in a tooltip/aria attribute, NOT in the
+// a11y snapshot's accessible name). Zero-LLM, observe-only. Runs ONLY when the recovered
+// name is empty (no cost on named elements). Best-effort: a CSP page that blocks eval
+// just leaves name null. TOOLTIP-ATTR LIST is broad on purpose — libraries name the
+// attribute differently (title/aria-label, data-tooltip, data-tooltip-content [react-
+// tooltip], data-title, data-original-title [bootstrap]).
+export const NAME_PROBE_JS = `(el) => {
+  // Defense in depth: even if a page's a11y snapshot exposes our own REC-overlay
+  // pill (a focusable element inside an aria-hidden container isn't reliably
+  // suppressed), never let the probe mint a name for it — that could mint a
+  // bogus overlay affordance into the map (wrong-map class).
+  if (el.closest && el.closest('#__webnav_rec_badge')) return '';
+  const ATTRS = ['aria-label','title','data-tooltip-content','data-tooltip','data-title','data-original-title','data-tip','aria-description'];
+  const g = (n) => { if (!n || !n.getAttribute) return ''; for (const a of ATTRS) { const v = n.getAttribute(a); if (v && v.trim()) return v.trim(); } return ''; };
+  let s = g(el);
+  if (!s) { const t = el.querySelector && el.querySelector('svg title, title'); if (t) s = (t.textContent || '').trim(); }
+  if (!s && el.getAttribute) { const lb = el.getAttribute('aria-labelledby'); if (lb) { const r = el.ownerDocument.getElementById(lb); if (r) s = (r.textContent || '').trim(); } }
+  if (!s) { let n = el.parentElement, d = 0; while (n && d < 2 && !s) { s = g(n); n = n.parentElement; d++; } }
+  // Last resort — the element's OWN text content. A label-less control whose text IS its
+  // label: a sortable column header 'Name', or a date-range button reading 'Last 7 Days
+  // (CD) : 02 Jul 2026 - 08 Jul 2026 UTC'. SINGLE-LINE only (no newline) so we never scrape
+  // a whole multi-row card (the leaf-vs-container rule from live.ts); the length cap is
+  // generous (120) because real button labels can be long — the final slice(0,80) still
+  // bounds what we store.
+  if (!s) { const own = (el.textContent || '').trim(); if (own && own.length <= 120 && !/\\n/.test(own)) s = own; }
+  return (s || '').trim().slice(0, 80);
+}`;
+/** Pick the best label for a recorded action: the recovered accessible name if present,
+ *  else the DOM-probed attribute label (tooltip/aria), else null. REJECTS a probe result
+ *  that's actually a playwright-cli error blob (a stale-ref eval returns "### Error …" as
+ *  a string — that must never be stored as the element's name). Pure — unit-tested. */
+export function enrichName(recoveredName, probed) {
+    const r = (recoveredName ?? '').trim();
+    if (r)
+        return r;
+    const p = (probed ?? '').trim();
+    if (!p || p.startsWith('### Error') || /^Error:/.test(p))
+        return null; // eval failed → no name, not the error text
+    return p;
+}
+/** Run the interactive loop until quit/EOF. Returns a summary. */
+export async function runAgentSession(deps) {
+    let steps = 0;
+    let video = null;
+    const out = (obj) => deps.write(JSON.stringify(obj));
+    // open + video + first navigate is the caller's job (it built the adapter); here we
+    // assume the browser is open at startUrl. Start video now so it spans everything.
+    await deps.startVideo().catch(() => { });
+    deps.notify('sessions', 'agent session started: ' + deps.sessionId);
+    out({ ok: true, ready: true, session: deps.sessionId, url: deps.startUrl });
+    try {
+        for (;;) {
+            const line = await deps.readLine();
+            if (line === null)
+                break; // EOF → teardown
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let c;
+            try {
+                c = JSON.parse(trimmed);
+            }
+            catch {
+                out({ ok: false, error: 'invalid JSON command' });
+                continue;
+            }
+            if (c.cmd === 'quit')
+                break;
+            let pendingLedger = null; // reset per command; stamped by this command or the catch below
+            try {
+                if (c.cmd === 'navigate') {
+                    if (!c.url) {
+                        out({ ok: false, error: 'navigate needs url' });
+                        continue;
+                    }
+                    const fromUrl = await deps.adapter.currentUrl().catch(() => '');
+                    const fromSnapshot = fromUrl ? await deps.adapter.snapshot().catch(() => '') : '';
+                    pendingLedger = deps.store.appendEvent(deps.sessionId, {
+                        source: 'agent', kind: 'navigate', descriptor: { cmd: 'navigate', url: c.url, fromUrl: fromUrl || c.url }
+                    });
+                    await deps.adapter.goto(c.url);
+                    await deps.adapter.evalJs(OVERLAY_ON_JS).catch(() => { }); // best-effort: video overlay
+                    // SETTLE before reading url+snapshot: a client-side redirect/late render otherwise
+                    // records a transient URL as a page (the ghost-state class of bugs). Bounded retry.
+                    const toSnapshot = await settleSnapshot(() => deps.adapter.snapshot());
+                    const toUrl = await deps.adapter.currentUrl();
+                    // X6: probe the SETTLED landing's nameless icon controls (title/aria/tooltip) before
+                    // appending — fires only when nameless interactive nodes exist. Best-effort.
+                    const nameHints = await probeLanding(deps.adapter, toSnapshot).catch(() => undefined);
+                    if (deps.store.isActive(deps.sessionId)) {
+                        const stepSeq = deps.store.appendActionEffect(deps.sessionId, {
+                            fromUrl: fromUrl || c.url, fromSnapshot, action: null,
+                            toUrl, toSnapshot, navigated: true, diff: { added: [], removed: [] },
+                            requestedUrl: c.url, nameHints,
+                        });
+                        if (pendingLedger != null && stepSeq != null)
+                            deps.store.stampEvent(deps.sessionId, pendingLedger, 'step:' + stepSeq);
+                        pendingLedger = null;
+                        steps++;
+                        deps.notify('step', 'agent nav: ' + toUrl);
+                    }
+                    out({ ok: true, url: toUrl });
+                }
+                else if (c.cmd === 'snapshot') {
+                    out({ ok: true, snapshot: await deps.adapter.snapshot() });
+                }
+                else if (c.cmd === 'click' || c.cmd === 'type') {
+                    if (!c.ref) {
+                        out({ ok: false, error: c.cmd + ' needs ref' });
+                        continue;
+                    }
+                    const fromSnapshot = await deps.adapter.snapshot();
+                    const fromUrl = await deps.adapter.currentUrl();
+                    const { action } = deps.recover(fromSnapshot, c.ref);
+                    // NAMELESS icon controls (expand/favorite/duplicate) have no a11y name → the
+                    // step would log as the page URL. Probe the element's own attributes for a
+                    // human label BEFORE acting (title/aria-label/svg-title/tooltip). No cost on
+                    // named elements. Best-effort: eval failure leaves the name as-is.
+                    if (!(action.name ?? '').trim()) {
+                        const probed = parseEvalResult(await deps.adapter.evalJs(NAME_PROBE_JS, c.ref).catch(() => ''));
+                        action.name = enrichName(action.name, probed);
+                    }
+                    const r = await runActionRecorded({
+                        sessionId: deps.sessionId, recordStore: deps.store,
+                        fromUrl, fromSnapshot, action: action,
+                        text: c.cmd === 'type' ? c.text : undefined,
+                        adapter: deps.adapter,
+                    });
+                    if (r.status === 'failed') {
+                        out({ ok: false, error: r.reason });
+                        continue;
+                    }
+                    if (r.recorded) {
+                        steps++;
+                        deps.notify('step', 'agent ' + c.cmd + ': ' + (action.name ?? c.ref));
+                    }
+                    if (r.navigated)
+                        await deps.adapter.evalJs(OVERLAY_ON_JS).catch(() => { }); // best-effort: video overlay (fresh page from in-page nav)
+                    out({ ok: true, navigated: r.navigated, name: action.name });
+                }
+                else if (c.cmd === 'hover') {
+                    // HOVER = reveal-on-hover menus/tooltips. A same-page action (never navigates):
+                    // hover the ref, snapshot the revealed state, record an ActionEffect whose diff
+                    // shows what the hover exposed. Marked action.hover so the kind is distinguishable.
+                    if (!c.ref) {
+                        out({ ok: false, error: 'hover needs ref' });
+                        continue;
+                    }
+                    const fromSnapshot = await deps.adapter.snapshot();
+                    const fromUrl = await deps.adapter.currentUrl();
+                    const { action } = deps.recover(fromSnapshot, c.ref);
+                    if (!(action.name ?? '').trim()) {
+                        const probed = parseEvalResult(await deps.adapter.evalJs(NAME_PROBE_JS, c.ref).catch(() => ''));
+                        action.name = enrichName(action.name, probed);
+                    }
+                    pendingLedger = deps.store.appendEvent(deps.sessionId, {
+                        source: 'agent', kind: 'hover',
+                        descriptor: { cmd: 'hover', ref: c.ref, role: action.role, name: action.name, url: fromUrl }
+                    });
+                    await deps.adapter.hover(c.ref);
+                    const toSnapshot = await deps.adapter.snapshot();
+                    const toUrl = await deps.adapter.currentUrl();
+                    if (deps.store.isActive(deps.sessionId)) {
+                        const stepSeq = deps.store.appendActionEffect(deps.sessionId, {
+                            fromUrl, fromSnapshot, action: { ...action, hover: true },
+                            toUrl, toSnapshot, navigated: false,
+                            diff: diffSnapshots(parseSnapshot(fromSnapshot), parseSnapshot(toSnapshot)),
+                        });
+                        if (pendingLedger != null && stepSeq != null)
+                            deps.store.stampEvent(deps.sessionId, pendingLedger, 'step:' + stepSeq);
+                        pendingLedger = null;
+                        steps++;
+                        deps.notify('step', 'agent hover: ' + (action.name ?? c.ref));
+                    }
+                    out({ ok: true, name: action.name, revealed: parseSnapshot(toSnapshot).length - parseSnapshot(fromSnapshot).length });
+                }
+                else if (c.cmd === 'eval') {
+                    if (!c.js) {
+                        out({ ok: false, error: 'eval needs js' });
+                        continue;
+                    }
+                    out({ ok: true, result: await deps.adapter.evalJs(c.js) });
+                }
+                else {
+                    out({ ok: false, error: 'unknown cmd: ' + String(c.cmd) });
+                }
+            }
+            catch (e) {
+                if (pendingLedger != null) {
+                    deps.store.stampEvent(deps.sessionId, pendingLedger, 'dropped:failed:' + String(e.message ?? e).slice(0, 120));
+                    pendingLedger = null;
+                }
+                out({ ok: false, error: String(e.message ?? e) });
+            }
+        }
+    }
+    finally {
+        // teardown IN THIS PROCESS: stop video (must happen while the session is open),
+        // then close the browser. Order matters — video-stop after close saves nothing.
+        video = await deps.stopVideo().catch(() => null);
+        await deps.adapter.close().catch(() => { });
+        deps.notify('sessions', 'agent session ended: ' + deps.sessionId + (video ? ' (video saved)' : ''));
+    }
+    out({ ok: true, done: true, steps, video });
+    return { steps, video };
+}

package/dist/recorder/capture-loop.d.ts

@@ -0,0 +1,19 @@
+import type { CaptureGap } from './review.js';
+export interface CaptureLoopDeps {
+    objective: string;
+    maxRounds?: number;
+    explore: (round: number) => Promise<string | null>;
+    review: (sessionId: string) => Promise<CaptureGap[]>;
+    log: (line: string) => void;
+}
+export interface CaptureRound {
+    round: number;
+    session: string | null;
+    gaps: CaptureGap[];
+}
+export interface CaptureLoopResult {
+    status: 'clean' | 'needs-fix' | 'max-rounds';
+    rounds: CaptureRound[];
+    gaps: CaptureGap[];
+}
+export declare function runCaptureLoop(deps: CaptureLoopDeps): Promise<CaptureLoopResult>;

package/dist/recorder/capture-loop.js

@@ -0,0 +1,40 @@
+/** Signature of a gap for thrash-detection: a NEW gap type is one not seen before. */
+function gapKind(g) { return (g.kind ?? 'other') + ':' + (g.shouldHaveCaptured ?? g.whatHappened ?? ''); }
+export async function runCaptureLoop(deps) {
+    const maxRounds = deps.maxRounds ?? 5;
+    const rounds = [];
+    const seenKinds = new Set();
+    let noNewGapStreak = 0;
+    for (let round = 1; round <= maxRounds; round++) {
+        deps.log(`capture-loop round ${round}/${maxRounds}: exploring "${deps.objective}"…`);
+        const session = await deps.explore(round);
+        if (!session) {
+            deps.log(`round ${round}: exploration failed (no session) — stopping`);
+            rounds.push({ round, session: null, gaps: [] });
+            return { status: 'needs-fix', rounds, gaps: [] };
+        }
+        const gaps = await deps.review(session);
+        rounds.push({ round, session, gaps });
+        deps.log(`round ${round}: ${gaps.length} capture gap(s)`);
+        if (gaps.length === 0) {
+            deps.log(`round ${round}: CLEAN — capture is complete for this objective`);
+            return { status: 'clean', rounds, gaps: [] };
+        }
+        // thrash guard: if a whole round surfaced no NEW gap TYPE, we're not converging
+        // via re-exploration alone → the gaps need code fixes; stop and hand them over.
+        const fresh = gaps.filter((g) => !seenKinds.has(gapKind(g)));
+        fresh.forEach((g) => seenKinds.add(gapKind(g)));
+        if (fresh.length === 0) {
+            if (++noNewGapStreak >= 2) {
+                deps.log(`round ${round}: no new gap types in 2 rounds — needs code fixes`);
+                return { status: 'needs-fix', rounds, gaps };
+            }
+        }
+        else {
+            noNewGapStreak = 0;
+        }
+        deps.log(`round ${round}: gaps remain → (fix recorder code, then next round)`);
+    }
+    deps.log(`capture-loop: hit max rounds (${maxRounds}) with gaps remaining`);
+    return { status: 'max-rounds', rounds, gaps: rounds[rounds.length - 1]?.gaps ?? [] };
+}

package/dist/recorder/coverage.d.ts

@@ -0,0 +1,22 @@
+import type { StoredLedgerEvent } from '../mapstore/record.js';
+import type { StoredActionEffect } from '../mapstore/record.js';
+export interface Coverage {
+    total: number;
+    captured: number;
+    dropped: {
+        seq: number;
+        kind: string;
+        label: string | null;
+        reason: string;
+    }[];
+}
+export declare function coverage(events: StoredLedgerEvent[]): Coverage;
+export interface LandingStructure {
+    url: string;
+    named: number;
+    nameless: number;
+}
+/** Structure audit (fidelity roadmap 1c/gap-3): per distinct landing, how many
+ *  interactive nodes are named vs NAMELESS. A page thick with nameless controls
+ *  is a sensor gap the review prompt should flag for a frame-by-frame compare. */
+export declare function landingStructure(effects: Pick<StoredActionEffect, 'toUrl' | 'toSnapshot'>[]): LandingStructure[];

package/dist/recorder/coverage.js

@@ -0,0 +1,49 @@
+import { parseSnapshot } from '../playwright/snapshot.js';
+import { PROBE_ROLES, namelessInteractive } from './probe.js';
+export function coverage(events) {
+    const dropped = [];
+    let captured = 0;
+    for (const e of events) {
+        const d = e.disposition ?? 'dropped:unprocessed'; // never stamped = lost mid-pair
+        if (d.startsWith('step:')) {
+            captured++;
+            continue;
+        }
+        const desc = e.descriptor;
+        const candidates = [desc.ariaLabel, desc.leafText, desc.name, desc.placeholder];
+        const label = (candidates.find((c) => typeof c === 'string' && c.trim() !== '') ?? null);
+        dropped.push({ seq: e.seq, kind: e.kind, label, reason: d.replace(/^dropped:/, '') });
+    }
+    return { total: events.length, captured, dropped };
+}
+/** Dedupe key for "same landing page": host+pathname, matching `didNavigate`'s
+ *  notion of same-page (query/hash differences don't make a new landing). */
+function landingKey(url) {
+    try {
+        const u = new URL(url);
+        return u.host + u.pathname;
+    }
+    catch {
+        return url;
+    }
+}
+/** Structure audit (fidelity roadmap 1c/gap-3): per distinct landing, how many
+ *  interactive nodes are named vs NAMELESS. A page thick with nameless controls
+ *  is a sensor gap the review prompt should flag for a frame-by-frame compare. */
+export function landingStructure(effects) {
+    const byKey = new Map();
+    for (const e of effects) {
+        if (!e.toUrl || !e.toSnapshot)
+            continue;
+        const nodes = parseSnapshot(e.toSnapshot);
+        const interactive = nodes.filter((n) => n.ref && PROBE_ROLES.has(n.role));
+        const nameless = namelessInteractive(nodes).length;
+        const named = interactive.length - nameless;
+        const k = landingKey(e.toUrl);
+        const prev = byKey.get(k);
+        // worst-wins: a later, healthier revisit must not hide an earlier gap (tie → keep existing)
+        if (!prev || nameless > prev.nameless)
+            byKey.set(k, { url: e.toUrl, named, nameless });
+    }
+    return [...byKey.values()];
+}

package/dist/recorder/hover-probe.d.ts

@@ -0,0 +1,35 @@
+import { type SnapNode } from '../playwright/snapshot.js';
+/** 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 declare function hoverCandidates(nodes: SnapNode[], limit?: number): SnapNode[];
+export interface HoverProbeStore {
+    isActive(sessionId: string): boolean;
+    appendActionEffect(sessionId: string, fx: unknown): number | null;
+    appendEvent(sessionId: string, ev: unknown): number | null;
+    stampEvent(sessionId: string, seq: number, disposition: string): void;
+}
+export interface HoverProbeAdapter {
+    snapshot(): Promise<string>;
+    hover(ref: string): Promise<unknown>;
+    rightClick(ref: string): Promise<unknown>;
+    press(key: string): Promise<unknown>;
+    currentUrl(): Promise<string>;
+}
+export interface HoverProbeDeps {
+    adapter: HoverProbeAdapter;
+    store: HoverProbeStore;
+    sessionId: string;
+    limit: number;
+    rightClick: boolean;
+    log: (line: string) => void;
+}
+/** 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 declare function runHoverProbe(deps: HoverProbeDeps): Promise<{
+    probed: number;
+    revealed: number;
+}>;