publishport-opencli 1.0.0

package/dist/src/browser/daemon-client.js

@@ -0,0 +1 @@
+import{sleep as L}from"../utils.js";import{BrowserConnectError as D}from"../errors.js";import{classifyBrowserError as S}from"./errors.js";import{resolveProfileContextId as M}from"./profile.js";import{DEFAULT_BROWSER_CONNECT_TIMEOUT as $}from"./config.js";import{ensureBrowserBridgeReady as H}from"./daemon-lifecycle.js";import{isPreDispatchError as O}from"./bridge-readiness.js";import{fetchDaemonStatus,getDaemonHealth,requestDaemon as _,requestDaemonShutdown}from"./daemon-transport.js";let g=0;function N(){return`cmd_${process.pid}_${Date.now()}_${++g}`}export class BrowserCommandError extends Error{code;hint;constructor(K,J,Q){super(K);this.code=J;this.hint=Q;this.name="BrowserCommandError"}}export{fetchDaemonStatus,getDaemonHealth,requestDaemonShutdown};async function f(K,J){const Q=4;let X=!1,P=!1,Y=!1;const b=K==="navigate";let Z=!1;for(let F=1;F<=Q;F++){const j=N(),q=process.env.OPENCLI_WINDOW,x=q==="foreground"||q==="background"?q:void 0,V=J.contextId??M(),k=J.windowMode??x,W={id:j,action:K,...J,...V&&{contextId:V},...k&&{windowMode:k}};try{const G=await _("/command",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(W),timeout:30000}),z=await G.json();if(z.ok)return z;if(z.errorCode==="command_result_unknown"){if(b&&!Z){Z=!0;await H({timeoutSeconds:$,contextId:V,verbose:!1});continue}throw new BrowserCommandError(z.error??"Browser command result is unknown",z.errorCode,z.errorHint)}if(!X&&O(z.errorCode)){X=!0;await H({timeoutSeconds:$,contextId:V,verbose:!1});continue}if(G.status===409&&!z.errorCode&&(z.error??"").includes("Duplicate command id")&&!P){P=!0;continue}const A=S(Error(z.error??""));if(A.retryable&&!Y){Y=!0;await L(A.delayMs);continue}throw new BrowserCommandError(z.error??"Daemon command failed",z.errorCode,z.errorHint)}catch(G){if(G instanceof BrowserCommandError||G instanceof D)throw G;if(G instanceof Error&&G.name==="AbortError"){if(b&&!Z){Z=!0;await H({timeoutSeconds:$,contextId:V,verbose:!1});continue}throw new BrowserCommandError("Browser command timed out client-side; the page may still have applied it.","command_result_unknown","Inspect the page state before retrying. Idempotent reads are safe to retry; non-idempotent writes may have already happened.")}if(!X&&G instanceof TypeError){X=!0;await H({timeoutSeconds:$,contextId:V,verbose:!1});continue}if(G instanceof Error){const z=S(G);if(z.retryable&&!Y){Y=!0;await L(z.delayMs);continue}}throw G}}throw new BrowserCommandError("sendCommand: max attempts exhausted","max_attempts_exhausted")}export async function sendCommand(K,J={}){return(await f(K,J)).data}export async function sendCommandFull(K,J={}){const Q=await f(K,J);return{data:Q.data,page:Q.page}}export async function bindTab(K,J={}){return sendCommand("bind",{session:K,surface:"browser",...J})}

package/dist/src/browser/daemon-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/daemon-lifecycle.d.ts

