@dikshanty94/webnav 0.2.0

package/dist/playwright/fingerprint.js

@@ -0,0 +1,139 @@
+// ─── layer-3 anchor (the `near` content disambiguator) ───────────────────────
+// All structural, zero-LLM. Verified against the snapshot fixtures in tests/fixtures/.
+/** Ancestors of a node: preceding nodes at strictly-decreasing depth, nearest first. */
+function ancestorsOf(nodes, idx) {
+    const out = [];
+    let minDepth = nodes[idx].depth;
+    for (let i = idx - 1; i >= 0; i--) {
+        if (nodes[i].depth < minDepth) {
+            out.push({ node: nodes[i], idx: i });
+            minDepth = nodes[i].depth;
+        }
+    }
+    return out;
+}
+/** Does ancestor A's bounded subtree (until the next node at depth <= A.depth) contain
+ *  a node matching `pred`? */
+function subtreeHas(nodes, aIdx, aDepth, pred) {
+    for (let j = aIdx + 1; j < nodes.length; j++) {
+        if (nodes[j].depth <= aDepth)
+            break;
+        if (pred(nodes[j], j))
+            return true;
+    }
+    return false;
+}
+/** The LARGEST enclosing ancestor of `candIdx` whose bounded subtree EXCLUDES every other
+ *  candidate (the candidate's per-row/card scope) — or null if none (flat page). NOT the
+ *  nearest container (too small) and NOT the smallest-containing-near (too big). */
+function anchorScope(nodes, candIdx, others) {
+    let scope = null;
+    for (const a of ancestorsOf(nodes, candIdx)) {
+        if (subtreeHas(nodes, a.idx, a.node.depth, (_n, j) => j !== candIdx && others.has(j)))
+            break; // pulls in a sibling candidate → stop
+        scope = a; // still clean → remember, try larger
+    }
+    return scope;
+}
+/** Given a `near` text, which of `candidateIdxs` have it inside their clean anchor scope. */
+export function resolveByNear(nodes, candidateIdxs, near) {
+    const set = new Set(candidateIdxs);
+    const hits = [];
+    for (const ci of candidateIdxs) {
+        const scope = anchorScope(nodes, ci, set);
+        if (!scope)
+            continue;
+        if (subtreeHas(nodes, scope.idx, scope.node.depth, (n, j) => j !== ci && n.name === near))
+            hits.push(ci);
+    }
+    return hits;
+}
+/** 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 function nearStability(text) {
+    let s = 0;
+    if (/\d{3,}/.test(text))
+        s += 3;
+    s += Math.min(text.length, 40) / 40;
+    if (/\s/.test(text) && !/\d/.test(text))
+        s -= 2;
+    return s;
+}
+/** Text-bearing names inside `scope` (doc order, excluding the candidate, skip empty). */
+function scopeTexts(nodes, scope, candIdx) {
+    const out = [];
+    for (let j = scope.idx + 1; j < nodes.length; j++) {
+        if (nodes[j].depth <= scope.node.depth)
+            break;
+        if (j !== candIdx && nodes[j].name && nodes[j].name.trim())
+            out.push(nodes[j].name);
+    }
+    return out;
+}
+/**
+ * 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 function deriveNear(nodes, candIdx, role, name) {
+    const cands = nodes.map((n, i) => ({ n, i })).filter((x) => x.n.role === role && x.n.name === name && x.n.ref).map((x) => x.i);
+    if (cands.length <= 1)
+        return null; // unique by role+name → no near needed
+    if (!cands.includes(candIdx))
+        return null;
+    const scope = anchorScope(nodes, candIdx, new Set(cands));
+    if (!scope)
+        return null;
+    const qualifying = scopeTexts(nodes, scope, candIdx).filter((t) => {
+        const hits = resolveByNear(nodes, cands, t);
+        return hits.length === 1 && hits[0] === candIdx;
+    });
+    if (qualifying.length === 0)
+        return null; // honest flag → escalate
+    qualifying.sort((a, b) => nearStability(b) - nearStability(a)); // prefer durable anchors (D3)
+    return qualifying[0];
+}
+/**
+ * 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 function recoverFingerprint(nodes, ref) {
+    const idx = nodes.findIndex((n) => n.ref === ref);
+    if (idx < 0)
+        return null;
+    const node = nodes[idx];
+    return { role: node.role, name: node.name, near: deriveNear(nodes, idx, node.role, node.name) };
+}
+// ─── resolution (the read path) ──────────────────────────────────────────────
+/**
+ * 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 function resolveByFingerprint(fp, nodes) {
+    if (fp.testId) {
+        const hits = nodes.filter((n) => n.ref && n.testId === fp.testId && n.role === fp.role);
+        if (hits.length === 1)
+            return hits[0].ref;
+        // else fall through — testId is a hint, never an override of role+name
+    }
+    const cands = nodes.map((n, i) => ({ n, i })).filter((x) => x.n.ref && x.n.role === fp.role && x.n.name === fp.name);
+    if (cands.length === 1)
+        return cands[0].n.ref;
+    if (cands.length === 0)
+        return null;
+    if (!fp.near)
+        return null; // genuinely ambiguous, no anchor → escalate
+    const hits = resolveByNear(nodes, cands.map((c) => c.i), fp.near);
+    return hits.length === 1 ? nodes[hits[0]].ref : null;
+}

package/dist/playwright/profile-lock.d.ts

@@ -0,0 +1,15 @@
+export interface LockDeps {
+    readlink: (p: string) => string;
+    isWebnavChrome: (pid: number) => boolean;
+    kill: (pid: number) => void;
+    unlink: (p: string) => void;
+}
+/** Parse the holder pid from a SingletonLock symlink target ("<host>-<pid>"). */
+export declare function lockHolderPid(target: string): number | null;
+/** Reap a live webnav-owned holder + clear stale Singleton* so a launch starts clean. */
+export declare function prepProfileWith(dir: string, deps: LockDeps): void;
+/** Is pid a WEBNAV-launched Chrome (safe to kill), not the user's real one?
+ *  Gate on the profiles path in argv — the user's real Chrome never has that. */
+export declare function isWebnavChromePid(pid: number): boolean;
+/** Production wiring. */
+export declare function prepProfile(dir: string): void;

