@jackwener/opencli 1.7.5 → 1.7.6

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

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

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

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

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest';
+import { buildFindJs, 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-opencli-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('__opencli_ref_identity');
+        expect(js).toContain("identity['' + refNum] = fingerprintOf(el)");
+        // Allocation walks both the identity map and any existing data-opencli-ref
+        // annotations — guards against collisions after a soft nav.
+        expect(js).toContain("document.querySelectorAll('[data-opencli-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);
+    });
+});

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

package/dist/src/browser/html-tree.js

@@ -0,0 +1,112 @@
+/**
+ * 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 { COMPOUND_INFO_JS } from './compound.js';
+/**
+ * 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 function buildHtmlTreeJs(opts = {}) {
+    const selectorLiteral = opts.selector ? JSON.stringify(opts.selector) : 'null';
+    const depthLiteral = Number.isFinite(opts.depth) && opts.depth >= 0
+        ? String(opts.depth)
+        : 'null';
+    const childrenMaxLiteral = Number.isFinite(opts.childrenMax) && opts.childrenMax >= 0
+        ? String(opts.childrenMax)
+        : 'null';
+    const textMaxLiteral = Number.isFinite(opts.textMax) && opts.textMax >= 0
+        ? String(opts.textMax)
+        : 'null';
+    return `(() => {
+  ${COMPOUND_INFO_JS}
+  const selector = ${selectorLiteral};
+  const maxDepth = ${depthLiteral};
+  const maxChildren = ${childrenMaxLiteral};
+  const maxText = ${textMaxLiteral};
+  let matches;
+  if (selector) {
+    try { matches = document.querySelectorAll(selector); }
+    catch (e) {
+      return { selector: selector, invalidSelector: true, reason: (e && e.message) || String(e) };
+    }
+  } else {
+    matches = [document.documentElement];
+  }
+  const matched = matches.length;
+  const root = matches[0] || null;
+  const trunc = { depth: false, children_dropped: 0, text_truncated: 0 };
+  function serialize(el, depth) {
+    if (!el || el.nodeType !== 1) return null;
+    const attrs = {};
+    for (const a of el.attributes) attrs[a.name] = a.value;
+    let text = '';
+    for (const n of el.childNodes) {
+      if (n.nodeType === 3) text += n.nodeValue;
+    }
+    text = text.replace(/\\s+/g, ' ').trim();
+    if (maxText !== null && text.length > maxText) {
+      text = text.slice(0, maxText);
+      trunc.text_truncated++;
+    }
+    const children = [];
+    if (maxDepth === null || depth < maxDepth) {
+      const childEls = [];
+      for (const n of el.childNodes) if (n.nodeType === 1) childEls.push(n);
+      const keep = maxChildren === null ? childEls.length : Math.min(childEls.length, maxChildren);
+      for (let i = 0; i < keep; i++) {
+        const child = serialize(childEls[i], depth + 1);
+        if (child) children.push(child);
+      }
+      if (maxChildren !== null && childEls.length > maxChildren) {
+        trunc.children_dropped += childEls.length - maxChildren;
+      }
+    } else {
+      // Budget hit: we're at max depth. Count any element children we would have visited.
+      for (const n of el.childNodes) if (n.nodeType === 1) { trunc.depth = true; break; }
+    }
+    const node = { tag: el.tagName.toLowerCase(), attrs, text, children };
+    const compound = compoundInfoOf(el);
+    if (compound) node.compound = compound;
+    return node;
+  }
+  const tree = root ? serialize(root, 0) : null;
+  const truncatedOut = {};
+  if (trunc.depth) truncatedOut.depth = true;
+  if (trunc.children_dropped > 0) truncatedOut.children_dropped = trunc.children_dropped;
+  if (trunc.text_truncated > 0) truncatedOut.text_truncated = trunc.text_truncated;
+  const envelope = { selector: selector, matched: matched, tree: tree };
+  if (Object.keys(truncatedOut).length > 0) envelope.truncated = truncatedOut;
+  return envelope;
+})()`;
+}

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

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

package/dist/src/browser/html-tree.test.js

@@ -0,0 +1,181 @@
+import { describe, expect, it } from 'vitest';
+import { buildHtmlTreeJs } from './html-tree.js';
+/**
+ * The serializer runs in a page context via `page.evaluate`. In unit tests we
+ * substitute `document` with a minimal stub that mirrors the DOM surface used
+ * by the expression, then Function-eval the returned JS.
+ */
+function runTreeJs(root, selectorMatches, selector, budgets = {}) {
+    const js = buildHtmlTreeJs({ selector, ...budgets });
+    const fakeDocument = {
+        querySelectorAll: () => selectorMatches,
+        documentElement: root,
+    };
+    const fn = new Function('document', `return ${js};`);
+    return fn(fakeDocument);
+}
+function runTreeJsInvalid(selector, errorMessage) {
+    const js = buildHtmlTreeJs({ selector });
+    const fakeDocument = {
+        querySelectorAll: () => { const e = new Error(errorMessage); e.name = 'SyntaxError'; throw e; },
+        documentElement: null,
+    };
+    const fn = new Function('document', `return ${js};`);
+    return fn(fakeDocument);
+}
+function el(tag, attrs, children, extras = {}) {
+    return {
+        nodeType: 1,
+        tagName: tag.toUpperCase(),
+        attributes: Object.entries(attrs).map(([name, value]) => ({ name, value })),
+        childNodes: children,
+        getAttribute: (name) => (name in attrs ? attrs[name] : null),
+        value: extras.value,
+        multiple: extras.multiple,
+        files: extras.files,
+        options: extras.options,
+    };
+}
+function txt(value) { return { nodeType: 3, nodeValue: value }; }
+describe('buildHtmlTreeJs', () => {
+    it('serializes a simple element into {tag, attrs, text, children}', () => {
+        const root = el('div', { class: 'hero', id: 'x' }, [txt('Hello')]);
+        const result = runTreeJs(root, [root], null);
+        expect(result.selector).toBeNull();
+        expect(result.matched).toBe(1);
+        expect(result.tree).toEqual({
+            tag: 'div',
+            attrs: { class: 'hero', id: 'x' },
+            text: 'Hello',
+            children: [],
+        });
+    });
+    it('collapses whitespace in direct text content only', () => {
+        const root = el('p', {}, [
+            txt('  line  \n  one  '),
+            el('span', {}, [txt('inner text')]),
+            txt('\tline two\t'),
+        ]);
+        const result = runTreeJs(root, [root], null);
+        expect(result.tree?.text).toBe('line one line two');
+        expect(result.tree?.children[0].text).toBe('inner text');
+    });
+    it('recurses into element children and preserves their attrs', () => {
+        const root = el('ul', { role: 'list' }, [
+            el('li', { 'data-id': '1' }, [txt('first')]),
+            el('li', { 'data-id': '2' }, [txt('second')]),
+        ]);
+        const result = runTreeJs(root, [root], null);
+        expect(result.tree?.children).toHaveLength(2);
+        expect(result.tree?.children[0]).toEqual({
+            tag: 'li',
+            attrs: { 'data-id': '1' },
+            text: 'first',
+            children: [],
+        });
+    });
+    it('returns matched=N and serializes only the first match', () => {
+        const first = el('article', { id: 'a' }, [txt('first')]);
+        const second = el('article', { id: 'b' }, [txt('second')]);
+        const result = runTreeJs(null, [first, second], 'article');
+        expect(result.matched).toBe(2);
+        expect(result.tree?.attrs.id).toBe('a');
+    });
+    it('returns tree=null and matched=0 when selector matches nothing', () => {
+        const result = runTreeJs(null, [], '.nothing');
+        expect(result.matched).toBe(0);
+        expect(result.tree).toBeNull();
+    });
+    it('catches SyntaxError from querySelectorAll and returns {invalidSelector:true, reason}', () => {
+        const result = runTreeJsInvalid('##$@@', "'##$@@' is not a valid selector");
+        expect(result.invalidSelector).toBe(true);
+        expect(result.selector).toBe('##$@@');
+        expect(result.reason).toContain('not a valid selector');
+    });
+    it('omits `truncated` when no budget is hit', () => {
+        const root = el('div', {}, [el('span', {}, [txt('ok')])]);
+        const result = runTreeJs(root, [root], null, { depth: 5, childrenMax: 10, textMax: 100 });
+        expect(result.truncated).toBeUndefined();
+    });
+});
+describe('buildHtmlTreeJs budget knobs', () => {
+    it('caps tree at `depth` and reports truncated.depth', () => {
+        const deep = el('a', {}, [
+            el('b', {}, [
+                el('c', {}, [el('d', {}, [txt('deep')])]),
+            ]),
+        ]);
+        // depth=1 → root + one level of children; grandchildren should be dropped.
+        const result = runTreeJs(deep, [deep], null, { depth: 1 });
+        expect(result.tree?.tag).toBe('a');
+        expect(result.tree?.children).toHaveLength(1);
+        expect(result.tree?.children[0].tag).toBe('b');
+        // The "b" node had element children but we hit the depth budget before
+        // recursing into them — children array is empty, truncated.depth is true.
+        expect(result.tree?.children[0].children).toEqual([]);
+        expect(result.truncated?.depth).toBe(true);
+    });
+    it('depth=0 keeps only the root', () => {
+        const root = el('ul', {}, [
+            el('li', {}, [txt('a')]),
+            el('li', {}, [txt('b')]),
+        ]);
+        const result = runTreeJs(root, [root], null, { depth: 0 });
+        expect(result.tree?.children).toEqual([]);
+        expect(result.truncated?.depth).toBe(true);
+    });
+    it('caps children per node at `childrenMax` and reports children_dropped count', () => {
+        const root = el('ul', {}, [
+            el('li', {}, [txt('1')]),
+            el('li', {}, [txt('2')]),
+            el('li', {}, [txt('3')]),
+            el('li', {}, [txt('4')]),
+            el('li', {}, [txt('5')]),
+        ]);
+        const result = runTreeJs(root, [root], null, { childrenMax: 2 });
+        expect(result.tree?.children).toHaveLength(2);
+        expect(result.truncated?.children_dropped).toBe(3);
+    });
+    it('caps direct text per node at `textMax` and reports text_truncated count', () => {
+        const root = el('p', {}, [
+            txt('a'.repeat(50)),
+            el('span', {}, [txt('b'.repeat(50))]),
+        ]);
+        const result = runTreeJs(root, [root], null, { textMax: 10 });
+        expect(result.tree?.text).toHaveLength(10);
+        expect(result.tree?.children[0].text).toHaveLength(10);
+        expect(result.truncated?.text_truncated).toBe(2);
+    });
+    // Blocker B regression: compound contract must ride along with the
+    // json tree so `browser get html --as json` surfaces the full contract
+    // to agents without an extra round-trip.
+    it('attaches compound info to date/file/select nodes and omits it elsewhere', () => {
+        const date = el('input', { type: 'date', min: '2026-01-01' }, [], { value: '2026-04-21' });
+        const file = el('input', { type: 'file', accept: 'image/*' }, [], { multiple: true, files: [{ name: 'a.png' }] });
+        const sel = el('select', { name: 'country' }, [], {
+            options: [
+                { value: 'us', label: 'United States', selected: true },
+                { value: 'ca', label: 'Canada' },
+            ],
+        });
+        const plain = el('input', { type: 'text' }, [], { value: 'hi' });
+        const root = el('form', {}, [date, file, sel, plain]);
+        const result = runTreeJs(root, [root], null);
+        expect(result.tree?.children[0].compound).toMatchObject({ control: 'date', format: 'YYYY-MM-DD', current: '2026-04-21', min: '2026-01-01' });
+        expect(result.tree?.children[1].compound).toMatchObject({ control: 'file', multiple: true, current: ['a.png'], accept: 'image/*' });
+        expect(result.tree?.children[2].compound).toMatchObject({ control: 'select', multiple: false, current: 'United States' });
+        expect(result.tree?.children[3].compound).toBeUndefined();
+    });
+    it('combines budgets and reports every hit', () => {
+        const root = el('ul', {}, [
+            el('li', {}, [txt('x'.repeat(20)), el('em', {}, [txt('y')])]),
+            el('li', {}, []),
+            el('li', {}, []),
+        ]);
+        const result = runTreeJs(root, [root], null, { depth: 1, childrenMax: 2, textMax: 5 });
+        expect(result.tree?.children).toHaveLength(2);
+        expect(result.truncated?.children_dropped).toBe(1);
+        expect(result.truncated?.text_truncated).toBe(1);
+        expect(result.truncated?.depth).toBe(true);
+    });
+});