@jackwener/opencli 1.7.4 → 1.7.6

package/dist/src/browser/dom-snapshot.test.js

@@ -102,6 +102,9 @@ describe('generateSnapshotJs', () => {
         // BBox dedup
         expect(js).toContain('isContainedBy');
         expect(js).toContain('PROPAGATING_TAGS');
+        expect(js).toContain('PROPAGATING_ROLES');
+        expect(js).toContain('isBboxPropagator');
+        expect(js).toContain('isDistinctivelyInteractive');
         // Shadow DOM
         expect(js).toContain('shadowRoot');
         expect(js).toContain('|shadow|');
@@ -151,6 +154,55 @@ describe('generateSnapshotJs', () => {
         expect(js).toContain('page_scroll');
     });
 });
+describe('BBox 99% containment filter', () => {
+    it('propagates bbox for both PROPAGATING_TAGS and PROPAGATING_ROLES', () => {
+        const js = generateSnapshotJs();
+        // Role-based propagator list covers the common wrapper-as-control patterns
+        // that show up as <div role=button><svg/><span/></div> on modern SPAs.
+        for (const role of ['button', 'link', 'menuitem', 'tab', 'option']) {
+            expect(js).toContain(`'${role}'`);
+        }
+        // propagate site uses the unified helper, not only the tag set
+        expect(js).toContain('isBboxPropagator(el, tag)');
+    });
+    it('suppresses interactive descendants at 0.99 containment when they are not distinctive', () => {
+        const js = generateSnapshotJs();
+        expect(js).toContain('isContainedBy(rect, parentPropagatingRect, 0.99)');
+        expect(js).toContain('!isDistinctivelyInteractive(el)');
+        // The suppression path flips the local interactive flag so the node is
+        // still emitted (for text / shape) but does not get its own [N] ref.
+        expect(js).toContain('interactive = false');
+    });
+    it('does not suppress inputs / href-bearing anchors even when fully contained', () => {
+        const js = generateSnapshotJs();
+        // Guards inside isDistinctivelyInteractive
+        expect(js).toContain("tag === 'input'");
+        expect(js).toContain("tag === 'select'");
+        expect(js).toContain("tag === 'textarea'");
+        expect(js).toContain("tag === 'a'");
+        expect(js).toContain("el.hasAttribute('href')");
+        // aria-label / aria-labelledby / id / test-id / name preserve distinctness
+        expect(js).toContain("el.hasAttribute('aria-label')");
+        expect(js).toContain("el.hasAttribute('aria-labelledby')");
+        expect(js).toContain("el.id");
+        expect(js).toContain("el.getAttribute('data-testid')");
+        expect(js).toContain("el.hasAttribute('name')");
+    });
+    it('keeps the existing 0.95 non-interactive dedup tier in place', () => {
+        const js = generateSnapshotJs();
+        // The original non-interactive bbox filter is still present alongside the
+        // new interactive tier — two complementary thresholds, not a replacement.
+        expect(js).toContain('isContainedBy(rect, parentPropagatingRect, 0.95)');
+    });
+    it('bbox containment branches are gated on BBOX_DEDUP flag', () => {
+        const off = generateSnapshotJs({ bboxDedup: false });
+        // When the option is off, the filter becomes inert (BBOX_DEDUP = false)
+        // but the inlined helpers still ship — we only guard at the call sites.
+        expect(off).toContain('BBOX_DEDUP = false');
+        expect(off).toContain('isBboxPropagator');
+        expect(off).toContain('isDistinctivelyInteractive');
+    });
+});
 describe('scrollToRefJs', () => {
     it('generates valid JS', () => {
         const js = scrollToRefJs('42');
@@ -245,4 +297,17 @@ describe('Search Element Detection', () => {
         const js = generateSnapshotJs();
         expect(js).toContain('isSearchElement(el)');
     });
+    // Blocker B regression: compound contract must be emitted by `browser state`,
+    // not only by `browser find --css`. Otherwise agents inspecting the default
+    // snapshot still have to round-trip `find` on every date/select/file control.
+    it('inlines compoundInfoOf() and attaches compound info to each interactive ref', () => {
+        const js = generateSnapshotJs();
+        expect(js).toContain('function compoundInfoOf(el)');
+        // Wiring: the walk body should call compoundInfoOf on every interactive node
+        expect(js).toContain('compoundInfoOf(el)');
+        // And collect them into a per-ref map keyed by the same [N] index as the tree
+        expect(js).toContain('compoundInfos');
+        // And emit a sidecar section after the tree so agents can find the JSON
+        expect(js).toContain("'compounds ('");
+    });
 });

package/dist/src/browser/extract.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `browser extract` — agent-native article/content reading channel.
+ *
+ * Pipeline (from first principles — agents want the *content*, not the DOM):
+ *   1. Scope:    select `--selector` (default: document.body or <main>/<article>)
+ *   2. Denoise:  strip script/style/nav/header/footer/aside/iframe/svg/form, inline noise
+ *   3. Convert:  HTML → Markdown via shared `htmlToMarkdown` (turndown)
+ *   4. Chunk:    paragraph-boundary-aware slicing with `next_start_char` cursor
+ *
+ * Why a separate command:
+ * - `get html --as json` returns tree structure; useless for "read the article".
+ * - `get text` flattens everything; loses headings, lists, links.
+ * - Markdown is the agent-readable middle ground: structure preserved, noise gone.
+ *
+ * Continuation contract: the envelope always carries `start`, `end`,
+ * `total_chars`, and `next_start_char` (null when the last chunk was emitted).
+ * Agents pass `--start <next>` to continue. No session state required.
+ */
+/**
+ * Returns the JS expression string used with `page.evaluate` to produce the
+ * cleaned HTML subtree that we then hand to `htmlToMarkdown`. We do the
+ * denoise/clone inside the page so we can use DOM APIs (querySelectorAll,
+ * cloneNode) rather than regex on serialized HTML.
+ */
+export declare function buildExtractHtmlJs(selector: string | null): string;
+export interface ExtractChunkOptions {
+    content: string;
+    start: number;
+    chunkSize: number;
+}
+export interface ExtractChunkResult {
+    content: string;
+    start: number;
+    end: number;
+    nextStartChar: number | null;
+}
+/**
+ * Slice `content` into one chunk starting at `start` with target size
+ * `chunkSize`. When the chunk would land mid-paragraph, we pull the break
+ * back to the nearest `\n\n` (or `\n`) within a small window to keep the
+ * output readable. If no boundary is found, we hard-cut at `start+chunkSize`.
+ */
+export declare function chunkMarkdown(opts: ExtractChunkOptions): ExtractChunkResult;
+export interface RunExtractOptions {
+    html: string;
+    url: string;
+    title: string;
+    selector: string | null;
+    start: number;
+    chunkSize: number;
+}
+export interface RunExtractResult {
+    url: string;
+    title: string;
+    selector: string | null;
+    total_chars: number;
+    chunk_size: number;
+    start: number;
+    end: number;
+    next_start_char: number | null;
+    content: string;
+}
+/** End-to-end host-side pipeline: HTML → markdown → chunked envelope. */
+export declare function runExtractFromHtml(opts: RunExtractOptions): RunExtractResult;
+export declare const __extractInternals: {
+    DEFAULT_CHUNK_SIZE: number;
+    MIN_CHUNK_SIZE: number;
+    MAX_CHUNK_SIZE: number;
+};

package/dist/src/browser/extract.js

@@ -0,0 +1,132 @@
+/**
+ * `browser extract` — agent-native article/content reading channel.
+ *
+ * Pipeline (from first principles — agents want the *content*, not the DOM):
+ *   1. Scope:    select `--selector` (default: document.body or <main>/<article>)
+ *   2. Denoise:  strip script/style/nav/header/footer/aside/iframe/svg/form, inline noise
+ *   3. Convert:  HTML → Markdown via shared `htmlToMarkdown` (turndown)
+ *   4. Chunk:    paragraph-boundary-aware slicing with `next_start_char` cursor
+ *
+ * Why a separate command:
+ * - `get html --as json` returns tree structure; useless for "read the article".
+ * - `get text` flattens everything; loses headings, lists, links.
+ * - Markdown is the agent-readable middle ground: structure preserved, noise gone.
+ *
+ * Continuation contract: the envelope always carries `start`, `end`,
+ * `total_chars`, and `next_start_char` (null when the last chunk was emitted).
+ * Agents pass `--start <next>` to continue. No session state required.
+ */
+import { htmlToMarkdown } from '../utils.js';
+const DEFAULT_CHUNK_SIZE = 20000;
+const MIN_CHUNK_SIZE = 100;
+const MAX_CHUNK_SIZE = 200000;
+const BOUNDARY_WINDOW_RATIO = 0.15;
+/**
+ * Returns the JS expression string used with `page.evaluate` to produce the
+ * cleaned HTML subtree that we then hand to `htmlToMarkdown`. We do the
+ * denoise/clone inside the page so we can use DOM APIs (querySelectorAll,
+ * cloneNode) rather than regex on serialized HTML.
+ */
+export function buildExtractHtmlJs(selector) {
+    const selectorLiteral = selector ? JSON.stringify(selector) : 'null';
+    return `(() => {
+  const sel = ${selectorLiteral};
+  let root = null;
+  if (sel) {
+    try { root = document.querySelector(sel); }
+    catch (e) {
+      return { invalidSelector: true, reason: (e && e.message) || String(e) };
+    }
+    if (!root) return { notFound: true };
+  } else {
+    root = document.querySelector('main') || document.querySelector('article') || document.body || document.documentElement;
+  }
+  if (!root) return { notFound: true };
+  const clone = root.cloneNode(true);
+  const drop = [
+    'script', 'style', 'noscript', 'template',
+    'nav', 'header', 'footer', 'aside',
+    'iframe', 'svg', 'canvas',
+    'form', 'button', 'input', 'select', 'textarea',
+    '[role="navigation"]', '[role="banner"]', '[role="contentinfo"]', '[role="complementary"]',
+    '[aria-hidden="true"]',
+  ];
+  for (const q of drop) {
+    for (const n of clone.querySelectorAll(q)) n.remove();
+  }
+  // Also strip event-handler and style attributes that bloat markdown output.
+  const walker = document.createTreeWalker(clone, NodeFilter.SHOW_ELEMENT);
+  let n = walker.currentNode;
+  while (n) {
+    if (n.nodeType === 1) {
+      const el = n;
+      for (const a of [...el.attributes]) {
+        if (a.name.startsWith('on') || a.name === 'style' || a.name.startsWith('data-')) el.removeAttribute(a.name);
+      }
+    }
+    n = walker.nextNode();
+  }
+  return { ok: true, url: location.href, title: document.title || '', html: clone.outerHTML || '' };
+})()`;
+}
+/**
+ * Slice `content` into one chunk starting at `start` with target size
+ * `chunkSize`. When the chunk would land mid-paragraph, we pull the break
+ * back to the nearest `\n\n` (or `\n`) within a small window to keep the
+ * output readable. If no boundary is found, we hard-cut at `start+chunkSize`.
+ */
+export function chunkMarkdown(opts) {
+    const { content, start } = opts;
+    const chunkSize = Math.max(MIN_CHUNK_SIZE, Math.min(MAX_CHUNK_SIZE, opts.chunkSize));
+    if (start >= content.length) {
+        return { content: '', start, end: start, nextStartChar: null };
+    }
+    const hardEnd = Math.min(content.length, start + chunkSize);
+    if (hardEnd === content.length) {
+        return { content: content.slice(start, hardEnd), start, end: hardEnd, nextStartChar: null };
+    }
+    const windowSize = Math.max(1, Math.floor(chunkSize * BOUNDARY_WINDOW_RATIO));
+    const windowStart = Math.max(start + 1, hardEnd - windowSize);
+    const slice = content.slice(windowStart, hardEnd);
+    const paraBreak = slice.lastIndexOf('\n\n');
+    let cut = hardEnd;
+    if (paraBreak >= 0) {
+        cut = windowStart + paraBreak + 2;
+    }
+    else {
+        const lineBreak = slice.lastIndexOf('\n');
+        if (lineBreak >= 0)
+            cut = windowStart + lineBreak + 1;
+    }
+    return {
+        content: content.slice(start, cut),
+        start,
+        end: cut,
+        nextStartChar: cut,
+    };
+}
+/** End-to-end host-side pipeline: HTML → markdown → chunked envelope. */
+export function runExtractFromHtml(opts) {
+    const md = htmlToMarkdown(opts.html);
+    const chunk = chunkMarkdown({
+        content: md,
+        start: Math.max(0, opts.start),
+        chunkSize: opts.chunkSize || DEFAULT_CHUNK_SIZE,
+    });
+    return {
+        url: opts.url,
+        title: opts.title,
+        selector: opts.selector,
+        total_chars: md.length,
+        chunk_size: chunk.end - chunk.start,
+        start: chunk.start,
+        end: chunk.end,
+        next_start_char: chunk.nextStartChar,
+        content: chunk.content,
+    };
+}
+export const __extractInternals = {
+    DEFAULT_CHUNK_SIZE,
+    MIN_CHUNK_SIZE,
+    MAX_CHUNK_SIZE,
+};

package/dist/src/browser/extract.test.js

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest';
+import { buildExtractHtmlJs, chunkMarkdown, runExtractFromHtml } from './extract.js';
+describe('chunkMarkdown', () => {
+    it('returns the full content when it fits in one chunk', () => {
+        const content = 'short body';
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 20000 });
+        expect(r.content).toBe(content);
+        expect(r.start).toBe(0);
+        expect(r.end).toBe(content.length);
+        expect(r.nextStartChar).toBeNull();
+    });
+    it('emits next_start_char when more content remains', () => {
+        // Build content long enough that chunkSize cuts it mid-stream.
+        const para = 'p'.repeat(400);
+        const content = [para, para, para].join('\n\n');
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 500 });
+        expect(r.nextStartChar).not.toBeNull();
+        expect(r.nextStartChar).toBeGreaterThan(0);
+        expect(r.nextStartChar).toBeLessThan(content.length);
+    });
+    it('prefers to break at a paragraph boundary inside the boundary window', () => {
+        // chunkSize=500, window=15% → [425, 500). Place `\n\n` at 450 so it lands
+        // inside the window; the chunker should snap the cut back to it.
+        const a = 'a'.repeat(450);
+        const b = 'b'.repeat(400);
+        const content = `${a}\n\n${b}`;
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 500 });
+        expect(r.content.endsWith('\n\n')).toBe(true);
+        expect(r.nextStartChar).toBe(r.end);
+        expect(content.slice(r.end).startsWith('b')).toBe(true);
+    });
+    it('falls back to a single newline when no paragraph boundary is in window', () => {
+        // 6 lines × 90 chars joined by `\n` → `\n` at 90, 181, 272, 363, 454.
+        // chunkSize=500 with window [425, 500) catches the `\n` at 454.
+        const line = 'l'.repeat(90);
+        const content = Array.from({ length: 6 }, () => line).join('\n');
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 500 });
+        expect(r.content.endsWith('\n')).toBe(true);
+        expect(content.slice(r.end).startsWith('l')).toBe(true);
+    });
+    it('hard-cuts when no boundary is found within the window', () => {
+        const content = 'x'.repeat(5000);
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 500 });
+        expect(r.end).toBe(500);
+        expect(r.content).toHaveLength(500);
+        expect(r.nextStartChar).toBe(500);
+    });
+    it('handles start >= content.length with an empty final chunk', () => {
+        const content = 'hello';
+        const r = chunkMarkdown({ content, start: 5, chunkSize: 100 });
+        expect(r.content).toBe('');
+        expect(r.nextStartChar).toBeNull();
+    });
+    it('resumes from a provided start cursor until the stream terminates', () => {
+        const content = `${'a'.repeat(100)}\n\n${'b'.repeat(100)}\n\n${'c'.repeat(100)}`;
+        const first = chunkMarkdown({ content, start: 0, chunkSize: 110 });
+        expect(first.nextStartChar).not.toBeNull();
+        const second = chunkMarkdown({ content, start: first.nextStartChar, chunkSize: 110 });
+        expect(second.start).toBe(first.nextStartChar);
+        expect(second.content.length).toBeGreaterThan(0);
+        let cursor = second.nextStartChar;
+        let safety = 20;
+        while (cursor !== null && safety-- > 0) {
+            const step = chunkMarkdown({ content, start: cursor, chunkSize: 110 });
+            cursor = step.nextStartChar;
+        }
+        expect(cursor).toBeNull();
+    });
+    it('clamps chunk size to the configured minimum', () => {
+        const content = 'a'.repeat(2000);
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 1 });
+        // MIN_CHUNK_SIZE is 100 — requesting 1 should still produce >= 100 chars.
+        expect(r.end).toBeGreaterThanOrEqual(100);
+    });
+});
+describe('runExtractFromHtml', () => {
+    it('converts HTML to markdown and wraps it in the chunking envelope', () => {
+        const html = '<article><h1>Title</h1><p>Hello <strong>world</strong>.</p></article>';
+        const r = runExtractFromHtml({
+            html,
+            url: 'https://example.com/a',
+            title: 'Example',
+            selector: 'article',
+            start: 0,
+            chunkSize: 20000,
+        });
+        expect(r.url).toBe('https://example.com/a');
+        expect(r.title).toBe('Example');
+        expect(r.selector).toBe('article');
+        expect(r.content).toContain('# Title');
+        expect(r.content).toContain('**world**');
+        expect(r.start).toBe(0);
+        expect(r.end).toBe(r.content.length);
+        expect(r.total_chars).toBe(r.content.length);
+        expect(r.next_start_char).toBeNull();
+    });
+    it('reports total_chars and chunk_size against the final markdown', () => {
+        const body = Array.from({ length: 30 }, (_, i) => `<p>paragraph ${i} ${'x'.repeat(200)}</p>`).join('');
+        const r = runExtractFromHtml({
+            html: `<main>${body}</main>`,
+            url: 'https://example.com/b',
+            title: 't',
+            selector: 'main',
+            start: 0,
+            chunkSize: 500,
+        });
+        expect(r.total_chars).toBeGreaterThan(r.end);
+        expect(r.chunk_size).toBe(r.end - r.start);
+        expect(r.next_start_char).toBe(r.end);
+    });
+});
+describe('buildExtractHtmlJs', () => {
+    it('embeds the selector as a JSON literal', () => {
+        const js = buildExtractHtmlJs('main.article');
+        expect(js).toContain('"main.article"');
+    });
+    it('uses null when no selector given', () => {
+        const js = buildExtractHtmlJs(null);
+        // The expression references `sel` and compares to null.
+        expect(js).toContain('const sel = null;');
+    });
+    it('includes the denoise selector list', () => {
+        const js = buildExtractHtmlJs(null);
+        expect(js).toContain("'script'");
+        expect(js).toContain("'nav'");
+        expect(js).toContain("'iframe'");
+        expect(js).toContain("'[aria-hidden=\"true\"]'");
+    });
+});

