@jackwener/opencli 1.7.14 → 1.7.15

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

@@ -69,6 +69,7 @@ describe('CDPBridge cookies', () => {
             ['Input.insertText', { text: 'hello' }],
             ['Input.dispatchKeyEvent', { type: 'keyDown', key: 'a', modifiers: 2 }],
             ['Input.dispatchKeyEvent', { type: 'keyUp', key: 'a', modifiers: 2 }],
+            ['Input.dispatchMouseEvent', { type: 'mouseMoved', x: 10, y: 20 }],
             ['Input.dispatchMouseEvent', { type: 'mousePressed', x: 10, y: 20, button: 'left', clickCount: 1 }],
             ['Input.dispatchMouseEvent', { type: 'mouseReleased', x: 10, y: 20, button: 'left', clickCount: 1 }],
             ['Page.handleJavaScriptDialog', { accept: true, promptText: 'ok' }],

package/dist/src/browser/daemon-client.d.ts

@@ -6,7 +6,7 @@
 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' | 'network-capture-start' | 'network-capture-read' | 'cdp' | 'frames';
+    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'sessions' | 'set-file-input' | 'insert-text' | 'bind' | 'network-capture-start' | 'network-capture-read' | 'wait-download' | 'cdp' | 'frames';
     /** Target page identity (targetId). Cross-layer contract with the extension. */
     page?: string;
     code?: string;
@@ -32,6 +32,8 @@ export interface DaemonCommand {
     text?: string;
     /** URL substring filter pattern for network capture */
     pattern?: string;
+    /** Download wait timeout in milliseconds */
+    timeoutMs?: number;
     cdpMethod?: string;
     cdpParams?: Record<string, unknown>;
     /** When true, the owned automation container is created in the foreground */

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

@@ -57,7 +57,7 @@ export interface FindResult {
 }
 export interface FindError {
     error: {
-        code: 'invalid_selector' | 'selector_not_found';
+        code: 'invalid_selector' | 'selector_not_found' | 'semantic_not_found';
         message: string;
         hint?: string;
     };
@@ -68,9 +68,17 @@ export interface FindOptions {
     /** Max chars of trimmed text per entry. Default 120. */
     textMax?: number;
 }
+export interface SemanticFindOptions extends FindOptions {
+    role?: string;
+    name?: string;
+    label?: string;
+    text?: string;
+    testid?: string;
+}
 /**
  * Build the browser-side JS that performs the CSS query and emits the
  * FindResult (or FindError) envelope. Evaluated inside `page.evaluate`.
  */
 export declare function buildFindJs(selector: string, opts?: FindOptions): string;
+export declare function buildSemanticFindJs(opts: SemanticFindOptions): string;
 export declare function isFindError(result: unknown): result is FindError;

package/dist/src/browser/find.js

@@ -174,6 +174,225 @@ export function buildFindJs(selector, opts = {}) {
     })()
   `;
 }
+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.__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;
+      }
+      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 (_) {}
+
+      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-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]) {
+          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.js

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import { buildFindJs, FIND_ATTR_WHITELIST, isFindError } from './find.js';
+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
@@ -118,3 +119,62 @@ describe('isFindError', () => {
         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-opencli-ref'");
+        expect(js).toContain('__opencli_ref_identity');
+        expect(js).toContain("identity['' + refNum] = fingerprintOf(el)");
+        expect(js).toContain("document.querySelectorAll('[data-opencli-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-opencli-ref')).toBe('1');
+        expect(dom.window.__opencli_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/page.d.ts

@@ -8,7 +8,7 @@
  * by the navigate action and pass it to all subsequent commands. This ensures
  * page-scoped operations target the correct page without guessing.
  */
-import type { BrowserCookie, ScreenshotOptions } from '../types.js';
+import type { BrowserCookie, BrowserDownloadWaitResult, ScreenshotOptions } from '../types.js';
 import { BasePage } from './base-page.js';
 /**
  * Page — implements IPage by talking to the daemon via HTTP.
@@ -53,6 +53,7 @@ export declare class Page extends BasePage {
     screenshot(options?: ScreenshotOptions): Promise<string>;
     startNetworkCapture(pattern?: string): Promise<boolean>;
     readNetworkCapture(): Promise<unknown[]>;
+    waitForDownload(pattern?: string, timeoutMs?: number): Promise<BrowserDownloadWaitResult>;
     /**
      * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
      * Chrome reads the files directly from the local filesystem, avoiding the

package/dist/src/browser/page.js

@@ -246,6 +246,14 @@ export class Page extends BasePage {
             return [];
         }
     }
+    async waitForDownload(pattern = '', timeoutMs = 30_000) {
+        const result = await sendCommand('wait-download', {
+            pattern,
+            timeoutMs,
+            ...this._cmdOpts(),
+        });
+        return result;
+    }
     /**
      * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
      * Chrome reads the files directly from the local filesystem, avoiding the
@@ -360,6 +368,11 @@ export class Page extends BasePage {
     `);
     }
     async nativeClick(x, y) {
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mouseMoved',
+            x,
+            y,
+        });
         await this.cdp('Input.dispatchMouseEvent', {
             type: 'mousePressed',
             x, y,

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

@@ -102,6 +102,34 @@ describe('Page network capture compatibility', () => {
         expect(warnMock).toHaveBeenCalledTimes(1);
     });
 });
