@jackwener/opencli 1.7.5 → 1.7.7

package/dist/src/cli.js

@@ -21,11 +21,177 @@ import { registerAllCommands } from './commanderAdapter.js';
 import { EXIT_CODES, getErrorMessage, BrowserConnectError } from './errors.js';
 import { TargetError } from './browser/target-errors.js';
 import { resolveTargetJs, getTextResolvedJs, getValueResolvedJs, getAttributesResolvedJs, selectResolvedJs, isAutocompleteResolvedJs } from './browser/target-resolver.js';
+import { buildFindJs, isFindError } from './browser/find.js';
+import { inferShape } from './browser/shape.js';
+import { assignKeys } from './browser/network-key.js';
+import { DEFAULT_TTL_MS, findEntry, loadNetworkCache, saveNetworkCache } from './browser/network-cache.js';
+import { parseFilter, shapeMatchesFilter } from './browser/shape-filter.js';
+import { buildHtmlTreeJs } from './browser/html-tree.js';
+import { buildExtractHtmlJs, runExtractFromHtml } from './browser/extract.js';
+import { analyzeSite } from './browser/analyze.js';
 import { daemonStatus, daemonStop } from './commands/daemon.js';
 import { log } from './logger.js';
 const CLI_FILE = fileURLToPath(import.meta.url);
 const DEFAULT_BROWSER_WORKSPACE = 'browser:default';
 const BROWSER_TAB_OPTION_DESCRIPTION = 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"';
+/**
+ * Normalize raw capture entries (from daemon/CDP `readNetworkCapture` or
+ * the JS interceptor's `window.__opencli_net`) into a consistent shape.
+ * Response preview is parsed as JSON when possible, otherwise kept as string.
+ * `bodyFullSize` / `bodyTruncated` surface capture-layer truncation so the
+ * agent-facing envelope can warn when the body isn't whole.
+ */
+async function captureNetworkItems(page) {
+    if (page.readNetworkCapture) {
+        const raw = await page.readNetworkCapture();
+        if (Array.isArray(raw) && raw.length > 0) {
+            return raw.map((e) => {
+                const preview = e.responsePreview ?? null;
+                let body = null;
+                if (preview) {
+                    try {
+                        body = JSON.parse(preview);
+                    }
+                    catch {
+                        body = preview;
+                    }
+                }
+                const fullSize = typeof e.responseBodyFullSize === 'number'
+                    ? e.responseBodyFullSize
+                    : (preview ? preview.length : 0);
+                const truncated = e.responseBodyTruncated === true;
+                return {
+                    url: e.url || '',
+                    method: e.method || 'GET',
+                    status: e.responseStatus || 0,
+                    size: fullSize,
+                    ct: e.responseContentType || '',
+                    body,
+                    bodyFullSize: fullSize,
+                    bodyTruncated: truncated,
+                };
+            });
+        }
+    }
+    const raw = await page.evaluate(`(function(){ var out = window.__opencli_net || []; window.__opencli_net = []; return JSON.stringify(out); })()`);
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        if (process.env.OPENCLI_VERBOSE)
+            log.warn(`[network] Failed to parse interceptor buffer: ${typeof raw === 'string' ? raw.slice(0, 200) : String(raw)}`);
+        return [];
+    }
+}
+/** Drop static-resource / telemetry noise so agents see only API-shaped traffic. */
+function filterNetworkItems(items) {
+    return items.filter((r) => (r.ct?.includes('json') || r.ct?.includes('xml') || r.ct?.includes('text/plain')) &&
+        !/\.(js|css|png|jpg|gif|svg|woff|ico|map)(\?|$)/i.test(r.url) &&
+        !/analytics|tracking|telemetry|beacon|pixel|gtag|fbevents/i.test(r.url));
+}
+/** Exit codes by network error code — usage errors vs runtime failures. */
+const NETWORK_ERROR_EXIT = {
+    invalid_args: EXIT_CODES.USAGE_ERROR,
+    invalid_filter: EXIT_CODES.USAGE_ERROR,
+    invalid_max_body: EXIT_CODES.USAGE_ERROR,
+};
+/** Emit a structured error JSON so agents can branch on `error.code` without regex. */
+function emitNetworkError(code, message, extra = {}) {
+    console.log(JSON.stringify({ error: { code, message, ...extra } }, null, 2));
+    process.exitCode = NETWORK_ERROR_EXIT[code] ?? EXIT_CODES.GENERIC_ERROR;
+}
+export function checkSiteMemory(site) {
+    const siteDir = path.join(os.homedir(), '.opencli', 'sites', site);
+    const endpointsPath = path.join(siteDir, 'endpoints.json');
+    const notesPath = path.join(siteDir, 'notes.md');
+    let endpointsCount = 0;
+    let endpointsPresent = fs.existsSync(endpointsPath);
+    if (endpointsPresent) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(endpointsPath, 'utf-8'));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                endpointsCount = Object.keys(parsed).length;
+            }
+            else if (Array.isArray(parsed)) {
+                endpointsCount = parsed.length;
+            }
+        }
+        catch {
+            endpointsPresent = false;
+        }
+    }
+    const notesPresent = fs.existsSync(notesPath);
+    return {
+        ok: endpointsPresent && endpointsCount > 0 && notesPresent,
+        siteDir,
+        endpoints: { present: endpointsPresent, count: endpointsCount, path: endpointsPath },
+        notes: { present: notesPresent, path: notesPath },
+    };
+}
+export function printSiteMemoryReport(report, strict) {
+    if (report.ok) {
+        console.log(`  ✓ Memory: endpoints.json (${report.endpoints.count}), notes.md present at ${report.siteDir}`);
+        return;
+    }
+    const marker = strict ? '✗' : '⚠';
+    const missing = [];
+    if (!report.endpoints.present)
+        missing.push('endpoints.json');
+    else if (report.endpoints.count === 0)
+        missing.push('endpoints.json (empty)');
+    if (!report.notes.present)
+        missing.push('notes.md');
+    console.log(`  ${marker} Memory: missing ${missing.join(', ')} under ${report.siteDir}`);
+    console.log(`    Write the endpoint you just verified + a 1-line session note so the next agent starts from minute 0, not minute 95.`);
+    if (!strict) {
+        console.log(`    (Re-run with --strict-memory to fail instead of warn.)`);
+    }
+}
+/** Coerce adapter JSON output into a row array. Accepts `[{...}]`, single `{}`, or `{items:[...]}`-style envelopes. */
+export function normalizeVerifyRows(data) {
+    if (Array.isArray(data)) {
+        return data.map((r) => (r && typeof r === 'object' ? r : { value: r }));
+    }
+    if (data && typeof data === 'object') {
+        const obj = data;
+        for (const k of ['rows', 'items', 'data', 'results']) {
+            if (Array.isArray(obj[k])) {
+                return obj[k].map((r) => (r && typeof r === 'object' ? r : { value: r }));
+            }
+        }
+        return [obj];
+    }
+    return [];
+}
+/** Render up to 10 rows as a compact padded table for eyeball inspection during verify. */
+export function renderVerifyPreview(rows, opts = {}) {
+    const maxRows = opts.maxRows ?? 10;
+    const maxCols = opts.maxCols ?? 6;
+    const cellMax = opts.cellMax ?? 40;
+    if (rows.length === 0)
+        return '  (no rows)';
+    const allCols = Array.from(new Set(rows.flatMap((r) => Object.keys(r))));
+    const cols = allCols.slice(0, maxCols);
+    const shown = rows.slice(0, maxRows);
+    const cellOf = (v) => {
+        if (v === null || v === undefined)
+            return '';
+        const s = typeof v === 'object' ? JSON.stringify(v) : String(v);
+        return s.replace(/\s+/g, ' ').slice(0, cellMax);
+    };
+    const widths = cols.map((c) => Math.max(c.length, ...shown.map((r) => cellOf(r[c]).length)));
+    const fmtRow = (vals) => vals.map((v, i) => v.padEnd(widths[i])).join('  ');
+    const out = [];
+    out.push(`  ${fmtRow(cols)}`);
+    out.push(`  ${widths.map((w) => '-'.repeat(w)).join('  ')}`);
+    for (const r of shown)
+        out.push(`  ${fmtRow(cols.map((c) => cellOf(r[c])))}`);
+    if (rows.length > maxRows)
+        out.push(`  ... and ${rows.length - maxRows} more row(s)`);
+    if (allCols.length > maxCols)
+        out.push(`  (${allCols.length - maxCols} more column(s) hidden)`);
+    return out.join('\n');
+}
 function getBrowserCacheDir() {
     return process.env.OPENCLI_CACHE_DIR || path.join(os.homedir(), '.opencli', 'cache');
 }
