@dikshanty94/webnav 0.2.0

package/dist/router/live-extension-browser.js

@@ -0,0 +1,175 @@
+import { adaptAXTreeWithRefs } from '../playwright/ax-adapter.js';
+import { parseSnapshot, findByRoleAndName } from '../playwright/snapshot.js';
+/**
+ * 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 function makeLiveExtensionBrowser(channel, inputs) {
+    let calls = 0;
+    let lastSnapshot = '';
+    let refMap = new Map();
+    // --- recording state (all internal; snapshot()/act()/goto() behavior is unchanged) ---
+    // The raw AX + eN->bN map of the CURRENT snapshot. We must keep the RAW ax (not the
+    // eN-rekeyed SnapNode[]) because ingestAX re-adapts fromAX itself and looks up the
+    // clicked node by its bN ref — the same ref adaptAXTreeWithRefs assigned here.
+    let lastAX = [];
+    let lastUrl = '';
+    let eToB = new Map();
+    const steps = [];
+    // A step whose action has fired but whose post-action AX isn't observed yet. The next
+    // refresh() completes it (toAX = that snapshot); getRecordedSteps() finalizes any leftover.
+    let pending = null;
+    // URL is fetched only when a step actually needs it (begin/complete), never on every
+    // bare snapshot — avoids an extra channel round-trip per agent read. Falls back to the
+    // last known url when the channel can't report one (unit fake / test channel).
+    async function url() {
+        return channel.currentUrl ? await channel.currentUrl() : lastUrl;
+    }
+    async function completePending(toAX) {
+        if (!pending)
+            return;
+        const p = pending;
+        pending = null; // clear before await so a re-entrant begin can't double-close
+        // tMs = when this step's post-action snapshot landed → the ledger shows real per-step
+        // times instead of the single flush-time. (Browser runtime: Date.now() is fine here.)
+        steps.push({ fromUrl: p.fromUrl, fromAX: p.fromAX, toUrl: await url(), toAX, clickedRef: p.clickedRef, tMs: Date.now() });
+    }
+    // Open a step for a just-fired action. fromAX/fromUrl = the last observed snapshot;
+    // clickedRef = the bN in that fromAX for the eN acted on (null for a pure goto). If an
+    // action was already pending (no snapshot since), close it first using the current AX
+    // so we never drop a step or mis-pair two actions.
+    async function beginStep(clickedRef) {
+        if (pending)
+            await completePending(lastAX);
+        pending = { fromUrl: await url(), fromAX: lastAX, clickedRef };
+    }
+    async function refresh() {
+        const ax = await channel.getAX();
+        calls++;
+        // A prior action was awaiting its landing — THIS snapshot is it.
+        await completePending(ax);
+        const { nodes, refMap: bRefMap } = adaptAXTreeWithRefs(ax);
+        const walkRefMap = new Map();
+        const walkEToB = new Map();
+        const lines = [];
+        nodes.forEach((n, i) => {
+            const walkRef = 'e' + (i + 1);
+            const real = bRefMap.get(n.ref); // every emitted node has a ref (ax-adapter invariant)
+            walkRefMap.set(walkRef, real);
+            walkEToB.set(walkRef, n.ref); // retain eN -> bN so a recorded click maps to fromAX's bN
+            const raw = n.ref ? n.raw.replace(`[ref=${n.ref}]`, `[ref=${walkRef}]`) : n.raw;
+            lines.push(' '.repeat(n.depth) + raw);
+            if (n.url)
+                lines.push(' '.repeat(n.depth + 1) + '/url: ' + n.url);
+        });
+        refMap = walkRefMap;
+        eToB = walkEToB;
+        lastAX = ax;
+        lastSnapshot = lines.join('\n');
+        return lastSnapshot;
+    }
+    // eN (what the walk/agent acts on) -> bN (the ref indexing the RAW fromAX ingestAX
+    // re-adapts). THIS is the pairing trap: recording the eN would make ingestAX's
+    // fromNodes.find(n => n.ref === clickedRef) miss (adapted nodes carry bN, not eN).
+    function clickedBRef(ref) {
+        return eToB.get(ref) ?? null;
+    }
+    // Resolve a textbox ref by accessible name against the CACHED snapshot (mirrors
+    // makeLiveWalkBrowser's fieldRef), refreshing once on miss.
+    async function fieldRef(name) {
+        let nodes = parseSnapshot(lastSnapshot);
+        let node = findByRoleAndName(nodes, 'textbox', name);
+        if (!node || !node.ref) {
+            await refresh();
+            nodes = parseSnapshot(lastSnapshot);
+            node = findByRoleAndName(nodes, 'textbox', name);
+        }
+        if (!node || !node.ref)
+            throw new Error('live-extension-browser: could not resolve textbox "' + name + '"');
+        return node.ref;
+    }
+    function nodeIdFor(ref) {
+        const entry = refMap.get(ref);
+        if (!entry)
+            throw new Error('live-extension-browser: ref "' + ref + '" not found in the current snapshot');
+        return entry.nodeId;
+    }
+    async function dispatchClick(ref) {
+        await channel.dispatch({ kind: 'click', nodeId: nodeIdFor(ref) });
+        calls++;
+    }
+    async function dispatchType(ref, text) {
+        await channel.dispatch({ kind: 'type', nodeId: nodeIdFor(ref), text });
+        calls++;
+    }
+    const browser = {
+        snapshot: () => refresh(),
+        callCount: () => calls,
+        waitMs: (ms) => new Promise((r) => setTimeout(r, ms)),
+        act: async (ref, inputSlot) => {
+            // ponytail: commit-gating (hard rule #2) is walkRoute's job, not the
+            // browser's — act() doesn't see the edge, so it just resolves+dispatches.
+            // RECORD the SEMANTIC clicked node (ref = the button), NOT the credential/shipping
+            // pre-fills below. Resolve its bN NOW — a fieldRef miss can refresh() and rebuild
+            // eToB, which would invalidate this ref's mapping.
+            await beginStep(clickedBRef(ref));
+            if (inputSlot === 'credentials') {
+                await dispatchType(await fieldRef('Username'), inputs.username);
+                await dispatchType(await fieldRef('Password'), inputs.password);
+                await dispatchClick(ref);
+                return;
+            }
+            if (inputSlot === 'shipping') {
+                await dispatchType(await fieldRef('First Name'), inputs.firstName ?? 'A');
+                await dispatchType(await fieldRef('Last Name'), inputs.lastName ?? 'B');
+                await dispatchType(await fieldRef('Zip/Postal Code'), inputs.zip);
+                await dispatchClick(ref);
+                return;
+            }
+            await dispatchClick(ref);
+        },
+        // A standalone type (the agent's `type` tool). Records the typed FIELD's identity
+        // (role+name+fp), NEVER the text — the step carries no value (secret-safe).
+        typeText: async (ref, text) => {
+            await beginStep(clickedBRef(ref));
+            await dispatchType(ref, text);
+        },
+        getRecordedSteps: () => {
+            // Finalize a step whose landing was never snapshotted (run ended right after an
+            // action): use its own fromAX as toAX. didNavigate('','') → false; a degenerate but
+            // honest same-page effect, better than dropping the click entirely.
+            if (pending) {
+                steps.push({ fromUrl: pending.fromUrl, fromAX: pending.fromAX, toUrl: pending.fromUrl, toAX: pending.fromAX, clickedRef: pending.clickedRef, tMs: Date.now() });
+                pending = null;
+            }
+            return steps;
+        },
+    };
+    if (channel.goto) {
+        // A pure navigation: clickedRef = null. beginStep captures the current page as fromAX;
+        // the next snapshot (or getRecordedSteps) supplies toAX.
+        browser.goto = async (url) => { await beginStep(null); await channel.goto(url); };
+    }
+    if (channel.scroll) {
+        // A pure in-page reveal (no navigation, no click) — records NO step. The next
+        // snapshot() naturally picks up whatever scrolled into view.
+        browser.scroll = (dy) => channel.scroll(dy);
+    }
+    if (channel.currentUrl) {
+        browser.currentUrl = () => channel.currentUrl();
+    }
+    // ponytail: no reopenFresh — the extension can't reopen a fresh browser tab;
+    // walkRoute already treats an absent reopenFresh as "skip the wall retry".
+    return browser;
+}

package/dist/router/path.d.ts

@@ -0,0 +1,7 @@
+import type { MapStore } from '../mapstore/store.js';
+/**
+ * Weighted shortest path (Dijkstra) over graph edges from startId to goalId.
+ * Returns the ordered state-id list (inclusive of both ends), or null if the
+ * goal is unreachable. Pure: reads the store only. Cycles terminate (visited set).
+ */
+export declare function findPath(store: MapStore, startId: string, goalId: string): string[] | null;

