@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/browser/find.js

@@ -0,0 +1,398 @@
+/**
+ * `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-webcmd-ref` is set on the element
+ * and a fingerprint is written into `window.__webcmd_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.__webcmd_ref_identity\` (the same map
+      // snapshot populates) as the source of truth. For matched elements that
+      // don't already carry a \`data-webcmd-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.__webcmd_ref_identity = window.__webcmd_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-webcmd-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-webcmd-ref]');
+        for (let t = 0; t < tagged.length; t++) {
+          const v = tagged[t].getAttribute('data-webcmd-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-webcmd-ref');
+        let refNum = refAttr != null && /^\\d+$/.test(refAttr) ? parseInt(refAttr, 10) : null;
+        if (refNum === null) {
+          refNum = ++maxRef;
+          try { el.setAttribute('data-webcmd-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 buildSemanticFindJs(opts) {
+    const criteria = JSON.stringify({
+        role: opts.role ?? '',
+        name: opts.name ?? '',
+        label: opts.label ?? '',
+        text: opts.text ?? '',
+        testid: opts.testid ?? '',
+    });
+    const limit = opts.limit ?? 50;
+    const textMax = opts.textMax ?? 120;
+    const whitelist = JSON.stringify(FIND_ATTR_WHITELIST);
+    return `
+    (() => {
+      const CRITERIA = ${criteria};
+      const LIMIT = ${limit};
+      const TEXT_MAX = ${textMax};
+      const ATTR_WHITELIST = ${whitelist};
+
+      ${COMPOUND_INFO_JS}
+
+      function normalize(value) {
+        return String(value || '').replace(/\\s+/g, ' ').trim().toLowerCase();
+      }
+
+      function includesNeedle(value, needle) {
+        const n = normalize(needle);
+        if (!n) return true;
+        return normalize(value).includes(n);
+      }
+
+      function nativeRole(el) {
+        const explicit = el.getAttribute('role');
+        if (explicit) return explicit;
+        const tag = el.tagName.toLowerCase();
+        const type = (el.getAttribute('type') || '').toLowerCase();
+        if (tag === 'button') return 'button';
+        if (tag === 'a' && el.getAttribute('href')) return 'link';
+        if (tag === 'textarea') return 'textbox';
+        if (tag === 'select') return 'combobox';
+        if (tag === 'option') return 'option';
+        if (tag === 'input') {
+          if (type === 'button' || type === 'submit' || type === 'reset') return 'button';
+          if (type === 'checkbox') return 'checkbox';
+          if (type === 'radio') return 'radio';
+          if (type === 'range') return 'slider';
+          if (type === 'search') return 'searchbox';
+          return 'textbox';
+        }
+        return '';
+      }
+
+      function labelText(el) {
+        const parts = [];
+        function cssEscape(value) {
+          try {
+            if (window.CSS && typeof window.CSS.escape === 'function') return window.CSS.escape(value);
+          } catch (_) {}
+          return String(value).replace(/["\\\\]/g, '\\\\$&');
+        }
+        if (el.id) {
+          try {
+            const label = document.querySelector('label[for="' + cssEscape(el.id) + '"]');
+            if (label) parts.push(label.textContent || '');
+          } catch (_) {}
+        }
+        const parentLabel = el.closest?.('label');
+        if (parentLabel) parts.push(parentLabel.textContent || '');
+        return parts.join(' ');
+      }
+
+      function byIdText(ids) {
+        if (!ids) return '';
+        const parts = [];
+        for (const id of String(ids).split(/\\s+/)) {
+          if (!id) continue;
+          try {
+            const el = document.getElementById(id);
+            if (el) parts.push(el.textContent || '');
+          } catch (_) {}
+        }
+        return parts.join(' ');
+      }
+
+      function accessibleName(el) {
+        return [
+          el.getAttribute('aria-label') || '',
+          byIdText(el.getAttribute('aria-labelledby')),
+          labelText(el),
+          el.getAttribute('alt') || '',
+          el.getAttribute('title') || '',
+          el.getAttribute('placeholder') || '',
+          el.getAttribute('value') || '',
+          el.textContent || '',
+        ].filter(Boolean).join(' ');
+      }
+
+      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;
+      }
+
+      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') || '',
+        };
+      }
+
+      function matches(el) {
+        const role = nativeRole(el);
+        const name = accessibleName(el);
+        const label = labelText(el);
+        const text = el.textContent || '';
+        const testid = el.getAttribute('data-testid') || el.getAttribute('data-test') || el.getAttribute('test-id') || '';
+        if (CRITERIA.role && normalize(role) !== normalize(CRITERIA.role)) return false;
+        if (CRITERIA.name && !includesNeedle(name, CRITERIA.name)) return false;
+        if (CRITERIA.label && !includesNeedle(label, CRITERIA.label)) return false;
+        if (CRITERIA.text && !includesNeedle(text, CRITERIA.text)) return false;
+        if (CRITERIA.testid && !includesNeedle(testid, CRITERIA.testid)) return false;
+        return true;
+      }
+
+      const candidates = Array.from(document.querySelectorAll([
+        'a[href]',
+        'button',
+        'input',
+        'textarea',
+        'select',
+        'option',
+        '[role]',
+        '[aria-label]',
+        '[aria-labelledby]',
+        '[data-testid]',
+        '[data-test]',
+        '[test-id]',
+        'label',
+        '[contenteditable="true"]',
+      ].join(',')));
+      const matchesList = candidates.filter(matches);
+
+      if (matchesList.length === 0) {
+        return {
+          error: {
+            code: 'semantic_not_found',
+            message: 'Semantic locator matched 0 elements',
+            hint: 'Try browser state, --source ax, or relax --role/--name/--label/--text/--testid.',
+          },
+        };
+      }
+
+      const identity = (window.__webcmd_ref_identity = window.__webcmd_ref_identity || {});
+      let maxRef = 0;
+      for (const k in identity) {
+        const n = parseInt(k, 10);
+        if (!isNaN(n) && n > maxRef) maxRef = n;
+      }
+      try {
+        const tagged = document.querySelectorAll('[data-webcmd-ref]');
+        for (let t = 0; t < tagged.length; t++) {
+          const v = tagged[t].getAttribute('data-webcmd-ref');
+          const n = v != null && /^\\d+$/.test(v) ? parseInt(v, 10) : NaN;
+          if (!isNaN(n) && n > maxRef) maxRef = n;
+        }
+      } catch (_) {}
+
+      const take = Math.min(matchesList.length, LIMIT);
+      const entries = [];
+      for (let i = 0; i < take; i++) {
+        const el = matchesList[i];
+        const refAttr = el.getAttribute('data-webcmd-ref');
+        let refNum = refAttr != null && /^\\d+$/.test(refAttr) ? parseInt(refAttr, 10) : null;
+        if (refNum === null) {
+          refNum = ++maxRef;
+          try { el.setAttribute('data-webcmd-ref', '' + refNum); } catch (_) {}
+          identity['' + refNum] = fingerprintOf(el);
+        } else if (!identity['' + refNum]) {
+          identity['' + refNum] = fingerprintOf(el);
+        }
+        const text = (el.textContent || '').trim();
+        const entry = {
+          nth: i,
+          ref: refNum,
+          tag: el.tagName.toLowerCase(),
+          role: nativeRole(el),
+          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: matchesList.length,
+        entries,
+      };
+    })()
+  `;
+}
+export function isFindError(result) {
+    return !!result && typeof result === 'object' && 'error' in result;
+}

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

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

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

@@ -0,0 +1,180 @@
+import { describe, expect, it } from 'vitest';
+import { JSDOM } from 'jsdom';
+import { buildFindJs, buildSemanticFindJs, FIND_ATTR_WHITELIST, isFindError } from './find.js';
+/**
+ * These tests validate the shape and options of the generated JS string
+ * (no DOM available in the default vitest unit env). Runtime behavior of
+ * the generated JS against a real DOM is covered by the browser e2e suite.
+ */
+describe('buildFindJs', () => {
+    it('produces syntactically valid JS that can be parsed', () => {
+        expect(() => new Function(`return (${buildFindJs('.btn')});`)).not.toThrow();
+    });
+    it('embeds the selector via JSON.stringify (injection-safe)', () => {
+        const js = buildFindJs('[data-x="a\"b"]');
+        // Unescaped literal break-out must not appear
+        expect(js).not.toContain('[data-x="a"b"]');
+        // The JSON-encoded form (with escaped quotes) should
+        expect(js).toContain(JSON.stringify('[data-x="a\"b"]'));
+    });
+    it('emits invalid_selector + selector_not_found branches', () => {
+        const js = buildFindJs('.btn');
+        expect(js).toContain("code: 'invalid_selector'");
+        expect(js).toContain("code: 'selector_not_found'");
+    });
+    it('emits matches_n + entries + per-entry shape', () => {
+        const js = buildFindJs('.btn');
+        expect(js).toContain('matches_n: matches.length');
+        expect(js).toContain('entries.push(');
+        // Per-entry keys reviewers signed off on: nth, ref, tag, role, text, attrs, visible
+        expect(js).toContain('nth: i');
+        expect(js).toContain('ref: refNum');
+        expect(js).toContain('tag: el.tagName.toLowerCase()');
+        expect(js).toContain("el.getAttribute('role')");
+        expect(js).toContain('visible: isVisible(el)');
+    });
+    it('allocates fresh refs for untagged matches (write attribute + identity map)', () => {
+        const js = buildFindJs('.btn');
+        // On the just-annotated branch we must flip the attribute on the element
+        // so downstream `browser click <ref>` works off the find output.
+        expect(js).toContain("el.setAttribute('data-webcmd-ref'");
+        // The fingerprint must also land in the shared identity map so the
+        // target resolver's stale-ref check has data to verify against.
+        expect(js).toContain('__webcmd_ref_identity');
+        expect(js).toContain("identity['' + refNum] = fingerprintOf(el)");
+        // Allocation walks both the identity map and any existing data-webcmd-ref
+        // annotations — guards against collisions after a soft nav.
+        expect(js).toContain("document.querySelectorAll('[data-webcmd-ref]')");
+    });
+    it('fingerprint shape matches the snapshot / resolver contract', () => {
+        const js = buildFindJs('.btn');
+        // The six fields resolveTargetJs verifies in its stale_ref check.
+        for (const field of ['tag:', 'role:', 'text:', 'ariaLabel:', 'id:', 'testId:']) {
+            expect(js).toContain(field);
+        }
+    });
+    it('embeds defaults for limit and textMax', () => {
+        const js = buildFindJs('.btn');
+        expect(js).toContain('LIMIT = 50');
+        expect(js).toContain('TEXT_MAX = 120');
+    });
+    it('overrides limit and textMax when requested', () => {
+        const js = buildFindJs('.btn', { limit: 3, textMax: 20 });
+        expect(js).toContain('LIMIT = 3');
+        expect(js).toContain('TEXT_MAX = 20');
+    });
+    it('embeds the attribute whitelist verbatim (no style/onclick leaking)', () => {
+        const js = buildFindJs('.btn');
+        // Whitelist fields appear inside the generated JS
+        for (const key of FIND_ATTR_WHITELIST) {
+            expect(js).toContain(`"${key}"`);
+        }
+        // Sensitive / high-noise attrs must stay out of the whitelist
+        expect(FIND_ATTR_WHITELIST).not.toContain('style');
+        expect(FIND_ATTR_WHITELIST).not.toContain('onclick');
+        expect(FIND_ATTR_WHITELIST).not.toContain('onload');
+    });
+    it('inlines compoundInfoOf and attaches compound field per entry', () => {
+        const js = buildFindJs('input, select');
+        // Helper definition is inlined so each matched element can be classified.
+        expect(js).toContain('function compoundInfoOf(el)');
+        // The emitted entry opts in only when compound data is present — no noisy
+        // compound: null on every non-form element.
+        expect(js).toContain('const compound = compoundInfoOf(el);');
+        expect(js).toContain('if (compound) entry.compound = compound;');
+        // Spot-check all three compound families are covered in the inlined helper.
+        expect(js).toContain("'YYYY-MM-DD'");
+        expect(js).toContain("control: 'file'");
+        expect(js).toContain("control: 'select'");
+    });
+    it('keeps the whitelist small and explicit (guardrail against silent expansion)', () => {
+        expect(FIND_ATTR_WHITELIST).toEqual([
+            'id',
+            'class',
+            'name',
+            'type',
+            'placeholder',
+            'aria-label',
+            'title',
+            'href',
+            'value',
+            'role',
+            'data-testid',
+        ]);
+    });
+});
+describe('isFindError', () => {
+    it('narrows { error: ... } as FindError', () => {
+        const payload = { error: { code: 'invalid_selector', message: 'x' } };
+        expect(isFindError(payload)).toBe(true);
+        if (isFindError(payload)) {
+            const err = payload;
+            expect(err.error.code).toBe('invalid_selector');
+        }
+    });
+    it('rejects successful envelopes', () => {
+        expect(isFindError({ matches_n: 0, entries: [] })).toBe(false);
+        expect(isFindError(null)).toBe(false);
+        expect(isFindError(undefined)).toBe(false);
+        expect(isFindError('string')).toBe(false);
+    });
+});
+describe('buildSemanticFindJs', () => {
+    function runSemanticFind(html, opts) {
+        const dom = new JSDOM(html, { runScripts: 'outside-only' });
+        return {
+            dom,
+            result: dom.window.eval(buildSemanticFindJs(opts)),
+        };
+    }
+    it('produces syntactically valid JS and embeds semantic criteria safely', () => {
+        const js = buildSemanticFindJs({ role: 'button', name: 'Save "now"', testid: 'submit' });
+        expect(() => new Function(`return (${js});`)).not.toThrow();
+        expect(js).toContain(JSON.stringify({
+            role: 'button',
+            name: 'Save "now"',
+            label: '',
+            text: '',
+            testid: 'submit',
+        }));
+    });
+    it('matches native roles, accessible name, labels, text, and test ids', () => {
+        const js = buildSemanticFindJs({ role: 'button', name: 'Save', label: 'Category', text: 'Travel', testid: 'category' });
+        expect(js).toContain('function nativeRole(el)');
+        expect(js).toContain('function accessibleName(el)');
+        expect(js).toContain('function labelText(el)');
+        expect(js).toContain('CRITERIA.role');
+        expect(js).toContain('CRITERIA.name');
+        expect(js).toContain('CRITERIA.label');
+        expect(js).toContain('CRITERIA.text');
+        expect(js).toContain('CRITERIA.testid');
+    });
+    it('allocates refs exactly like CSS find so downstream actions can click them', () => {
+        const js = buildSemanticFindJs({ role: 'button', name: 'Save' });
+        expect(js).toContain("el.setAttribute('data-webcmd-ref'");
+        expect(js).toContain('__webcmd_ref_identity');
+        expect(js).toContain("identity['' + refNum] = fingerprintOf(el)");
+        expect(js).toContain("document.querySelectorAll('[data-webcmd-ref]')");
+    });
+    it('executes semantic role/name/testid matching and allocates a clickable ref', () => {
+        const { dom, result } = runSemanticFind('<button aria-label="Save expense" data-testid="save-button">Ignored copy</button>', { role: 'button', name: 'Save', testid: 'save' });
+        expect(result).toMatchObject({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 1, tag: 'button', role: 'button', attrs: { 'aria-label': 'Save expense', 'data-testid': 'save-button' } },
+            ],
+        });
+        const button = dom.window.document.querySelector('button');
+        expect(button.getAttribute('data-webcmd-ref')).toBe('1');
+        expect(dom.window.__webcmd_ref_identity['1']).toMatchObject({ tag: 'button', ariaLabel: 'Save expense' });
+    });
+    it('matches associated labels and placeholders for form controls', () => {
+        const { result } = runSemanticFind('<label for="category">Category</label><input id="category" placeholder="Expense category" value="Travel" />', { role: 'textbox', label: 'Category', name: 'Expense category' });
+        expect(result).toMatchObject({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 1, tag: 'input', role: 'textbox' },
+            ],
+        });
+    });
+});