package/dist/playwright/profile-lock.js

@@ -0,0 +1,51 @@
+// A Chrome profile dir can be opened by only ONE process. A prior webnav Chrome
+// that didn't fully die leaves a SingletonLock (symlink "<host>-<pid>") and keeps
+// the dir held → the next launch fails or hands off to the orphan ("Opening in
+// existing browser session"). prepProfile reaps a LIVE webnav-owned holder and
+// clears the (now stale) Singleton* files before a launch. Deps injected for tests.
+import { readlinkSync, rmSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join } from 'node:path';
+/** Parse the holder pid from a SingletonLock symlink target ("<host>-<pid>"). */
+export function lockHolderPid(target) {
+    const n = Number(target.split('-').pop());
+    return Number.isInteger(n) && n > 0 ? n : null;
+}
+/** Reap a live webnav-owned holder + clear stale Singleton* so a launch starts clean. */
+export function prepProfileWith(dir, deps) {
+    try {
+        const pid = lockHolderPid(deps.readlink(join(dir, 'SingletonLock')));
+        if (pid && deps.isWebnavChrome(pid))
+            deps.kill(pid);
+    }
+    catch { /* no lock / not a symlink → nothing to reap */ }
+    for (const f of ['SingletonLock', 'SingletonSocket', 'SingletonCookie']) {
+        try {
+            deps.unlink(join(dir, f));
+        }
+        catch { /* */ }
+    }
+}
+/** Is pid a WEBNAV-launched Chrome (safe to kill), not the user's real one?
+ *  Gate on the profiles path in argv — the user's real Chrome never has that. */
+export function isWebnavChromePid(pid) {
+    try {
+        const cmd = execSync('ps -p ' + pid + ' -o command=', { encoding: 'utf8' });
+        return cmd.includes('.webnav/profiles') && /chrom/i.test(cmd);
+    }
+    catch {
+        return false;
+    } // ps says gone → dead holder (stale lock)
+}
+/** Production wiring. */
+export function prepProfile(dir) {
+    prepProfileWith(dir, {
+        readlink: (p) => readlinkSync(p),
+        isWebnavChrome: isWebnavChromePid,
+        kill: (pid) => { try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch { /* */ } },
+        unlink: (p) => rmSync(p, { force: true }),
+    });
+}