package/dist/router/path.js

@@ -0,0 +1,55 @@
+/** Weight for an edge: lower = preferred. Cheap edges win; cost is static
+ *  declared data (playwright-cli call count). Usage-learned weighting
+ *  (reliability/confidence) is a hosted-service concern, not stored here. */
+function edgeWeight(e) {
+    return 1 + e.cost;
+}
+/**
+ * Weighted shortest path (Dijkstra) over graph edges from startId to goalId.
+ * Returns the ordered state-id list (inclusive of both ends), or null if the
+ * goal is unreachable. Pure: reads the store only. Cycles terminate (visited set).
+ */
+export function findPath(store, startId, goalId) {
+    if (startId === goalId)
+        return [startId];
+    const dist = new Map([[startId, 0]]);
+    const prev = new Map();
+    const visited = new Set();
+    const frontier = new Set([startId]);
+    while (frontier.size > 0) {
+        let cur = '';
+        let best = Infinity;
+        for (const id of frontier) {
+            const d = dist.get(id) ?? Infinity;
+            if (d < best) {
+                best = d;
+                cur = id;
+            }
+        }
+        frontier.delete(cur);
+        if (cur === goalId)
+            break;
+        if (visited.has(cur))
+            continue;
+        visited.add(cur);
+        for (const e of store.edgesFrom(cur)) {
+            if (visited.has(e.toState))
+                continue;
+            const nd = (dist.get(cur) ?? Infinity) + edgeWeight(e);
+            if (nd < (dist.get(e.toState) ?? Infinity)) {
+                dist.set(e.toState, nd);
+                prev.set(e.toState, cur);
+            }
+            frontier.add(e.toState);
+        }
+    }
+    if (!dist.has(goalId))
+        return null;
+    const path = [];
+    let node = goalId;
+    while (node !== undefined) {
+        path.unshift(node);
+        node = prev.get(node);
+    }
+    return path[0] === startId ? path : null;
+}