+describe('Page download waits', () => {
+    beforeEach(() => {
+        sendCommandMock.mockReset();
+        sendCommandFullMock.mockReset();
+        warnMock.mockReset();
+    });
+    it('sends wait-download through the daemon with workspace and timeout', async () => {
+        sendCommandMock.mockResolvedValueOnce({
+            downloaded: true,
+            filename: '/tmp/receipt.pdf',
+            state: 'complete',
+            elapsedMs: 5,
+        });
+        const page = new Page('site:mercury');
+        const result = await page.waitForDownload('receipt', 1234);
+        expect(result).toEqual({
+            downloaded: true,
+            filename: '/tmp/receipt.pdf',
+            state: 'complete',
+            elapsedMs: 5,
+        });
+        expect(sendCommandMock).toHaveBeenCalledWith('wait-download', expect.objectContaining({
+            workspace: 'site:mercury',
+            pattern: 'receipt',
+            timeoutMs: 1234,
+        }));
+    });
+});
 describe('Page CDP helpers', () => {
     beforeEach(() => {
         sendCommandMock.mockReset();

package/dist/src/browser/target-errors.d.ts

@@ -16,8 +16,10 @@
  *   - selector_ambiguous:     >1 matches for a write op without --nth
  *   - selector_nth_out_of_range: --nth beyond matches_n
  *   - not_editable:           target exists but cannot accept text input
+ *   - not_checkable:          target exists but cannot be checked/unchecked
+ *   - not_file_input:         target exists but is not a usable file input
  */
-export type TargetErrorCode = 'not_found' | 'stale_ref' | 'invalid_selector' | 'selector_not_found' | 'selector_ambiguous' | 'selector_nth_out_of_range' | 'not_editable';
+export type TargetErrorCode = 'not_found' | 'stale_ref' | 'invalid_selector' | 'selector_not_found' | 'selector_ambiguous' | 'selector_nth_out_of_range' | 'not_editable' | 'not_checkable' | 'not_file_input';
 export interface TargetErrorInfo {
     code: TargetErrorCode;
     message: string;

package/dist/src/browser/target-errors.js

@@ -16,6 +16,8 @@
  *   - selector_ambiguous:     >1 matches for a write op without --nth
  *   - selector_nth_out_of_range: --nth beyond matches_n
  *   - not_editable:           target exists but cannot accept text input
+ *   - not_checkable:          target exists but cannot be checked/unchecked
+ *   - not_file_input:         target exists but is not a usable file input
  */
 export class TargetError extends Error {
     code;

package/dist/src/browser/target-resolver.d.ts

@@ -68,9 +68,23 @@ export type TargetMatchLevel = 'exact' | 'stable' | 'reidentified';
  * The resolved element is stored in `window.__resolved` for downstream helpers.
  */
 export declare function resolveTargetJs(ref: string, opts?: ResolveOptions): string;
+/**
+ * Generate JS that scrolls + measures `__resolved` without clicking.
+ *
+ * Generic click prefers CDP `Input.dispatchMouseEvent`, which fires the full
+ * pointer/mouse chain that Radix/MUI/shadcn dropdowns rely on. Keep measurement
+ * separate so the CDP-primary path does not call DOM `el.click()` first.
+ */
+export declare function boundingRectResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
 /**
  * Generate JS for click that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
+ *
+ * This is the JS fallback path. BasePage.click uses boundingRectResolvedJs for
+ * the CDP-primary path and only reaches this when native click is unavailable
+ * or the target has no usable rect.
  */
 export declare function clickResolvedJs(opts?: {
     skipScroll?: boolean;

package/dist/src/browser/target-resolver.js

@@ -273,9 +273,37 @@ export function resolveTargetJs(ref, opts = {}) {
     })()
   `;
 }
+/**
+ * Generate JS that scrolls + measures `__resolved` without clicking.
+ *
+ * Generic click prefers CDP `Input.dispatchMouseEvent`, which fires the full
+ * pointer/mouse chain that Radix/MUI/shadcn dropdowns rely on. Keep measurement
+ * separate so the CDP-primary path does not call DOM `el.click()` first.
+ */
+export function boundingRectResolvedJs(opts = {}) {
+    const shouldScroll = opts.skipScroll ? 'false' : 'true';
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      if (${shouldScroll}) el.scrollIntoView({ behavior: 'instant', block: 'center' });
+      const rect = el.getBoundingClientRect();
+      const w = Math.round(rect.width);
+      const h = Math.round(rect.height);
+      const x = Math.round(rect.left + rect.width / 2);
+      const y = Math.round(rect.top + rect.height / 2);
+      const visible = w > 0 && h > 0;
+      return { x, y, w, h, visible };
+    })()
+  `;
+}
 /**
  * Generate JS for click that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
+ *
+ * This is the JS fallback path. BasePage.click uses boundingRectResolvedJs for
+ * the CDP-primary path and only reaches this when native click is unavailable
+ * or the target has no usable rect.
  */
 export function clickResolvedJs(opts = {}) {
     const shouldScroll = opts.skipScroll ? 'false' : 'true';

package/dist/src/browser/visual-refs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Visual ref overlay for annotated screenshots.
+ *
+ * The overlay is intentionally DOM-side and temporary. It reuses the same
+ * `data-opencli-ref` attributes produced by the DOM snapshot path so the
+ * screenshot labels map back to normal `browser click <ref>` targets.
+ */
+export declare function installVisualRefOverlayJs(opts?: {
+    maxRefs?: number;
+}): string;
+export declare function removeVisualRefOverlayJs(): string;

package/dist/src/browser/visual-refs.js

@@ -0,0 +1,108 @@
+/**
+ * Visual ref overlay for annotated screenshots.
+ *
+ * The overlay is intentionally DOM-side and temporary. It reuses the same
+ * `data-opencli-ref` attributes produced by the DOM snapshot path so the
+ * screenshot labels map back to normal `browser click <ref>` targets.
+ */
+const OVERLAY_ID = '__opencli_visual_ref_overlay';
+export function installVisualRefOverlayJs(opts = {}) {
+    const maxRefs = Math.max(1, Math.min(opts.maxRefs ?? 120, 500));
+    return `
+    (() => {
+      const OVERLAY_ID = ${JSON.stringify(OVERLAY_ID)};
+      const MAX_REFS = ${maxRefs};
+      document.getElementById(OVERLAY_ID)?.remove();
+
+      const overlay = document.createElement('div');
+      overlay.id = OVERLAY_ID;
+      overlay.setAttribute('aria-hidden', 'true');
+      Object.assign(overlay.style, {
+        position: 'fixed',
+        inset: '0',
+        zIndex: '2147483647',
+        pointerEvents: 'none',
+        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+      });
+
+      const refs = Array.from(document.querySelectorAll('[data-opencli-ref]'))
+        .map((el) => {
+          const rawRef = el.getAttribute('data-opencli-ref') || '';
+          const ref = Number(rawRef);
+          const rect = el.getBoundingClientRect();
+          const visible = Number.isFinite(ref)
+            && rect.width >= 2
+            && rect.height >= 2
+            && rect.bottom >= 0
+            && rect.right >= 0
+            && rect.top <= window.innerHeight
+            && rect.left <= window.innerWidth;
+          return { el, rawRef, ref, rect, visible };
+        })
+        .filter((entry) => entry.visible)
+        .sort((a, b) => a.ref - b.ref)
+        .slice(0, MAX_REFS);
+
+      for (const entry of refs) {
+        const left = Math.max(0, Math.min(window.innerWidth - 1, entry.rect.left));
+        const top = Math.max(0, Math.min(window.innerHeight - 1, entry.rect.top));
+        const right = Math.max(0, Math.min(window.innerWidth, entry.rect.right));
+        const bottom = Math.max(0, Math.min(window.innerHeight, entry.rect.bottom));
+        const width = Math.max(2, right - left);
+        const height = Math.max(2, bottom - top);
+
+        const box = document.createElement('div');
+        Object.assign(box.style, {
+          position: 'fixed',
+          left: left + 'px',
+          top: top + 'px',
+          width: width + 'px',
+          height: height + 'px',
+          border: '2px solid #ff3b30',
+          borderRadius: '4px',
+          boxSizing: 'border-box',
+          boxShadow: '0 0 0 1px rgba(255,255,255,.9), 0 4px 16px rgba(0,0,0,.25)',
+          background: 'rgba(255,59,48,.08)',
+        });
+
+        const badge = document.createElement('div');
+        badge.textContent = entry.rawRef;
+        Object.assign(badge.style, {
+          position: 'fixed',
+          left: left + 'px',
+          top: Math.max(0, top - 20) + 'px',
+          minWidth: '18px',
+          height: '18px',
+          padding: '0 5px',
+          borderRadius: '999px',
+          border: '1px solid rgba(255,255,255,.95)',
+          background: '#ff3b30',
+          color: '#fff',
+          fontSize: '12px',
+          fontWeight: '700',
+          lineHeight: '18px',
+          textAlign: 'center',
+          textShadow: '0 1px 1px rgba(0,0,0,.25)',
+          boxShadow: '0 2px 8px rgba(0,0,0,.35)',
+        });
+
+        overlay.appendChild(box);
+        overlay.appendChild(badge);
+      }
+
+      document.documentElement.appendChild(overlay);
+      return {
+        annotated: refs.length,
+        truncated: refs.length >= MAX_REFS,
+      };
+    })()
+  `.trim();
+}
+export function removeVisualRefOverlayJs() {
+    return `
+    (() => {
+      document.getElementById(${JSON.stringify(OVERLAY_ID)})?.remove();
+      return true;
+    })()
+  `.trim();
+}

package/dist/src/build-manifest.d.ts

@@ -66,6 +66,29 @@ export declare function loadManifestEntries(filePath: string, site: string, impo
 export declare function scanClisDir(clisDir: string, importer?: (moduleHref: string) => Promise<unknown>): Promise<BuildManifestResult>;
 export declare function buildManifest(): Promise<BuildManifestResult>;
 export declare function serializeManifest(manifest: ManifestEntry[]): string;
+/**
+ * Metadata audit: every positional arg must carry a non-empty `help` string.
+ *
+ * Why this is a hard gate (not advisory):
+ *   - `opencli twitter followers --help` rendered `Arguments:\n  user  ` with
+ *     an empty trailing column. Agents and humans both saw a blank field —
+ *     impossible to recover the parameter's purpose without reading source.
+ *   - This is metadata completeness, not stylistic taste; failing closed is
+ *     the only way to keep the help surface trustworthy as adapters land.
+ *
+ * Note: semantic quality (e.g. "what does the optional positional mean when
+ * omitted?") is intentionally NOT enforced here. That belongs to a follow-up
+ * advisory audit — see PR plan `Arg metadata v2` for the structured
+ * `when_omitted / when_present / value_format` schema.
+ */
+export interface ManifestMetadataIssue {
+    site: string;
+    command: string;
+    arg: string;
+    sourceFile?: string;
+    reason: string;
+}
+export declare function findManifestMetadataIssues(entries: readonly ManifestEntry[]): ManifestMetadataIssue[];
 /**
  * Diff helper: returns site/name keys that exist in `prev` but not in
  * `next`. Used as a safety net to detect accidental mass-deletions caused