@jackwener/opencli 1.7.4 → 1.7.6

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

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+export type DateLikeControl = 'date' | 'time' | 'datetime-local' | 'month' | 'week';
+export interface DateCompound {
+    control: DateLikeControl;
+    format: string;
+    current: string;
+    min?: string;
+    max?: string;
+}
+export interface SelectOption {
+    label: string;
+    value: string;
+    selected: boolean;
+    disabled?: boolean;
+}
+export interface SelectCompound {
+    control: 'select';
+    multiple: boolean;
+    current: string | string[];
+    options: SelectOption[];
+    options_total: number;
+}
+export interface FileCompound {
+    control: 'file';
+    multiple: boolean;
+    current: string[];
+    accept?: string;
+}
+export type CompoundInfo = DateCompound | SelectCompound | FileCompound;
+/** Max options included in a SelectCompound.options[]. Above this, `options_total` still reflects the true count. */
+export declare const COMPOUND_SELECT_OPTIONS_CAP = 50;
+/** Max characters per option label / file name. */
+export declare 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 declare const COMPOUND_INFO_JS = "\nfunction compoundInfoOf(el) {\n  if (!el || !el.tagName) return null;\n  const tag = el.tagName;\n  const LABEL_CAP = 80;\n  const OPTS_CAP = 50;\n  if (tag === 'INPUT') {\n    const type = (el.getAttribute('type') || 'text').toLowerCase();\n    const FORMATS = {\n      'date': 'YYYY-MM-DD',\n      'time': 'HH:MM',\n      'datetime-local': 'YYYY-MM-DDTHH:MM',\n      'month': 'YYYY-MM',\n      'week': 'YYYY-W##',\n    };\n    if (FORMATS[type]) {\n      const info = {\n        control: type,\n        format: FORMATS[type],\n        current: (el.value == null ? '' : String(el.value)),\n      };\n      const min = el.getAttribute('min');\n      if (min) info.min = min;\n      const max = el.getAttribute('max');\n      if (max) info.max = max;\n      return info;\n    }\n    if (type === 'file') {\n      const info = {\n        control: 'file',\n        multiple: !!el.multiple,\n        current: [],\n      };\n      const accept = el.getAttribute('accept');\n      if (accept) info.accept = accept;\n      try {\n        if (el.files && el.files.length) {\n          for (let i = 0; i < el.files.length; i++) {\n            const name = (el.files[i].name || '').slice(0, LABEL_CAP);\n            info.current.push(name);\n          }\n        }\n      } catch (_) {}\n      return info;\n    }\n    return null;\n  }\n  if (tag === 'SELECT') {\n    const multiple = !!el.multiple;\n    const options = [];\n    const selectedLabels = [];\n    let total = 0;\n    try {\n      const opts = el.options || [];\n      total = opts.length;\n      // Walk ALL options so `current` reflects selections that sit beyond the\n      // serialization cap. Only the first OPTS_CAP entries get pushed into\n      // options[]; anything past the cap still contributes to selectedLabels\n      // so agents see the true current state of big dropdowns.\n      for (let i = 0; i < opts.length; i++) {\n        const o = opts[i];\n        const labelRaw = (o.label != null && o.label !== '') ? o.label : (o.text || '');\n        const label = String(labelRaw).trim().slice(0, LABEL_CAP);\n        if (i < OPTS_CAP) {\n          const entry = { label: label, value: o.value, selected: !!o.selected };\n          if (o.disabled) entry.disabled = true;\n          options.push(entry);\n        }\n        if (o.selected) selectedLabels.push(label);\n      }\n    } catch (_) {}\n    return {\n      control: 'select',\n      multiple: multiple,\n      current: multiple ? selectedLabels : (selectedLabels[0] || ''),\n      options: options,\n      options_total: total,\n    };\n  }\n  return null;\n}\n";

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.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/daemon-client.d.ts