package/dist/router/read.d.ts

@@ -0,0 +1,26 @@
+import { type ContentEvidence } from './extract-content.js';
+export type ReadResponse = {
+    status: 'done';
+    url: string;
+    content: ContentEvidence;
+    raw?: string;
+} | {
+    status: 'blocked';
+    url: string;
+    reason: string;
+} | {
+    status: 'failed';
+    url: string;
+    reason: string;
+};
+export interface ReadOpts {
+    raw?: boolean;
+    queryTerms?: string[];
+}
+/**
+ * Open a URL and return its DISTILLED content (or the raw snapshot with --raw).
+ * Zero-LLM: readiness + extraction are deterministic. On a loading/interstitial
+ * page we report `blocked` and do NOT evade (principle: detect, never bypass).
+ * `fetchSnapshot` is injected so this is unit-testable without a browser.
+ */
+export declare function readUrl(url: string, fetchSnapshot: (url: string) => Promise<string>, opts?: ReadOpts): Promise<ReadResponse>;

package/dist/router/read.js

@@ -0,0 +1,30 @@
+import { classifyReadiness } from './readiness.js';
+import { extractContent } from './extract-content.js';
+/**
+ * Open a URL and return its DISTILLED content (or the raw snapshot with --raw).
+ * Zero-LLM: readiness + extraction are deterministic. On a loading/interstitial
+ * page we report `blocked` and do NOT evade (principle: detect, never bypass).
+ * `fetchSnapshot` is injected so this is unit-testable without a browser.
+ */
+export async function readUrl(url, fetchSnapshot, opts = {}) {
+    let snapshot;
+    try {
+        snapshot = await fetchSnapshot(url);
+    }
+    catch (e) {
+        return { status: 'failed', url, reason: String(e) };
+    }
+    const readiness = classifyReadiness(snapshot);
+    if (readiness !== 'ready') {
+        return {
+            status: 'blocked',
+            url,
+            reason: `page not ready (${readiness}); webnav does not evade walls`,
+        };
+    }
+    const content = extractContent(snapshot, url, opts.queryTerms);
+    if (opts.raw) {
+        return { status: 'done', url, content, raw: snapshot };
+    }
+    return { status: 'done', url, content };
+}