@@ -0,0 +1,37 @@
+import { type ChildProcess } from 'node:child_process';
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+import { requestDaemonShutdown, type DaemonHealth, type DaemonStatus } from './daemon-transport.js';
+export interface DaemonLaunchSpec {
+    binary: string;
+    args: string[];
+    scriptPath: string;
+}
+export interface DaemonRestartResult {
+    previousStatus: DaemonStatus | null;
+    status: DaemonStatus | null;
+    stopped: boolean;
+    spawned: boolean;
+}
+export interface EnsureBrowserBridgeReadyResult {
+    health: DaemonHealth;
+    spawnedProcess: ChildProcess | null;
+}
+export declare function resolveDaemonLaunchSpec(): DaemonLaunchSpec;
+export declare function spawnDaemonProcess(): ChildProcess;
+export declare function waitForDaemonStop(timeoutMs: number): Promise<boolean>;
+export declare function waitForDaemonStatus(timeoutMs: number): Promise<DaemonStatus | null>;
+export declare const daemonLifecycleHooks: {
+    requestDaemonShutdown: typeof requestDaemonShutdown;
+    spawnDaemonProcess: typeof spawnDaemonProcess;
+    waitForDaemonStop: typeof waitForDaemonStop;
+};
+export declare function restartDaemon(opts?: {
+    stopTimeoutMs?: number;
+    startTimeoutMs?: number;
+}): Promise<DaemonRestartResult>;
+export declare function ensureBrowserBridgeReady(opts?: {
+    timeoutSeconds?: number;
+    contextId?: string;
+    verbose?: boolean;
+}): Promise<EnsureBrowserBridgeReadyResult>;
+export { DEFAULT_DAEMON_PORT };

package/dist/src/browser/daemon-lifecycle.js

@@ -0,0 +1,12 @@
+import{spawn as C}from"node:child_process";import{fileURLToPath as F}from"node:url";import*as M from"node:fs";import*as K from"node:path";import{DEFAULT_DAEMON_PORT}from"../constants.js";import{BrowserConnectError as J}from"../errors.js";import{PKG_VERSION as N}from"../version.js";import{waitForBridgeReady as b}from"./bridge-readiness.js";import{fetchDaemonStatus as B,getDaemonHealth as g,requestDaemonShutdown as O}from"./daemon-transport.js";export function resolveDaemonLaunchSpec(){const z=K.dirname(F(import.meta.url)),Q=K.resolve(z,".."),W=K.join(Q,"daemon.ts"),Z=K.join(Q,"daemon.js"),Y=M.existsSync(W),X=Y?W:Z,$=!!process.versions?.bun,U=Y&&!$;return{binary:process.execPath,args:U?["--import","tsx/esm",X]:[X],scriptPath:X}}export function spawnDaemonProcess(){const z=resolveDaemonLaunchSpec(),Q=C(z.binary,z.args,{detached:!0,stdio:"ignore",env:{...process.env}});Q.unref();return Q}export async function waitForDaemonStop(z){const Q=Date.now()+z;while(Date.now()<Q){await x(200);if((await g()).state==="stopped")return!0}return!1}export async function waitForDaemonStatus(z){const Q=Date.now()+z;while(Date.now()<Q){const W=await B({timeout:Math.min(1000,Math.max(100,Q-Date.now()))});if(W)return W;await x(200)}return null}export const daemonLifecycleHooks={requestDaemonShutdown:O,spawnDaemonProcess,waitForDaemonStop};export async function restartDaemon(z={}){const Q=await B();let W=Q===null;if(Q){W=await O()&&await waitForDaemonStop(z.stopTimeoutMs??3000);if(!W)return{previousStatus:Q,status:Q,stopped:!1,spawned:!1}}spawnDaemonProcess();const Z=await waitForDaemonStatus(z.startTimeoutMs??5000);return{previousStatus:Q,status:Z,stopped:W,spawned:!0}}export async function ensureBrowserBridgeReady(z={}){const W=(z.timeoutSeconds&&z.timeoutSeconds>0?z.timeoutSeconds:10)*1000,Z=z.verbose??!0,Y=z.contextId,X=await g({contextId:Y}),$=X.status?.daemonVersion,U=!!X.status&&(!$||$!==N);let q=!1,k=null;if(U){const y=$?`v${$} ≠ v${N}`:`pre-version daemon, CLI is v${N}`;if(Z&&(process.env.OPENCLI_VERBOSE||process.stderr.isTTY))process.stderr.write(`⚠️  Stale daemon detected (${y}). Restarting...
+`);let j=await daemonLifecycleHooks.requestDaemonShutdown()&&await daemonLifecycleHooks.waitForDaemonStop(3000);if(!j){const G=X.status?.pid;if(typeof G==="number"&&Number.isInteger(G)&&G>0){try{process.kill(G,"SIGKILL")}catch{}j=await daemonLifecycleHooks.waitForDaemonStop(2000)}}if(!j)throw new J("Stale daemon could not be replaced",`A stale daemon (${y}) is running but did not shut down (graceful + SIGKILL both failed).
+  Run manually: opencli daemon stop`,"daemon-not-running");q=!0}if(!q&&X.state==="ready")return{health:X,spawnedProcess:k};if(!q&&X.state==="profile-required")throw V(X,Y);if(q||X.state==="stopped"){if(Z&&(process.env.OPENCLI_VERBOSE||process.stderr.isTTY))process.stderr.write(`⏳ Starting daemon...
+`);k=daemonLifecycleHooks.spawnDaemonProcess()}else if(Z&&(process.env.OPENCLI_VERBOSE||process.stderr.isTTY)){process.stderr.write(`⏳ Waiting for Chrome/Chromium extension to connect...
+`);process.stderr.write(`   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.
+`)}const A=await b(g,{timeoutMs:W,contextId:Y});if(A.state==="ready")return{health:A,spawnedProcess:k};throw V(A,Y)}function V(z,Q){if(z.state==="profile-required")return new J("Multiple Browser Bridge profiles are connected",`Select one with --profile <name>, OPENCLI_PROFILE=<name>, or opencli profile use <name>.
+Run opencli profile list to see connected profiles.`,"profile-required");if(z.state==="profile-disconnected"){const W=Q??z.status.contextId??"unknown";return new J(`Browser profile "${W}" is not connected`,"Open the matching Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.","profile-disconnected")}if(z.state==="no-extension")return new J("Browser Bridge extension not connected",`Make sure Chrome/Chromium is open and the OpenCLI extension is enabled.
+If not installed:
+  1. Download: https://github.com/jackwener/opencli/releases
+`+"  2. Open chrome://extensions → Developer Mode → Load unpacked","extension-not-connected");return new J("Failed to start opencli daemon",`Try running manually:
+  node ${resolveDaemonLaunchSpec().scriptPath}
+Make sure port ${DEFAULT_DAEMON_PORT} is available.`,"daemon-not-running")}function x(z){return new Promise((Q)=>setTimeout(Q,z))}export{DEFAULT_DAEMON_PORT};

