@dikshanty94/webnav 0.2.0

package/dist/mcp/server.js

@@ -0,0 +1,163 @@
+// MCP wrapper (Phase 5): serve webnav's verbs as Model Context Protocol tools
+// over stdio, so MCP-native agents see them without shelling out. A THIN layer:
+// tools are GENERATED from the cli-spec registry (one tool per verb — the spec
+// stays the single source of truth) and every call executes the real CLI, so
+// the CLI remains primary and the two surfaces cannot drift.
+//
+// Deliberate exception to the one-JSON-object-stdout rule: in `webnav mcp`
+// server mode, stdout carries newline-delimited JSON-RPC 2.0 messages (the MCP
+// stdio transport). Diagnostics still go to stderr.
+import { execFile } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { CONSUMER_COMMANDS, DEV_COMMANDS, VERSION } from '../cli-spec.js';
+// Long-running server modes can't be request/response tools.
+const EXCLUDED = new Set(['dashboard', 'mcp']);
+const PROTOCOL_VERSION = '2025-06-18';
+// `--to-cluster` → schema property `to_cluster` (and back, in argvFor).
+const propName = (flag) => flag.replace(/^--/, '').replace(/-/g, '_');
+const flagName = (prop) => '--' + prop.replace(/_/g, '-');
+function toolFor(spec, dev) {
+    const properties = {};
+    const required = [];
+    for (const a of spec.args) {
+        properties[a.name] = { type: 'string', description: a.description };
+        if (a.required)
+            required.push(a.name);
+    }
+    for (const f of spec.flags) {
+        const p = propName(f.name);
+        if (f.name === '--input') {
+            // Repeatable slot=value pairs (walk's runtime-only inputs).
+            properties[p] = { type: 'array', items: { type: 'string' }, description: f.description };
+        }
+        else {
+            properties[p] = {
+                type: f.takesValue ? 'string' : 'boolean',
+                description: f.description + (f.default !== undefined ? ` (default: ${f.default})` : ''),
+            };
+        }
+    }
+    return {
+        name: 'webnav_' + (dev ? 'dev_' : '') + spec.name.replace(/-/g, '_'),
+        description: spec.summary + ' Example: ' + spec.example,
+        inputSchema: { type: 'object', properties, required },
+        spec,
+        dev,
+    };
+}
+function verbTools() {
+    return [
+        ...CONSUMER_COMMANDS.filter((c) => !EXCLUDED.has(c.name)).map((c) => toolFor(c, false)),
+        ...DEV_COMMANDS.filter((c) => !EXCLUDED.has(c.name)).map((c) => toolFor(c, true)),
+    ];
+}
+/** The MCP tool list (schema only — what tools/list returns). */
+export function mcpTools() {
+    return verbTools().map(({ spec: _s, dev: _d, ...tool }) => tool);
+}
+/** Rebuild the CLI argv for a tool call: positionals in spec order, then flags. */
+export function argvFor(toolName, args) {
+    const tool = verbTools().find((t) => t.name === toolName);
+    if (!tool)
+        throw new Error(`unknown tool: ${toolName}`);
+    const argv = tool.dev ? ['dev', tool.spec.name] : [tool.spec.name];
+    for (const a of tool.spec.args) {
+        const v = args[a.name];
+        if (v !== undefined && v !== null)
+            argv.push(String(v));
+    }
+    for (const f of tool.spec.flags) {
+        const v = args[propName(f.name)];
+        if (v === undefined || v === null)
+            continue;
+        if (f.name === '--input') {
+            for (const pair of Array.isArray(v) ? v : [v])
+                argv.push('--input', String(pair));
+        }
+        else if (!f.takesValue) {
+            if (v === true || v === 'true')
+                argv.push(f.name);
+        }
+        else {
+            argv.push(flagName(propName(f.name)), String(v));
+        }
+    }
+    return argv;
+}
+const ROOT = fileURLToPath(new URL('../..', import.meta.url));
+export const cliExecutor = (argv) => new Promise((resolve) => {
+    const child = execFile(join(ROOT, 'node_modules', '.bin', 'tsx'), [join(ROOT, 'src', 'cli.ts'), ...argv], { maxBuffer: 64 * 1024 * 1024 }, (_err, stdout, stderr) => {
+        if (stderr)
+            process.stderr.write(stderr);
+        resolve({ stdout, code: child.exitCode ?? 0 });
+    });
+});
+/** Handle one JSON-RPC message; null = notification (no response). */
+export async function handleMcpMessage(msg, exec = cliExecutor) {
+    const id = msg.id ?? null;
+    const reply = (result) => ({ jsonrpc: '2.0', id, result });
+    const fail = (code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+    switch (msg.method) {
+        case 'initialize':
+            return reply({
+                protocolVersion: msg.params?.protocolVersion ?? PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: { name: 'webnav', version: VERSION },
+            });
+        case 'notifications/initialized':
+            return null;
+        case 'ping':
+            return reply({});
+        case 'tools/list':
+            return reply({ tools: mcpTools() });
+        case 'tools/call': {
+            const name = msg.params?.name;
+            const args = msg.params?.arguments ?? {};
+            let argv;
+            try {
+                argv = argvFor(name, args);
+            }
+            catch (e) {
+                return fail(-32602, e.message);
+            }
+            const { stdout, code } = await exec(argv);
+            // Exit 2 = error; exit 3 = ran-fine-but-empty (a valid result, not an error).
+            return reply({
+                content: [{ type: 'text', text: stdout.trim() || '{}' }],
+                isError: code === 2,
+            });
+        }
+        default:
+            return id === null ? null : fail(-32601, `method not found: ${msg.method}`);
+    }
+}
+/** stdio loop: one JSON-RPC message per line in, one per line out. */
+export function startMcpServer(exec = cliExecutor) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin });
+        let pending = Promise.resolve();
+        rl.on('line', (line) => {
+            if (!line.trim())
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                process.stdout.write(JSON.stringify({
+                    jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' },
+                }) + '\n');
+                return;
+            }
+            // Serialize handling so responses keep request order.
+            pending = pending.then(async () => {
+                const res = await handleMcpMessage(msg, exec);
+                if (res)
+                    process.stdout.write(JSON.stringify(res) + '\n');
+            });
+        });
+        rl.on('close', () => { void pending.then(resolve); });
+    });
+}