package/dist/router/readiness.d.ts

@@ -0,0 +1,9 @@
+export type Readiness = 'ready' | 'loading' | 'interstitial';
+export interface ReadinessOpts {
+    minNodes?: number;
+}
+/**
+ * Classify whether a snapshot represents a ready page, an unfinished render to
+ * retry, or a hard interstitial/bot-wall to escalate. Pure + deterministic.
+ */
+export declare function classifyReadiness(snapshotYaml: string, opts?: ReadinessOpts): Readiness;

package/dist/router/readiness.js

@@ -0,0 +1,55 @@
+import { parseSnapshot } from '../playwright/snapshot.js';
+// Known bot-wall / verification phrases. These are matched against a lowercased
+// blob of all node names to DETECT a hard interstitial so the caller can
+// ESCALATE — never to evade it. Each entry is specific enough that ordinary
+// prose ("human resources") does not trip it: we match phrases, not bare words.
+const INTERSTITIAL_PATTERNS = [
+    /just a moment/,
+    /checking your browser/,
+    /verify you are (?:a )?human/,
+    /cloudflare/,
+    /please enable javascript and cookies/,
+    /attention required/,
+    /ddos protection/,
+    /are you a robot/,
+    /complete the (?:captcha|security check)/,
+];
+// Roles that carry real page content. A finished render has at least one such
+// node with a non-empty name; a nav-only/empty shell has none.
+const CONTENT_ROLES = new Set([
+    'heading',
+    'paragraph',
+    'link',
+    'button',
+    'listitem',
+    'article',
+    'cell',
+    'textbox',
+    'img',
+]);
+const DEFAULT_MIN_NODES = 8;
+/**
+ * Classify whether a snapshot represents a ready page, an unfinished render to
+ * retry, or a hard interstitial/bot-wall to escalate. Pure + deterministic.
+ */
+export function classifyReadiness(snapshotYaml, opts) {
+    const minNodes = opts?.minNodes ?? DEFAULT_MIN_NODES;
+    const nodes = parseSnapshot(snapshotYaml);
+    // 1. Lowercased blob of all node names.
+    const blob = nodes
+        .map((n) => n.name ?? '')
+        .join(' ')
+        .toLowerCase();
+    // 2. Interstitial FIRST: a verification screen can be small AND match these.
+    if (INTERSTITIAL_PATTERNS.some((re) => re.test(blob))) {
+        return 'interstitial';
+    }
+    // 3. Loading: too sparse to be a finished render — fewer than minNodes total,
+    //    OR no content-ish node with a non-empty name (nav-only/empty shell).
+    const hasContent = nodes.some((n) => CONTENT_ROLES.has(n.role.toLowerCase()) && (n.name ?? '').trim() !== '');
+    if (nodes.length < minNodes || !hasContent) {
+        return 'loading';
+    }
+    // 4. Ready otherwise.
+    return 'ready';
+}