package/dist/src/browser/daemon-transport.d.ts

@@ -0,0 +1,55 @@
+export interface DaemonStatus {
+    ok: boolean;
+    pid: number;
+    uptime: number;
+    daemonVersion?: string;
+    extensionConnected: boolean;
+    extensionVersion?: string;
+    extensionCompatRange?: string;
+    contextId?: string;
+    profileRequired?: boolean;
+    profileDisconnected?: boolean;
+    profiles?: BrowserProfileStatus[];
+    pending: number;
+    commandResultUnknown?: number;
+    memoryMB: number;
+    port: number;
+}
+export interface BrowserProfileStatus {
+    contextId: string;
+    extensionConnected: boolean;
+    extensionVersion?: string;
+    extensionCompatRange?: string;
+    pending: number;
+    lastSeenAt?: number;
+}
+export type DaemonHealth = {
+    state: 'stopped';
+    status: null;
+} | {
+    state: 'no-extension';
+    status: DaemonStatus;
+} | {
+    state: 'profile-required';
+    status: DaemonStatus;
+} | {
+    state: 'profile-disconnected';
+    status: DaemonStatus;
+} | {
+    state: 'ready';
+    status: DaemonStatus;
+};
+export declare function requestDaemon(pathname: string, init?: RequestInit & {
+    timeout?: number;
+}): Promise<Response>;
+export declare function fetchDaemonStatus(opts?: {
+    timeout?: number;
+    contextId?: string;
+}): Promise<DaemonStatus | null>;
+export declare function getDaemonHealth(opts?: {
+    timeout?: number;
+    contextId?: string;
+}): Promise<DaemonHealth>;
+export declare function requestDaemonShutdown(opts?: {
+    timeout?: number;
+}): Promise<boolean>;

