@dikshanty94/webnav 0.2.0

package/dist/router/auth-status.d.ts

@@ -0,0 +1,20 @@
+import type { State } from '../mapstore/types.js';
+export type AuthStatus = 'valid' | 'needs-login' | 'unknown';
+export interface AuthClassification {
+    auth: AuthStatus;
+    loginUrl?: string;
+}
+/**
+ * Classify a settled landing page as evidence of whether a profile is still
+ * logged in for `site` (a site-node id / host). Judgment-free: no site-specific
+ * rules, just the three honest signals from the design doc. Reused by the verb
+ * (Task A) and by the walk/use-navigate wall-handling escalation (Task 2).
+ *
+ *   valid        — the snapshot matches a known map content state (⇒ logged in and on a
+ *                  real page — this is the STRONGEST signal, so it wins over the URL-host
+ *                  heuristic below), OR the landing is on `site`'s host with no wall signal.
+ *   needs-login  — foreign-host landing, OR an interstitial/bot-wall, OR a password
+ *                  field is present. loginUrl = the landed url.
+ *   unknown      — everything else (no map yet / ambiguous landing on the right host).
+ */
+export declare function classifyAuthLanding(landedUrl: string, snapshotYaml: string, site: string, states: State[]): AuthClassification;

package/dist/router/auth-status.js

@@ -0,0 +1,55 @@
+import { parseSnapshot } from '../playwright/snapshot.js';
+import { matchState } from '../explorer/fingerprint.js';
+import { classifyReadiness } from './readiness.js';
+/** Host of a URL, or null if unparseable (never throws — same posture as
+ *  playwright/throttle.ts's hostOf). */
+function hostOf(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return null;
+    }
+}
+/** A password field, going only by what parseSnapshot actually exposes: role
+ *  `textbox` with an accessible name matching /password/i. playwright-cli's a11y
+ *  snapshot carries no HTML `type=` attribute, so this is the honest signal
+ *  available (per the design doc) — not a substitute for a real type=password read. */
+function hasPasswordField(nodes) {
+    return nodes.some((n) => n.role === 'textbox' && /password/i.test(n.name ?? ''));
+}
+/**
+ * Classify a settled landing page as evidence of whether a profile is still
+ * logged in for `site` (a site-node id / host). Judgment-free: no site-specific
+ * rules, just the three honest signals from the design doc. Reused by the verb
+ * (Task A) and by the walk/use-navigate wall-handling escalation (Task 2).
+ *
+ *   valid        — the snapshot matches a known map content state (⇒ logged in and on a
+ *                  real page — this is the STRONGEST signal, so it wins over the URL-host
+ *                  heuristic below), OR the landing is on `site`'s host with no wall signal.
+ *   needs-login  — foreign-host landing, OR an interstitial/bot-wall, OR a password
+ *                  field is present. loginUrl = the landed url.
+ *   unknown      — everything else (no map yet / ambiguous landing on the right host).
+ */
+export function classifyAuthLanding(landedUrl, snapshotYaml, site, states) {
+    const nodes = parseSnapshot(snapshotYaml);
+    // MATCH FIRST — a snapshot that matches a known content state (non-empty fingerprint,
+    // every token present; matchState never matches a bare login/shell page) is direct
+    // proof the profile is logged in and on a real page. It OVERRIDES the URL-host
+    // heuristic below: `landedUrl` can be a stale/withheld reading from the driver (e.g.
+    // the extension's chrome.tabs.get returns '' or a mid-navigation host), which used to
+    // trip `foreignHost` and fire a false `needs-login` on an authed SPA. The page itself
+    // is the honest evidence; trust it over the address bar.
+    if (matchState(nodes, states).status === 'matched')
+        return { auth: 'valid' };
+    const landedHost = hostOf(landedUrl);
+    const foreignHost = landedHost !== null && landedHost !== site;
+    if (foreignHost)
+        return { auth: 'needs-login', loginUrl: landedUrl };
+    if (classifyReadiness(snapshotYaml) === 'interstitial') {
+        return { auth: 'needs-login', loginUrl: landedUrl };
+    }
+    if (hasPasswordField(nodes))
+        return { auth: 'needs-login', loginUrl: landedUrl };
+    return { auth: 'unknown' };
+}

