@jackwener/opencli 1.7.5 → 1.7.6

package/clis/youtube/channel.js

@@ -115,6 +115,41 @@ cli({
           }
         }
 
+        // If Home tab has no videos, try Videos tab
+        if (recentVideos.length === 0) {
+          const videosTab = tabs.find(t => {
+            const tab = t.tabRenderer;
+            const url = tab?.endpoint?.commandMetadata?.webCommandMetadata?.url || '';
+            return tab?.tabIdentifier === 'VIDEOS'
+              || url.endsWith('/videos')
+              || tab?.title === 'Videos';
+          });
+          const videosTabParams = videosTab?.tabRenderer?.endpoint?.browseEndpoint?.params;
+          if (videosTabParams) {
+            const videosResp = await fetch('/youtubei/v1/browse?key=' + apiKey + '&prettyPrint=false', {
+              method: 'POST', credentials: 'include',
+              headers: {'Content-Type': 'application/json'},
+              body: JSON.stringify({context, browseId, params: videosTabParams})
+            });
+            if (videosResp.ok) {
+              const videosData = await videosResp.json();
+              const richGrid = videosData.contents?.twoColumnBrowseResultsRenderer?.tabs?.[0]?.tabRenderer?.content?.richGridRenderer?.contents || [];
+              for (const item of richGrid) {
+                if (recentVideos.length >= limit) break;
+                const v = item.richItemRenderer?.content?.videoRenderer;
+                if (v) {
+                  recentVideos.push({
+                    title: v.title?.runs?.[0]?.text || '',
+                    duration: v.lengthText?.simpleText || '',
+                    views: (v.shortViewCountText?.simpleText || '') + (v.publishedTimeText?.simpleText ? ' | ' + v.publishedTimeText.simpleText : ''),
+                    url: 'https://www.youtube.com/watch?v=' + v.videoId,
+                  });
+                }
+              }
+            }
+          }
+        }
+
         return {
           name: metadata.title || '',
           channelId: metadata.externalId || browseId,

package/dist/src/browser/base-page.d.ts

@@ -9,6 +9,16 @@
  * getCookies, screenshot, tabs, etc.
  */
 import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
+import { type ResolveOptions, type TargetMatchLevel } from './target-resolver.js';
+export interface ResolveSuccess {
+    matches_n: number;
+    /**
+     * Cascading stale-ref tier the resolver traversed. Callers surface this to
+     * agents so `stable` / `reidentified` hits are visibly distinct from a
+     * clean `exact` match — the page changed, the action still succeeded.
+     */
+    match_level: TargetMatchLevel;
+}
 export declare abstract class BasePage implements IPage {
     protected _lastUrl: string | null;
     /** Cached previous snapshot hashes for incremental diff marking */
@@ -34,12 +44,12 @@ export declare abstract class BasePage implements IPage {
     abstract screenshot(options?: ScreenshotOptions): Promise<string>;
     abstract tabs(): Promise<unknown[]>;
     abstract selectTab(target: number | string): Promise<void>;
-    click(ref: string): Promise<void>;
+    click(ref: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
     /** Override in subclasses with CDP native click support */
     protected tryNativeClick(_x: number, _y: number): Promise<boolean>;
-    typeText(ref: string, text: string): Promise<void>;
+    typeText(ref: string, text: string, opts?: ResolveOptions): Promise<ResolveSuccess>;
     pressKey(key: string): Promise<void>;
-    scrollTo(ref: string): Promise<unknown>;
+    scrollTo(ref: string, opts?: ResolveOptions): Promise<unknown>;
     getFormState(): Promise<Record<string, unknown>>;
     scroll(direction?: string, amount?: number): Promise<void>;
     autoScroll(options?: {

package/dist/src/browser/base-page.js

@@ -10,8 +10,26 @@
  */
 import { generateSnapshotJs, getFormStateJs } from './dom-snapshot.js';
 import { pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
-import { resolveTargetJs, clickResolvedJs, typeResolvedJs, scrollResolvedJs } from './target-resolver.js';
+import { resolveTargetJs, clickResolvedJs, typeResolvedJs, scrollResolvedJs, } from './target-resolver.js';
 import { TargetError } from './target-errors.js';
+/**
+ * Execute `resolveTargetJs` once, throw structured `TargetError` on failure.
+ * Single helper so click/typeText/scrollTo share one resolution pathway,
+ * which is what the selector-first contract promises agents.
+ */
+async function runResolve(page, ref, opts = {}) {
+    const resolution = (await page.evaluate(resolveTargetJs(ref, opts)));
+    if (!resolution.ok) {
+        throw new TargetError({
+            code: resolution.code,
+            message: resolution.message,
+            hint: resolution.hint,
+            candidates: resolution.candidates,
+            matches_n: resolution.matches_n,
+        });
+    }
+    return { matches_n: resolution.matches_n, match_level: resolution.match_level };
+}
 import { formatSnapshot } from '../snapshotFormatter.js';
 export class BasePage {
     _lastUrl = null;
@@ -37,25 +55,20 @@ export class BasePage {
         return this.evaluate(`${declarations}\n${js}`);
     }
     // ── Shared DOM helper implementations ──
-    async click(ref) {
+    async click(ref, opts = {}) {
         // Phase 1: Resolve target with fingerprint verification
-        const resolution = await this.evaluate(resolveTargetJs(ref));
-        if (!resolution.ok) {
-            throw new TargetError(resolution);
-        }
+        const resolved = await runResolve(this, ref, opts);
         // Phase 2: Execute click on resolved element
         const result = await this.evaluate(clickResolvedJs());
-        // Backwards compat: old format returned 'clicked' string
         if (typeof result === 'string' || result == null)
-            return;
-        // JS click succeeded
+            return resolved;
         if (result.status === 'clicked')
-            return;
+            return resolved;
         // JS click failed — try CDP native click if coordinates available
         if (result.x != null && result.y != null) {
             const success = await this.tryNativeClick(result.x, result.y);
             if (success)
-                return;
+                return resolved;
         }
         throw new Error(`Click failed: ${result.error ?? 'JS click and CDP fallback both failed'}`);
     }
@@ -63,26 +76,23 @@ export class BasePage {
     async tryNativeClick(_x, _y) {
         return false;
     }
-    async typeText(ref, text) {
-        // Phase 1: Resolve target with fingerprint verification
-        const resolution = await this.evaluate(resolveTargetJs(ref));
-        if (!resolution.ok) {
-            throw new TargetError(resolution);
-        }
-        // Phase 2: Execute type on resolved element
+    async typeText(ref, text, opts = {}) {
+        const resolved = await runResolve(this, ref, opts);
         await this.evaluate(typeResolvedJs(text));
+        return resolved;
     }
     async pressKey(key) {
         await this.evaluate(pressKeyJs(key));
     }
-    async scrollTo(ref) {
-        // Phase 1: Resolve target with fingerprint verification
-        const resolution = await this.evaluate(resolveTargetJs(ref));
-        if (!resolution.ok) {
-            throw new TargetError(resolution);
+    async scrollTo(ref, opts = {}) {
+        const resolved = await runResolve(this, ref, opts);
+        const result = (await this.evaluate(scrollResolvedJs()));
+        // Fold match_level into the scroll payload so the user-facing envelope
+        // carries it the same way click / type do.
+        if (result && typeof result === 'object') {
+            return { ...result, matches_n: resolved.matches_n, match_level: resolved.match_level };
         }
-        // Phase 2: Scroll to resolved element
-        return this.evaluate(scrollResolvedJs());
+        return { matches_n: resolved.matches_n, match_level: resolved.match_level };
     }
     async getFormState() {
         return (await this.evaluate(getFormStateJs()));

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

@@ -15,6 +15,7 @@ export interface CDPTarget {
     title?: string;
     webSocketDebuggerUrl?: string;
 }
+export declare const CDP_RESPONSE_BODY_CAPTURE_LIMIT: number;
 export declare class CDPBridge implements IBrowserFactory {
     private _ws;
     private _idCounter;

package/dist/src/browser/cdp.js

@@ -17,6 +17,12 @@ import { isRecord, saveBase64ToFile } from '../utils.js';
 import { getAllElectronApps } from '../electron-apps.js';
 import { BasePage } from './base-page.js';
 const CDP_SEND_TIMEOUT = 30_000;
+// Memory guard for in-process capture. The 4k cap we used to apply everywhere
+// silently truncated JSON so `JSON.parse` failed or gave partial objects — the
+// primary agent-facing bug. Now we keep the full body up to a large cap and
+// surface `responseBodyFullSize` + `responseBodyTruncated` so downstream layers
+// can tell the agent what happened instead of lying about the payload.
+export const CDP_RESPONSE_BODY_CAPTURE_LIMIT = 8 * 1024 * 1024;
 export class CDPBridge {
     _ws = null;
     _idCounter = 0;
@@ -240,9 +246,12 @@ class CDPPage extends BasePage {
                     const bodyFetch = this.bridge.send('Network.getResponseBody', { requestId: p.requestId }).then((result) => {
                         const r = result;
                         if (typeof r?.body === 'string') {
-                            this._networkEntries[idx].responsePreview = r.base64Encoded
-                                ? `base64:${r.body.slice(0, 4000)}`
-                                : r.body.slice(0, 4000);
+                            const fullSize = r.body.length;
+                            const truncated = fullSize > CDP_RESPONSE_BODY_CAPTURE_LIMIT;
+                            const body = truncated ? r.body.slice(0, CDP_RESPONSE_BODY_CAPTURE_LIMIT) : r.body;
+                            this._networkEntries[idx].responsePreview = r.base64Encoded ? `base64:${body}` : body;
+                            this._networkEntries[idx].responseBodyFullSize = fullSize;
+                            this._networkEntries[idx].responseBodyTruncated = truncated;
                         }
                     }).catch(() => {
                         // Body unavailable for some requests (e.g. uploads) — non-fatal

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.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) */