package/dist/src/browser/daemon-transport.js

@@ -0,0 +1 @@
+import{DEFAULT_DAEMON_PORT as c,unsupportedDaemonPortEnvMessage as u}from"../constants.js";const f=c,l=`http://127.0.0.1:${f}`,d={"X-OpenCLI":"1"};class o extends Error{constructor(e){super(u(e));this.name="UnsupportedDaemonPortEnvError"}}function m(){const e=process.env.OPENCLI_DAEMON_PORT;if(e!==void 0&&e!=="")throw new o(e)}export async function requestDaemon(e,t){m();const{timeout:n=2000,headers:s,...a}=t??{},r=new AbortController,i=setTimeout(()=>r.abort(),n);try{return await fetch(`${l}${e}`,{...a,headers:{...d,...s},signal:r.signal})}finally{clearTimeout(i)}}export async function fetchDaemonStatus(e){try{const t=e?.contextId?`?contextId=${encodeURIComponent(e.contextId)}`:"",n=await requestDaemon(`/status${t}`,{timeout:e?.timeout??2000});if(!n.ok)return null;return await n.json()}catch(t){if(t instanceof o)throw t;return null}}export async function getDaemonHealth(e){const t=await fetchDaemonStatus(e);if(!t)return{state:"stopped",status:null};if(t.profileRequired)return{state:"profile-required",status:t};if(t.profileDisconnected)return{state:"profile-disconnected",status:t};if(!t.extensionConnected)return{state:"no-extension",status:t};return{state:"ready",status:t}}export async function requestDaemonShutdown(e){try{return(await requestDaemon("/shutdown",{method:"POST",timeout:e?.timeout??5000})).ok}catch(t){if(t instanceof o)throw t;return!1}}

package/dist/src/browser/daemon-version.d.ts

@@ -0,0 +1,4 @@
+import type { DaemonStatus } from './daemon-client.js';
+export declare function isDaemonStale(status: Pick<DaemonStatus, 'daemonVersion'> | null | undefined, cliVersion?: string): boolean;
+export declare function formatDaemonVersion(status: Pick<DaemonStatus, 'daemonVersion'> | null | undefined): string;
+export declare function staleDaemonIssue(status: Pick<DaemonStatus, 'daemonVersion'> | null | undefined, cliVersion: string): string;

package/dist/src/browser/daemon-version.js

@@ -0,0 +1,2 @@
+export function isDaemonStale(e,n){if(!e||!n)return!1;return!e.daemonVersion||e.daemonVersion!==n}export function formatDaemonVersion(e){return e?.daemonVersion?`v${e.daemonVersion}`:"version unknown"}export function staleDaemonIssue(e,n){return`Stale daemon detected: daemon ${formatDaemonVersion(e)} != CLI v${n}.
+  Run: opencli daemon restart`}

package/dist/src/browser/dom-helpers.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared DOM operation JS generators.
+ *
+ * Used by both Page (daemon mode) and CDPPage (direct CDP mode)
+ * to eliminate code duplication for click, type, press, wait, scroll, etc.
+ */
+/** Generate JS to click an element by ref.
+ *  Returns { status, x, y, w, h } for CDP fallback when JS click fails. */
+export declare function clickJs(ref: string): string;
+/** Generate JS to type text into an element by ref.
+ *  Uses native setter for React compat + execCommand for contenteditable. */
+export declare function typeTextJs(ref: string, text: string): string;
+/** Generate JS to press a keyboard key */
+export declare function pressKeyJs(key: string, modifiers?: string[]): string;
+/** Generate JS to wait for text to appear in the page */
+export declare function waitForTextJs(text: string, timeoutMs: number): string;
+/** Generate JS for scroll */
+export declare function scrollJs(direction: string, amount: number): string;
+/** Generate JS for auto-scroll with lazy-load detection */
+export declare function autoScrollJs(times: number, delayMs: number): string;
+/** Generate JS to read performance resource entries as network requests */
+export declare function networkRequestsJs(includeStatic: boolean): string;
+/**
+ * Generate JS to wait until the DOM stabilizes (no mutations for `quietMs`),
+ * with a hard cap at `maxMs`. Uses MutationObserver in the browser.
+ *
+ * Returns as soon as the page stops changing, avoiding unnecessary fixed waits.
+ * If document.body is not available, falls back to a fixed sleep of maxMs.
+ */
+export declare function waitForDomStableJs(maxMs: number, quietMs: number): string;
+/**
+ * Generate JS to wait until window.__opencli_xhr has ≥1 captured response.
+ * Polls every 100ms. Resolves 'captured' on success; rejects after maxMs.
+ * Used after installInterceptor() + goto() instead of a fixed sleep.
+ */
+export declare function waitForCaptureJs(maxMs: number): string;
+/**
+ * Generate JS to wait until document.querySelector(selector) returns a match.
+ * Uses MutationObserver for near-instant resolution; falls back to reject after timeoutMs.
+ */
+export declare function waitForSelectorJs(selector: string, timeoutMs: number): string;

