@crouton-kit/capture 1.3.4 → 1.3.6

package/src/cdp/connection.ts

@@ -1,8 +1,7 @@
 import * as fs from 'fs';
 import { CDPClient } from './client.js';
+import { findTabByIdAcrossEndpoints, findTabByUrlAcrossEndpoints } from './targets.js';
 import { type CDPTarget, type ParsedArgs } from './types.js';
-import { findTabById } from './targets.js';
-import { detectCdpPortsAsync } from './detect.js';
 import { ConsoleRecorder, printConsoleSummary } from './console-recorder.js';
 import { HARRecorder } from './har-recorder.js';
 import {
@@ -11,33 +10,31 @@ import {
 } from '../har-manager.js';
 import { getActiveSession, updateActiveSession } from '../session-context.js';
 
+function getPortFromWebSocketDebuggerUrl(url?: string): number | null {
+  if (!url) return null;
+  try {
+    return Number(new URL(url).port);
+  } catch {
+    return null;
+  }
+}
+
 export async function connectForCommand(
   parsed: ParsedArgs,
 ): Promise<{ client: CDPClient; tab: CDPTarget }> {
-  if (!parsed.target) {
-    throw new Error('Use --target <tabId> to target a tab. Run "capture list" to see available tabs.');
+  if (!parsed.target && !parsed.url) {
+    throw new Error('Use --target <tabId> or --url <pattern> to target a tab. Run "capture list" to see available tabs.');
   }
 
-  // If --port is explicit, search only that port. Otherwise search all endpoints.
-  let tab: CDPTarget | null = null;
-  if (parsed.port) {
-    tab = await findTabById(parsed.port, parsed.target);
-  } else {
-    const endpoints = await detectCdpPortsAsync();
-    for (const ep of endpoints) {
-      try {
-        tab = await findTabById(ep.port, parsed.target);
-        if (tab) break;
-      } catch {
-        // Skip endpoints that fail
-      }
-    }
-  }
+  const resolved = parsed.target
+    ? await findTabByIdAcrossEndpoints(parsed.target, parsed.port)
+    : await findTabByUrlAcrossEndpoints(parsed.url!, parsed.port);
+  const tab = resolved?.tab ?? null;
 
   if (!tab) {
-    const query = parsed.target;
+    const query = parsed.target ?? parsed.url;
     throw new Error(
-      `No tab found for target "${query}". Run "capture list" to see available tabs.`,
+      `No tab found for ${parsed.target ? 'target' : 'URL pattern'} "${query}". Run "capture list" to see available tabs.`,
     );
   }
 
@@ -51,6 +48,11 @@ export async function connectForCommand(
     updateActiveSession({ targetId: tab.id });
   }
 
+  const port = resolved?.port ?? getPortFromWebSocketDebuggerUrl(tab.webSocketDebuggerUrl);
+  console.error(
+    `Using target ${tab.id.slice(0, 8)}${port ? ` on port ${port}` : ''}${tab.url ? ` (${tab.url})` : ''}`,
+  );
+
   const client = new CDPClient(tab.webSocketDebuggerUrl);
   await client.waitReady();
 

package/src/cdp/detect.ts

@@ -27,8 +27,17 @@ interface CdpProbeResult {
   browser: string;
   app: string;
   isElectron: boolean;
+  hasPageTarget: boolean;
 }
 
+// Node's inspector, workerd/Miniflare's inspector, and similar V8-Inspector-
+// protocol processes all speak enough of the Chrome DevTools Protocol to
+// answer /json/version with a `Browser` field, so a naive probe mistakes them
+// for a real browser. They are not: they never return a top-level
+// `webSocketDebuggerUrl` (there's no browser-level target to attach to, only
+// the single runtime target) and they never host a `page`-type target. Both
+// are checked so these endpoints are excluded from auto-selection instead of
+// being confused for the intended browser.
 async function probeCdpPort(port: number): Promise<CdpProbeResult | null> {
   try {
     const controller = new AbortController();
@@ -41,10 +50,14 @@ async function probeCdpPort(port: number): Promise<CdpProbeResult | null> {
       const version = (await resp.json()) as {
         Browser?: string;
         'User-Agent'?: string;
+        webSocketDebuggerUrl?: string;
       };
       const browser = version.Browser;
       const userAgent = version['User-Agent'] ?? '';
       if (!browser) return null;
+      // No browser-level WebSocket debugger URL means there's nothing to
+      // open new tabs on — this isn't a controllable browser.
+      if (!version.webSocketDebuggerUrl) return null;
 
       const isElectron = userAgent.includes('Electron');
 
@@ -58,7 +71,9 @@ async function probeCdpPort(port: number): Promise<CdpProbeResult | null> {
         if (appMatch) app = appMatch[1];
       }
 
-      return { browser, app, isElectron };
+      const hasPageTarget = await probeHasPageTarget(port);
+
+      return { browser, app, isElectron, hasPageTarget };
     }
   } catch {
     // Not a CDP port or not responding
@@ -66,6 +81,22 @@ async function probeCdpPort(port: number): Promise<CdpProbeResult | null> {
   return null;
 }
 
+async function probeHasPageTarget(port: number): Promise<boolean> {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 500);
+    const resp = await fetch(`http://localhost:${port}/json/list`, {
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    if (!resp.ok) return false;
+    const list = (await resp.json()) as Array<{ type?: string }>;
+    return Array.isArray(list) && list.some((t) => t.type === 'page');
+  } catch {
+    return false;
+  }
+}
+
 function getLocalhostListeningPorts(): number[] {
   try {
     // netstat is much faster than lsof on macOS
@@ -92,6 +123,7 @@ export interface CdpEndpoint {
   app: string;
   bundleId: string;
   isElectron: boolean;
+  hasPageTarget: boolean;
 }
 
 export async function detectCdpPortsAsync(): Promise<CdpEndpoint[]> {
@@ -116,6 +148,7 @@ export async function detectCdpPortsAsync(): Promise<CdpEndpoint[]> {
         app: probe.app,
         bundleId,
         isElectron: probe.isElectron,
+        hasPageTarget: probe.hasPageTarget,
       });
     }
   });
@@ -124,6 +157,33 @@ export async function detectCdpPortsAsync(): Promise<CdpEndpoint[]> {
   return results;
 }
 
+// Selects the endpoint `detect`/`detectCdpPort` should treat as "the"
+// browser out of everything discovered on localhost. Shared so `capture
+// detect`'s printed default always matches what auto-discovery actually
+// picks for session start / navigate / etc.
+export function pickPreferredEndpoint(
+  endpoints: CdpEndpoint[],
+  defaultBrowser: string | null,
+): CdpEndpoint {
+  // Endpoints that already host a real page/tab are real browsers. CDP-
+  // speaking non-browser processes (Node/workerd inspectors, etc.) never do,
+  // so prefer real browsers whenever at least one is present — this is what
+  // keeps an unrelated CDP listener from being picked over the intended one.
+  const withPages = endpoints.filter((e) => e.hasPageTarget);
+  const candidates = withPages.length > 0 ? withPages : endpoints;
+
+  if (defaultBrowser) {
+    const match = candidates.find(
+      (p) => p.bundleId === defaultBrowser && !p.isElectron,
+    );
+    if (match) return match;
+  }
+
+  // Fall back to first non-Electron, then first found
+  const nonElectron = candidates.find((p) => !p.isElectron);
+  return nonElectron ?? candidates[0];
+}
+
 export async function detectCdpPort(): Promise<number> {
   const endpoints = await detectCdpPortsAsync();
   if (endpoints.length === 0) {
@@ -135,16 +195,5 @@ export async function detectCdpPort(): Promise<number> {
     );
   }
 
-  // Use default browser if available (prefer non-Electron)
-  const defaultBrowser = getDefaultBrowserId();
-  if (defaultBrowser) {
-    const match = endpoints.find(
-      (p) => p.bundleId === defaultBrowser && !p.isElectron,
-    );
-    if (match) return match.port;
-  }
-
-  // Fall back to first non-Electron, then first found
-  const nonElectron = endpoints.find((p) => !p.isElectron);
-  return (nonElectron ?? endpoints[0]).port;
+  return pickPreferredEndpoint(endpoints, getDefaultBrowserId()).port;
 }

package/src/cdp/dispatch.ts

@@ -5,6 +5,7 @@ import { cmdExec } from './commands/exec.js';
 import { cmdScreenshot, cmdClick, cmdType, cmdA11y } from './commands/ui.js';
 import { cmdRecord, cmdNavigate, cmdNetwork } from './commands/traffic.js';
 import { cmdHar } from './commands/har.js';
+import { cmdLib } from './commands/lib.js';
 
 export async function cdpMain(): Promise<void> {
   const args = process.argv.slice(2);
@@ -24,6 +25,7 @@ export async function cdpMain(): Promise<void> {
     case 'navigate': return cmdNavigate(parsed, args);
     case 'network': return cmdNetwork(parsed, args);
     case 'har': return cmdHar(parsed, args);
+    case 'lib': return cmdLib(parsed, args);
     default:
       console.log(CDP_USAGE);
   }

package/src/cdp/exec-expression.ts

@@ -0,0 +1,49 @@
+import * as ts from 'typescript';
+
+function compiles(source: string): boolean {
+  try {
+    new Function(source);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function wrapAsyncBody(code: string): string {
+  return `(async () => { ${code} })()`;
+}
+
+function wrapFinalExpression(code: string, source: ts.SourceFile): string {
+  const lastStatement = source.statements[source.statements.length - 1];
+  if (!ts.isExpressionStatement(lastStatement)) {
+    return wrapAsyncBody(code);
+  }
+
+  const expressionStart = lastStatement.expression.getStart(source);
+  const expressionEnd = lastStatement.expression.end;
+  return `(async () => { ${code.slice(0, lastStatement.getStart(source))}return (${code.slice(expressionStart, expressionEnd)}); })()`;
+}
+
+export function buildExecExpression(code: string, prebuilt?: string): string {
+  if (prebuilt) return prebuilt;
+
+  if (compiles(`return (${code});`)) {
+    return code;
+  }
+
+  const expression = `return (async () => (${code}))();`;
+  if (compiles(expression)) {
+    return `(async () => (${code}))()`;
+  }
+
+  const source = ts.createSourceFile('exec.js', code, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+  if (
+    source.statements.length > 0 &&
+    !source.statements.some(ts.isReturnStatement) &&
+    ts.isExpressionStatement(source.statements[source.statements.length - 1])
+  ) {
+    return wrapFinalExpression(code, source);
+  }
+
+  return wrapAsyncBody(code);
+}

package/src/cdp/execute.ts

@@ -1,7 +1,6 @@
 import { CDPClient } from './client.js';
-import { type CDPTarget } from './types.js';
-import { detectCdpPort } from './detect.js';
-import { findTabById } from './targets.js';
+import { findTabByIdAcrossEndpoints } from './targets.js';
+import { buildExecExpression } from './exec-expression.js';
 import { ConsoleRecorder, type ConsoleEntry } from './console-recorder.js';
 import { HARRecorder } from './har-recorder.js';
 import { printConsoleSummary } from './console-recorder.js';
@@ -28,15 +27,12 @@ export async function executeInBrowser(
   code: string,
   options: ExecuteOptions = {},
 ): Promise<ExecuteResult> {
-  const port = options.port ?? (await detectCdpPort());
-
   if (!options.targetId) {
     throw new Error('Use --target <tabId> to target a tab. Run "capture list" to see available tabs.');
   }
 
-  // Find tab by exact/prefix ID
-  let tab: CDPTarget | null = null;
-  tab = await findTabById(port, options.targetId);
+  const resolved = await findTabByIdAcrossEndpoints(options.targetId, options.port);
+  const tab = resolved?.tab ?? null;
   if (!tab) {
     throw new Error(
       `No tab found for target "${options.targetId}". Run "capture list" to see available tabs.`,
@@ -68,7 +64,7 @@ export async function executeInBrowser(
     const result = (await client.send(
       'Runtime.evaluate',
       {
-        expression: code,
+        expression: buildExecExpression(code),
         awaitPromise: true,
         returnByValue: true,
       },

package/src/cdp/record.ts

@@ -1,7 +1,13 @@
 import { CDPClient } from './client.js';
-import { type CDPTarget } from './types.js';
 import { detectCdpPort } from './detect.js';
-import { findTab, findTabById, openTab, listTargets } from './targets.js';
+import {
+  findTab,
+  findTabByIdAcrossEndpoints,
+  findTabByUrlAcrossEndpoints,
+  listTargets,
+  openTab,
+  type CDPTarget,
+} from './targets.js';
 import { HARRecorder } from './har-recorder.js';
 import { writeHarAndPrintSummary } from './har-output.js';
 import { type HAREntry } from '../har-manager.js';
@@ -22,14 +28,18 @@ export interface RecordResult {
 export async function recordTraffic(
   options: RecordOptions,
 ): Promise<RecordResult> {
-  const port = options.port ?? (await detectCdpPort());
+  let port = options.port ?? 0;
   const duration = options.duration ?? 10;
 
   if (!options.targetId) {
     throw new Error('Use --target <tabId> to target a tab. Run "capture list" to see available tabs.');
   }
 
-  const tab = await findTabById(port, options.targetId);
+  const resolved = await findTabByIdAcrossEndpoints(options.targetId, options.port);
+  const tab = resolved?.tab ?? null;
+  if (resolved) {
+    port = resolved.port;
+  }
   if (!tab) {
     throw new Error(
       `No tab found for target "${options.targetId}". Run "capture list" to see available tabs.`,
@@ -43,11 +53,15 @@ export async function recordTraffic(
   const client = new CDPClient(tab.webSocketDebuggerUrl);
   await client.waitReady();
 
+  console.error(
+    `Using target ${tab.id.slice(0, 8)} on port ${port} (${tab.url})`,
+  );
+
   const recorder = new HARRecorder(client);
   await recorder.start();
 
   console.error(
-    `Recording traffic on "${tab.url}" for ${duration}s... (click around in the browser)`,
+    `Recording traffic on target ${tab.id.slice(0, 8)} on port ${port} (${tab.url}) for ${duration}s... (click around in the browser)`,
   );
 
   await new Promise((r) => setTimeout(r, duration * 1000));
@@ -79,30 +93,41 @@ export interface NavigateAndRecordResult {
 export async function navigateAndRecord(
   options: NavigateAndRecordOptions,
 ): Promise<NavigateAndRecordResult> {
-  const port = options.port ?? (await detectCdpPort());
+  let requestedUrl: URL;
+  try {
+    requestedUrl = new URL(options.url);
+  } catch {
+    throw new Error(`Invalid URL: ${options.url}`);
+  }
   const settle = options.settle ?? 2000;
 
-  // Find tab — prefer targetId (exact) over domain match (fuzzy)
+  // Find tab — prefer exact target or an already-open matching URL across all endpoints.
+  let port = options.port ?? 0;
   let tab: CDPTarget | null = null;
   let isNewTab = false;
+
   if (options.targetId) {
-    tab = await findTabById(port, options.targetId);
-    if (!tab) {
+    const resolved = await findTabByIdAcrossEndpoints(options.targetId, options.port);
+    if (!resolved) {
       throw new Error(
         `No tab found with target ID "${options.targetId}". Tab may have been closed.`,
       );
     }
+    port = resolved.port;
+    tab = resolved.tab;
   } else {
-    let domain: string;
-    try {
-      domain = new URL(options.url).hostname;
-    } catch {
-      throw new Error(`Invalid URL: ${options.url}`);
-    }
-    tab = await findTab(port, domain);
-    if (!tab) {
-      tab = await openTab(port, options.url);
-      isNewTab = true;
+    const matched = await findTabByUrlAcrossEndpoints(options.url, options.port);
+    if (matched) {
+      port = matched.port;
+      tab = matched.tab;
+    } else {
+      port = options.port ?? (await detectCdpPort());
+      const domain = requestedUrl.hostname;
+      tab = await findTab(port, domain);
+      if (!tab) {
+        tab = await openTab(port, options.url);
+        isNewTab = true;
+      }
     }
   }
   if (!tab.webSocketDebuggerUrl) {
@@ -113,6 +138,10 @@ export async function navigateAndRecord(
   await client.waitReady();
   await client.send('Page.enable');
 
+  console.error(
+    `Using target ${tab.id.slice(0, 8)} on port ${port} (${tab.url})`,
+  );
+
   // Start recording BEFORE navigation
   const recorder = new HARRecorder(client);
   await recorder.start();
@@ -120,7 +149,21 @@ export async function navigateAndRecord(
   if (!isNewTab) {
     // Navigate existing tab
     console.error(`Navigating to: ${options.url}`);
-    await client.send('Page.navigate', { url: options.url });
+    const navResult = (await client.send('Page.navigate', {
+      url: options.url,
+    })) as { loaderId?: string; errorText?: string };
+    // A fragment-only change against the current document is a same-document
+    // navigation: Chrome updates location.hash but does NOT reload the page, so
+    // SPAs that read the fragment on mount (e.g. Excalidraw's #url= scene import)
+    // never see it. Same-document navigations return no loaderId. When that
+    // happens, force a genuine cross-document load by bouncing through
+    // about:blank and re-navigating, so the target URL (fragment included) is
+    // delivered to a freshly-mounted document. A plain Page.reload here races
+    // the still-committing fragment nav and can reload the pre-fragment URL.
+    if (!navResult.loaderId) {
+      await client.send('Page.navigate', { url: 'about:blank' });
+      await client.send('Page.navigate', { url: options.url });
+    }
   }
 
   const deadline = 60_000;

package/src/cdp/targets.ts

@@ -1,4 +1,5 @@
 import { CDPClient } from './client.js';
+import { detectCdpPortsAsync } from './detect.js';
 import { type CDPTarget } from './types.js';
 
 async function getBrowserClient(
@@ -11,8 +12,15 @@ async function getBrowserClient(
     );
   }
   const version = (await versionResp.json()) as {
-    webSocketDebuggerUrl: string;
+    webSocketDebuggerUrl?: string;
   };
+  if (!version.webSocketDebuggerUrl) {
+    throw new Error(
+      `Port ${port} answers CDP's /json/version but has no browser-level WebSocket debugger URL — ` +
+        `it's not a real browser (e.g. a Node/workerd inspector), so it can't host tabs. ` +
+        `Run "capture detect" to find a real browser endpoint, or pass --port explicitly.`,
+    );
+  }
   const client = new CDPClient(version.webSocketDebuggerUrl);
   await client.waitReady();
   return { client, browserWsUrl: version.webSocketDebuggerUrl };
@@ -86,6 +94,113 @@ export async function findTabById(
   return null;
 }
 
+export async function findTabByIdInPorts(
+  targetId: string,
+  ports: number[],
+  finder: (port: number, targetId: string) => Promise<CDPTarget | null> = findTabById,
+): Promise<{ port: number; tab: CDPTarget } | null> {
+  for (const port of ports) {
+    try {
+      const tab = await finder(port, targetId);
+      if (tab) return { port, tab };
+    } catch {
+      // Skip endpoints that fail or are ambiguous on a different port.
+    }
+  }
+  return null;
+}
+
+function normalizeUrlForMatch(value: string): { full: string; host: string; path: string } | null {
+  try {
+    const url = new URL(value);
+    const path = url.pathname.replace(/\/+$/, '') || '/';
+    return {
+      full: `${url.origin}${path}${url.search}${url.hash}`.toLowerCase(),
+      host: url.hostname.toLowerCase(),
+      path: path.toLowerCase(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function scoreTabUrlMatch(tabUrl: string, requestedUrl: string): number {
+  const tab = normalizeUrlForMatch(tabUrl);
+  const requested = normalizeUrlForMatch(requestedUrl);
+
+  if (tab && requested) {
+    if (tab.full === requested.full) return 100;
+    if (tab.host === requested.host && tab.path === requested.path) return 95;
+    if (tab.host === requested.host && tab.path.startsWith(requested.path)) return 90;
+    if (tab.host === requested.host && requested.path.startsWith(tab.path)) return 85;
+    if (tab.host === requested.host) return 70;
+    if (tab.full.includes(requested.full)) return 60;
+    if (tab.full.includes(requested.host)) return 50;
+    if (requested.full.includes(tab.full)) return 40;
+    return 0;
+  }
+
+  const tabLower = tabUrl.toLowerCase();
+  const requestedLower = requestedUrl.toLowerCase();
+  if (tabLower === requestedLower) return 100;
+  if (tabLower.includes(requestedLower)) return 60;
+  if (requestedLower.includes(tabLower)) return 40;
+  return 0;
+}
+
+function resolveSearchPorts(
+  endpoints: Array<{ port: number }>,
+  preferredPort?: number,
+): number[] {
+  if (preferredPort) return [preferredPort];
+  return endpoints.map((endpoint) => endpoint.port);
+}
+
+export async function findTabByIdAcrossEndpoints(
+  targetId: string,
+  preferredPort?: number,
+): Promise<{ port: number; tab: CDPTarget } | null> {
+  const ports = resolveSearchPorts(await detectCdpPortsAsync(), preferredPort);
+  return findTabByIdInPorts(targetId, ports);
+}
+
+export async function findTabByUrlAcrossEndpoints(
+  url: string,
+  preferredPort?: number,
+): Promise<{ port: number; tab: CDPTarget } | null> {
+  const ports = resolveSearchPorts(await detectCdpPortsAsync(), preferredPort);
+  let best: { port: number; tab: CDPTarget; score: number } | null = null;
+
+  for (const port of ports) {
+    try {
+      const targets = await listTargets(port);
+      for (const tab of targets.filter((t) => t.type === 'page')) {
+        const score = scoreTabUrlMatch(tab.url, url);
+        if (score <= 0) continue;
+        if (!best || score > best.score || (score === best.score && port < best.port)) {
+          best = { port, tab, score };
+        }
+      }
+    } catch {
+      // Skip endpoints that fail to respond.
+    }
+  }
+
+  return best ? { port: best.port, tab: best.tab } : null;
+}
+
+export function requireTargetId(
+  targetId: string | null | undefined,
+  url: string,
+): string {
+  if (!targetId) {
+    throw new Error(
+      `Target.createTarget returned no targetId for ${url}. Reuse an existing tab with --target.`,
+    );
+  }
+  return targetId;
+}
+
 export async function openTab(port: number, url: string): Promise<CDPTarget> {
   const { client } = await getBrowserClient(port);
 
@@ -95,16 +210,17 @@ export async function openTab(port: number, url: string): Promise<CDPTarget> {
       url,
       background: true,
     })) as {
-      targetId: string;
+      targetId: string | null;
     };
+    const targetId = requireTargetId(result.targetId, url);
 
     // Return target info
     return {
-      id: result.targetId,
+      id: targetId,
       title: '',
       url,
       type: 'page',
-      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${result.targetId}`,
+      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${targetId}`,
     };
   } finally {
     client.close();

package/src/cdp/types.ts

@@ -22,6 +22,7 @@ export interface ParsedArgs {
   har?: string;
   new?: boolean;
   target?: string;
+  url?: string;
   role?: string;
   into?: string;
   noScreenshot?: boolean;

package/src/cdp/usage.ts

@@ -1,7 +1,7 @@
 export const CDP_USAGE = `CDP — browser automation via exec, a11y interactions, and screenshots.
 
 Commands:
-  exec <code>         Execute JavaScript in a browser tab
+  exec <code>         Execute JavaScript in a browser tab (expressions, return, await)
   exec --file <path>  Execute JS from file
   detect              Detect CDP port (prioritizes default browser)
   list                List all browser tabs
@@ -17,10 +17,15 @@ Commands:
   har create          Create a HAR recording (returns id)
   har read [id]       Read accumulated HAR entries (id optional in active session)
   har delete <id>     Delete a HAR recording
+  lib list            List available vault libs (dev checkout only)
+  lib search "<q>"     Fuzzy-search lib functions [--limit N]
+  lib show <name>     Lib + function summaries
+  lib read <name> [fn…]  Full input/output schemas (+ .ts source path)
 
 Options:
   --port <port>       Override CDP port
   --target <tabId>    Target tab by exact ID (preferred, parallel-safe)
+  CDP_PORT / CDP_TARGET  Default port + tab when set by orchestrators
   --new               Force new tab (open)
   --record            Enable HAR recording (exec)
   --har <id>          Append traffic to a HAR recording
@@ -49,8 +54,8 @@ Examples:
   capture list
   capture open "https://app.example.com" --new
   capture exec "document.title" --target <id>
-  capture exec "document.querySelector('.btn').click()" --target <id>
-  capture exec "fetch('/api/data').then(r=>r.json())" --target <id> --record
+  capture exec "return document.title" --target <id>
+  capture exec "const r = await fetch('/api/data'); return await r.json()" --target <id> --record
   capture exec --file /tmp/scrape.js --target <id>
   capture screenshot --target <id> --out /tmp/shot.png
   capture a11y --target <id> --interactive
@@ -59,4 +64,7 @@ Examples:
   capture har create
   capture exec "document.querySelector('form').submit()" --target <id> --har <id>
   capture har read <id>
+  capture lib search "search emails"
+  capture lib read gmail searchEmails
+  capture exec "import {searchEmails} from 'libs/gmail'; const ctx = await getContext(); return await searchEmails({ ...ctx, query: 'invoice' })"
 `;