package/dist/playwright/sessions.d.ts

@@ -0,0 +1,72 @@
+export interface SessionInfo {
+    name: string;
+    live: boolean;
+    ageMs: number;
+    pid?: number;
+}
+export interface ReapOpts {
+    all?: boolean;
+    maxAgeMs?: number;
+    exclude?: string;
+}
+/** Session name out of a daemon command line (`…--daemon-session=/…/<name>.session`). */
+export declare function sessionNameFromPs(line: string): string | null;
+/** Leading PID from a `ps -eo pid,command` line (or null if it has none). */
+export declare function pidFromPs(line: string): number | null;
+/**
+ * Merge on-disk session files with the live daemon process list (`ps -eo pid,command`
+ * lines) into one inventory. `live` = a daemon references the session (browser is up);
+ * a file with no daemon is an ORPHAN; a live daemon with no file still surfaces. Live
+ * sessions carry their daemon `pid` (for reap force-close). Pure — inputs injected.
+ */
+export declare function inventorySessions(files: {
+    name: string;
+    mtimeMs: number;
+}[], psLines: string[], nowMs: number): SessionInfo[];
+/** Which sessions to close. Default: only orphans (dead browser). all → every session.
+ *  maxAgeMs → also live sessions older than the TTL. exclude → never the current session. */
+export declare function planReap(inv: SessionInfo[], opts: ReapOpts): SessionInfo[];
+export declare const DEFAULT_MAX_SESSIONS = 16;
+/** Resolve the ceiling from `WEBNAV_MAX_SESSIONS`; default 16; garbage/≤0 → default. */
+export declare function ceilingFor(envValue: string | undefined): number;
+/** May a NEW daemonized session open? Pure soft-cap inequality — no per-session judgment
+ *  (#5a). `max <= 0` / NaN ⇒ unlimited. Best-effort: with no cross-process lock, concurrent
+ *  openers can briefly overshoot by the number racing — acceptable. */
+export declare function canOpen(liveCount: number, max: number): boolean;
+/** Delete every on-disk `.session` file for `name` (a session can appear under more than
+ *  one daemon subdir). Best-effort: missing files / unreadable dirs are ignored. This is
+ *  what actually clears an ORPHAN from the inventory — `playwright-cli close` only removes
+ *  the file of a LIVE daemon it can talk to, so a dead daemon's stale file lingers forever
+ *  (the reap-says-done-but-count-unchanged bug) unless we unlink it directly. `root` is the
+ *  daemon cache dir (injectable for tests; defaults to the real one). */
+export declare function removeSessionFiles(name: string, root?: string): void;
+/** Live inventory of all playwright-cli sessions on this machine. */
+export declare function listSessions(nowMs: number): Promise<SessionInfo[]>;
+/**
+ * Close one session: graceful `playwright-cli close` first; if that leaves the daemon ALIVE
+ * (wedged daemons ignore close — the case that needed a manual kill), force-kill the daemon
+ * process group (negative pid → the whole tree, reaping its chrome children too). `pid` is
+ * the daemon pid from the inventory; omit for orphans (graceful-only). Returns true if the
+ * session is gone after.
+ */
+export declare function closeSession(name: string, pid?: number): Promise<boolean>;
+/** Reap per `opts`; returns the names actually closed. */
+/** Close a session BY NAME: look up its daemon pid from the live inventory (so the
+ *  force-kill path works if graceful close wedges), then closeSession. */
+export declare function closeByName(name: string): Promise<boolean>;
+export declare function reapSessions(nowMs: number, opts: ReapOpts): Promise<string[]>;
+/**
+ * Enforce the live-session ceiling before a DAEMONIZED verb (walk / use navigate / record)
+ * opens a NEW browser. First frees what it safely can — orphans (dead-browser) AND
+ * abandoned paused-walk browsers older than the stale-walk TTL (the real leak: a `needs-*`
+ * pause leaves a LIVE daemon nothing else collects) — then checks `canOpen`. Returns
+ * `{ ok:true }` to proceed, or `{ ok:false, reason }` to refuse with a clear message.
+ * `staleWalkBrowsers` is the set of browser_session ids of paused walks older than the TTL
+ * (supplied by the caller, which has the WalkSessionStore); never reaps `currentSession`.
+ * Errors degrade to ok:true — the ceiling must never wedge a legitimate command shut on a
+ * housekeeping failure.
+ */
+export declare function ensureCanOpen(currentSession: string, staleWalkBrowsers?: string[]): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;