package/dist/router/replay.d.ts

@@ -0,0 +1,14 @@
+import type { Edge } from '../mapstore/types.js';
+import type { SnapNode } from '../playwright/snapshot.js';
+export type ReplayResult = {
+    status: 'ok';
+    ref: string;
+    repaired: boolean;
+} | {
+    status: 'escalate';
+} | {
+    status: 'needs-classify';
+} | {
+    status: 'blocked-commit';
+};
+export declare function replayStep(edge: Edge, nodes: SnapNode[]): ReplayResult;

package/dist/router/replay.js

@@ -0,0 +1,23 @@
+import { resolveStep } from './resolve.js';
+import { resolveByFingerprint } from '../playwright/fingerprint.js';
+export function replayStep(edge, nodes) {
+    if (edge.kind === 'commit-point')
+        return { status: 'blocked-commit' };
+    if (edge.kind === 'unclassified')
+        return { status: 'needs-classify' };
+    // Deterministic resolve, zero-LLM. When the edge carries a durable elementFp
+    // (role+name+content anchor), use the layered fingerprint resolver — this
+    // disambiguates heading-vs-button and identical siblings (e.g. 50 icon buttons in
+    // a table row) that name-only matching can't. Legacy edges (no elementFp) fall back
+    // to resolveStep's name match (+ selectorCache self-heal) — unchanged behavior.
+    if (edge.elementFp) {
+        const ref = resolveByFingerprint(edge.elementFp, nodes);
+        if (ref)
+            return { status: 'ok', ref, repaired: false };
+        return { status: 'escalate' };
+    }
+    const ref = resolveStep(edge.semanticStep, nodes, edge.selectorCache);
+    if (ref)
+        return { status: 'ok', ref, repaired: !!edge.selectorCache };
+    return { status: 'escalate' };
+}

package/dist/router/resolve.d.ts

@@ -0,0 +1,21 @@
+import type { SnapNode } from '../playwright/snapshot.js';
+/**
+ * Deterministically map a semantic step to a live element ref by matching a
+ * NAME against snapshot node names. Returns null on no/ambiguous match — the
+ * caller then escalates to the agent (needs-navigation). No LLM.
+ *
+ * Two name sources, tried in order:
+ *  1. the step's own quoted name (`click "Insights"` → "Insights").
+ *  2. `cachedSelector` — the SELF-HEAL repair: a name an agent's ref resolved to
+ *     on a PRIOR walk, written back to the edge when the step's own name failed
+ *     (drift / icon-only / renamed element). Lets a once-broken step resolve
+ *     deterministically again without re-asking the agent (principle #3).
+ * The step's own name wins when it matches; the cache is the fallback.
+ *
+ * Strict by design: returns a ref ONLY when exactly one node carries the name.
+ * If several do (e.g. 6 equivalent "Add to cart" buttons, or a product label
+ * shared by a link + its image), it returns null and the caller escalates —
+ * webnav never guesses among genuinely-equivalent targets; that judgment is the
+ * agent's (principle #5a). This is correct behavior, not a limitation.
+ */
+export declare function resolveStep(semanticStep: string, nodes: SnapNode[], cachedSelector?: string | null): string | null;

package/dist/router/resolve.js