@@ -249,12 +415,50 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     const browser = program
         .command('browser')
         .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
-    /** Resolve a ref/CSS target via the unified resolver, throwing TargetError on failure. */
-    async function resolveRef(page, ref) {
-        const resolution = await page.evaluate(resolveTargetJs(ref));
+    /**
+     * Resolve a `<target>` (numeric ref or CSS selector) via the unified resolver.
+     * Returns the CSS match count so callers can propagate `matches_n` into the
+     * JSON envelope printed back to the agent.
+     */
+    async function resolveRef(page, ref, opts = {}) {
+        const resolution = await page.evaluate(resolveTargetJs(ref, opts));
         if (!resolution.ok) {
-            throw new TargetError(resolution);
+            throw new TargetError({
+                code: resolution.code,
+                message: resolution.message,
+                hint: resolution.hint,
+                candidates: resolution.candidates,
+                matches_n: resolution.matches_n,
+            });
         }
+        return { matches_n: resolution.matches_n, match_level: resolution.match_level };
+    }
+    /**
+     * Parse `--nth <n>` flag, returning the parsed 0-based index or a usage error.
+     * The surface mirrors `--depth` etc. in `browser get html --as json`: the flag
+     * is optional, must be a non-negative integer when present, and on failure we
+     * emit the structured error envelope rather than throwing past the command.
+     */
+    function parseNthFlag(raw) {
+        if (raw === undefined || raw === null || raw === '')
+            return null;
+        const str = String(raw);
+        if (!/^\d+$/.test(str)) {
+            return { error: `--nth must be a non-negative integer, got "${str}"` };
+        }
+        return Number.parseInt(str, 10);
+    }
+    /** Emit the `{ error: { code, message, hint?, candidates?, matches_n? } }` envelope used by the selector-first commands. */
+    function emitTargetError(err) {
+        console.log(JSON.stringify({
+            error: {
+                code: err.code,
+                message: err.message,
+                hint: err.hint,
+                ...(err.candidates && { candidates: err.candidates }),
+                ...(err.matches_n !== undefined && { matches_n: err.matches_n }),
+            },
+        }, null, 2));
     }
     /** Wrap browser actions with error handling and optional --json output */
     function browserAction(fn) {
@@ -272,13 +476,11 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
                         log.error(`Hint: ${err.hint}`);
                 }
                 else if (err instanceof TargetError) {
+                    // Agent-facing structured envelope on stdout + short human line on stderr.
+                    emitTargetError(err);
                     log.error(`[${err.code}] ${err.message}`);
                     if (err.hint)
                         log.error(`Hint: ${err.hint}`);
-                    if (err.candidates?.length) {
-                        log.error('Candidates:');
-                        err.candidates.forEach((c, i) => log.error(`  ${i + 1}. ${c}`));
-                    }
                 }
                 else {
                     const msg = getErrorMessage(err);
@@ -352,8 +554,17 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         console.log(JSON.stringify({ closed: validatedTarget }, null, 2));
     }));
     // ── Navigation ──
-    /** Network interceptor JS — injected on every open/navigate to capture fetch/XHR */
-    const NETWORK_INTERCEPTOR_JS = `(function(){if(window.__opencli_net)return;window.__opencli_net=[];var M=200,B=50000,F=window.fetch;window.fetch=async function(){var r=await F.apply(this,arguments);try{var ct=r.headers.get('content-type')||'';if(ct.includes('json')||ct.includes('text')){var c=r.clone(),t=await c.text();if(window.__opencli_net.length<M){var b=null;if(t.length<=B)try{b=JSON.parse(t)}catch(e){b=t}window.__opencli_net.push({url:r.url||(arguments[0]&&arguments[0].url)||String(arguments[0]),method:(arguments[1]&&arguments[1].method)||'GET',status:r.status,size:t.length,ct:ct,body:b})}}}catch(e){}return r};var X=XMLHttpRequest.prototype,O=X.open,S=X.send;X.open=function(m,u){this._om=m;this._ou=u;return O.apply(this,arguments)};X.send=function(){var x=this;x.addEventListener('load',function(){try{var ct=x.getResponseHeader('content-type')||'';if((ct.includes('json')||ct.includes('text'))&&window.__opencli_net.length<M){var t=x.responseText,b=null;if(t&&t.length<=B)try{b=JSON.parse(t)}catch(e){b=t}window.__opencli_net.push({url:x._ou,method:x._om||'GET',status:x.status,size:t?t.length:0,ct:ct,body:b})}}catch(e){}});return S.apply(this,arguments)}})()`;
+    /**
+     * Network interceptor JS — injected on every open/navigate to capture
+     * fetch/XHR bodies when the session-level capture channel (CDP/extension)
+     * isn't available. Keeps parity with the CDP path's truncation contract:
+     * when a body exceeds the per-entry cap, we keep a string prefix and set
+     * `bodyTruncated: true` + `bodyFullSize: <original length>` so `browser
+     * network` can propagate a visible signal to the agent instead of
+     * silently dropping the body. Per-entry cap is 1 MiB and the ring is
+     * capped at 200 entries, bounding worst-case in-page memory.
+     */
+    const NETWORK_INTERCEPTOR_JS = `(function(){if(window.__opencli_net)return;window.__opencli_net=[];var M=200,B=1048576,F=window.fetch;function capture(url,method,status,text,ct){if(window.__opencli_net.length>=M)return;var full=text?text.length:0,trunc=full>B,stored=trunc?text.slice(0,B):text,body=null;if(stored){if(trunc){body=stored}else{try{body=JSON.parse(stored)}catch(e){body=stored}}}var e={url:url,method:method||'GET',status:status,size:full,ct:ct,body:body};if(trunc){e.bodyTruncated=true;e.bodyFullSize=full}window.__opencli_net.push(e)}window.fetch=async function(){var r=await F.apply(this,arguments);try{var ct=r.headers.get('content-type')||'';if(ct.includes('json')||ct.includes('text')){var c=r.clone(),t=await c.text();capture(r.url||(arguments[0]&&arguments[0].url)||String(arguments[0]),(arguments[1]&&arguments[1].method)||'GET',r.status,t,ct)}}catch(e){}return r};var X=XMLHttpRequest.prototype,O=X.open,S=X.send;X.open=function(m,u){this._om=m;this._ou=u;return O.apply(this,arguments)};X.send=function(){var x=this;x.addEventListener('load',function(){try{var ct=x.getResponseHeader('content-type')||'';if(ct.includes('json')||ct.includes('text')){capture(x._ou,x._om||'GET',x.status,x.responseText||'',ct)}}catch(e){}});return S.apply(this,arguments)}})()`;
     addBrowserTabOption(browser.command('open').argument('<url>').description('Open URL in automation window'))
         .action(browserAction(async (page, url) => {
         // Start session-level capture before navigation (catches initial requests)
@@ -413,6 +624,118 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             console.log(await page.screenshot({ format: 'png' }));
         }
     }));