package/dist/playwright/sessions.js

@@ -0,0 +1,229 @@
+import { execFile } from 'node:child_process';
+import { readdirSync, statSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { wireSessionName } from './adapter.js';
+const execFileAsync = promisify(execFile);
+/** Session name out of a daemon command line (`…--daemon-session=/…/<name>.session`). */
+export function sessionNameFromPs(line) {
+    const m = line.match(/--daemon-session=\S*?\/([^/]+)\.session\b/);
+    return m ? m[1] : null;
+}
+/** Leading PID from a `ps -eo pid,command` line (or null if it has none). */
+export function pidFromPs(line) {
+    const m = line.trim().match(/^(\d+)\s/);
+    return m ? Number(m[1]) : null;
+}
+/**
+ * Merge on-disk session files with the live daemon process list (`ps -eo pid,command`
+ * lines) into one inventory. `live` = a daemon references the session (browser is up);
+ * a file with no daemon is an ORPHAN; a live daemon with no file still surfaces. Live
+ * sessions carry their daemon `pid` (for reap force-close). Pure — inputs injected.
+ */
+export function inventorySessions(files, psLines, nowMs) {
+    const livePid = new Map();
+    for (const line of psLines) {
+        const name = sessionNameFromPs(line);
+        if (name)
+            livePid.set(name, pidFromPs(line) ?? undefined);
+    }
+    const byName = new Map();
+    for (const f of files) {
+        const live = livePid.has(f.name);
+        byName.set(f.name, { name: f.name, live, ageMs: nowMs - f.mtimeMs, ...(live ? { pid: livePid.get(f.name) } : {}) });
+    }
+    for (const [name, pid] of livePid) {
+        if (!byName.has(name))
+            byName.set(name, { name, live: true, ageMs: Infinity, pid });
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Which sessions to close. Default: only orphans (dead browser). all → every session.
+ *  maxAgeMs → also live sessions older than the TTL. exclude → never the current session. */
+export function planReap(inv, opts) {
+    return inv.filter((s) => {
+        if (opts.exclude !== undefined && s.name === opts.exclude)
+            return false; // never our own browser
+        if (opts.all)
+            return true;
+        if (!s.live)
+            return true; // orphan: always reap
+        if (opts.maxAgeMs !== undefined && s.ageMs >= opts.maxAgeMs)
+            return true;
+        return false;
+    });
+}
+// ─── live-session ceiling (prevents the browser-count explosion) ─────────────
+export const DEFAULT_MAX_SESSIONS = 16; // clears the sanctioned 11-agent fan-out with headroom
+/** Resolve the ceiling from `WEBNAV_MAX_SESSIONS`; default 16; garbage/≤0 → default. */
+export function ceilingFor(envValue) {
+    if (!envValue)
+        return DEFAULT_MAX_SESSIONS;
+    const n = Number(envValue);
+    return Number.isInteger(n) && n > 0 ? n : DEFAULT_MAX_SESSIONS;
+}
+/** May a NEW daemonized session open? Pure soft-cap inequality — no per-session judgment
+ *  (#5a). `max <= 0` / NaN ⇒ unlimited. Best-effort: with no cross-process lock, concurrent
+ *  openers can briefly overshoot by the number racing — acceptable. */
+export function canOpen(liveCount, max) {
+    if (!Number.isFinite(max) || max <= 0)
+        return true;
+    return liveCount < max;
+}
+// ─── live wrappers (not unit-tested; thin shells over fs/ps) ──────────────────
+const DAEMON_DIR = join(homedir(), 'Library', 'Caches', 'ms-playwright', 'daemon');
+function listSessionFiles() {
+    const out = [];
+    let dirs = [];
+    try {
+        dirs = readdirSync(DAEMON_DIR);
+    }
+    catch {
+        return out;
+    }
+    for (const d of dirs) {
+        let entries = [];
+        try {
+            entries = readdirSync(join(DAEMON_DIR, d));
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (!e.endsWith('.session'))
+                continue;
+            try {
+                const mtimeMs = statSync(join(DAEMON_DIR, d, e)).mtimeMs;
+                out.push({ name: e.replace(/\.session$/, ''), mtimeMs });
+            }
+            catch { /* file vanished mid-scan */ }
+        }
+    }
+    return out;
+}
+/** Delete every on-disk `.session` file for `name` (a session can appear under more than
+ *  one daemon subdir). Best-effort: missing files / unreadable dirs are ignored. This is
+ *  what actually clears an ORPHAN from the inventory — `playwright-cli close` only removes
+ *  the file of a LIVE daemon it can talk to, so a dead daemon's stale file lingers forever
+ *  (the reap-says-done-but-count-unchanged bug) unless we unlink it directly. `root` is the
+ *  daemon cache dir (injectable for tests; defaults to the real one). */
+export function removeSessionFiles(name, root = DAEMON_DIR) {
+    let dirs = [];
+    try {
+        dirs = readdirSync(root);
+    }
+    catch {
+        return;
+    }
+    for (const d of dirs) {
+        try {
+            rmSync(join(root, d, `${name}.session`), { force: true });
+        }
+        catch { /* gone */ }
+    }
+}
+async function listDaemonPs() {
+    try {
+        const { stdout } = await execFileAsync('ps', ['-eo', 'pid,command'], { maxBuffer: 8 * 1024 * 1024 });
+        return stdout.split('\n').filter((l) => l.includes('--daemon-session='));
+    }
+    catch {
+        return [];
+    }
+}
+/** Live inventory of all playwright-cli sessions on this machine. */
+export async function listSessions(nowMs) {
+    return inventorySessions(listSessionFiles(), await listDaemonPs(), nowMs);
+}
+/** Is a daemon pid still alive? (signal 0 = existence check, doesn't actually signal.) */
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Close one session: graceful `playwright-cli close` first; if that leaves the daemon ALIVE
+ * (wedged daemons ignore close — the case that needed a manual kill), force-kill the daemon
+ * process group (negative pid → the whole tree, reaping its chrome children too). `pid` is
+ * the daemon pid from the inventory; omit for orphans (graceful-only). Returns true if the
+ * session is gone after.
+ */
+export async function closeSession(name, pid) {
+    try {
+        await execFileAsync('playwright-cli', [`-s=${wireSessionName(name)}`, 'close'], { maxBuffer: 1024 * 1024 });
+    }
+    catch { /* graceful close failed; fall through to force-kill if we have a pid */ }
+    if (pid === undefined) {
+        removeSessionFiles(name);
+        return true;
+    } // orphan: unlink the stale file
+    if (!pidAlive(pid)) {
+        removeSessionFiles(name);
+        return true;
+    } // graceful close worked
+    // Wedged: kill the daemon's process GROUP so its chrome children die too. Fall back to the
+    // bare pid if the group kill isn't permitted.
+    try {
+        process.kill(-pid, 'SIGTERM');
+    }
+    catch {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch { /* gone */ }
+    }
+    removeSessionFiles(name); // and sweep the on-disk file regardless
+    return !pidAlive(pid);
+}
+/** Reap per `opts`; returns the names actually closed. */
+/** Close a session BY NAME: look up its daemon pid from the live inventory (so the
+ *  force-kill path works if graceful close wedges), then closeSession. */
+export async function closeByName(name) {
+    const pid = (await listSessions(Date.now())).find((s) => s.name === name)?.pid;
+    return closeSession(name, pid);
+}
+export async function reapSessions(nowMs, opts) {
+    const targets = planReap(await listSessions(nowMs), opts);
+    const closed = [];
+    for (const t of targets)
+        if (await closeSession(t.name, t.pid))
+            closed.push(t.name);
+    return closed;
+}
+/**
+ * Enforce the live-session ceiling before a DAEMONIZED verb (walk / use navigate / record)
+ * opens a NEW browser. First frees what it safely can — orphans (dead-browser) AND
+ * abandoned paused-walk browsers older than the stale-walk TTL (the real leak: a `needs-*`
+ * pause leaves a LIVE daemon nothing else collects) — then checks `canOpen`. Returns
+ * `{ ok:true }` to proceed, or `{ ok:false, reason }` to refuse with a clear message.
+ * `staleWalkBrowsers` is the set of browser_session ids of paused walks older than the TTL
+ * (supplied by the caller, which has the WalkSessionStore); never reaps `currentSession`.
+ * Errors degrade to ok:true — the ceiling must never wedge a legitimate command shut on a
+ * housekeeping failure.
+ */
+export async function ensureCanOpen(currentSession, staleWalkBrowsers = []) {
+    const max = ceilingFor(process.env.WEBNAV_MAX_SESSIONS);
+    try {
+        const now = Date.now();
+        let inv = await listSessions(now);
+        // free orphans + abandoned stale paused-walk browsers (never the current one)
+        const toFree = inv.filter((s) => s.name !== currentSession && (!s.live || staleWalkBrowsers.includes(s.name)));
+        for (const s of toFree)
+            await closeSession(s.name, s.pid);
+        if (toFree.length)
+            inv = await listSessions(Date.now());
+        const liveOthers = inv.filter((s) => s.live && s.name !== currentSession).length;
+        if (!canOpen(liveOthers, max)) {
+            return { ok: false, reason: `session ceiling reached (${liveOthers} live, max ${max}); close some with \`webnav dev sessions reap\` or raise WEBNAV_MAX_SESSIONS` };
+        }
+        return { ok: true };
+    }
+    catch {
+        return { ok: true }; // never wedge a real command shut on a housekeeping error
+    }
+}

package/dist/playwright/snapshot.d.ts

@@ -0,0 +1,10 @@
+export interface SnapNode {
+    role: string;
+    name: string | null;
+    ref: string | null;
+    url: string | null;
+    raw: string;
+    depth: number;
+}
+export declare function parseSnapshot(yml: string): SnapNode[];
+export declare function findByRoleAndName(nodes: SnapNode[], role: string, name?: string): SnapNode | undefined;

package/dist/playwright/snapshot.js

@@ -0,0 +1,52 @@
+// We parse line-by-line with regex rather than the `yaml` dependency on purpose:
+// playwright-cli's snapshot output is YAML-ISH but not valid YAML. Lines carry
+// non-YAML trailing tokens (`link "Learn more" [ref=e6] [cursor=pointer]`) and
+// bare keys like `/url:`, which would make `yaml.parse` choke. Do NOT swap this
+// for the yaml dep without first confirming it handles those trailing tokens.
+// Role token is matched case-insensitively (`\w[\w-]*`): playwright-cli emits
+// both lowercase roles (`link`, `searchbox`) and capitalized ones
+// (`StaticText`, `RootWebArea`, `WebArea`).
+const NODE_RE = /^(\w[\w-]*)\s*(?:"([^"]*)")?/;
+const REF_RE = /\[ref=(e\d+)\]/;
+// Any bracketed attribute, e.g. [ref=e6], [level=1], [cursor=pointer].
+const ATTR_RE = /\[[^\]]+\]/;
+const URL_RE = /^\/url:\s*(.+)$/;
+export function parseSnapshot(yml) {
+    const lines = yml.split('\n');
+    const nodes = [];
+    for (const line of lines) {
+        const depth = line.length - line.replace(/^ */, '').length; // leading-space count, BEFORE trim
+        const trimmed = line.trim().replace(/^-\s*/, '');
+        if (!trimmed)
+            continue;
+        // A `/url:` line declares the destination of the node ON THE LINE BEFORE it.
+        // We attach it to the most-recently-pushed node, assuming the `/url:` line
+        // immediately follows its owning node (true for playwright-cli output).
+        const urlMatch = trimmed.match(URL_RE);
+        if (urlMatch && nodes.length > 0) {
+            nodes[nodes.length - 1].url = urlMatch[1].trim();
+            continue;
+        }
+        const m = trimmed.match(NODE_RE);
+        if (!m || !m[1])
+            continue;
+        // A line is a real node only if it carries structure: a quoted "name", a
+        // bracketed attribute (`[ref=eN]`, `[level=N]`, `[cursor=...]`), or both. A
+        // bare word with none of those is wrapped prose continuation -> skip it.
+        // (Capitalization is NOT a signal: capitalized roles are valid nodes.)
+        const hasName = m[2] !== undefined;
+        const hasAttr = ATTR_RE.test(trimmed);
+        if (!hasName && !hasAttr)
+            continue;
+        const refMatch = trimmed.match(REF_RE);
+        // NOTE: names with escaped quotes (e.g. `"say \"hi\""`) are not handled;
+        // NODE_RE stops the name at the first inner quote. Out of scope for v1.
+        nodes.push({
+            role: m[1], name: m[2] ?? null, ref: refMatch ? refMatch[1] : null, url: null, raw: trimmed, depth,
+        });
+    }
+    return nodes;
+}
+export function findByRoleAndName(nodes, role, name) {
+    return nodes.find((n) => n.role === role && (name === undefined || n.name === name));
+}

package/dist/playwright/throttle.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_HOST_INTERVAL_MS = 1000;
+/** Min interval (ms) between opens to one host, from `WEBNAV_HOST_INTERVAL_MS`. 0/garbage → 0 (off). */
+export declare function intervalMs(envValue: string | undefined): number;
+/** How long to wait before opening `host` again. Pure. last=null (never seen) or interval≤0 → 0. */
+export declare function delayFor(lastOpenMs: number | null, nowMs: number, interval: number): number;
+/** Host of a URL, or null for globs / about:blank / non-URLs (→ skip the throttle). Never throws. */
+export declare function hostOf(url: string): string | null;
+/**
+ * Throttle an open to `url`'s host: read the last-open time, sleep the remaining interval if
+ * any, then record now as the new last-open (atomic UPSERT under the busy_timeout lock).
+ * No-ops for hostless urls (globs/about:blank) and when the interval is 0. Best-effort: any
+ * db error degrades to no-throttle so housekeeping never breaks the actual open.
+ */
+export declare function throttleOpen(url: string, nowMs?: number): Promise<void>;

package/dist/playwright/throttle.js

@@ -0,0 +1,76 @@
+import Database from 'better-sqlite3';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+// Per-host politeness throttle: a minimum interval between page-OPENS to the same host, so a
+// burst of CLI invocations can't hammer one site into a bot-wall (a live incident on a test site).
+// This is POLITENESS, not evasion — it slows webnav down, it never disguises it (the hard
+// no-evasion line, CLAUDE.md). Bot-walls are still detected + escalated; this just stops us
+// provoking one. Each CLI call is a separate PROCESS, so the last-open time must persist
+// CROSS-process — backed by sqlite (file-locked UPSERT) rather than a lockfree JSON that
+// would race under the exact 100-process burst it targets.
+export const DEFAULT_HOST_INTERVAL_MS = 1000;
+/** Min interval (ms) between opens to one host, from `WEBNAV_HOST_INTERVAL_MS`. 0/garbage → 0 (off). */
+export function intervalMs(envValue) {
+    if (!envValue)
+        return DEFAULT_HOST_INTERVAL_MS;
+    const n = Number(envValue);
+    return Number.isFinite(n) && n >= 0 ? n : DEFAULT_HOST_INTERVAL_MS;
+}
+/** How long to wait before opening `host` again. Pure. last=null (never seen) or interval≤0 → 0. */
+export function delayFor(lastOpenMs, nowMs, interval) {
+    if (lastOpenMs === null || interval <= 0)
+        return 0;
+    const elapsed = nowMs - lastOpenMs;
+    return elapsed >= interval ? 0 : interval - elapsed;
+}
+/** Host of a URL, or null for globs / about:blank / non-URLs (→ skip the throttle). Never throws. */
+export function hostOf(url) {
+    if (!url || url.startsWith('about:') || url.includes('*'))
+        return null;
+    try {
+        const h = new URL(url).host;
+        return h || null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── sqlite persistence (cross-process, file-locked) ──────────────────────────
+function throttleDbPath() {
+    // sibling of the creds/config dir; its own tiny db so it never contends with the map db
+    return join(homedir(), '.webnav', 'throttle.db');
+}
+let _db = null;
+function db() {
+    if (_db)
+        return _db;
+    const d = new Database(throttleDbPath());
+    d.pragma('journal_mode = WAL'); // concurrent readers + a writer
+    d.pragma('busy_timeout = 2000'); // wait out a lock under the burst rather than throw
+    d.exec('CREATE TABLE IF NOT EXISTS host_last_open (host TEXT PRIMARY KEY, ts INTEGER NOT NULL)');
+    _db = d;
+    return d;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Throttle an open to `url`'s host: read the last-open time, sleep the remaining interval if
+ * any, then record now as the new last-open (atomic UPSERT under the busy_timeout lock).
+ * No-ops for hostless urls (globs/about:blank) and when the interval is 0. Best-effort: any
+ * db error degrades to no-throttle so housekeeping never breaks the actual open.
+ */
+export async function throttleOpen(url, nowMs = Date.now()) {
+    const interval = intervalMs(process.env.WEBNAV_HOST_INTERVAL_MS);
+    const host = hostOf(url);
+    if (!host || interval <= 0)
+        return;
+    try {
+        const d = db();
+        const row = d.prepare('SELECT ts FROM host_last_open WHERE host=?').get(host);
+        const wait = delayFor(row ? row.ts : null, nowMs, interval);
+        if (wait > 0)
+            await sleep(wait);
+        d.prepare('INSERT INTO host_last_open (host, ts) VALUES (?, ?) ON CONFLICT(host) DO UPDATE SET ts=excluded.ts')
+            .run(host, Date.now());
+    }
+    catch { /* never break a real open on a throttle-bookkeeping failure */ }
+}