package/dist/src/browser/find.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `browser find --css <sel>` — structured CSS query.
+ *
+ * Returns every match of a selector as a JSON envelope agents can read
+ * without parsing free-text snapshot output. Each entry carries two
+ * identifiers — a numeric `ref` (matching the snapshot contract) and a
+ * stable 0-based `nth` — so the agent can act on a specific result via
+ * either path:
+ *
+ *   browser click <ref>              // when ref is numeric
+ *   browser click "<sel>" --nth <n>  // always works
+ *
+ * Refs are *allocated on the spot* for matched elements that were not
+ * tagged by a prior snapshot: `data-opencli-ref` is set on the element
+ * and a fingerprint is written into `window.__opencli_ref_identity`
+ * (same shape the snapshot uses). That makes `find` a first-class entry
+ * point to the ref system — agents can skip running `browser state`
+ * when they already know the selector.
+ *
+ * Attributes are whitelisted to keep output small and high-signal.
+ * Invisible elements are still returned so agents can reason about
+ * offscreen vs truly-missing targets.
+ *
+ * When a matched element is a compound form control (date-like input,
+ * select, file input), the entry gains a `compound` field with the
+ * rich view from `compound.ts`. This is what kills the three biggest
+ * agent-fail modes on form pages (wrong date format, guessed options,
+ * re-uploaded files) without forcing agents to probe further.
+ */
+import { type CompoundInfo } from './compound.js';
+/** Whitelist of attributes surfaced per entry. Keep small; agents do not need full DOM dumps. */
+export declare const FIND_ATTR_WHITELIST: readonly ["id", "class", "name", "type", "placeholder", "aria-label", "title", "href", "value", "role", "data-testid"];
+export interface FindEntry {
+    /** Zero-based position within the match set — pair with `--nth` on downstream commands. */
+    nth: number;
+    /**
+     * Numeric data-opencli-ref. Find assigns one if the element was not
+     * tagged by a prior snapshot, so downstream `browser click <ref>` works
+     * directly off the find output without requiring `browser state` first.
+     */
+    ref: number;
+    tag: string;
+    role: string;
+    text: string;
+    attrs: Record<string, string>;
+    visible: boolean;
+    /**
+     * Rich view for date / time / datetime-local / month / week / select /
+     * file inputs. Omitted (undefined) for all other element types. See
+     * `compound.ts` for the shape.
+     */
+    compound?: CompoundInfo;
+}
+export interface FindResult {
+    matches_n: number;
+    entries: FindEntry[];
+}
+export interface FindError {
+    error: {
+        code: 'invalid_selector' | 'selector_not_found';
+        message: string;
+        hint?: string;
+    };
+}
+export interface FindOptions {
+    /** Max entries returned. Default 50 — enough to pick from without flooding context. */
+    limit?: number;
+    /** Max chars of trimmed text per entry. Default 120. */
+    textMax?: number;
+}
+/**
+ * Build the browser-side JS that performs the CSS query and emits the
+ * FindResult (or FindError) envelope. Evaluated inside `page.evaluate`.
+ */
+export declare function buildFindJs(selector: string, opts?: FindOptions): string;
+export declare function isFindError(result: unknown): result is FindError;