+    // ── Analyze (site recon, agent-native) ──
+    //
+    // Mechanizes the `site-recon.md` decision tree into one CLI call. The agent
+    // calls `browser analyze <url>` and gets back:
+    //
+    //   - pattern: A/B/C/D (mapped from network + SSR-globals signals)
+    //   - anti_bot: vendor + evidence + the one-liner for "what to do next"
+    //   - initial_state: which window globals are populated
+    //   - nearest_adapter: existing commands for the same site, if any
+    //   - recommended_next_step: a single imperative sentence
+    //
+    // Intent: replace the "open → eyeball network → curl → WAF → try again"
+    // feedback loop with a single deterministic verdict. Without this, agents
+    // burn ~20min per WAF-protected site re-discovering anti-bot posture.
+    addBrowserTabOption(browser.command('analyze').argument('<url>'))
+        .description('Classify site: anti-bot vendor, pattern (A/B/C/D), nearest adapter, recommended next step')
+        .action(browserAction(async (page, url) => {
+        const hasSessionCapture = await page.startNetworkCapture?.() ?? false;
+        await page.goto(url);
+        await page.wait(2);
+        if (!hasSessionCapture) {
+            try {
+                await page.evaluate(NETWORK_INTERCEPTOR_JS);
+            }
+            catch { /* non-fatal */ }
+        }
+        await captureNetworkItems(page);
+        // Best-effort: give the page another beat so XHR after DOMContentLoaded lands.
+        await page.wait(1);
+        const rawItems = await captureNetworkItems(page);
+        const networkEntries = rawItems.map((e) => ({
+            url: e.url,
+            status: e.status,
+            contentType: e.ct,
+            bodyPreview: typeof e.body === 'string'
+                ? e.body.slice(0, 2000)
+                : (e.body ? JSON.stringify(e.body).slice(0, 2000) : null),
+        }));
+        const probeJs = `(function(){
+        return {
+          cookieNames: (document.cookie || '').split(';').map(function(c){ return c.trim().split('=')[0]; }).filter(Boolean),
+          initialState: {
+            __INITIAL_STATE__: typeof window.__INITIAL_STATE__ !== 'undefined',
+            __NUXT__: typeof window.__NUXT__ !== 'undefined',
+            __NEXT_DATA__: typeof window.__NEXT_DATA__ !== 'undefined',
+            __APOLLO_STATE__: typeof window.__APOLLO_STATE__ !== 'undefined',
+          },
+          title: document.title || '',
+          finalUrl: location.href,
+        };
+      })()`;
+        const probe = await page.evaluate(probeJs);
+        const browserCookieNames = (await page.getCookies({ url: probe.finalUrl || url }).catch(() => []))
+            .map((c) => c.name)
+            .filter(Boolean);
+        const cookieNames = [...new Set([...probe.cookieNames, ...browserCookieNames])];
+        const signals = {
+            requestedUrl: url,
+            finalUrl: probe.finalUrl,
+            cookieNames,
+            networkEntries,
+            initialState: probe.initialState,
+            title: probe.title,
+        };
+        const report = analyzeSite(signals, getRegistry());
+        console.log(JSON.stringify(report, null, 2));
+    }));
+    // ── Find (structured CSS query, agent-native) ──
+    //
+    // `browser find --css <sel>` lets agents jump straight from a semantic
+    // selector to a JSON list of matching elements, without having to parse
+    // the free-text state snapshot to recover indices.
+    addBrowserTabOption(browser.command('find')
+        .option('--css <selector>', 'CSS selector (required)')
+        .option('--limit <n>', 'Max entries returned', '50')
+        .option('--text-max <n>', 'Max chars of trimmed text per entry', '120')
+        .description('Find DOM elements by CSS selector — returns JSON {matches_n, entries[]}'))
+        .action(browserAction(async (page, opts) => {
+        if (!opts.css || typeof opts.css !== 'string') {
+            console.log(JSON.stringify({
+                error: {
+                    code: 'usage_error',
+                    message: '--css <selector> is required',
+                    hint: 'Example: opencli browser find --css ".btn.primary"',
+                },
+            }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const limit = parseNthFlag(opts.limit);
+        if (limit && typeof limit === 'object' && 'error' in limit) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: limit.error.replace('--nth', '--limit') } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const textMax = parseNthFlag(opts.textMax);
+        if (textMax && typeof textMax === 'object' && 'error' in textMax) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: textMax.error.replace('--nth', '--text-max') } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const result = await page.evaluate(buildFindJs(opts.css, {
+            limit: limit ?? undefined,
+            textMax: textMax ?? undefined,
+        }));
+        if (isFindError(result)) {
+            console.log(JSON.stringify(result, null, 2));
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
+            return;
+        }
+        console.log(JSON.stringify(result, null, 2));
+    }));
     // ── Get commands (structured data extraction) ──
     const get = browser.command('get').description('Get page properties');
     addBrowserTabOption(get.command('title').description('Page title'))
@@ -423,65 +746,271 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         .action(browserAction(async (page) => {
         console.log(await page.getCurrentUrl?.() ?? await page.evaluate('location.href'));
     }));
-    addBrowserTabOption(get.command('text').argument('<index>', 'Element index').description('Element text content'))
-        .action(browserAction(async (page, index) => {
-        await resolveRef(page, String(index));
-        const text = await page.evaluate(getTextResolvedJs());
-        console.log(text ?? '(empty)');
-    }));
-    addBrowserTabOption(get.command('value').argument('<index>', 'Element index').description('Input/textarea value'))
-        .action(browserAction(async (page, index) => {
-        await resolveRef(page, String(index));
-        const val = await page.evaluate(getValueResolvedJs());
-        console.log(val ?? '(empty)');
-    }));
-    addBrowserTabOption(get.command('html').option('--selector <css>', 'CSS selector scope').description('Page HTML (or scoped)'))
+    // Read commands (`get text/value/attributes`) always emit a JSON envelope:
+    //
+    //   { value, matches_n }                           — success
+    //   { error: { code, message, hint, matches_n? } } — structured failure
+    //
+    // `<target>` accepts either a numeric ref (from `browser state`/`browser find`)
+    // or a CSS selector. On multi-match CSS, the first element wins and the real
+    // match count is exposed via `matches_n`; `--nth <n>` picks a specific one.
+    const runGetCommand = async (page, target, opts, evalJs, field) => {
+        const nth = parseNthFlag(opts.nth);
+        if (nth && typeof nth === 'object' && 'error' in nth) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: nth.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const { matches_n, match_level } = await resolveRef(page, String(target), {
+            firstOnMulti: nth === null,
+            ...(typeof nth === 'number' ? { nth } : {}),
+        });
+        const raw = await page.evaluate(evalJs);
+        let value;
+        if (field === 'attributes') {
+            // getAttributesResolvedJs stringifies the attribute record — parse it back so
+            // the JSON envelope contains a real object rather than a nested JSON string.
+            try {
+                value = raw == null ? {} : JSON.parse(String(raw));
+            }
+            catch {
+                value = raw;
+            }
+        }
+        else {
+            value = raw ?? null;
+        }
+        console.log(JSON.stringify({ value, matches_n, match_level }, null, 2));
+    };
+    addBrowserTabOption(get.command('text')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .option('--nth <n>', 'Pick the nth match (0-based) when <target> is a multi-match CSS selector')
+        .description('Element text content — JSON envelope {value, matches_n}'))
+        .action(browserAction(async (page, target, opts) => runGetCommand(page, String(target), opts ?? {}, getTextResolvedJs(), 'text')));
+    addBrowserTabOption(get.command('value')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .option('--nth <n>', 'Pick the nth match (0-based) when <target> is a multi-match CSS selector')
+        .description('Input/textarea value — JSON envelope {value, matches_n}'))
+        .action(browserAction(async (page, target, opts) => runGetCommand(page, String(target), opts ?? {}, getValueResolvedJs(), 'value')));
+    addBrowserTabOption(get.command('html')
+        .option('--selector <css>', 'CSS selector scope (first match)')
+        .option('--as <format>', 'Output format: "html" (default) or "json" for structured tree', 'html')
+        .option('--max <n>', 'Max characters of raw HTML to return (0 = unlimited)', '0')
+        .option('--depth <n>', '(--as json) Max tree depth below root (0 = root only, 0 disables = unlimited via empty)', '')
+        .option('--children-max <n>', '(--as json) Max element children kept per node (empty = unlimited)', '')
+        .option('--text-max <n>', '(--as json) Max chars of direct text kept per node (empty = unlimited)', '')
+        .description('Page HTML (or scoped); use --as json for a {tag, attrs, text, children} tree'))
         .action(browserAction(async (page, opts) => {
+        const format = String(opts.as || 'html').toLowerCase();
+        if (format !== 'html' && format !== 'json') {
+            console.log(JSON.stringify({ error: { code: 'invalid_format', message: `--as must be "html" or "json", got "${opts.as}"` } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        // `--max` is validated up-front (before touching the page) so a bad value
+        // gets the same structured error regardless of selector/format path.
+        const rawMax = String(opts.max ?? '0');
+        if (!/^\d+$/.test(rawMax)) {
+            console.log(JSON.stringify({ error: { code: 'invalid_max', message: `--max must be a non-negative integer, got "${opts.max}"` } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const max = Number.parseInt(rawMax, 10);
+        if (format === 'json') {
+            const parseBudget = (flag, value) => {
+                const raw = value === undefined || value === null ? '' : String(value);
+                if (raw === '')
+                    return null;
+                if (!/^\d+$/.test(raw))
+                    return { error: `${flag} must be a non-negative integer, got "${raw}"` };
+                return Number.parseInt(raw, 10);
+            };
+            const depth = parseBudget('--depth', opts.depth);
+            const childrenMax = parseBudget('--children-max', opts.childrenMax);
+            const textMax = parseBudget('--text-max', opts.textMax);
+            for (const budget of [depth, childrenMax, textMax]) {
+                if (budget && typeof budget === 'object' && 'error' in budget) {
+                    console.log(JSON.stringify({ error: { code: 'invalid_budget', message: budget.error } }, null, 2));
+                    process.exitCode = EXIT_CODES.USAGE_ERROR;
+                    return;
+                }
+            }
+            const js = buildHtmlTreeJs({
+                selector: opts.selector ?? null,
+                depth: depth,
+                childrenMax: childrenMax,
+                textMax: textMax,
+            });
+            const result = await page.evaluate(js);
+            if (result && typeof result === 'object' && 'invalidSelector' in result && result.invalidSelector) {
+                console.log(JSON.stringify({
+                    error: { code: 'invalid_selector', message: `Selector "${opts.selector}" is not a valid CSS selector: ${result.reason}` },
+                }, null, 2));
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            const ok = result;
+            if (!ok || ok.matched === 0) {
+                console.log(JSON.stringify({
+                    error: {
+                        code: 'selector_not_found',
+                        message: opts.selector
+                            ? `Selector "${opts.selector}" matched 0 elements.`
+                            : 'Page has no documentElement.',
+                    },
+                }, null, 2));
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            console.log(JSON.stringify(ok, null, 2));
+            return;
+        }
+        // Raw HTML path — unbounded by default; --max optionally caps with a visible marker.
+        // Selector lookup is wrapped in try/catch inside page context so an invalid
+        // selector returns a structured signal instead of throwing through page.evaluate.
         const sel = opts.selector ? JSON.stringify(opts.selector) : 'null';
-        const html = await page.evaluate(`(${sel} ? document.querySelector(${sel})?.outerHTML : document.documentElement.outerHTML)?.slice(0, 50000)`);
-        console.log(html ?? '(empty)');
-    }));
-    addBrowserTabOption(get.command('attributes').argument('<index>', 'Element index').description('Element attributes'))
-        .action(browserAction(async (page, index) => {
-        await resolveRef(page, String(index));
-        const attrs = await page.evaluate(getAttributesResolvedJs());
-        console.log(attrs ?? '{}');
+        const rawResult = await page.evaluate(`(() => {
+          const s = ${sel};
+          if (s) {
+            try {
+              const el = document.querySelector(s);
+              return { kind: 'ok', html: el ? el.outerHTML : null };
+            } catch (e) {
+              return { kind: 'invalid_selector', reason: (e && e.message) || String(e) };
+            }
+          }
+          return { kind: 'ok', html: document.documentElement ? document.documentElement.outerHTML : null };
+        })()`);
+        if (rawResult.kind === 'invalid_selector') {
+            console.log(JSON.stringify({
+                error: { code: 'invalid_selector', message: `Selector "${opts.selector}" is not a valid CSS selector: ${rawResult.reason}` },
+            }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const html = rawResult.html;
+        if (html === null) {
+            if (opts.selector) {
+                console.log(JSON.stringify({
+                    error: { code: 'selector_not_found', message: `Selector "${opts.selector}" matched 0 elements.` },
+                }, null, 2));
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            console.log('(empty)');
+            return;
+        }
+        if (max > 0 && html.length > max) {
+            console.log(`<!-- opencli: truncated ${max} of ${html.length} chars; re-run without --max (or --max 0) for full -->\n${html.slice(0, max)}`);
+            return;
+        }
+        console.log(html);
     }));
+    addBrowserTabOption(get.command('attributes')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .option('--nth <n>', 'Pick the nth match (0-based) when <target> is a multi-match CSS selector')
+        .description('Element attributes — JSON envelope {value, matches_n}'))
+        .action(browserAction(async (page, target, opts) => runGetCommand(page, String(target), opts ?? {}, getAttributesResolvedJs(), 'attributes')));
     // ── Interact ──
-    addBrowserTabOption(browser.command('click').argument('<index>', 'Element index from state').description('Click element by index'))
-        .action(browserAction(async (page, index) => {
-        await page.click(index);
-        console.log(`Clicked element [${index}]`);
+    //
+    // Write commands (`click/type/select`) share the same `<target>` contract
+    // as the read commands but *reject* multi-match CSS as `selector_ambiguous`
+    // unless the caller passes `--nth <n>`. That asymmetry is intentional:
+    // clicking "one of three buttons" at random is almost never what the agent
+    // meant. Every branch emits a JSON envelope on stdout; error envelopes go
+    // through the unified TargetError handler in browserAction.
+    /**
+     * Parse the `--nth` flag and convert it to `ResolveOptions`.
+     * Returns `{ error }` when the flag was malformed (so the command can
+     * print the structured usage error and exit) or `{ opts }` to feed
+     * into resolveRef / page.click / page.typeText.
+     */
+    function nthToResolveOpts(raw) {
+        const parsed = parseNthFlag(raw);
+        if (parsed && typeof parsed === 'object' && 'error' in parsed)
+            return parsed;
+        if (typeof parsed === 'number')
+            return { opts: { nth: parsed } };
+        return { opts: {} };
+    }
+    addBrowserTabOption(browser.command('click')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Click element — JSON envelope {clicked, target, matches_n}'))
+        .action(browserAction(async (page, target, opts) => {
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const { matches_n, match_level } = await page.click(String(target), parsed.opts);
+        console.log(JSON.stringify({ clicked: true, target: String(target), matches_n, match_level }, null, 2));
     }));
-    addBrowserTabOption(browser.command('type').argument('<index>', 'Element index').argument('<text>', 'Text to type'))
-        .description('Click element, then type text')
-        .action(browserAction(async (page, index, text) => {
-        await page.click(index);
+    addBrowserTabOption(browser.command('type')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .argument('<text>', 'Text to type')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Click element, then type text — JSON envelope {typed, text, target, matches_n, autocomplete}'))
+        .action(browserAction(async (page, target, text, opts) => {
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        // Click first (focuses the field), wait briefly, then type.
+        await page.click(String(target), parsed.opts);
         await page.wait(0.3);
-        await page.typeText(index, text);
-        // Detect autocomplete/combobox fields and wait for dropdown suggestions
-        // __resolved is already set by typeText's resolver call
+        const { matches_n, match_level } = await page.typeText(String(target), String(text), parsed.opts);
+        // __resolved is already set by the resolver call inside page.typeText
         const isAutocomplete = await page.evaluate(isAutocompleteResolvedJs());
-        if (isAutocomplete) {
+        if (isAutocomplete)
             await page.wait(0.4);
-            console.log(`Typed "${text}" into autocomplete [${index}] — use state to see suggestions`);
-        }
-        else {
-            console.log(`Typed "${text}" into element [${index}]`);
-        }
+        console.log(JSON.stringify({
+            typed: true,
+            text: String(text),
+            target: String(target),
+            matches_n,
+            match_level,
+            autocomplete: !!isAutocomplete,
+        }, null, 2));
     }));
-    addBrowserTabOption(browser.command('select').argument('<index>', 'Element index of <select>').argument('<option>', 'Option text'))
-        .description('Select dropdown option')
-        .action(browserAction(async (page, index, option) => {
-        await resolveRef(page, String(index));
-        const result = await page.evaluate(selectResolvedJs(option));
+    addBrowserTabOption(browser.command('select')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector of a <select> element')
+        .argument('<option>', 'Option text (or value) to select')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Select dropdown option — JSON envelope {selected, target, matches_n}'))
+        .action(browserAction(async (page, target, option, opts) => {
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const { matches_n, match_level } = await resolveRef(page, String(target), parsed.opts);
+        const result = await page.evaluate(selectResolvedJs(String(option)));
         if (result?.error) {
-            console.error(`Error: ${result.error}${result.available ? ` — Available: ${result.available.join(', ')}` : ''}`);
+            // The select-specific "Not a <select>" / "Option not found" errors
+            // are domain-level failures — emit a structured envelope so agents
+            // can branch on code rather than scrape a log line.
+            console.log(JSON.stringify({
+                error: {
+                    code: result.error === 'Not a <select>' ? 'not_a_select' : 'option_not_found',
+                    message: result.error,
+                    ...(result.available && { available: result.available }),
+                    matches_n,
+                },
+            }, null, 2));
             process.exitCode = EXIT_CODES.GENERIC_ERROR;
+            return;
         }
-        else {
-            console.log(`Selected "${result?.selected}" in element [${index}]`);
-        }
+        console.log(JSON.stringify({
+            selected: result?.selected ?? String(option),
+            target: String(target),
+            matches_n,
+            match_level,
+        }, null, 2));
     }));
     addBrowserTabOption(browser.command('keys').argument('<key>', 'Key to press (Enter, Escape, Tab, Control+a)'))
         .description('Press keyboard key')
@@ -491,10 +1020,10 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     }));
     // ── Wait commands ──
     addBrowserTabOption(browser.command('wait'))
-        .argument('<type>', 'selector, text, or time')
-        .argument('[value]', 'CSS selector, text string, or seconds')
+        .argument('<type>', 'selector, text, time, or xhr')
+        .argument('[value]', 'CSS selector, text string, seconds, or XHR URL regex')
         .option('--timeout <ms>', 'Timeout in milliseconds', '10000')
-        .description('Wait for selector, text, or time (e.g. wait selector ".loaded", wait text "Success", wait time 3)')
+        .description('Wait for selector, text, time, or matching XHR (e.g. wait selector ".loaded", wait text "Success", wait time 3, wait xhr "/api/search")')
         .action(browserAction(async (page, type, value, opts) => {
         const timeout = parseInt(opts.timeout, 10);
         if (type === 'time') {
@@ -520,8 +1049,59 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             await page.wait({ text: value, timeout: timeout / 1000 });
             console.log(`Text "${value}" appeared`);
         }
+        else if (type === 'xhr') {
+            // Poll the capture ring until an entry matches the URL regex — turns
+            // the common "open page, wait N seconds, hope the data landed" idiom
+            // into a deterministic barrier keyed on the API the agent actually
+            // cares about. Prevents silent "empty DOM" failures on slow SPAs.
+            if (!value) {
+                console.error('Missing XHR URL regex');
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            let re;
+            try {
+                re = new RegExp(value);
+            }
+            catch (err) {
+                console.error(`Invalid regex "${value}": ${err instanceof Error ? err.message : String(err)}`);
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            const hasSessionCapture = await page.startNetworkCapture?.() ?? false;
+            if (!hasSessionCapture) {
+                try {
+                    await page.evaluate(NETWORK_INTERCEPTOR_JS);
+                }
+                catch { /* non-fatal */ }
+            }
+            await captureNetworkItems(page);
+            const deadline = Date.now() + timeout;
+            const pollMs = 400;
+            let matched = null;
+            while (Date.now() < deadline && !matched) {
+                const items = await captureNetworkItems(page);
+                matched = items.find((e) => re.test(e.url)) ?? null;
+                if (!matched)
+                    await new Promise((r) => setTimeout(r, pollMs));
+            }
+            if (!matched) {
+                console.log(JSON.stringify({
+                    error: {
+                        code: 'xhr_not_seen',
+                        message: `No captured XHR matched /${value}/ within ${timeout}ms`,
+                        hint: 'Check the pattern against `browser network` output; the endpoint may not have fired yet, or capture is disabled.',
+                    },
+                }, null, 2));
+                process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                return;
+            }
+            console.log(JSON.stringify({
+                matched: { url: matched.url, status: matched.status, contentType: matched.ct },
+            }, null, 2));
+        }
         else {
-            console.error(`Unknown wait type "${type}". Use: selector, text, or time`);
+            console.error(`Unknown wait type "${type}". Use: selector, text, time, or xhr`);
             process.exitCode = EXIT_CODES.USAGE_ERROR;
         }
     }));
@@ -552,86 +1132,232 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         else
             console.log(JSON.stringify(result, null, 2));
     }));
+    // ── Extract (content reading) ──
+    //
+    // `extract` answers the "read this page" question that `get html` / `get text`
+    // can't: denoise → markdown → paragraph-aware chunking. Agents walk long pages
+    // by passing back the `next_start_char` cursor instead of juggling selectors.
+    addBrowserTabOption(browser.command('extract')
+        .option('--selector <css>', 'CSS selector scope; defaults to <main>/<article>/<body>')
+        .option('--chunk-size <chars>', 'Target chunk size in chars', '20000')
+        .option('--start <char>', 'Start offset (use next_start_char from a previous extract)', '0')
+        .description('Extract page content as markdown, paragraph-aware chunks for long pages'))
+        .action(browserAction(async (page, opts) => {
+        const rawChunk = String(opts.chunkSize ?? '20000');
+        if (!/^\d+$/.test(rawChunk) || Number.parseInt(rawChunk, 10) <= 0) {
+            console.log(JSON.stringify({ error: { code: 'invalid_chunk_size', message: `--chunk-size must be a positive integer, got "${opts.chunkSize}"` } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const rawStart = String(opts.start ?? '0');
+        if (!/^\d+$/.test(rawStart)) {
+            console.log(JSON.stringify({ error: { code: 'invalid_start', message: `--start must be a non-negative integer, got "${opts.start}"` } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const chunkSize = Number.parseInt(rawChunk, 10);
+        const start = Number.parseInt(rawStart, 10);
+        const selector = typeof opts.selector === 'string' && opts.selector.length > 0 ? opts.selector : null;
+        const js = buildExtractHtmlJs(selector);
+        const res = await page.evaluate(js);
+        if (!res) {
+            console.log(JSON.stringify({ error: { code: 'extract_failed', message: 'Page returned no root element.' } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        if ('invalidSelector' in res) {
+            console.log(JSON.stringify({ error: { code: 'invalid_selector', message: `Selector "${selector}" is not a valid CSS selector: ${res.reason}` } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        if ('notFound' in res) {
+            console.log(JSON.stringify({ error: { code: 'selector_not_found', message: selector ? `Selector "${selector}" matched 0 elements.` : 'Page has no body/main/article element.' } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const envelope = runExtractFromHtml({
+            html: res.html,
+            url: res.url,
+            title: res.title,
+            selector,
+            start,
+            chunkSize,
+        });
+        console.log(JSON.stringify(envelope, null, 2));
+    }));
     // ── Network (API discovery) ──
+    //
+    // Default output is JSON (agent-native). Each entry carries a stable `key`
+    // (GraphQL operationName or `METHOD host+pathname`) so agents can fetch
+    // full bodies with `--detail <key>` even after subsequent commands.
+    // Captures are persisted per workspace under ~/.opencli/cache/browser-network/.
     addBrowserTabOption(browser.command('network'))
-        .option('--detail <index>', 'Show full response body of request at index')
-        .option('--all', 'Show all requests including static resources')
-        .description('Show captured network requests (auto-captured since last open)')
+        .option('--detail <key>', 'Emit full body for the entry with this key')
+        .option('--all', 'Include static resources (js/css/images/telemetry)')
+        .option('--raw', 'Emit full bodies for every entry (skip shape preview)')
+        .option('--filter <fields>', 'Comma-separated field names; keep only entries whose body shape has ALL names as path segments')
+        .option('--max-body <chars>', 'With --detail: cap the emitted body at N chars (0 = unlimited, default)', '0')
+        .option('--ttl <ms>', 'Cache TTL in ms for --detail lookups', String(DEFAULT_TTL_MS))
+        .description('Capture network requests as shape previews; retrieve full bodies by key')
         .action(browserAction(async (page, opts) => {
-        let items = [];
-        if (page.readNetworkCapture) {
-            const raw = await page.readNetworkCapture();
-            // Normalize daemon/CDP capture entries to __opencli_net shape.
-            // Daemon returns: responseStatus, responseContentType, responsePreview
-            // CDP returns the same shape after PR A fix.
-            items = raw.map(e => {
-                const preview = e.responsePreview ?? null;
-                let body = null;
-                if (preview) {
-                    try {
-                        body = JSON.parse(preview);
-                    }
-                    catch {
-                        body = preview;
-                    }
-                }
-                return {
-                    url: e.url || '',
-                    method: e.method || 'GET',
-                    status: e.responseStatus || 0,
-                    size: preview ? preview.length : 0,
-                    ct: e.responseContentType || '',
-                    body,
-                };
-            });
+        const ttlMs = parsePositiveIntOption(opts.ttl, 'ttl', DEFAULT_TTL_MS);
+        const workspace = DEFAULT_BROWSER_WORKSPACE;
+        const hasDetail = typeof opts.detail === 'string' && opts.detail.length > 0;
+        const hasFilter = typeof opts.filter === 'string';
+        // --detail and --filter do different things (one request by key vs. narrow
+        // the list by shape), don't compose, and combining them has no sensible
+        // semantic. Reject up front with a structured error instead of silently
+        // dropping one.
+        if (hasDetail && hasFilter) {
+            emitNetworkError('invalid_args', '--filter and --detail cannot be used together (one narrows a list, the other fetches a specific entry).');
+            return;
         }
-        else {
-            // Fallback to JS interceptor data
-            const requests = await page.evaluate(`(function(){
-          var reqs = window.__opencli_net || [];
-          return JSON.stringify(reqs);
-        })()`);
-            try {
-                items = JSON.parse(requests);
+        let filterFields = null;
+        if (hasFilter) {
+            const parsed = parseFilter(opts.filter);
+            if ('reason' in parsed) {
+                emitNetworkError('invalid_filter', parsed.reason);
+                return;
             }
-            catch {
-                console.log('No network data captured. Run "browser open <url>" first.');
+            filterFields = parsed.fields;
+        }
+        // --detail short-circuits: read from cache only, no live capture needed.
+        if (hasDetail) {
+            const res = loadNetworkCache(workspace, { ttlMs });
+            if (res.status === 'missing') {
+                emitNetworkError('cache_missing', `No cached capture. Run "browser network" first (in workspace "${workspace}").`);
+                return;
+            }
+            if (res.status === 'expired') {
+                emitNetworkError('cache_expired', `Cache is stale (age ${res.ageMs}ms > ttl ${ttlMs}ms). Re-run "browser network" to refresh.`);
+                return;
+            }
+            if (res.status === 'corrupt' || !res.file) {
+                emitNetworkError('cache_corrupt', 'Cache file is malformed; re-run "browser network" to regenerate.');
                 return;
             }
+            const entry = findEntry(res.file, opts.detail);
+            if (!entry) {
+                emitNetworkError('key_not_found', `Key "${opts.detail}" not in cache.`, {
+                    available_keys: res.file.entries.map((e) => e.key),
+                });
+                return;
+            }
+            const rawMaxBody = String(opts.maxBody ?? '0');
+            if (!/^\d+$/.test(rawMaxBody)) {
+                emitNetworkError('invalid_max_body', `--max-body must be a non-negative integer, got "${opts.maxBody}"`);
+                return;
+            }
+            const maxBody = Number.parseInt(rawMaxBody, 10);
+            // Body shape/source:
+            // - If capture already truncated it (entry.body_truncated), the body is a string.
+            // - If the adapter stored a JSON value, it parsed cleanly at capture time; leave it.
+            // - --max-body applies a transport-level cap when the caller wants to keep output small.
+            let outputBody = entry.body;
+            let transportTruncated = false;
+            if (maxBody > 0 && typeof entry.body === 'string' && entry.body.length > maxBody) {
+                outputBody = entry.body.slice(0, maxBody);
+                transportTruncated = true;
+            }
+            const captureTruncated = entry.body_truncated === true;
+            const detailEnvelope = {
+                key: entry.key,
+                url: entry.url,
+                method: entry.method,
+                status: entry.status,
+                ct: entry.ct,
+                size: entry.size,
+                shape: inferShape(entry.body),
+                body: outputBody,
+            };
+            if (captureTruncated || transportTruncated) {
+                detailEnvelope.body_truncated = true;
+                detailEnvelope.body_full_size = entry.body_full_size ?? entry.size;
+                detailEnvelope.body_truncation_reason = captureTruncated
+                    ? 'capture-limit'
+                    : 'max-body';
+            }
+            console.log(JSON.stringify(detailEnvelope, null, 2));
+            return;
+        }
+        // Fresh capture path.
+        let rawItems;
+        try {
+            rawItems = await captureNetworkItems(page);
         }
-        if (items.length === 0) {
-            console.log('No requests captured.');
+        catch (err) {
+            emitNetworkError('capture_failed', `Could not read network capture: ${err.message}`);
             return;
         }
-        // Filter out static resources unless --all
-        if (!opts.all) {
-            items = items.filter(r => (r.ct?.includes('json') || r.ct?.includes('xml') || r.ct?.includes('text/plain')) &&
-                !/\.(js|css|png|jpg|gif|svg|woff|ico|map)(\?|$)/i.test(r.url) &&
-                !/analytics|tracking|telemetry|beacon|pixel|gtag|fbevents/i.test(r.url));
-        }
-        if (opts.detail !== undefined) {
-            const idx = parseInt(opts.detail, 10);
-            const req = items[idx];
-            if (!req) {
-                console.error(`Request #${idx} not found. ${items.length} requests available.`);
-                process.exitCode = EXIT_CODES.USAGE_ERROR;
-                return;
-            }
-            console.log(`${req.method} ${req.url}`);
-            console.log(`Status: ${req.status} | Size: ${req.size} | Type: ${req.ct}`);
-            console.log('---');
-            console.log(typeof req.body === 'string' ? req.body : JSON.stringify(req.body, null, 2));
+        const items = opts.all ? rawItems : filterNetworkItems(rawItems);
+        const filteredOut = rawItems.length - items.length;
+        const keyed = assignKeys(items);
+        const cacheEntries = keyed.map((it) => ({
+            key: it.key,
+            url: it.url,
+            method: it.method,
+            status: it.status,
+            size: it.size,
+            ct: it.ct,
+            body: it.body,
+            ...(it.bodyTruncated ? { body_truncated: true } : {}),
+            ...(it.bodyTruncated && typeof it.bodyFullSize === 'number'
+                ? { body_full_size: it.bodyFullSize }
+                : {}),
+        }));
+        // Soft failure: the caller already has the data, so surface a warning
+        // via the output envelope rather than erroring out the whole command.
+        let cacheWarning = null;
+        try {
+            saveNetworkCache(workspace, cacheEntries);
         }
-        else {
-            console.log(`Captured ${items.length} API requests:\n`);
-            items.forEach((r, i) => {
-                const bodyPreview = r.body ? (typeof r.body === 'string' ? r.body.slice(0, 60) : JSON.stringify(r.body).slice(0, 60)) : '';
-                console.log(`  [${i}] ${r.method} ${r.status} ${r.url.slice(0, 80)}`);
-                if (bodyPreview)
-                    console.log(`      ${bodyPreview}...`);
-            });
-            console.log(`\nUse --detail <index> to see full response body.`);
+        catch (err) {
+            cacheWarning = `Could not persist capture cache: ${err.message}. --detail lookups may miss this capture.`;
+        }
+        // Pair each cache entry with its shape up front so --filter can read
+        // segments without recomputing, and the --raw view can keep the full
+        // body. Cache persistence above stored the unfiltered set on purpose:
+        // later `--detail <key>` lookups must still see requests that the
+        // current --filter narrowed out.
+        const shaped = cacheEntries.map((e) => ({ entry: e, shape: inferShape(e.body) }));
+        const visible = filterFields
+            ? shaped.filter((s) => shapeMatchesFilter(s.shape, filterFields))
+            : shaped;
+        const filterDropped = filterFields ? shaped.length - visible.length : 0;
+        const envelope = {
+            workspace,
+            captured_at: new Date().toISOString(),
+            count: visible.length,
+            filtered_out: filteredOut,
+        };
+        if (filterFields) {
+            envelope.filter = filterFields;
+            envelope.filter_dropped = filterDropped;
+        }
+        if (cacheWarning)
+            envelope.cache_warning = cacheWarning;
+        const truncatedCount = visible.filter((s) => s.entry.body_truncated).length;
+        if (truncatedCount > 0) {
+            envelope.body_truncated_count = truncatedCount;
+            envelope.body_truncated_hint = 'Some bodies exceeded the capture limit; their `shape` reflects only the captured prefix.';
         }
+        if (opts.raw) {
+            envelope.entries = visible.map((s) => s.entry);
+        }
+        else {
+            envelope.entries = visible.map((s) => ({
+                key: s.entry.key,
+                method: s.entry.method,
+                status: s.entry.status,
+                url: s.entry.url,
+                ct: s.entry.ct,
+                size: s.entry.size,
+                shape: s.shape,
+                ...(s.entry.body_truncated ? { body_truncated: true } : {}),
+            }));
+            envelope.detail_hint = 'Run "browser network --detail <key>" for full body.';
+        }
+        console.log(JSON.stringify(envelope, null, 2));
     }));
     // ── Init (adapter scaffolding) ──
     browser.command('init')
@@ -707,8 +1433,12 @@ cli({
     // ── Verify (test adapter) ──
     browser.command('verify')
         .argument('<name>', 'Adapter name in site/command format (e.g. hn/top)')
-        .description('Execute an adapter and show results')
-        .action(async (name) => {
+        .option('--write-fixture', 'Write a starter fixture to ~/.opencli/sites/<site>/verify/<command>.json if none exists')
+        .option('--update-fixture', 'Overwrite an existing fixture with one derived from current output')
+        .option('--no-fixture', 'Ignore any fixture file for this run (no value-level validation)')
+        .option('--strict-memory', 'Fail (not just warn) when ~/.opencli/sites/<site>/endpoints.json or notes.md is missing')
+        .description('Execute an adapter and validate output; uses fixture at ~/.opencli/sites/<site>/verify/<cmd>.json when present')
+        .action(async (name, opts = {}) => {
         try {
             const parts = name.split('/');
             if (parts.length !== 2) {
@@ -723,7 +1453,7 @@ cli({
                 return;
             }
             const { execFileSync } = await import('node:child_process');
-            const os = await import('node:os');
+            const { loadFixture, writeFixture, deriveFixture, validateRows, fixturePath, expandFixtureArgs } = await import('./browser/verify-fixture.js');
             const filePath = path.join(os.homedir(), '.opencli', 'clis', site, `${command}.js`);
             if (!fs.existsSync(filePath)) {
                 console.error(`Adapter not found: ${filePath}`);
@@ -733,14 +1463,24 @@ cli({
             }
             console.log(`🔍 Verifying ${name}...\n`);
             console.log(`  Loading: ${filePath}`);
-            // Read adapter to check if it defines a 'limit' arg
+            const useFixture = opts.fixture !== false;
+            let fixture = useFixture ? loadFixture(site, command) : null;
+            // Build adapter args: fixture.args override the legacy --limit 3 heuristic.
+            //   - object form   { "limit": 3 }            → `--limit 3`
+            //   - array form    ["123", "--limit", "3"]   → verbatim (for positional subjects)
             const adapterSrc = fs.readFileSync(filePath, 'utf-8');
             const hasLimitArg = /['"]limit['"]/.test(adapterSrc);
-            const limitFlag = hasLimitArg ? ' --limit 3' : '';
-            const limitArgs = hasLimitArg ? ['--limit', '3'] : [];
+            const fixtureArgs = fixture?.args;
+            const cliArgs = expandFixtureArgs(fixtureArgs);
+            if (cliArgs.length === 0 && hasLimitArg)
+                cliArgs.push('--limit', '3');
+            const argDisplay = cliArgs.join(' ');
             const invocation = resolveBrowserVerifyInvocation();
+            // Always request JSON so we can validate structurally.
+            const execArgs = [...invocation.args, site, command, ...cliArgs, '--format', 'json'];
+            let rawJson;
             try {
-                const output = execFileSync(invocation.binary, [...invocation.args, site, command, ...limitArgs], {
+                rawJson = execFileSync(invocation.binary, execArgs, {
                     cwd: invocation.cwd,
                     timeout: 30000,
                     encoding: 'utf-8',
@@ -748,13 +1488,9 @@ cli({
                     stdio: ['pipe', 'pipe', 'pipe'],
                     ...(invocation.shell ? { shell: true } : {}),
                 });
-                console.log(`  Executing: opencli ${site} ${command}${limitFlag}\n`);
-                console.log(output);
-                console.log(`\n  ✓ Adapter works!`);
             }
             catch (err) {
-                console.log(`  Executing: opencli ${site} ${command}${limitFlag}\n`);
-                // execFileSync attaches captured stdout/stderr on its thrown Error.
+                console.log(`  Executing: opencli ${site} ${command} ${argDisplay}\n`);
                 const execErr = err;
                 if (execErr.stdout)
                     console.log(String(execErr.stdout));
@@ -762,7 +1498,66 @@ cli({
                     console.error(String(execErr.stderr).slice(0, 500));
                 console.log(`\n  ✗ Adapter failed. Fix the code and try again.`);
                 process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                return;
+            }
+            console.log(`  Executing: opencli ${site} ${command} ${argDisplay}\n`);
+            let rows;
+            try {
+                rows = normalizeVerifyRows(JSON.parse(rawJson));
             }
+            catch {
+                console.log(rawJson);
+                console.log('\n  ✗ Could not parse adapter output as JSON. Is `--format json` broken?');
+                process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                return;
+            }
+            console.log(renderVerifyPreview(rows));
+            console.log(`\n  → ${rows.length} row${rows.length === 1 ? '' : 's'}`);
+            // ── Fixture handling ───────────────────────────────────────────
+            if (opts.writeFixture || opts.updateFixture) {
+                if (fixture && !opts.updateFixture) {
+                    console.log(`\n  Fixture already exists at ${fixturePath(site, command)}.`);
+                    console.log(`  Use --update-fixture to overwrite.`);
+                }
+                else {
+                    const seedArgs = fixtureArgs !== undefined
+                        ? fixtureArgs
+                        : (hasLimitArg ? { limit: 3 } : undefined);
+                    const derived = deriveFixture(rows, seedArgs);
+                    const p = writeFixture(site, command, derived);
+                    console.log(`\n  ${fixture ? '↻ Updated' : '✎ Wrote'} fixture: ${p}`);
+                    console.log(`  Review and hand-tune the derived expectations (add patterns / notEmpty, tighten rowCount).`);
+                    fixture = derived;
+                }
+            }
+            if (!fixture) {
+                console.log(`\n  ✓ Adapter runs. (No fixture at ${fixturePath(site, command)} — consider --write-fixture to seed one.)`);
+                const memoryReport = checkSiteMemory(site);
+                printSiteMemoryReport(memoryReport, opts.strictMemory);
+                if (!memoryReport.ok && opts.strictMemory) {
+                    process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                }
+                return;
+            }
+            const failures = validateRows(rows, fixture);
+            if (failures.length === 0) {
+                console.log(`\n  ✓ Adapter matches fixture (${fixturePath(site, command)}).`);
+                const memoryReport = checkSiteMemory(site);
+                printSiteMemoryReport(memoryReport, opts.strictMemory);
+                if (!memoryReport.ok && opts.strictMemory) {
+                    process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                }
+                return;
+            }
+            console.log(`\n  ✗ Adapter output does not match fixture:`);
+            for (const f of failures.slice(0, 20)) {
+                const where = f.rowIndex !== undefined ? `row[${f.rowIndex}] ` : '';
+                console.log(`    - [${f.rule}] ${where}${f.detail}`);
+            }
+            if (failures.length > 20) {
+                console.log(`    ... and ${failures.length - 20} more failure(s)`);
+            }
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
         catch (err) {
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);