@@ -0,0 +1,33 @@
+// Pull the quoted name out of a semantic step like `click "Insights"`.
+function quotedName(semanticStep) {
+    const m = semanticStep.match(/"([^"]+)"/);
+    return m ? m[1] : null;
+}
+/**
+ * Deterministically map a semantic step to a live element ref by matching a
+ * NAME against snapshot node names. Returns null on no/ambiguous match — the
+ * caller then escalates to the agent (needs-navigation). No LLM.
+ *
+ * Two name sources, tried in order:
+ *  1. the step's own quoted name (`click "Insights"` → "Insights").
+ *  2. `cachedSelector` — the SELF-HEAL repair: a name an agent's ref resolved to
+ *     on a PRIOR walk, written back to the edge when the step's own name failed
+ *     (drift / icon-only / renamed element). Lets a once-broken step resolve
+ *     deterministically again without re-asking the agent (principle #3).
+ * The step's own name wins when it matches; the cache is the fallback.
+ *
+ * Strict by design: returns a ref ONLY when exactly one node carries the name.
+ * If several do (e.g. 6 equivalent "Add to cart" buttons, or a product label
+ * shared by a link + its image), it returns null and the caller escalates —
+ * webnav never guesses among genuinely-equivalent targets; that judgment is the
+ * agent's (principle #5a). This is correct behavior, not a limitation.
+ */
+export function resolveStep(semanticStep, nodes, cachedSelector) {
+    const tryName = (name) => {
+        if (!name)
+            return null;
+        const hits = nodes.filter((n) => n.ref && n.name === name);
+        return hits.length === 1 ? hits[0].ref : null;
+    };
+    return tryName(quotedName(semanticStep)) ?? tryName(cachedSelector ?? null);
+}

package/dist/router/search-live.d.ts

@@ -0,0 +1,21 @@
+import { type ContentEvidence } from './extract-content.js';
+import { type TokenSavings } from './tokens.js';
+export interface SearchGatherResult {
+    query: string;
+    results: {
+        title: string;
+        url: string;
+    }[];
+    evidence: ContentEvidence[];
+    blocked: string[];
+    providers: {
+        id: string;
+        results: number;
+        blocked: boolean;
+    }[];
+    cost: {
+        playwright_calls: number;
+        savings: TokenSavings;
+    };
+}
+export declare function runSearchLive(query: string, topN?: number): Promise<SearchGatherResult>;

package/dist/router/search-live.js