package/dist/src/browser/find.js

@@ -0,0 +1,179 @@
+/**
+ * `browser find --css <sel>` — structured CSS query.
+ *
+ * Returns every match of a selector as a JSON envelope agents can read
+ * without parsing free-text snapshot output. Each entry carries two
+ * identifiers — a numeric `ref` (matching the snapshot contract) and a
+ * stable 0-based `nth` — so the agent can act on a specific result via
+ * either path:
+ *
+ *   browser click <ref>              // when ref is numeric
+ *   browser click "<sel>" --nth <n>  // always works
+ *
+ * Refs are *allocated on the spot* for matched elements that were not
+ * tagged by a prior snapshot: `data-opencli-ref` is set on the element
+ * and a fingerprint is written into `window.__opencli_ref_identity`
+ * (same shape the snapshot uses). That makes `find` a first-class entry
+ * point to the ref system — agents can skip running `browser state`
+ * when they already know the selector.
+ *
+ * Attributes are whitelisted to keep output small and high-signal.
+ * Invisible elements are still returned so agents can reason about
+ * offscreen vs truly-missing targets.
+ *
+ * When a matched element is a compound form control (date-like input,
+ * select, file input), the entry gains a `compound` field with the
+ * rich view from `compound.ts`. This is what kills the three biggest
+ * agent-fail modes on form pages (wrong date format, guessed options,
+ * re-uploaded files) without forcing agents to probe further.
+ */
+import { COMPOUND_INFO_JS } from './compound.js';
+/** Whitelist of attributes surfaced per entry. Keep small; agents do not need full DOM dumps. */
+export const FIND_ATTR_WHITELIST = [
+    'id',
+    'class',
+    'name',
+    'type',
+    'placeholder',
+    'aria-label',
+    'title',
+    'href',
+    'value',
+    'role',
+    'data-testid',
+];
+/**
+ * Build the browser-side JS that performs the CSS query and emits the
+ * FindResult (or FindError) envelope. Evaluated inside `page.evaluate`.
+ */
+export function buildFindJs(selector, opts = {}) {
+    const safeSel = JSON.stringify(selector);
+    const limit = opts.limit ?? 50;
+    const textMax = opts.textMax ?? 120;
+    const whitelist = JSON.stringify(FIND_ATTR_WHITELIST);
+    return `
+    (() => {
+      const sel = ${safeSel};
+      const LIMIT = ${limit};
+      const TEXT_MAX = ${textMax};
+      const ATTR_WHITELIST = ${whitelist};
+
+      ${COMPOUND_INFO_JS}
+
+      let matches;
+      try {
+        matches = document.querySelectorAll(sel);
+      } catch (e) {
+        return {
+          error: {
+            code: 'invalid_selector',
+            message: 'Invalid CSS selector: ' + sel + ' (' + ((e && e.message) || String(e)) + ')',
+            hint: 'Check the selector syntax.',
+          },
+        };
+      }
+
+      if (matches.length === 0) {
+        return {
+          error: {
+            code: 'selector_not_found',
+            message: 'CSS selector ' + sel + ' matched 0 elements',
+            hint: 'Use browser state to inspect the page, or try a less specific selector.',
+          },
+        };
+      }
+
+      function pickAttrs(el) {
+        const out = {};
+        for (const key of ATTR_WHITELIST) {
+          const v = el.getAttribute(key);
+          if (v != null && v !== '') out[key] = v;
+        }
+        return out;
+      }
+
+      function isVisible(el) {
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return false;
+        try {
+          const style = getComputedStyle(el);
+          if (style.display === 'none' || style.visibility === 'hidden') return false;
+          if (parseFloat(style.opacity || '1') === 0) return false;
+        } catch (_) {}
+        return true;
+      }
+
+      // Ref allocation: reuse \`window.__opencli_ref_identity\` (the same map
+      // snapshot populates) as the source of truth. For matched elements that
+      // don't already carry a \`data-opencli-ref\`, assign the next free numeric
+      // ref and write the fingerprint so the target resolver can verify it on
+      // downstream click/type/get calls.
+      const identity = (window.__opencli_ref_identity = window.__opencli_ref_identity || {});
+      let maxRef = 0;
+      for (const k in identity) {
+        const n = parseInt(k, 10);
+        if (!isNaN(n) && n > maxRef) maxRef = n;
+      }
+      // Also walk any \`data-opencli-ref\` already in the DOM in case the identity
+      // map was cleared but annotations remain (e.g. soft navigation without a
+      // fresh snapshot). Guarantees allocated refs don't collide.
+      try {
+        const tagged = document.querySelectorAll('[data-opencli-ref]');
+        for (let t = 0; t < tagged.length; t++) {
+          const v = tagged[t].getAttribute('data-opencli-ref');
+          const n = v != null && /^\\d+$/.test(v) ? parseInt(v, 10) : NaN;
+          if (!isNaN(n) && n > maxRef) maxRef = n;
+        }
+      } catch (_) {}
+
+      function fingerprintOf(el) {
+        return {
+          tag: el.tagName.toLowerCase(),
+          role: el.getAttribute('role') || '',
+          text: (el.textContent || '').trim().slice(0, 30),
+          ariaLabel: el.getAttribute('aria-label') || '',
+          id: el.id || '',
+          testId: el.getAttribute('data-testid') || el.getAttribute('data-test') || '',
+        };
+      }
+
+      const take = Math.min(matches.length, LIMIT);
+      const entries = [];
+      for (let i = 0; i < take; i++) {
+        const el = matches[i];
+        const refAttr = el.getAttribute('data-opencli-ref');
+        let refNum = refAttr != null && /^\\d+$/.test(refAttr) ? parseInt(refAttr, 10) : null;
+        if (refNum === null) {
+          refNum = ++maxRef;
+          try { el.setAttribute('data-opencli-ref', '' + refNum); } catch (_) {}
+          identity['' + refNum] = fingerprintOf(el);
+        } else if (!identity['' + refNum]) {
+          // Ref annotation survived but identity map was cleared — repopulate so the
+          // target resolver's fingerprint check passes on downstream calls.
+          identity['' + refNum] = fingerprintOf(el);
+        }
+        const text = (el.textContent || '').trim();
+        const entry = {
+          nth: i,
+          ref: refNum,
+          tag: el.tagName.toLowerCase(),
+          role: el.getAttribute('role') || '',
+          text: text.length > TEXT_MAX ? text.slice(0, TEXT_MAX) : text,
+          attrs: pickAttrs(el),
+          visible: isVisible(el),
+        };
+        const compound = compoundInfoOf(el);
+        if (compound) entry.compound = compound;
+        entries.push(entry);
+      }
+
+      return {
+        matches_n: matches.length,
+        entries,
+      };
+    })()
+  `;
+}
+export function isFindError(result) {
+    return !!result && typeof result === 'object' && 'error' in result;
+}