@jackwener/opencli 1.7.5 → 1.7.7

package/dist/src/browser/compound.js

@@ -0,0 +1,112 @@
+/**
+ * Compound-component expansion for high-agent-failure form controls.
+ *
+ * Agents burn turns on three recurring input categories because the raw
+ * attribute dump from `browser state` under-specifies them:
+ *
+ *   - date / time / datetime-local / month / week — agents type
+ *     free-form strings and the browser silently ignores mismatched formats.
+ *   - select — the snapshot caps visible options at ~6; agents don't know
+ *     the full option set, can't match by label, and waste turns clicking
+ *     to open the dropdown just to read options.
+ *   - file — the snapshot shows current filenames but not `accept` or
+ *     `multiple`; agents re-upload or pick unsupported MIME types.
+ *
+ * `compoundInfoOf(el)` returns a structured JSON summary agents can rely
+ * on. Included in `browser find --css` envelope so the agent gets the
+ * rich view without extra round-trips.
+ *
+ * Emitted as a JS source string (`COMPOUND_INFO_JS`) so it can be inlined
+ * into the generated evaluate scripts under find / snapshot / eval.
+ */
+/** Max options included in a SelectCompound.options[]. Above this, `options_total` still reflects the true count. */
+export const COMPOUND_SELECT_OPTIONS_CAP = 50;
+/** Max characters per option label / file name. */
+export const COMPOUND_LABEL_CAP = 80;
+/**
+ * JavaScript source declaring `compoundInfoOf(el)`. Inlined into the JS
+ * emitted by `buildFindJs` (and any other evaluate script that needs the
+ * rich compound view). Returns a `CompoundInfo` object or `null`.
+ */
+export const COMPOUND_INFO_JS = `
+function compoundInfoOf(el) {
+  if (!el || !el.tagName) return null;
+  const tag = el.tagName;
+  const LABEL_CAP = ${COMPOUND_LABEL_CAP};
+  const OPTS_CAP = ${COMPOUND_SELECT_OPTIONS_CAP};
+  if (tag === 'INPUT') {
+    const type = (el.getAttribute('type') || 'text').toLowerCase();
+    const FORMATS = {
+      'date': 'YYYY-MM-DD',
+      'time': 'HH:MM',
+      'datetime-local': 'YYYY-MM-DDTHH:MM',
+      'month': 'YYYY-MM',
+      'week': 'YYYY-W##',
+    };
+    if (FORMATS[type]) {
+      const info = {
+        control: type,
+        format: FORMATS[type],
+        current: (el.value == null ? '' : String(el.value)),
+      };
+      const min = el.getAttribute('min');
+      if (min) info.min = min;
+      const max = el.getAttribute('max');
+      if (max) info.max = max;
+      return info;
+    }
+    if (type === 'file') {
+      const info = {
+        control: 'file',
+        multiple: !!el.multiple,
+        current: [],
+      };
+      const accept = el.getAttribute('accept');
+      if (accept) info.accept = accept;
+      try {
+        if (el.files && el.files.length) {
+          for (let i = 0; i < el.files.length; i++) {
+            const name = (el.files[i].name || '').slice(0, LABEL_CAP);
+            info.current.push(name);
+          }
+        }
+      } catch (_) {}
+      return info;
+    }
+    return null;
+  }
+  if (tag === 'SELECT') {
+    const multiple = !!el.multiple;
+    const options = [];
+    const selectedLabels = [];
+    let total = 0;
+    try {
+      const opts = el.options || [];
+      total = opts.length;
+      // Walk ALL options so \`current\` reflects selections that sit beyond the
+      // serialization cap. Only the first OPTS_CAP entries get pushed into
+      // options[]; anything past the cap still contributes to selectedLabels
+      // so agents see the true current state of big dropdowns.
+      for (let i = 0; i < opts.length; i++) {
+        const o = opts[i];
+        const labelRaw = (o.label != null && o.label !== '') ? o.label : (o.text || '');
+        const label = String(labelRaw).trim().slice(0, LABEL_CAP);
+        if (i < OPTS_CAP) {
+          const entry = { label: label, value: o.value, selected: !!o.selected };
+          if (o.disabled) entry.disabled = true;
+          options.push(entry);
+        }
+        if (o.selected) selectedLabels.push(label);
+      }
+    } catch (_) {}
+    return {
+      control: 'select',
+      multiple: multiple,
+      current: multiple ? selectedLabels : (selectedLabels[0] || ''),
+      options: options,
+      options_total: total,
+    };
+  }
+  return null;
+}
+`;