@@ -0,0 +1,98 @@
+import { PlaywrightAdapter } from '../playwright/adapter.js';
+import { parseSearchResults } from './search.js';
+import { classifyReadiness } from './readiness.js';
+import { extractContent } from './extract-content.js';
+import { tokenSavings } from './tokens.js';
+import { SEARCH_PROVIDERS } from './search-providers.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Snapshot with a readiness retry: re-snapshot up to 3 times while 'loading'.
+async function readySnapshot(adapter) {
+    let yaml = await adapter.snapshot();
+    let readiness = classifyReadiness(yaml);
+    for (let attempt = 1; attempt < 3 && readiness === 'loading'; attempt++) {
+        await sleep(1500);
+        yaml = await adapter.snapshot();
+        readiness = classifyReadiness(yaml);
+    }
+    return { yaml, readiness };
+}
+/**
+ * Gather results from ONE provider: open its search url, then re-snapshot until
+ * results actually parse out (the search shell renders BEFORE the result list —
+ * a render race) or a bounded number of attempts. An interstitial search page is
+ * recorded as blocked (DETECT + escalate, never evade). Caps to topN.
+ */
+async function gatherFromProvider(adapter, provider, query, topN) {
+    await adapter.open(provider.searchUrl(query));
+    let resultsYaml = '';
+    let searchReadiness = 'loading';
+    let results = [];
+    for (let attempt = 0; attempt < 4; attempt++) {
+        const snap = await readySnapshot(adapter);
+        resultsYaml = snap.yaml;
+        searchReadiness = snap.readiness;
+        if (searchReadiness === 'interstitial')
+            break;
+        results = parseSearchResults(resultsYaml, topN);
+        if (results.length > 0)
+            break; // results rendered — proceed
+        await sleep(1500); // shell-only render — wait for results
+    }
+    if (searchReadiness === 'interstitial') {
+        // The provider's search page is bot-walled — record + skip. Never evade.
+        return { results: [], blocked: true, rawChars: resultsYaml.length };
+    }
+    // results already parsed in the loop above (possibly empty for a thin index).
+    return { results, blocked: false, rawChars: resultsYaml.length };
+}
+export async function runSearchLive(query, topN = 3) {
+    const adapter = new PlaywrightAdapter('search-' + Date.now());
+    const evidence = [];
+    const blocked = [];
+    const providers = [];
+    let rawChars = 0;
+    let results = [];
+    try {
+        // 1. Fan out across providers sequentially (one shared adapter). A blocked
+        //    provider is recorded and skipped; the others still contribute (the whole
+        //    point — resilience + broader coverage).
+        const perProvider = [];
+        for (const provider of SEARCH_PROVIDERS) {
+            const gather = await gatherFromProvider(adapter, provider, query, topN);
+            rawChars += gather.rawChars;
+            providers.push({ id: provider.id, results: gather.results.length, blocked: gather.blocked });
+            perProvider.push({ provider, gather });
+        }
+        // 2. MERGE + DEDUPE by url, preserving first-seen order (Marginalia first).
+        //    Cap the merged list to topN*2 so both providers can contribute.
+        const seen = new Set();
+        for (const { gather } of perProvider) {
+            for (const r of gather.results) {
+                if (seen.has(r.url))
+                    continue;
+                seen.add(r.url);
+                results.push(r);
+            }
+        }
+        results = results.slice(0, topN * 2);
+        // 3. Visit each merged result url, readiness-retry, interstitial -> blocked,
+        //    else extract content.
+        const queryTerms = query.toLowerCase().split(/\s+/);
+        for (const result of results) {
+            await adapter.goto(result.url);
+            const { yaml, readiness } = await readySnapshot(adapter);
+            if (readiness === 'interstitial') {
+                // DETECT + escalate, never evade.
+                blocked.push(result.url);
+                continue;
+            }
+            rawChars += yaml.length;
+            evidence.push(extractContent(yaml, result.url, queryTerms));
+        }
+    }
+    finally {
+        await adapter.close();
+    }
+    const savings = tokenSavings(rawChars, JSON.stringify({ results, evidence }));
+    return { query, results, evidence, blocked, providers, cost: { playwright_calls: adapter.callCount, savings } };
+}

package/dist/router/search-providers.d.ts

@@ -0,0 +1,5 @@
+export interface SearchProvider {
+    id: string;
+    searchUrl: (query: string) => string;
+}
+export declare const SEARCH_PROVIDERS: SearchProvider[];

package/dist/router/search-providers.js

@@ -0,0 +1,12 @@
+// Browser-navigable search engines webnav fans out across. Live-probed: only
+// these TWO work cleanly without bot-walling a real browser AND have DIFFERENT
+// indexes (Marginalia: broad ~40 results; Wiby: curated/older-web ~8). The
+// good mainstream engines (Google/Bing/Brave/DuckDuckGo) bot-wall real browsers;
+// others probed (mojeek/ecosia/searx/stract/4get) return empty shells — NOT
+// registered. Pure data + a URL builder; no logic.
+// Ordered list — Marginalia first (broader index), then Wiby. Merge preserves
+// this first-seen order.
+export const SEARCH_PROVIDERS = [
+    { id: 'marginalia', searchUrl: (q) => 'https://search.marginalia.nu/search?query=' + encodeURIComponent(q) },
+    { id: 'wiby', searchUrl: (q) => 'https://wiby.me/?q=' + encodeURIComponent(q) },
+];

package/dist/router/search.d.ts

@@ -0,0 +1,6 @@
+export interface SearchResult {
+    title: string;
+    url: string;
+}
+/** Parse external result links from a Marginalia results snapshot. Pure. */
+export declare function parseSearchResults(resultsYaml: string, limit: number): SearchResult[];