package/dist/router/browse.d.ts

@@ -0,0 +1,108 @@
+import type { RecordStore } from '../mapstore/record.js';
+import type { ActionRef } from '../mapstore/record.js';
+import type { State } from '../mapstore/types.js';
+export interface BrowseAdapter {
+    open(url: string): Promise<string>;
+    evalJs?(func: string, ref?: string): Promise<string>;
+    network?(): Promise<string>;
+    goBack?(): Promise<string>;
+    reload?(): Promise<string>;
+    snapshot?(): Promise<string>;
+    act?(ref: string): Promise<void>;
+    fill?(ref: string, text: string): Promise<string | void>;
+    currentUrl?(): Promise<string>;
+    close(): Promise<string>;
+}
+export type EvalResponse = {
+    status: 'done';
+    url: string;
+    value: string;
+} | {
+    status: 'failed';
+    url: string;
+    reason: string;
+};
+export type NetworkResponse = {
+    status: 'done';
+    url: string;
+    requests: string;
+} | {
+    status: 'failed';
+    url: string;
+    reason: string;
+};
+/** Open url, run a `() => value` JS expression in the page, return the value. */
+export declare function runEval(url: string, func: string, adapter?: BrowseAdapter): Promise<EvalResponse>;
+/**
+ * playwright-cli's `eval` prints the value inside a `### Result` block followed
+ * by `### Ran Playwright code` / `### Page` chrome. Extract just the value (and
+ * JSON-decode it if it's a quoted scalar) so the agent gets the answer, not the
+ * wrapper. Falls back to the trimmed raw output if no Result block is present
+ * (e.g. a fake/bare value in tests).
+ */
+export declare function parseEvalResult(raw: string): string;
+/** Open url, return the network requests the page issued (the API calls behind the DOM). */
+export declare function runNetwork(url: string, adapter?: BrowseAdapter): Promise<NetworkResponse>;
+/** Bounded settle: retry while the snapshot classifies as 'loading' (3x700ms) so a
+ *  client-side redirect/late render is never captured as the page (the ghost-state
+ *  class of bugs). Pass `first` when the caller already took the initial snapshot.
+ *  Never infinite: a permanently-loading page proceeds after 3 retries. */
+export declare function settleSnapshot(snap: () => Promise<string>, first?: string): Promise<string>;
+/** X6 landing name-probe: read tooltip/aria labels off the NAMELESS icon controls of a settled
+ *  landing. Returns undefined when the page is fully named (so nameHints stays absent — zero eval
+ *  cost on well-named pages). Best-effort: adapter with no evalJs (a bare fake) probes nothing. */
+export declare function probeLanding(adapter: {
+    evalJs?(js: string, ref?: string): Promise<string>;
+}, toSnapshot: string): Promise<Record<string, string> | undefined>;
+/** Capture + record the effect of a standalone `use navigate` (cli.ts routes here
+ *  AFTER opening `url` on the adapter — caller owns the browser lifecycle and the
+ *  session auto-start). Settles before reading, records requestedUrl = the url the
+ *  agent ASKED for (toUrl may differ on a redirect — the draft's alias evidence).
+ *  Returns toSnapshot too so the caller can classify the landing (e.g. an SSO-wall
+ *  check, design item 2) without an extra playwright call. */
+export declare function recordNavigateEffect(url: string, sessionId: string, recordStore: RecordStore, adapter: BrowseAdapter): Promise<{
+    toUrl: string;
+    toSnapshot: string;
+}>;
+export interface NavigateWallCheck {
+    authWall: boolean;
+    loginUrl?: string;
+}
+/** Design item 2 (`use navigate` half): classify a settled navigate landing as an
+ *  SSO/login wall — SAME classifyAuthLanding oracle as `walk` and `profile-status`,
+ *  applied to the TARGET url's own host + map states — with NO retry (a recording
+ *  captures what actually happened, judgment-free; that's `walk`'s job). Pure
+ *  composition, so it's unit-testable without a live browser. `requestedUrl` is the
+ *  url the agent ASKED to navigate to (its host names the site whose map states to
+ *  check against); an unparseable url honestly reports no wall (nothing to check). */
+export declare function classifyNavigateWall(requestedUrl: string, toUrl: string, toSnapshot: string, states: State[]): NavigateWallCheck;
+export interface SnapshotRecordedResult {
+    status: 'done' | 'failed';
+    url: string;
+    recorded: boolean;
+    reason?: string;
+}
+/** Open `url`, snapshot it, and (if `sessionId` is recording) append an
+ *  observation. The seam that makes a webnav browse contribute to the map. */
+export declare function runSnapshotRecorded(url: string, sessionId: string, recordStore: RecordStore, adapter?: BrowseAdapter): Promise<SnapshotRecordedResult>;
+export interface RunActionArgs {
+    sessionId: string;
+    recordStore: RecordStore;
+    fromUrl: string;
+    fromSnapshot: string;
+    action: ActionRef;
+    text?: string;
+    adapter?: BrowseAdapter;
+}
+export interface ActionRecordedResult {
+    status: 'done' | 'failed';
+    recorded: boolean;
+    navigated?: boolean;
+    reason?: string;
+    stepSeq?: number | null;
+}
+/** Perform the agent's action, capture the after-page, record an ActionEffect.
+ *  webnav does NOT decide what to fire — the agent supplies `action`; we record
+ *  what changed (full before/after + diff + navigated). The caller manages the
+ *  browser lifecycle (an action sequence reuses the session) — we do NOT close. */
+export declare function runActionRecorded(args: RunActionArgs): Promise<ActionRecordedResult>;