package/dist/src/browser/dom-helpers.js

@@ -0,0 +1,166 @@
+function D(g,p){return`
+      const ref = ${g};
+      let el = document.querySelector('[data-opencli-ref="' + ref + '"]');
+      if (!el) el = document.querySelector('[data-ref="' + ref + '"]');
+      if (!el && ref.match(/^[a-zA-Z#.\\[]/)) {
+        try { el = document.querySelector(ref); } catch {}
+      }
+      if (!el) {
+        const idx = parseInt(ref, 10);
+        if (!isNaN(idx)) {
+          el = document.querySelectorAll('${p}')[idx];
+        }
+      }`}export function clickJs(g){const p=JSON.stringify(g);return`
+    (() => {
+      ${D(p,'a, button, input, select, textarea, [role="button"], [tabindex]:not([tabindex="-1"])')}
+      if (!el) throw new Error('Element not found: ' + ref);
+      el.scrollIntoView({ behavior: 'instant', block: 'center' });
+      const rect = el.getBoundingClientRect();
+      const x = Math.round(rect.left + rect.width / 2);
+      const y = Math.round(rect.top + rect.height / 2);
+      try {
+        el.click();
+        return { status: 'clicked', x, y, w: Math.round(rect.width), h: Math.round(rect.height) };
+      } catch (e) {
+        return { status: 'js_failed', x, y, w: Math.round(rect.width), h: Math.round(rect.height), error: e.message };
+      }
+    })()
+  `}export function typeTextJs(g,p){const B=JSON.stringify(g),z=JSON.stringify(p);return`
+    (() => {
+      ${D(B,'input, textarea, [contenteditable="true"]')}
+      if (!el) throw new Error('Element not found: ' + ref);
+      el.focus();
+      if (el.isContentEditable) {
+        // Select all content + delete, then insert (supports undo, works with rich text editors)
+        const sel = window.getSelection();
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        sel.removeAllRanges();
+        sel.addRange(range);
+        document.execCommand('delete', false);
+        document.execCommand('insertText', false, ${z});
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+      } else {
+        // Use native setter for React/framework compatibility (match element type)
+        const proto = el instanceof HTMLTextAreaElement
+          ? HTMLTextAreaElement.prototype
+          : HTMLInputElement.prototype;
+        const nativeSetter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;
+        if (nativeSetter) {
+          nativeSetter.call(el, ${z});
+        } else {
+          el.value = ${z};
+        }
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+      }
+      return 'typed';
+    })()
+  `}export function pressKeyJs(g,p=[]){const B=p.includes("Ctrl")||p.includes("Control"),z=p.includes("Alt"),F=p.includes("Meta"),H=p.includes("Shift");return`
+    (() => {
+      const el = document.activeElement || document.body;
+      const init = {
+        key: ${JSON.stringify(g)},
+        bubbles: true,
+        ctrlKey: ${B},
+        altKey: ${z},
+        metaKey: ${F},
+        shiftKey: ${H},
+      };
+      el.dispatchEvent(new KeyboardEvent('keydown', init));
+      el.dispatchEvent(new KeyboardEvent('keyup', init));
+      return 'pressed';
+    })()
+  `}export function waitForTextJs(g,p){return`
+    new Promise((resolve, reject) => {
+      const deadline = Date.now() + ${p};
+      const check = () => {
+        if (document.body.innerText.includes(${JSON.stringify(g)})) return resolve('found');
+        if (Date.now() > deadline) return reject(new Error('Text not found: ' + ${JSON.stringify(g)}));
+        setTimeout(check, 200);
+      };
+      check();
+    })
+  `}export function scrollJs(g,p){const B=g==="left"?-p:g==="right"?p:0,z=g==="up"?-p:g==="down"?p:0;return`window.scrollBy(${B}, ${z})`}export function autoScrollJs(g,p){return`
+    (async () => {
+      if (!document.body) return;
+      for (let i = 0; i < ${g}; i++) {
+        const lastHeight = document.body.scrollHeight;
+        window.scrollTo(0, lastHeight);
+        await new Promise(resolve => {
+          let timeoutId;
+          const observer = new MutationObserver(() => {
+            if (document.body.scrollHeight > lastHeight) {
+              clearTimeout(timeoutId);
+              observer.disconnect();
+              setTimeout(resolve, 100);
+            }
+          });
+          observer.observe(document.body, { childList: true, subtree: true });
+          timeoutId = setTimeout(() => { observer.disconnect(); resolve(null); }, ${p});
+        });
+      }
+    })()
+  `}export function networkRequestsJs(g){return`
+    (() => {
+      const entries = performance.getEntriesByType('resource');
+      return entries
+        ${g?"":'.filter(e => !["img", "font", "css", "script"].some(t => e.initiatorType === t))'}
+        .map(e => ({
+          url: e.name,
+          type: e.initiatorType,
+          duration: Math.round(e.duration),
+          size: e.transferSize || 0,
+        }));
+    })()
+  `}export function waitForDomStableJs(g,p){return`
+    new Promise(resolve => {
+      if (!document.body) {
+        setTimeout(() => resolve('nobody'), ${g});
+        return;
+      }
+      let timer = null;
+      let cap = null;
+      const done = (reason) => {
+        clearTimeout(timer);
+        clearTimeout(cap);
+        obs.disconnect();
+        resolve(reason);
+      };
+      const resetQuiet = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => done('quiet'), ${p});
+      };
+      const obs = new MutationObserver(resetQuiet);
+      obs.observe(document.body, { childList: true, subtree: true, attributes: true });
+      resetQuiet();
+      cap = setTimeout(() => done('capped'), ${g});
+    })
+  `}export function waitForCaptureJs(g){return`
+    new Promise((resolve, reject) => {
+      const deadline = Date.now() + ${g};
+      const check = () => {
+        if ((window.__opencli_xhr || []).length > 0) return resolve('captured');
+        if (Date.now() > deadline) return reject(new Error('No network capture within ${g/1000}s'));
+        setTimeout(check, 100);
+      };
+      check();
+    })
+  `}export function waitForSelectorJs(g,p){return`
+    new Promise((resolve, reject) => {
+      const sel = ${JSON.stringify(g)};
+      if (document.querySelector(sel)) return resolve('found');
+      const cap = setTimeout(() => {
+        obs.disconnect();
+        reject(new Error('Selector not found: ' + sel));
+      }, ${p});
+      const obs = new MutationObserver(() => {
+        if (document.querySelector(sel)) {
+          clearTimeout(cap);
+          obs.disconnect();
+          resolve('found');
+        }
+      });
+      obs.observe(document.body || document.documentElement, { childList: true, subtree: true });
+    })
+  `}

