@jackwener/opencli 1.7.5 → 1.7.6

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

@@ -22,7 +22,15 @@
  * 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.
  */
+import { COMPOUND_INFO_JS } from './compound.js';
 // ─── Utility JS Generators ───────────────────────────────────────────
 /**
  * Generate JS to scroll to an element identified by data-opencli-ref.
@@ -155,6 +163,8 @@ export function generateSnapshotJs(opts = {}) {
 (() => {
   'use strict';
 
+  ${COMPOUND_INFO_JS}
+
   // ── Config ─────────────────────────────────────────────────────────
   const VIEWPORT_EXPAND = ${viewportExpand};
   const MAX_DEPTH = ${maxDepth};
@@ -222,6 +232,38 @@ export function generateSnapshotJs(opts = {}) {
 
   const PROPAGATING_TAGS = new Set(['a', 'button']);
 
+  // Roles whose element wraps its own interactive descendants (icon spans
+  // inside a role=button, chevron inside role=link). When we see one of these,
+  // we propagate its bbox to children so we can suppress duplicate refs on
+  // undistinctive descendants that are ≥99% contained.
+  const PROPAGATING_ROLES = new Set(['button', 'link', 'menuitem', 'tab', 'option']);
+
+  function isBboxPropagator(el, tag) {
+    if (PROPAGATING_TAGS.has(tag)) return true;
+    const role = el.getAttribute('role');
+    return !!(role && PROPAGATING_ROLES.has(role));
+  }
+
+  // True when an interactive element still deserves its own [N] ref even
+  // though it's visually subsumed by a propagating ancestor. Anything with
+  // an aria-label, aria-labelledby, id, test id, name, or its own form
+  // semantics is treated as distinctive — everything else (naked spans /
+  // divs / svgs that merely inherit click from the parent button) gets
+  // folded into the parent so the snapshot doesn't ship [1]<button>[2]<svg>.
+  function isDistinctivelyInteractive(el) {
+    if (el.hasAttribute('aria-label')) return true;
+    if (el.hasAttribute('aria-labelledby')) return true;
+    if (el.id) return true;
+    if (el.getAttribute('data-testid') || el.getAttribute('data-test')) return true;
+    if (el.hasAttribute('name')) return true;
+    const tag = el.tagName.toLowerCase();
+    // Real form controls always stand on their own, even when nested in a label/button
+    if (tag === 'input' || tag === 'select' || tag === 'textarea') return true;
+    // Anchors with their own href are distinct targets
+    if (tag === 'a' && el.hasAttribute('href')) return true;
+    return false;
+  }
+
   const AD_PATTERNS = [
     'googleadservices.com', 'doubleclick.net', 'googlesyndication.com',
     'facebook.com/tr', 'analytics.google.com', 'connect.facebook.net',
@@ -576,6 +618,7 @@ export function generateSnapshotJs(opts = {}) {
   const hiddenInteractives = [];
   const currentHashes = [];
   const refIdentity = {};
+  const compoundInfos = {};
   let iframeCount = 0;
   let crossOriginIndex = 0;
 
@@ -627,7 +670,9 @@ export function generateSnapshotJs(opts = {}) {
       if (!(tag === 'input' && el.type === 'file')) return false;
     }
 
-    const interactive = isInteractive(el);
+    // \`interactive\` gets demoted below if bbox containment folds this node
+    // into a propagating ancestor — using \`let\` so the dedup pass can mutate it.
+    let interactive = isInteractive(el);
 
     // Viewport threshold pruning
     if (hasArea && !isInExpandedViewport(rect)) {
@@ -648,7 +693,7 @@ export function generateSnapshotJs(opts = {}) {
     const scrollInfo = getScrollInfo(el);
     const isScrollable = scrollInfo !== null;
 
-    // BBox dedup
+    // BBox dedup — tier 1 (non-interactive descendants, 0.95 threshold)
     let excludedByParent = false;
     if (BBOX_DEDUP && parentPropagatingRect && !interactive) {
       if (hasArea && isContainedBy(rect, parentPropagatingRect, 0.95)) {
@@ -660,8 +705,19 @@ export function generateSnapshotJs(opts = {}) {
       }
     }
 
+    // BBox dedup — tier 2 (interactive descendants, 0.99 threshold, browser-use style).
+    // This kills the "[1]<button> [2]<svg> [3]<span>" noise on icon-buttons by
+    // folding the icon / chevron into the button's ref. The 0.99 threshold + the
+    // isDistinctivelyInteractive gate together ensure we only drop nodes that
+    // add no new actionable surface — a nested <input> or <a href> stays.
+    if (BBOX_DEDUP && parentPropagatingRect && interactive && hasArea) {
+      if (isContainedBy(rect, parentPropagatingRect, 0.99) && !isDistinctivelyInteractive(el)) {
+        interactive = false;
+      }
+    }
+
     let propagateRect = parentPropagatingRect;
-    if (BBOX_DEDUP && PROPAGATING_TAGS.has(tag) && hasArea) propagateRect = rect;
+    if (BBOX_DEDUP && hasArea && isBboxPropagator(el, tag)) propagateRect = rect;
 
     // Process children
     const origLen = lines.length;
@@ -725,6 +781,10 @@ export function generateSnapshotJs(opts = {}) {
         id: el.id || '',
         testId: el.getAttribute('data-testid') || el.getAttribute('data-test') || '',
       };
+      // Compound contract for date/select/file — captured per-ref so the
+      // sidecar maps one-to-one with the [N] tokens in the tree.
+      const compound = compoundInfoOf(el);
+      if (compound) compoundInfos['' + interactiveIndex] = compound;
     }
 
     // Tag + attributes
@@ -806,6 +866,19 @@ export function generateSnapshotJs(opts = {}) {
     if (hiddenInteractives.length > 10) lines.push('  …' + (hiddenInteractives.length - 10) + ' more');
   }
 
+  // Compound sidecar — rich JSON for date/select/file refs. Keys align with [N] tokens in the tree.
+  const compoundRefs = Object.keys(compoundInfos);
+  if (compoundRefs.length > 0) {
+    lines.push('---');
+    lines.push('compounds (' + compoundRefs.length + '):');
+    compoundRefs.sort(function (a, b) { return parseInt(a, 10) - parseInt(b, 10); });
+    for (const ref of compoundRefs) {
+      try {
+        lines.push('  [' + ref + '] ' + JSON.stringify(compoundInfos[ref]));
+      } catch {}
+    }
+  }
+
   // Footer
   lines.push('---');
   lines.push('interactive: ' + interactiveIndex + ' | iframes: ' + iframeCount);

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.d.ts

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

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;