package/dist/router/browse.js

@@ -0,0 +1,214 @@
+import { PlaywrightAdapter } from '../playwright/adapter.js';
+import { parseSnapshot } from '../playwright/snapshot.js';
+import { fingerprintPage, declaredLinks } from '../explorer/fingerprint-page.js';
+import { diffSnapshots, didNavigate } from '../explorer/diff.js';
+import { classifyReadiness } from './readiness.js';
+import { classifyAuthLanding } from './auth-status.js';
+import { namelessInteractive, probeNames } from '../recorder/probe.js';
+function newAdapter() {
+    return new PlaywrightAdapter(`browse-${Date.now()}`);
+}
+/** Open url, run a `() => value` JS expression in the page, return the value. */
+export async function runEval(url, func, adapter = newAdapter()) {
+    try {
+        await adapter.open(url);
+        const raw = await adapter.evalJs(func);
+        return { status: 'done', url, value: parseEvalResult(raw) };
+    }
+    catch (e) {
+        return { status: 'failed', url, reason: String(e) };
+    }
+    finally {
+        await adapter.close().catch(() => { });
+    }
+}
+/**
+ * playwright-cli's `eval` prints the value inside a `### Result` block followed
+ * by `### Ran Playwright code` / `### Page` chrome. Extract just the value (and
+ * JSON-decode it if it's a quoted scalar) so the agent gets the answer, not the
+ * wrapper. Falls back to the trimmed raw output if no Result block is present
+ * (e.g. a fake/bare value in tests).
+ */
+export function parseEvalResult(raw) {
+    const m = raw.match(/###\s*Result\s*\n([\s\S]*?)(?:\n###|\s*$)/);
+    const body = (m ? m[1] : raw).trim();
+    try {
+        const parsed = JSON.parse(body);
+        return typeof parsed === 'string' ? parsed : body;
+    }
+    catch {
+        return body;
+    }
+}
+/** Open url, return the network requests the page issued (the API calls behind the DOM). */
+export async function runNetwork(url, adapter = newAdapter()) {
+    try {
+        await adapter.open(url);
+        const requests = (await adapter.network()).trim();
+        return { status: 'done', url, requests };
+    }
+    catch (e) {
+        return { status: 'failed', url, reason: String(e) };
+    }
+    finally {
+        await adapter.close().catch(() => { });
+    }
+}
+/** Bounded settle: retry while the snapshot classifies as 'loading' (3x700ms) so a
+ *  client-side redirect/late render is never captured as the page (the ghost-state
+ *  class of bugs). Pass `first` when the caller already took the initial snapshot.
+ *  Never infinite: a permanently-loading page proceeds after 3 retries. */
+export async function settleSnapshot(snap, first) {
+    let s = first ?? await snap();
+    for (let i = 0; i < 3 && classifyReadiness(s) === 'loading'; i++) {
+        await new Promise((r) => setTimeout(r, 700));
+        s = await snap();
+    }
+    return s;
+}
+/** X6 landing name-probe: read tooltip/aria labels off the NAMELESS icon controls of a settled
+ *  landing. Returns undefined when the page is fully named (so nameHints stays absent — zero eval
+ *  cost on well-named pages). Best-effort: adapter with no evalJs (a bare fake) probes nothing. */
+export async function probeLanding(adapter, toSnapshot) {
+    if (!adapter.evalJs)
+        return undefined;
+    const nameless = namelessInteractive(parseSnapshot(toSnapshot));
+    if (nameless.length === 0)
+        return undefined;
+    const hints = await probeNames({ evalJs: adapter.evalJs.bind(adapter) }, nameless);
+    return Object.keys(hints).length ? hints : undefined;
+}
+/** Capture + record the effect of a standalone `use navigate` (cli.ts routes here
+ *  AFTER opening `url` on the adapter — caller owns the browser lifecycle and the
+ *  session auto-start). Settles before reading, records requestedUrl = the url the
+ *  agent ASKED for (toUrl may differ on a redirect — the draft's alias evidence).
+ *  Returns toSnapshot too so the caller can classify the landing (e.g. an SSO-wall
+ *  check, design item 2) without an extra playwright call. */
+export async function recordNavigateEffect(url, sessionId, recordStore, adapter) {
+    // Ledger the intent BEFORE settling (spec 2026-07-16): an un-stamped row honestly
+    // reads as dropped:unprocessed in coverage if this function has no failure branch
+    // of its own — the caller's try owns errors.
+    const led = recordStore.appendEvent(sessionId, {
+        source: 'agent', kind: 'navigate', descriptor: { cmd: 'navigate', url, fromUrl: url },
+    });
+    const toSnapshot = await settleSnapshot(() => adapter.snapshot());
+    const toUrl = adapter.currentUrl ? await adapter.currentUrl() : url;
+    const nameHints = await probeLanding(adapter, toSnapshot);
+    const stepSeq = recordStore.appendActionEffect(sessionId, {
+        fromUrl: url, fromSnapshot: '', action: null,
+        toUrl, toSnapshot, navigated: true,
+        diff: diffSnapshots([], parseSnapshot(toSnapshot)),
+        requestedUrl: url, nameHints,
+    });
+    if (led != null)
+        recordStore.stampEvent(sessionId, led, stepSeq != null ? 'step:' + stepSeq : 'dropped:not-recorded');
+    return { toUrl, toSnapshot };
+}
+/** Design item 2 (`use navigate` half): classify a settled navigate landing as an
+ *  SSO/login wall — SAME classifyAuthLanding oracle as `walk` and `profile-status`,
+ *  applied to the TARGET url's own host + map states — with NO retry (a recording
+ *  captures what actually happened, judgment-free; that's `walk`'s job). Pure
+ *  composition, so it's unit-testable without a live browser. `requestedUrl` is the
+ *  url the agent ASKED to navigate to (its host names the site whose map states to
+ *  check against); an unparseable url honestly reports no wall (nothing to check). */
+export function classifyNavigateWall(requestedUrl, toUrl, toSnapshot, states) {
+    let site;
+    try {
+        site = new URL(requestedUrl).host;
+    }
+    catch {
+        return { authWall: false };
+    }
+    const { auth, loginUrl } = classifyAuthLanding(toUrl, toSnapshot, site, states);
+    return auth === 'needs-login' ? { authWall: true, loginUrl } : { authWall: false };
+}
+/** Open `url`, snapshot it, and (if `sessionId` is recording) append an
+ *  observation. The seam that makes a webnav browse contribute to the map. */
+export async function runSnapshotRecorded(url, sessionId, recordStore, adapter = newAdapter()) {
+    try {
+        await adapter.open(url);
+        const yml = await adapter.snapshot();
+        const nodes = parseSnapshot(yml);
+        let recorded = false;
+        if (recordStore.isActive(sessionId)) {
+            recordStore.append(sessionId, {
+                url, fingerprint: fingerprintPage(nodes), declaredLinks: declaredLinks(nodes),
+            });
+            recorded = true;
+        }
+        return { status: 'done', url, recorded };
+    }
+    catch (e) {
+        return { status: 'failed', url, recorded: false, reason: String(e) };
+    }
+    finally {
+        await adapter.close().catch(() => { });
+    }
+}
+/** Perform the agent's action, capture the after-page, record an ActionEffect.
+ *  webnav does NOT decide what to fire — the agent supplies `action`; we record
+ *  what changed (full before/after + diff + navigated). The caller manages the
+ *  browser lifecycle (an action sequence reuses the session) — we do NOT close. */
+export async function runActionRecorded(args) {
+    const adapter = args.adapter ?? newAdapter();
+    // Ledger the intent BEFORE acting (spec 2026-07-16): a failed action must still be
+    // on the record. NO typed text in the descriptor — this path has no secret oracle.
+    const led = args.recordStore.appendEvent(args.sessionId, {
+        source: 'agent', kind: args.text != null ? 'type' : 'click',
+        descriptor: { cmd: args.text != null ? 'type' : 'click', ref: args.action.ref,
+            role: args.action.role, name: args.action.name, url: args.fromUrl },
+    });
+    try {
+        if (args.action.ref) {
+            if (args.text != null)
+                await adapter.fill(args.action.ref, args.text);
+            else
+                await adapter.act(args.action.ref);
+        }
+        let toSnapshot = await adapter.snapshot();
+        const toUrl = adapter.currentUrl ? await adapter.currentUrl() : args.fromUrl;
+        const navigated = didNavigate(args.fromUrl, toUrl);
+        // SETTLE before using the snapshot, but ONLY when the action navigated: a
+        // client-side redirect/late render on the NEW page otherwise records a transient
+        // shell as the page (the ghost-state class of bugs). An in-page mutate/reveal has
+        // no such settledness concern — its snapshot IS the (possibly sparse) diff.
+        if (navigated)
+            toSnapshot = await settleSnapshot(() => adapter.snapshot(), toSnapshot);
+        // The clicked node's declared href = the URL the click ASKED for (observed
+        // evidence, judgment-free); the settled toUrl may differ when the server
+        // redirects the declared destination. Recording it lets the draft alias
+        // requestedKey→settledKey. Only a real cross-page http(s) destination
+        // counts: a '#'/javascript: href declares no destination, and recording one
+        // would alias the FROM page onto the TO page (state-merge poison).
+        let requestedUrl;
+        if (navigated && args.action.ref) {
+            const href = parseSnapshot(args.fromSnapshot).find((n) => n.ref === args.action.ref)?.url;
+            if (href) {
+                try {
+                    const abs = new URL(href, args.fromUrl);
+                    if (/^https?:$/.test(abs.protocol) && didNavigate(args.fromUrl, abs.href))
+                        requestedUrl = abs.href;
+                }
+                catch { /* unparseable href → no requested url */ }
+            }
+        }
+        let recorded = false;
+        let stepSeq = null;
+        if (args.recordStore.isActive(args.sessionId)) {
+            stepSeq = args.recordStore.appendActionEffect(args.sessionId, {
+                fromUrl: args.fromUrl, fromSnapshot: args.fromSnapshot, action: args.action,
+                toUrl, toSnapshot, navigated, requestedUrl,
+                diff: diffSnapshots(parseSnapshot(args.fromSnapshot), parseSnapshot(toSnapshot)),
+            });
+            recorded = stepSeq != null;
+        }
+        if (led != null)
+            args.recordStore.stampEvent(args.sessionId, led, stepSeq != null ? 'step:' + stepSeq : 'dropped:not-recorded');
+        return { status: 'done', recorded, navigated, stepSeq };
+    }
+    catch (e) {
+        if (led != null)
+            args.recordStore.stampEvent(args.sessionId, led, 'dropped:failed:' + String(e.message ?? e).slice(0, 120));
+        return { status: 'failed', recorded: false, reason: String(e) };
+    }
+}

package/dist/router/catalog.d.ts

@@ -0,0 +1,18 @@
+import type { MapStore } from '../mapstore/store.js';
+/**
+ * `list` — the table of contents. "What's on this map?" Reads the local store
+ * and returns every site webnav has a map for, with its state count. Pure read,
+ * no browser, no LLM. The agent reads this to learn which sites it can walk.
+ *
+ * (Richer per-site inspection — states, affordances, edges — is `dev graph-show`
+ * / `dev outline` / `dev mermaid`. `list` is just the index.)
+ */
+export interface SiteListing {
+    site: string;
+    homeUrl: string;
+    states: number;
+}
+export interface Coverage {
+    sites: SiteListing[];
+}
+export declare function listCoverage(store: MapStore): Coverage;

package/dist/router/catalog.js

@@ -0,0 +1,6 @@
+export function listCoverage(store) {
+    const sites = store.allNodes()
+        .map((n) => ({ site: n.id, homeUrl: n.homeUrl, states: store.statesForNode(n.id).length }))
+        .sort((a, b) => a.site.localeCompare(b.site));
+    return { sites };
+}

package/dist/router/extract-content.d.ts

@@ -0,0 +1,13 @@
+export interface ContentEvidence {
+    url: string;
+    text: string;
+    relevant: string[];
+}
+/**
+ * Extract answer-relevant readable content from a page snapshot. Zero LLM:
+ * pulls human-readable node names (headings, paragraphs, list items, cells,
+ * links), drops chrome/noise, and (if query terms given) surfaces the lines
+ * that contain those terms as `relevant`. The agent reasons over this compact
+ * text instead of the full raw snapshot.
+ */
+export declare function extractContent(snapshotYaml: string, url: string, queryTerms?: string[]): ContentEvidence;

package/dist/router/extract-content.js

@@ -0,0 +1,87 @@
+import { parseSnapshot } from '../playwright/snapshot.js';
+// Roles whose `name` carries human-readable page content (vs. structural chrome).
+// `generic`/`text` are included on purpose: real pages stash visible prose in
+// generic/text nodes (confirmed against our captured snapshots).
+const CONTENT_ROLES = new Set([
+    'heading',
+    'paragraph',
+    'listitem',
+    'cell',
+    'link',
+    'generic',
+    'text',
+    'button',
+    'term',
+    'definition',
+]);
+// Pure nav boilerplate to drop. Matched case-insensitively against the full
+// node name. These add no answer signal and only inflate the bundle.
+const CHROME = new Set([
+    'skip to content',
+    'skip to main content',
+    'open menu',
+    'close menu',
+    'menu',
+    'search',
+    'toggle navigation',
+]);
+// Cap the compacted text so the bundle stays small — this is the whole point:
+// the agent ingests this instead of the full raw snapshot. ~4000 chars with a
+// little slack.
+const TEXT_CAP = 4000;
+// Most-relevant snippets are capped so `relevant` stays a tight shortlist.
+const RELEVANT_CAP = 20;
+function isChrome(name) {
+    const lower = name.toLowerCase().trim();
+    // Drop empty and single-char names (icon labels, bullets, etc.).
+    if (lower.length <= 1)
+        return true;
+    return CHROME.has(lower);
+}
+/**
+ * Extract answer-relevant readable content from a page snapshot. Zero LLM:
+ * pulls human-readable node names (headings, paragraphs, list items, cells,
+ * links), drops chrome/noise, and (if query terms given) surfaces the lines
+ * that contain those terms as `relevant`. The agent reasons over this compact
+ * text instead of the full raw snapshot.
+ */
+export function extractContent(snapshotYaml, url, queryTerms) {
+    const nodes = parseSnapshot(snapshotYaml);
+    const kept = [];
+    for (const node of nodes) {
+        if (!CONTENT_ROLES.has(node.role.toLowerCase()))
+            continue;
+        const name = node.name?.trim();
+        if (!name)
+            continue;
+        if (isChrome(name))
+            continue;
+        // Dedupe consecutive identical lines (repeated labels, etc.). Keep order.
+        if (kept.length > 0 && kept[kept.length - 1] === name)
+            continue;
+        kept.push(name);
+    }
+    // Compact text, capped for bundle size.
+    const text = kept.join('\n').slice(0, TEXT_CAP);
+    // Query-relevant lines: any line containing ANY term (case-insensitive).
+    // NOTE (v1): terms are matched as plain substrings, so a short term like
+    // 'am' can match inside an unrelated word. Accepted simplification — no
+    // word-boundary logic for v1.
+    let relevant = [];
+    if (queryTerms && queryTerms.length > 0) {
+        const terms = queryTerms
+            .map((t) => t.toLowerCase().trim())
+            .filter((t) => t.length > 0);
+        if (terms.length > 0) {
+            for (const line of kept) {
+                const lower = line.toLowerCase();
+                if (terms.some((t) => lower.includes(t))) {
+                    relevant.push(line);
+                    if (relevant.length >= RELEVANT_CAP)
+                        break;
+                }
+            }
+        }
+    }
+    return { url, text, relevant };
+}

package/dist/router/live-extension-browser.d.ts

@@ -0,0 +1,35 @@
+import { type AXNode } from '../playwright/ax-adapter.js';
+import type { RawAXStep } from '../recorder/ingest.js';
+import type { WalkBrowser } from './walk.js';
+export interface AgentChannel {
+    getAX(): Promise<AXNode[]>;
+    dispatch(cmd: {
+        kind: 'click' | 'type';
+        nodeId: string;
+        text?: string;
+    }): Promise<void>;
+    currentUrl?(): Promise<string>;
+    goto?(url: string): Promise<void>;
+    scroll?(dy: number): Promise<void>;
+}
+export interface RecordingBrowser extends WalkBrowser {
+    /** All completed steps (fromAX/toAX raw, clickedRef = bN in fromAX). Finalizes any
+     *  step still awaiting its post-action snapshot using the last observed AX. */
+    getRecordedSteps(): RawAXStep[];
+}
+/**
+ * WalkBrowser over an AgentChannel — the extension-driven counterpart to
+ * makeLiveWalkBrowser (walk-live.ts), so walkRoute runs UNMODIFIED against a live
+ * tab instead of a playwright-cli session.
+ *
+ * REF FORMAT NOTE: adaptAXTreeWithRefs assigns each node a synthetic `bN` ref
+ * (settled format, tests/playwright/ax-adapter.test.ts asserts /^b\d+$/). But
+ * parseSnapshot's REF_RE only matches `e\d+` (playwright-cli's own format) — a
+ * literal `bN` token would round-trip as SnapNode.ref === null, and every walk-side
+ * consumer (resolveStep, resolveByFingerprint) filters on `n.ref` truthy, so the
+ * walk could never resolve anything. Fix: re-key each node's ref to a sequential
+ * `eN` "walk ref" when serializing, and cache walkRef -> real {nodeId,
+ * backendDOMNodeId} for act() to dispatch against. This is entirely internal to
+ * this file — ax-adapter.ts / snapshot.ts are untouched.
+ */
+export declare function makeLiveExtensionBrowser(channel: AgentChannel, inputs: Record<string, string>): RecordingBrowser;