package/dist/src/browser/compound.test.d.ts

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

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

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest';
+import { COMPOUND_INFO_JS, COMPOUND_LABEL_CAP, COMPOUND_SELECT_OPTIONS_CAP, } from './compound.js';
+/**
+ * Tests run the JS source in a sandbox via `new Function`, feeding it
+ * minimal mock elements shaped like the DOM elements the real code sees
+ * at runtime. Avoids a full jsdom setup while still exercising the logic
+ * end-to-end instead of only snapshotting string markers.
+ */
+function runCompound(mockEl) {
+    const fn = new Function('el', `${COMPOUND_INFO_JS}\nreturn compoundInfoOf(el);`);
+    return fn(mockEl);
+}
+function mockInput(attrs, extras = {}) {
+    return {
+        tagName: 'INPUT',
+        value: extras.value,
+        multiple: extras.multiple,
+        files: extras.files,
+        getAttribute(name) {
+            return attrs[name] ?? null;
+        },
+    };
+}
+function mockSelect(options, multiple = false) {
+    const opts = options.map(o => ({ ...o, selected: !!o.selected }));
+    return {
+        tagName: 'SELECT',
+        multiple,
+        options: opts,
+        getAttribute: () => null,
+    };
+}
+describe('compoundInfoOf — date-like inputs', () => {
+    it('returns { control, format, current } for <input type=date>', () => {
+        const info = runCompound(mockInput({ type: 'date' }, { value: '2026-04-21' }));
+        expect(info).toEqual({ control: 'date', format: 'YYYY-MM-DD', current: '2026-04-21' });
+    });
+    it('surfaces min + max when present', () => {
+        const info = runCompound(mockInput({ type: 'date', min: '2026-01-01', max: '2026-12-31' }, { value: '2026-04-21' }));
+        expect(info).toMatchObject({ min: '2026-01-01', max: '2026-12-31' });
+    });
+    it('handles time / datetime-local / month / week with correct format strings', () => {
+        const formats = {
+            time: 'HH:MM',
+            'datetime-local': 'YYYY-MM-DDTHH:MM',
+            month: 'YYYY-MM',
+            week: 'YYYY-W##',
+        };
+        for (const [type, fmt] of Object.entries(formats)) {
+            const info = runCompound(mockInput({ type }, { value: '' }));
+            expect(info.format).toBe(fmt);
+        }
+    });
+    it('coerces null value into empty string instead of crashing', () => {
+        const info = runCompound(mockInput({ type: 'date' }));
+        expect(info).toMatchObject({ control: 'date', current: '' });
+    });
+});
+describe('compoundInfoOf — file inputs', () => {
+    it('returns { control: file, multiple, current[] }', () => {
+        const info = runCompound(mockInput({ type: 'file' }, {
+            multiple: true,
+            files: [{ name: 'a.png' }, { name: 'b.jpg' }],
+        }));
+        expect(info).toEqual({ control: 'file', multiple: true, current: ['a.png', 'b.jpg'] });
+    });
+    it('includes accept when present', () => {
+        const info = runCompound(mockInput({ type: 'file', accept: 'image/*' }, { multiple: false }));
+        expect(info).toMatchObject({ control: 'file', accept: 'image/*' });
+    });
+    it('returns empty current[] when nothing uploaded', () => {
+        const info = runCompound(mockInput({ type: 'file' }, { multiple: false }));
+        expect(info).toEqual({ control: 'file', multiple: false, current: [] });
+    });
+    it('caps file name at COMPOUND_LABEL_CAP', () => {
+        const longName = 'x'.repeat(COMPOUND_LABEL_CAP + 50);
+        const info = runCompound(mockInput({ type: 'file' }, { multiple: false, files: [{ name: longName }] }));
+        expect(info.current[0].length).toBe(COMPOUND_LABEL_CAP);
+    });
+});
+describe('compoundInfoOf — select', () => {
+    it('returns full options list with labels, values, selected flag', () => {
+        const info = runCompound(mockSelect([
+            { value: 'us', label: 'United States', selected: true },
+            { value: 'ca', label: 'Canada' },
+            { value: 'fr', label: 'France' },
+        ]));
+        expect(info.options).toHaveLength(3);
+        expect(info.options[0]).toEqual({ label: 'United States', value: 'us', selected: true });
+        expect(info.options[2]).toEqual({ label: 'France', value: 'fr', selected: false });
+    });
+    it('sets current to the selected label (single-select)', () => {
+        const info = runCompound(mockSelect([
+            { value: 'a', label: 'Alpha' },
+            { value: 'b', label: 'Bravo', selected: true },
+        ]));
+        expect(info).toMatchObject({ control: 'select', multiple: false, current: 'Bravo' });
+    });
+    it('sets current to an array of labels when multiple=true', () => {
+        const info = runCompound(mockSelect([
+            { value: 'a', label: 'Alpha', selected: true },
+            { value: 'b', label: 'Bravo' },
+            { value: 'c', label: 'Charlie', selected: true },
+        ], true));
+        expect(info).toMatchObject({ control: 'select', multiple: true, current: ['Alpha', 'Charlie'] });
+    });
+    it('falls back from option.label to option.text', () => {
+        const info = runCompound(mockSelect([
+            { value: 'a', text: 'FromText' },
+            { value: 'b', label: '', text: 'EmptyLabelFallback' },
+        ]));
+        expect(info.options[0].label).toBe('FromText');
+        expect(info.options[1].label).toBe('EmptyLabelFallback');
+    });
+    it('marks disabled options', () => {
+        const info = runCompound(mockSelect([
+            { value: 'a', label: 'A' },
+            { value: 'b', label: 'B', disabled: true },
+        ]));
+        expect(info.options[0].disabled).toBeUndefined();
+        expect(info.options[1].disabled).toBe(true);
+    });
+    it('caps options[] at COMPOUND_SELECT_OPTIONS_CAP but keeps true options_total', () => {
+        const big = Array.from({ length: COMPOUND_SELECT_OPTIONS_CAP + 25 }, (_, i) => ({
+            value: 'v' + i,
+            label: 'L' + i,
+        }));
+        const info = runCompound(mockSelect(big));
+        expect(info.options.length).toBe(COMPOUND_SELECT_OPTIONS_CAP);
+        expect(info.options_total).toBe(COMPOUND_SELECT_OPTIONS_CAP + 25);
+    });
+    it('returns "" for current on single-select with no selected option', () => {
+        const info = runCompound(mockSelect([
+            { value: 'a', label: 'A' },
+            { value: 'b', label: 'B' },
+        ]));
+        expect(info).toMatchObject({ current: '' });
+    });
+    // Regression: the previous loop stopped walking options once it hit
+    // COMPOUND_SELECT_OPTIONS_CAP, so a long country dropdown with the
+    // selected country sitting at index 80 would be reported with current="".
+    // Agents then thought nothing was selected and picked another country.
+    it('populates current even when the selected option sits past the serialization cap', () => {
+        const big = Array.from({ length: COMPOUND_SELECT_OPTIONS_CAP + 25 }, (_, i) => ({
+            value: 'v' + i,
+            label: 'L' + i,
+            selected: i === COMPOUND_SELECT_OPTIONS_CAP + 10,
+        }));
+        const info = runCompound(mockSelect(big));
+        expect(info.current).toBe('L' + (COMPOUND_SELECT_OPTIONS_CAP + 10));
+        expect(info.options.length).toBe(COMPOUND_SELECT_OPTIONS_CAP);
+        expect(info.options_total).toBe(COMPOUND_SELECT_OPTIONS_CAP + 25);
+    });
+    it('multi-select: current[] includes labels for selected options beyond the cap', () => {
+        const big = Array.from({ length: COMPOUND_SELECT_OPTIONS_CAP + 10 }, (_, i) => ({
+            value: 'v' + i,
+            label: 'L' + i,
+            selected: i === 3 || i === COMPOUND_SELECT_OPTIONS_CAP + 5,
+        }));
+        const info = runCompound(mockSelect(big, true));
+        expect(info.current).toEqual(['L3', 'L' + (COMPOUND_SELECT_OPTIONS_CAP + 5)]);
+    });
+});
+describe('compoundInfoOf — unsupported shapes', () => {
+    it('returns null for plain text input', () => {
+        expect(runCompound(mockInput({ type: 'text' }, { value: 'hi' }))).toBeNull();
+    });
+    it('returns null for non-form tags', () => {
+        expect(runCompound({ tagName: 'DIV', getAttribute: () => null })).toBeNull();
+    });
+    it('returns null for null / missing element', () => {
+        expect(runCompound(null)).toBeNull();
+        expect(runCompound({})).toBeNull();
+    });
+});

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

@@ -22,6 +22,13 @@
  * 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) */

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;
+};