package/dist/src/browser/html-tree.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Client-side HTML → structured tree serializer.
+ *
+ * Returned as a JS string that gets passed to `page.evaluate`. The expression
+ * walks the DOM subtree rooted at the first selector match (or documentElement
+ * when no selector is given) and emits a compact `{tag, attrs, text, children}`
+ * tree for agents to consume instead of re-parsing raw HTML.
+ *
+ * Text handling: `text` is the concatenated text of direct text children only,
+ * whitespace-collapsed. Nested element text is left inside `children[].text`.
+ * Ordering between text and elements is not preserved — agents that need it
+ * should fall back to raw HTML mode.
+ *
+ * Budget knobs let the caller bound the output on large pages — previously an
+ * unscoped `get html --as json` could return a giant tree. Callers set any
+ * combination of `depth` / `childrenMax` / `textMax`; each hit is reported in
+ * the `truncated` envelope so agents know to narrow their selector or raise
+ * the budget.
+ *
+ * Compound controls (date / time / datetime-local / month / week / select /
+ * file) gain a `compound` field so agents inspecting the JSON tree see the
+ * full contract — date format, full option list (up to cap) with selections
+ * preserved for options beyond the cap, file `accept` and `multiple`. Without
+ * this wiring agents repeatedly guess values on these controls from the raw
+ * attributes, which is the failure mode compound.ts was built to eliminate.
+ */
+import { type CompoundInfo } from './compound.js';
+export interface BuildHtmlTreeJsOptions {
+    /** CSS selector to scope the tree; unscoped = documentElement */
+    selector?: string | null;
+    /** Max depth below the root (0 = root only, no children). Omit = unlimited. */
+    depth?: number | null;
+    /** Max element children per node before the rest get dropped. Omit = unlimited. */
+    childrenMax?: number | null;
+    /** Max chars of direct text per node before truncation. Omit = unlimited. */
+    textMax?: number | null;
+}
+/**
+ * Returns a JS expression string. When evaluated in a page context the
+ * expression resolves to either
+ *   `{selector, matched, tree, truncated}` on success, or
+ *   `{selector, invalidSelector: true, reason}` when `querySelectorAll`
+ *   throws a `SyntaxError` for an unparseable selector.
+ *
+ * Callers must branch on `invalidSelector` to convert it into the CLI's
+ * `invalid_selector` structured error; otherwise the browser-level exception
+ * would bubble out of `page.evaluate` and bypass the structured-error
+ * contract that agents rely on.
+ */
+export declare function buildHtmlTreeJs(opts?: BuildHtmlTreeJsOptions): string;
+export interface HtmlNode {
+    tag: string;
+    attrs: Record<string, string>;
+    text: string;
+    children: HtmlNode[];
+    /**
+     * Rich view for date/select/file controls. Omitted for non-compound elements
+     * so agents can rely on `compound != null` as a signal.
+     */
+    compound?: CompoundInfo;
+}
+export interface HtmlTreeTruncationInfo {
+    /** At least one element child was dropped because depth budget was hit. */
+    depth?: true;
+    /** Count of element children dropped across the tree due to `childrenMax`. */
+    children_dropped?: number;
+    /** Count of nodes whose `text` was cut to `textMax`. */
+    text_truncated?: number;
+}
+export interface HtmlTreeResult {
+    selector: string | null;
+    matched: number;
+    tree: HtmlNode | null;
+    truncated?: HtmlTreeTruncationInfo;
+}