package/dist/paths.d.ts

@@ -0,0 +1,10 @@
+export declare function webnavDir(): string;
+/** The shared map DB path. Honors WEBNAV_DB (override / tests); otherwise the
+ *  per-user ~/.webnav/webnav.db. Ensures ~/.webnav exists for a real file path
+ *  (an in-memory ':memory:' override needs no directory). */
+export declare function dbPath(): string;
+/** Non-secret CLI config (the hosted-route API key + optional API base URL) at
+ *  ~/.webnav/config.json. SEPARATE from credentials.json (site logins) and the
+ *  map DB — this only holds the hosted-service key, never site credentials.
+ *  Honors WEBNAV_CONFIG (tests). */
+export declare function configPath(): string;

package/dist/paths.js

@@ -0,0 +1,33 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+// Single source of truth for where webnav keeps its STATE on a laptop.
+//
+// The map (SQLite) is a per-USER resource, not per-directory: every session and
+// every agent on the machine should share ONE map regardless of which folder it
+// runs webnav from. So the DB lives at ~/.webnav/webnav.db (next to the creds
+// file at ~/.webnav/credentials.json), NOT as a CWD-relative 'webnav.db' — the
+// latter silently gave each working directory its own map ("works in one
+// terminal, empty in another"). WEBNAV_DB overrides (tests pass ':memory:').
+export function webnavDir() {
+    const dir = join(homedir(), '.webnav');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+/** The shared map DB path. Honors WEBNAV_DB (override / tests); otherwise the
+ *  per-user ~/.webnav/webnav.db. Ensures ~/.webnav exists for a real file path
+ *  (an in-memory ':memory:' override needs no directory). */
+export function dbPath() {
+    const override = process.env.WEBNAV_DB;
+    if (override)
+        return override;
+    return join(webnavDir(), 'webnav.db');
+}
+/** Non-secret CLI config (the hosted-route API key + optional API base URL) at
+ *  ~/.webnav/config.json. SEPARATE from credentials.json (site logins) and the
+ *  map DB — this only holds the hosted-service key, never site credentials.
+ *  Honors WEBNAV_CONFIG (tests). */
+export function configPath() {
+    return process.env.WEBNAV_CONFIG ?? join(webnavDir(), 'config.json');
+}

package/dist/playwright/adapter.d.ts

@@ -0,0 +1,62 @@
+export type RunFn = (args: string[]) => Promise<string>;
+export type ReadFileFn = (path: string) => string;
+export interface BrowserOpts {
+    headed?: boolean;
+    persistent?: boolean;
+    profile?: string;
+    browser?: string;
+    configPath?: string;
+}
+export declare function wireSessionName(name: string): string;
+export declare class PlaywrightAdapter {
+    private session;
+    private run;
+    private readFile;
+    private opts;
+    callCount: number;
+    constructor(session: string, run?: RunFn, readFile?: ReadFileFn, opts?: BrowserOpts);
+    private exec;
+    /** The `open`-only launch flags from BrowserOpts (headed/persistent/profile/browser/config). */
+    private openFlags;
+    open(url: string): Promise<string>;
+    goto(url: string): Promise<string>;
+    click(ref: string): Promise<string>;
+    rightClick(ref: string): Promise<string>;
+    fill(ref: string, text: string): Promise<string>;
+    type(text: string): Promise<string>;
+    press(key: string): Promise<string>;
+    hover(ref: string): Promise<string>;
+    evalJs(func: string, ref?: string): Promise<string>;
+    network(): Promise<string>;
+    goBack(): Promise<string>;
+    reload(): Promise<string>;
+    waitFor(condition: string): Promise<string>;
+    close(): Promise<string>;
+    /** Fire an action on a ref (alias for click — the agent decides what to fire). */
+    act(ref: string): Promise<undefined>;
+    /** Current page URL. Extracts the value from playwright-cli's `### Result`
+     *  wrapper (if present) and strips the surrounding quotes off the scalar. */
+    currentUrl(): Promise<string>;
+    /** Returns the snapshot YAML content (reads the file path printed by the CLI). */
+    snapshot(): Promise<string>;
+    /** Session video: start/stop recording of the driven window. stop() writes to the
+     *  given filename (playwright-cli --filename) — best-effort, never throws. */
+    videoStart(): Promise<void>;
+    videoStop(filename: string): Promise<boolean>;
+    /** Screenshot the current page; returns the .png path playwright-cli printed, or
+     *  null if none was found (callers treat shots as optional decoration). */
+    screenshot(): Promise<string | null>;
+    /**
+     * Snapshot, but RETRY until the page is `ready` (a JS-SPA renders after first paint, so an
+     * immediate snapshot catches an unfinished shell). Re-snapshots up
+     * to `tries` times, `gapMs` apart, returning as soon as `classifyReadiness === 'ready'`;
+     * returns the last snapshot if the budget is exhausted (so the caller still classifies it —
+     * a genuine interstitial/bot-wall is surfaced, never evaded). The one-shot verbs (read /
+     * eval-on-page / search visits) use THIS instead of a bare snapshot.
+     */
+    snapshotReady(tries?: number, gapMs?: number): Promise<string>;
+}
+/** A --profile value is either an absolute/relative PATH (has a slash) or a bare
+ *  session NAME → ~/.webnav/profiles/<name> (the dir the dashboard's persistent
+ *  recording writes; a hand-done login/2FA there carries into every walk). Pure. */
+export declare function resolveProfile(value: string, profilesRoot: string): string;

package/dist/playwright/adapter.js

@@ -0,0 +1,145 @@
+import { execFile } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { promisify } from 'node:util';
+import { throttleOpen } from './throttle.js';
+import { classifyReadiness } from '../router/readiness.js';
+const execFileAsync = promisify(execFile);
+const defaultRun = async (args) => {
+    const { stdout } = await execFileAsync('playwright-cli', args, { maxBuffer: 10 * 1024 * 1024 });
+    return stdout;
+};
+// macOS caps a unix-socket path (sun_path) at 104 bytes. playwright-cli's socket is
+// $TMPDIR/playwright-cli/<16-char-hash>/<session>.sock and the darwin TMPDIR prefix is
+// ~82 chars — so a session NAME over ~16 chars can hit `listen EINVAL` (live crash:
+// 'replay-report-builder', 21 chars). Deterministic cap: same input → same wire name,
+// so reattach through this adapter keeps working; names ≤16 are untouched (every seed/
+// walk/record name in use today).
+const WIRE_MAX = 16;
+// djb2 xor variant — cheap, deterministic, good-enough spread for a 6-hex-digit tag.
+export function wireSessionName(name) {
+    if (name.length <= WIRE_MAX)
+        return name;
+    let h = 5381;
+    for (let i = 0; i < name.length; i++)
+        h = ((h * 33) ^ name.charCodeAt(i)) >>> 0;
+    const head = name.slice(0, 9).replace(/[^\w.-]/g, '_');
+    return head + '-' + h.toString(16).padStart(6, '0').slice(0, 6);
+}
+export class PlaywrightAdapter {
+    session;
+    run;
+    readFile;
+    opts;
+    callCount = 0;
+    constructor(session, run = defaultRun, readFile = (p) => readFileSync(p, 'utf8'), opts = { headed: true }) {
+        this.session = session;
+        this.run = run;
+        this.readFile = readFile;
+        this.opts = opts;
+        this.session = wireSessionName(session);
+    }
+    async exec(...args) {
+        this.callCount++;
+        return this.run([`-s=${this.session}`, ...args]);
+    }
+    /** The `open`-only launch flags from BrowserOpts (headed/persistent/profile/browser/config). */
+    openFlags() {
+        const f = [];
+        if (this.opts.headed)
+            f.push('--headed');
+        if (this.opts.persistent)
+            f.push('--persistent');
+        if (this.opts.profile)
+            f.push('--profile', this.opts.profile);
+        if (this.opts.browser)
+            f.push('--browser', this.opts.browser);
+        // --config launches the window MAXIMIZED (viewport follows the window). Headed only:
+        // headless has no window to maximize and wants a fixed viewport, so skip it there.
+        if (this.opts.configPath && this.opts.headed)
+            f.push('--config', this.opts.configPath);
+        return f;
+    }
+    // open/goto are the NEW-client / explicit-jump page loads — gate them with the per-host
+    // politeness throttle so a burst can't hammer one site. Intra-session clicks (below) are
+    // NOT throttled: a held session navigating its own pages isn't a new client.
+    async open(url) { await throttleOpen(url); return this.exec('open', url, ...this.openFlags()); }
+    async goto(url) { await throttleOpen(url); return this.exec('goto', url); }
+    click(ref) { return this.exec('click', ref); }
+    rightClick(ref) { return this.exec('click', ref, 'right'); }
+    fill(ref, text) { return this.exec('fill', ref, text); }
+    type(text) { return this.exec('type', text); }
+    press(key) { return this.exec('press', key); }
+    hover(ref) { return this.exec('hover', ref); }
+    evalJs(func, ref) { return this.exec('eval', func, ...(ref ? [ref] : [])); }
+    network() { return this.exec('network'); }
+    goBack() { return this.exec('go-back'); }
+    reload() { return this.exec('reload'); }
+    waitFor(condition) { return this.exec('wait-for', condition); }
+    close() { return this.exec('close'); }
+    /** Fire an action on a ref (alias for click — the agent decides what to fire). */
+    act(ref) { return this.click(ref).then(() => undefined); }
+    /** Current page URL. Extracts the value from playwright-cli's `### Result`
+     *  wrapper (if present) and strips the surrounding quotes off the scalar. */
+    async currentUrl() {
+        const raw = await this.evalJs('() => location.href');
+        const m = raw.match(/###\s*Result\s*\n([\s\S]*?)(?:\n###|\s*$)/);
+        const body = (m ? m[1] : raw).trim();
+        return body.replace(/^"|"$/g, '');
+    }
+    /** Returns the snapshot YAML content (reads the file path printed by the CLI). */
+    async snapshot() {
+        const out = await this.exec('snapshot');
+        const m = out.match(/\(([^)]+\.yml)\)/);
+        if (!m)
+            throw new Error('snapshot: could not find YAML path in CLI output');
+        return this.readFile(m[1]);
+    }
+    /** Session video: start/stop recording of the driven window. stop() writes to the
+     *  given filename (playwright-cli --filename) — best-effort, never throws. */
+    async videoStart() { await this.exec('video-start'); } // caller logs failure
+    async videoStop(filename) {
+        try {
+            await this.exec('video-stop', '--filename', filename);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Screenshot the current page; returns the .png path playwright-cli printed, or
+     *  null if none was found (callers treat shots as optional decoration). */
+    async screenshot() {
+        try {
+            const out = await this.exec('screenshot');
+            const m = out.match(/\(([^)]+\.png)\)/) ?? out.match(/(\/\S+\.png)/);
+            return m ? m[1] : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Snapshot, but RETRY until the page is `ready` (a JS-SPA renders after first paint, so an
+     * immediate snapshot catches an unfinished shell). Re-snapshots up
+     * to `tries` times, `gapMs` apart, returning as soon as `classifyReadiness === 'ready'`;
+     * returns the last snapshot if the budget is exhausted (so the caller still classifies it —
+     * a genuine interstitial/bot-wall is surfaced, never evaded). The one-shot verbs (read /
+     * eval-on-page / search visits) use THIS instead of a bare snapshot.
+     */
+    async snapshotReady(tries = 6, gapMs = 800) {
+        let snap = await this.snapshot();
+        for (let i = 0; i < tries && classifyReadiness(snap) === 'loading'; i++) {
+            await new Promise((r) => setTimeout(r, gapMs));
+            snap = await this.snapshot();
+        }
+        return snap;
+    }
+}
+/** A --profile value is either an absolute/relative PATH (has a slash) or a bare
+ *  session NAME → ~/.webnav/profiles/<name> (the dir the dashboard's persistent
+ *  recording writes; a hand-done login/2FA there carries into every walk). Pure. */
+export function resolveProfile(value, profilesRoot) {
+    if (value.includes('/'))
+        return value;
+    return profilesRoot.replace(/\/$/, '') + '/' + value.replace(/[^\w.-]/g, '_');
+}

package/dist/playwright/ax-adapter.d.ts

@@ -0,0 +1,33 @@
+import type { SnapNode } from './snapshot.js';
+export interface AXNode {
+    nodeId: string;
+    ignored?: boolean;
+    role?: {
+        value: string;
+    };
+    name?: {
+        value: string;
+    };
+    properties?: {
+        name: string;
+        value: {
+            value?: unknown;
+        };
+    }[];
+    childIds?: string[];
+    parentId?: string;
+    backendDOMNodeId?: number;
+}
+/** AX tree (flat, childIds-linked) → SnapNode[] in document order, depth = nesting.
+ *  Every emitted node gets a synthetic ref (b1,b2,…) — playwright refs every node too,
+ *  and cross-resolve compares fingerprints (role+name+near), never the ref strings. */
+export declare function adaptAXTree(nodes: AXNode[]): SnapNode[];
+/** AX tree → both SnapNode[] and a Map<bN ref, {nodeId, backendDOMNodeId}> for CDP driving.
+ *  The nodes are identical to adaptAXTree; the refMap enables clicking via ref. */
+export declare function adaptAXTreeWithRefs(nodes: AXNode[]): {
+    nodes: SnapNode[];
+    refMap: Map<string, {
+        nodeId: string;
+        backendDOMNodeId?: number;
+    }>;
+};

package/dist/playwright/ax-adapter.js

@@ -0,0 +1,76 @@
+// CDP roles playwright folds away (text merged into parent names, or structural/
+// presentational wrappers) or that are the document root. Dropping these makes the
+// two producers structurally comparable.
+//
+// `option` and `MenuListPopup` are dropped deliberately, not just for parity: a native
+// <select>'s options are a VALUE DOMAIN (the choices a user could pick), and the map
+// stores structure, never data values (CLAUDE.md "map stores structure not values").
+// Surfacing them would leak instance data into the skeleton the same way an option
+// list or instance heading would.
+const DROP = new Set([
+    'RootWebArea', 'StaticText', 'InlineTextBox', 'LineBreak', 'none', 'presentation',
+    'option', 'MenuListPopup', 'LabelText', 'Legend',
+]);
+// CDP role token → playwright/ARIA vocabulary. Chromium already returns ARIA-canonical
+// tokens for checkbox/radio/switch/combobox/menu/menuitem/menuitemcheckbox/button —
+// verified empirically against tests/fixtures/ax/rich.ax.json — so `image`→`img` is the
+// only translation needed.
+const ROLE_MAP = { image: 'img' };
+function prop(n, name) {
+    return n.properties?.find((p) => p.name === name)?.value?.value;
+}
+/** Internal walk function shared by adaptAXTree and adaptAXTreeWithRefs.
+ *  Traverses the AX tree and emits SnapNode[], optionally building a refMap.
+ */
+function walkAXTree(nodes, collectRefs = false) {
+    const byId = new Map(nodes.map((n) => [n.nodeId, n]));
+    const root = nodes.find((n) => !n.parentId) ?? nodes[0];
+    const out = [];
+    const refMap = collectRefs ? new Map() : null;
+    let ref = 0;
+    const visit = (id, depth) => {
+        const n = byId.get(id);
+        if (!n)
+            return;
+        const rawRole = n.role?.value ?? '';
+        const kept = !n.ignored && rawRole && !DROP.has(rawRole);
+        let childDepth = depth;
+        if (kept) {
+            const role = ROLE_MAP[rawRole] ?? rawRole;
+            const nm = (n.name?.value ?? '').trim();
+            const url = prop(n, 'url');
+            const bRef = 'b' + (++ref);
+            out.push({
+                role,
+                name: nm || null,
+                ref: bRef,
+                url: typeof url === 'string' && url ? url : null,
+                raw: `${role}${nm ? ` "${nm}"` : ''} [ref=${bRef}]`,
+                depth,
+            });
+            if (refMap) {
+                refMap.set(bRef, { nodeId: n.nodeId, backendDOMNodeId: n.backendDOMNodeId });
+            }
+            childDepth = depth + 1;
+        }
+        for (const c of n.childIds ?? [])
+            visit(c, childDepth);
+    };
+    visit(root.nodeId, 0);
+    return { nodes: out, refMap };
+}
+/** AX tree (flat, childIds-linked) → SnapNode[] in document order, depth = nesting.
+ *  Every emitted node gets a synthetic ref (b1,b2,…) — playwright refs every node too,
+ *  and cross-resolve compares fingerprints (role+name+near), never the ref strings. */
+export function adaptAXTree(nodes) {
+    return walkAXTree(nodes, false).nodes;
+}
+/** AX tree → both SnapNode[] and a Map<bN ref, {nodeId, backendDOMNodeId}> for CDP driving.
+ *  The nodes are identical to adaptAXTree; the refMap enables clicking via ref. */
+export function adaptAXTreeWithRefs(nodes) {
+    const result = walkAXTree(nodes, true);
+    return {
+        nodes: result.nodes,
+        refMap: result.refMap,
+    };
+}

package/dist/playwright/capture.d.ts

@@ -0,0 +1,2 @@
+/** Dev helper: open a URL and save its snapshot YAML to `out` (spec §6 fixtures). */
+export declare function capture(url: string, out: string): Promise<void>;

package/dist/playwright/capture.js

@@ -0,0 +1,10 @@
+import { PlaywrightAdapter } from './adapter.js';
+/** Dev helper: open a URL and save its snapshot YAML to `out` (spec §6 fixtures). */
+export async function capture(url, out) {
+    const a = new PlaywrightAdapter(`capture-${Date.now()}`);
+    await a.open(url);
+    const yml = await a.snapshot();
+    const { writeFileSync } = await import('node:fs');
+    writeFileSync(out, yml);
+    await a.close();
+}

package/dist/playwright/fingerprint.d.ts

@@ -0,0 +1,40 @@
+import type { SnapNode } from './snapshot.js';
+export interface ElementFingerprint {
+    role: string;
+    name: string | null;
+    testId?: string | null;
+    placeholder?: string | null;
+    near?: string | null;
+}
+/** Given a `near` text, which of `candidateIdxs` have it inside their clean anchor scope. */
+export declare function resolveByNear(nodes: SnapNode[], candidateIdxs: number[], near: string): number[];
+/** Stability score for a candidate `near` text (HIGHER = more durable). Prefers anchors
+ *  that survive content edits/i18n: +3 id-like (3+ digit run), +0..1 length, -2 free-text
+ *  prose (space + no digit). Pure, deterministic. */
+export declare function nearStability(text: string): number;
+/**
+ * Choose WHICH text to store as `near` for a target candidate (the matcher's twin —
+ * used at BOTH record-time and step-5 heal so they never diverge). Collect every
+ * text in the candidate's clean scope that UNIQUELY resolves to it, then pick the MOST
+ * STABLE (nearStability desc; doc order tiebreak). null = honest "can't make unique" flag
+ * (a truly content-identical sibling) → the caller escalates.
+ */
+export declare function deriveNear(nodes: SnapNode[], candIdx: number, role: string, name: string | null): string | null;
+/**
+ * Recover a durable ElementFingerprint for the element at `ref` in a live snapshot —
+ * role + accessible name + (when the element has same-(role,name) siblings) a `near`
+ * content anchor. Used at record-time (the clicked element) and at heal-time (the
+ * agent-chosen element) so both produce the same durable key. Returns null if the ref
+ * isn't in the snapshot.
+ */
+export declare function recoverFingerprint(nodes: SnapNode[], ref: string): ElementFingerprint | null;
+/**
+ * Resolve an ElementFingerprint to a live element ref, deterministically (zero-LLM).
+ * Strict order:
+ *  1. testId (when present) + role match → unique? return it. (Inert in v1: a11y snapshots
+ *     carry no testid; testId never overrides the durable role+name key.)
+ *  2. candidates = role==fp.role AND name==fp.name. 1 → return; 0 → null (drift); >1 → step 3.
+ *  3. fp.near present → resolveByNear; exactly 1 → return; else null (escalate).
+ * Returns null on no/ambiguous match — the caller escalates to the agent (#5a).
+ */
+export declare function resolveByFingerprint(fp: ElementFingerprint, nodes: SnapNode[]): string | null;