@@ -6,11 +6,9 @@
 import type { BrowserSessionInfo } from '../types.js';
 export interface DaemonCommand {
     id: string;
-    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'sessions' | 'set-file-input' | 'insert-text' | 'bind-current' | 'network-capture-start' | 'network-capture-read' | 'cdp';
-    /** Target page identity (targetId). Cross-layer contract — preferred over tabId. */
+    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'sessions' | 'set-file-input' | 'insert-text' | 'bind-current' | 'network-capture-start' | 'network-capture-read' | 'cdp' | 'frames';
+    /** Target page identity (targetId). Cross-layer contract with the extension. */
     page?: string;
-    /** @deprecated Legacy tab ID — use `page` (targetId) instead. */
-    tabId?: number;
     code?: string;
     workspace?: string;
     url?: string;
@@ -34,6 +32,10 @@ export interface DaemonCommand {
     cdpParams?: Record<string, unknown>;
     /** When true, automation windows are created in the foreground */
     windowFocused?: boolean;
+    /** Custom idle timeout in seconds for this workspace session. Overrides the default. */
+    idleTimeout?: number;
+    /** Frame index for cross-frame operations (0-based, from 'frames' action) */
+    frameIndex?: number;
 }
 export interface DaemonResult {
     id: string;

package/dist/src/browser/daemon-client.js

@@ -11,7 +11,7 @@ const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
 const OPENCLI_HEADERS = { 'X-OpenCLI': '1' };
 let _idCounter = 0;
 function generateId() {
-    return `cmd_${Date.now()}_${++_idCounter}`;
+    return `cmd_${process.pid}_${Date.now()}_${++_idCounter}`;
 }
 async function requestDaemon(pathname, init) {
     const { timeout = 2000, headers, ...rest } = init ?? {};
@@ -85,6 +85,11 @@ async function sendCommandRaw(action, params) {
             });
             const result = (await res.json());
             if (!result.ok) {
+                const isDuplicateCommandId = res.status === 409
+                    || (result.error ?? '').includes('Duplicate command id');
+                if (isDuplicateCommandId && attempt < maxRetries) {
+                    continue;
+                }
                 const advice = classifyBrowserError(new Error(result.error ?? ''));
                 if (advice.retryable && attempt < maxRetries) {
                     await sleep(advice.delayMs);

package/dist/src/browser/daemon-client.test.js

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, } from './daemon-client.js';
+import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, sendCommand, } from './daemon-client.js';
 describe('daemon-client', () => {
     beforeEach(() => {
         vi.stubGlobal('fetch', vi.fn());
@@ -78,4 +78,43 @@ describe('daemon-client', () => {
         });
         await expect(getDaemonHealth()).resolves.toEqual({ state: 'ready', status });
     });
+    it('sendCommand includes the current pid in generated command ids', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
+        vi.mocked(fetch).mockResolvedValue({
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+        });
+        await expect(sendCommand('exec', { code: '1 + 1' })).resolves.toBe('ok');
+        await expect(sendCommand('exec', { code: '2 + 2' })).resolves.toBe('ok');
+        const ids = vi.mocked(fetch).mock.calls.map(([, init]) => {
+            const body = JSON.parse(String(init?.body));
+            return body.id;
+        });
+        expect(ids).toHaveLength(2);
+        expect(ids[0]).toMatch(new RegExp(`^cmd_${process.pid}_1763000000000_\\d+$`));
+        expect(ids[1]).toMatch(new RegExp(`^cmd_${process.pid}_1763000000000_\\d+$`));
+        expect(ids[0]).not.toBe(ids[1]);
+    });
+    it('sendCommand retries with a new id when daemon reports a duplicate pending id', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_123);
+        const fetchMock = vi.mocked(fetch);
+        fetchMock
+            .mockResolvedValueOnce({
+            ok: false,
+            status: 409,
+            json: () => Promise.resolve({ ok: false, error: 'Duplicate command id already pending; retry' }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 42 }),
+        });
+        await expect(sendCommand('exec', { code: '6 * 7' })).resolves.toBe(42);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        const ids = fetchMock.mock.calls.map(([, init]) => {
+            const body = JSON.parse(String(init?.body));
+            return body.id;
+        });
+        expect(ids[0]).not.toBe(ids[1]);
+    });
 });

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,7 +618,9 @@ export function generateSnapshotJs(opts = {}) {
   const hiddenInteractives = [];
   const currentHashes = [];
   const refIdentity = {};
+  const compoundInfos = {};
   let iframeCount = 0;
+  let crossOriginIndex = 0;
 
   function walk(el, depth, parentPropagatingRect) {
     if (depth > MAX_DEPTH) return false;
@@ -626,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)) {
@@ -647,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)) {
@@ -659,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;
@@ -724,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
@@ -757,7 +818,9 @@ export function generateSnapshotJs(opts = {}) {
       const doc = el.contentDocument;
       if (!doc || !doc.body) {
         const attrs = serializeAttrs(el);
-        lines.push(indent + '|iframe|<iframe' + (attrs ? ' ' + attrs : '') + ' /> (cross-origin)');
+        const frameLabel = '[F' + crossOriginIndex + ']';
+        lines.push(indent + '|iframe|' + frameLabel + '<iframe' + (attrs ? ' ' + attrs : '') + ' /> (cross-origin, use: opencli browser frames + browser eval --frame <index>)');
+        crossOriginIndex++;
         return false;
       }
       iframeCount++;
@@ -770,7 +833,9 @@ export function generateSnapshotJs(opts = {}) {
       return has;
     } catch {
       const attrs = serializeAttrs(el);
-      lines.push(indent + '|iframe|<iframe' + (attrs ? ' ' + attrs : '') + ' /> (blocked)');
+      const frameLabel = '[F' + crossOriginIndex + ']';
+      lines.push(indent + '|iframe|' + frameLabel + '<iframe' + (attrs ? ' ' + attrs : '') + ' /> (blocked, use: opencli browser frames + browser eval --frame <index>)');
+      crossOriginIndex++;
       return false;
     }
   }
@@ -801,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);