package/dist/src/browser/dom-helpers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/dom-snapshot.d.ts

@@ -0,0 +1,93 @@
+/**
+ * DOM Snapshot Engine — Advanced DOM pruning for LLM consumption.
+ *
+ * Inspired by browser-use's multi-layer pruning pipeline, adapted for opencli's
+ * Chrome Extension + CDP architecture. Runs entirely in-page via Runtime.evaluate.
+ *
+ * Pipeline:
+ *   1. Walk DOM tree, collect visibility + layout + interactivity signals
+ *   2. Prune invisible, zero-area, non-content elements
+ *   3. SVG & decoration collapse
+ *   4. Shadow DOM traversal
+ *   5. Same-origin iframe content extraction
+ *   6. Bounding-box parent-child dedup (link/button wrapping children)
+ *   7. Paint-order occlusion detection (overlay/modal coverage)
+ *   8. Attribute whitelist filtering
+ *   9. Table-aware serialization (markdown tables)
+ *  10. Token-efficient serialization with interactive indices
+ *  11. data-ref annotation for click/type targeting
+ *  12. Hidden interactive element hints (scroll-to-reveal)
+ *  13. Incremental diff (mark new elements with *)
+ *
+ * Additional tools:
+ *   - scrollToRefJs(ref) — scroll to a data-opencli-ref element
+ *   - getFormStateJs()  — extract all form fields as structured JSON
+ *
+ * Compound sidecar:
+ *   After the tree, a `compounds:` section lists rich JSON for every
+ *   date/select/file ref — format, full option list (up to cap) with
+ *   `options_total` reflecting the true count, file `accept` + `multiple`.
+ *   This is what the snapshot's inline attr dump cannot express and what
+ *   agents kept blowing turns on.
+ */
+export interface DomSnapshotOptions {
+    /** Extra pixels beyond viewport to include (default 800) */
+    viewportExpand?: number;
+    /** Maximum DOM depth to traverse (default 50) */
+    maxDepth?: number;
+    /** Only emit interactive elements and their landmark ancestors */
+    interactiveOnly?: boolean;
+    /** Maximum text content length per node (default 120) */
+    maxTextLength?: number;
+    /** Include scroll position info on scrollable containers (default true) */
+    includeScrollInfo?: boolean;
+    /** Enable bounding-box parent-child dedup (default true) */
+    bboxDedup?: boolean;
+    /** Traverse Shadow DOM roots (default true) */
+    includeShadowDom?: boolean;
+    /** Extract same-origin iframe content (default true) */
+    includeIframes?: boolean;
+    /** Maximum number of iframes to process (default 5) */
+    maxIframes?: number;
+    /** Enable paint-order occlusion detection (default true) */
+    paintOrderCheck?: boolean;
+    /** Annotate interactive elements with data-opencli-ref (default true) */
+    annotateRefs?: boolean;
+    /** Report hidden interactive elements outside viewport (default true) */
+    reportHidden?: boolean;
+    /** Filter ad/noise elements (default true) */
+    filterAds?: boolean;
+    /** Serialize tables as markdown (default true) */
+    markdownTables?: boolean;
+    /** Previous snapshot hash set (JSON array of hashes) for diff marking (default null) */
+    previousHashes?: string | null;
+}
+/**
+ * Generate JS to scroll to an element identified by data-opencli-ref.
+ * Completes the snapshot→action loop: snapshot identifies `[3]<button>`,
+ * caller can then `scrollToRef('3')` to bring it into view.
+ */
+export declare function scrollToRefJs(ref: string): string;
+/**
+ * Generate JS to extract all form field values from the page.
+ * Returns structured JSON: { forms: [{ id, action, fields: [{ tag, type, name, value, ... }] }] }
+ */
+export declare function getFormStateJs(): string;
+/**
+ * Generate JavaScript code that, when evaluated in a page context via CDP
+ * Runtime.evaluate, returns a pruned DOM snapshot string optimised for LLMs.
+ *
+ * The snapshot output format:
+ *   [42]<button type=submit>Search</button>
+ *   |scroll|<div> (0.5↑ 3.2↓)
+ *     *[58]<a href=/r/1>Result 1</a>
+ *     [59]<a href=/r/2>Result 2</a>
+ *
+ * - `[id]` — interactive element with backend index for targeting
+ * - `*` prefix — newly appeared element (incremental diff)
+ * - `|scroll|` — scrollable container with page counts
+ * - `|shadow|` — Shadow DOM boundary
+ * - `|iframe|` — iframe content
+ * - `|table|` — markdown table rendering
+ */
+export declare function generateSnapshotJs(opts?: DomSnapshotOptions): string;