@jackwener/opencli 1.3.2 → 1.4.0

package/dist/analysis.js

@@ -0,0 +1,166 @@
+/**
+ * Shared API analysis helpers used by both explore.ts and record.ts.
+ *
+ * Extracts common logic for:
+ *   - URL pattern normalization
+ *   - Array path discovery in JSON responses
+ *   - Field role detection
+ *   - Auth indicator inference
+ *   - Capability name inference
+ *   - Strategy inference
+ */
+import { VOLATILE_PARAMS, SEARCH_PARAMS, PAGINATION_PARAMS, LIMIT_PARAMS, FIELD_ROLES, } from './constants.js';
+// ── URL pattern normalization ───────────────────────────────────────────────
+/** Normalize a full URL into a pattern (replace IDs, strip volatile params). */
+export function urlToPattern(url) {
+    try {
+        const p = new URL(url);
+        const pathNorm = p.pathname
+            .replace(/\/\d+/g, '/{id}')
+            .replace(/\/[0-9a-fA-F]{8,}/g, '/{hex}')
+            .replace(/\/BV[a-zA-Z0-9]{10}/g, '/{bvid}');
+        const params = [];
+        p.searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k))
+            params.push(k); });
+        return `${p.host}${pathNorm}${params.length ? '?' + params.sort().map(k => `${k}={}`).join('&') : ''}`;
+    }
+    catch {
+        return url;
+    }
+}
+/** Find the best (largest) array of objects in a JSON response body. */
+export function findArrayPath(obj, depth = 0) {
+    if (depth > 5 || !obj || typeof obj !== 'object')
+        return null;
+    if (Array.isArray(obj)) {
+        if (obj.length >= 2 && obj.some(i => i && typeof i === 'object' && !Array.isArray(i))) {
+            return { path: '', items: obj };
+        }
+        return null;
+    }
+    let best = null;
+    for (const [key, val] of Object.entries(obj)) {
+        const found = findArrayPath(val, depth + 1);
+        if (found) {
+            const fullPath = found.path ? `${key}.${found.path}` : key;
+            const candidate = { path: fullPath, items: found.items };
+            if (!best || candidate.items.length > best.items.length)
+                best = candidate;
+        }
+    }
+    return best;
+}
+// ── Field flattening & role detection ───────────────────────────────────────
+/** Flatten nested object keys up to maxDepth. */
+export function flattenFields(obj, prefix, maxDepth) {
+    if (maxDepth <= 0 || !obj || typeof obj !== 'object')
+        return [];
+    const names = [];
+    const record = obj;
+    for (const key of Object.keys(record)) {
+        const full = prefix ? `${prefix}.${key}` : key;
+        names.push(full);
+        const val = record[key];
+        if (val && typeof val === 'object' && !Array.isArray(val))
+            names.push(...flattenFields(val, full, maxDepth - 1));
+    }
+    return names;
+}
+/** Detect semantic field roles (title, url, author, etc.) from sample fields. */
+export function detectFieldRoles(sampleFields) {
+    const detectedFields = {};
+    for (const [role, aliases] of Object.entries(FIELD_ROLES)) {
+        for (const f of sampleFields) {
+            if (aliases.includes(f.split('.').pop()?.toLowerCase() ?? '')) {
+                detectedFields[role] = f;
+                break;
+            }
+        }
+    }
+    return detectedFields;
+}
+// ── Capability name inference ───────────────────────────────────────────────
+/** Infer a CLI capability name from a URL. */
+export function inferCapabilityName(url, goal) {
+    if (goal)
+        return goal;
+    const u = url.toLowerCase();
+    if (u.includes('hot') || u.includes('popular') || u.includes('ranking') || u.includes('trending'))
+        return 'hot';
+    if (u.includes('search'))
+        return 'search';
+    if (u.includes('feed') || u.includes('timeline') || u.includes('dynamic'))
+        return 'feed';
+    if (u.includes('comment') || u.includes('reply'))
+        return 'comments';
+    if (u.includes('history'))
+        return 'history';
+    if (u.includes('profile') || u.includes('userinfo') || u.includes('/me'))
+        return 'me';
+    if (u.includes('favorite') || u.includes('collect') || u.includes('bookmark'))
+        return 'favorite';
+    try {
+        const segs = new URL(url).pathname
+            .split('/')
+            .filter(s => s && !s.match(/^\d+$/) && !s.match(/^[0-9a-f]{8,}$/i) && !s.match(/^v\d+$/));
+        if (segs.length)
+            return segs[segs.length - 1].replace(/[^a-z0-9]/gi, '_').toLowerCase();
+    }
+    catch { }
+    return 'data';
+}
+// ── Strategy inference ──────────────────────────────────────────────────────
+/** Infer auth strategy from detected indicators. */
+export function inferStrategy(authIndicators) {
+    if (authIndicators.includes('signature'))
+        return 'intercept';
+    if (authIndicators.includes('bearer') || authIndicators.includes('csrf'))
+        return 'header';
+    return 'cookie';
+}
+// ── Auth indicator detection ────────────────────────────────────────────────
+/** Detect auth indicators from HTTP headers. */
+export function detectAuthFromHeaders(headers) {
+    if (!headers)
+        return [];
+    const indicators = [];
+    const keys = Object.keys(headers).map(k => k.toLowerCase());
+    if (keys.some(k => k === 'authorization'))
+        indicators.push('bearer');
+    if (keys.some(k => k.startsWith('x-csrf') || k.startsWith('x-xsrf')))
+        indicators.push('csrf');
+    if (keys.some(k => k.startsWith('x-s') || k === 'x-t' || k === 'x-s-common'))
+        indicators.push('signature');
+    return indicators;
+}
+/** Detect auth indicators from URL and response body (heuristic). */
+export function detectAuthFromContent(url, body) {
+    const indicators = [];
+    if (body && typeof body === 'object') {
+        const keys = Object.keys(body).map(k => k.toLowerCase());
+        if (keys.some(k => k.includes('sign') || k === 'w_rid' || k.includes('token'))) {
+            indicators.push('signature');
+        }
+    }
+    if (url.includes('/wbi/') || url.includes('w_rid='))
+        indicators.push('signature');
+    if (url.includes('bearer') || url.includes('access_token'))
+        indicators.push('bearer');
+    return indicators;
+}
+// ── Query param classification ──────────────────────────────────────────────
+/** Extract non-volatile query params and classify them. */
+export function classifyQueryParams(url) {
+    const params = [];
+    try {
+        new URL(url).searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k))
+            params.push(k); });
+    }
+    catch { }
+    return {
+        params,
+        hasSearch: params.some(p => SEARCH_PARAMS.has(p)),
+        hasPagination: params.some(p => PAGINATION_PARAMS.has(p)),
+        hasLimit: params.some(p => LIMIT_PARAMS.has(p)),
+    };
+}

package/dist/browser/cdp.d.ts

@@ -24,13 +24,9 @@ export declare class CDPBridge {
         workspace?: string;
     }): Promise<IPage>;
     close(): Promise<void>;
-    /** Send a CDP command with timeout guard (P0 fix #4) */
     send(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
-    /** Listen for a CDP event */
     on(event: string, handler: (params: unknown) => void): void;
-    /** Remove a CDP event listener */
     off(event: string, handler: (params: unknown) => void): void;
-    /** Wait for a CDP event to fire (one-shot) */
     waitForEvent(event: string, timeoutMs?: number): Promise<unknown>;
 }
 declare function selectCDPTarget(targets: CDPTarget[]): CDPTarget | undefined;

package/dist/browser/cdp.js

@@ -8,26 +8,28 @@
  * - Shared DOM helper methods extracted to reduce duplication with Page (P1 #5)
  */
 import { WebSocket } from 'ws';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
 import { wrapForEval } from './utils.js';
 import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
+import { generateStealthJs } from './stealth.js';
 import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
-const CDP_SEND_TIMEOUT = 30_000; // 30s per command
+import { isRecord, saveBase64ToFile } from '../utils.js';
+const CDP_SEND_TIMEOUT = 30_000;
 export class CDPBridge {
     _ws = null;
     _idCounter = 0;
     _pending = new Map();
     _eventListeners = new Map();
     async connect(opts) {
+        if (this._ws)
+            throw new Error('CDPBridge is already connected. Call close() before reconnecting.');
         const endpoint = process.env.OPENCLI_CDP_ENDPOINT;
         if (!endpoint)
             throw new Error('OPENCLI_CDP_ENDPOINT is not set');
-        // If it's a direct ws:// URL, use it. Otherwise, fetch the /json endpoint to find a page.
         let wsUrl = endpoint;
         if (endpoint.startsWith('http')) {
-            const res = await fetch(`${endpoint.replace(/\/$/, '')}/json`);
-            if (!res.ok)
-                throw new Error(`Failed to fetch CDP targets: ${res.statusText}`);
-            const targets = await res.json();
+            const targets = await fetchJsonDirect(`${endpoint.replace(/\/$/, '')}/json`);
             const target = selectCDPTarget(targets);
             if (!target || !target.webSocketDebuggerUrl) {
                 throw new Error('No inspectable targets found at CDP endpoint');
@@ -36,11 +38,16 @@ export class CDPBridge {
         }
         return new Promise((resolve, reject) => {
             const ws = new WebSocket(wsUrl);
-            const timeoutMs = (opts?.timeout ?? 10) * 1000; // opts.timeout is in seconds
+            const timeoutMs = (opts?.timeout ?? 10) * 1000;
             const timeout = setTimeout(() => reject(new Error('CDP connect timeout')), timeoutMs);
-            ws.on('open', () => {
+            ws.on('open', async () => {
                 clearTimeout(timeout);
                 this._ws = ws;
+                try {
+                    await this.send('Page.enable');
+                    await this.send('Page.addScriptToEvaluateOnNewDocument', { source: generateStealthJs() });
+                }
+                catch { }
                 resolve(new CDPPage(this));
             });
             ws.on('error', (err) => {
@@ -50,7 +57,6 @@ export class CDPBridge {
             ws.on('message', (data) => {
                 try {
                     const msg = JSON.parse(data.toString());
-                    // Handle command responses
                     if (msg.id && this._pending.has(msg.id)) {
                         const entry = this._pending.get(msg.id);
                         clearTimeout(entry.timer);
@@ -62,7 +68,6 @@ export class CDPBridge {
                             entry.resolve(msg.result);
                         }
                     }
-                    // Handle CDP events
                     if (msg.method) {
                         const listeners = this._eventListeners.get(msg.method);
                         if (listeners) {
@@ -71,9 +76,7 @@ export class CDPBridge {
                         }
                     }
                 }
-                catch {
-                    // ignore parsing errors
-                }
+                catch { }
             });
         });
     }
@@ -89,7 +92,6 @@ export class CDPBridge {
         this._pending.clear();
         this._eventListeners.clear();
     }
-    /** Send a CDP command with timeout guard (P0 fix #4) */
     async send(method, params = {}, timeoutMs = CDP_SEND_TIMEOUT) {
         if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
             throw new Error('CDP connection is not open');
@@ -104,7 +106,6 @@ export class CDPBridge {
             this._ws.send(JSON.stringify({ id, method, params }));
         });
     }
-    /** Listen for a CDP event */
     on(event, handler) {
         let set = this._eventListeners.get(event);
         if (!set) {
@@ -113,11 +114,9 @@ export class CDPBridge {
         }
         set.add(handler);
     }
-    /** Remove a CDP event listener */
     off(event, handler) {
         this._eventListeners.get(event)?.delete(handler);
     }
-    /** Wait for a CDP event to fire (one-shot) */
     waitForEvent(event, timeoutMs = 15_000) {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -135,18 +134,18 @@ export class CDPBridge {
 }
 class CDPPage {
     bridge;
+    _pageEnabled = false;
     constructor(bridge) {
         this.bridge = bridge;
     }
-    /** Navigate with proper load event waiting (P1 fix #3) */
     async goto(url, options) {
-        await this.bridge.send('Page.enable');
-        const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000)
-            .catch(() => { }); // Don't fail if event times out
+        if (!this._pageEnabled) {
+            await this.bridge.send('Page.enable');
+            this._pageEnabled = true;
+        }
+        const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000).catch(() => { });
         await this.bridge.send('Page.navigate', { url });
         await loadPromise;
-        // Smart settle: use DOM stability detection instead of fixed sleep.
-        // settleMs is now a timeout cap (default 1000ms), not a fixed wait.
         if (options?.waitUntil !== 'none') {
             const maxMs = options?.settleMs ?? 1000;
             await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
@@ -157,7 +156,7 @@ class CDPPage {
         const result = await this.bridge.send('Runtime.evaluate', {
             expression,
             returnByValue: true,
-            awaitPromise: true
+            awaitPromise: true,
         });
         if (result.exceptionDetails) {
             throw new Error('Evaluate error: ' + (result.exceptionDetails.exception?.description || 'Unknown exception'));
@@ -169,7 +168,7 @@ class CDPPage {
         const cookies = isRecord(result) && Array.isArray(result.cookies) ? result.cookies : [];
         const domain = opts.domain;
         return domain
-            ? cookies.filter((cookie) => isCookie(cookie) && cookie.domain.includes(domain))
+            ? cookies.filter((cookie) => isCookie(cookie) && matchesCookieDomain(cookie.domain, domain))
             : cookies;
     }
     async snapshot(opts = {}) {
@@ -183,7 +182,6 @@ class CDPPage {
         });
         return this.evaluate(snapshotJs);
     }
-    // ── Shared DOM operations (P1 fix #5 — using dom-helpers.ts) ──
     async click(ref) {
         await this.evaluate(clickJs(ref));
     }
@@ -201,12 +199,12 @@ class CDPPage {
     }
     async wait(options) {
         if (typeof options === 'number') {
-            await new Promise(resolve => setTimeout(resolve, options * 1000));
+            await new Promise((resolve) => setTimeout(resolve, options * 1000));
             return;
         }
         if (typeof options.time === 'number') {
             const waitTime = options.time;
-            await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
+            await new Promise((resolve) => setTimeout(resolve, waitTime * 1000));
             return;
         }
         if (options.text) {
@@ -214,7 +212,6 @@ class CDPPage {
             await this.evaluate(waitForTextJs(options.text, timeout));
         }
     }
-    // ── Implemented methods (P1 fix #2) ──
     async scroll(direction = 'down', amount = 500) {
         await this.evaluate(scrollJs(direction, amount));
     }
@@ -231,11 +228,7 @@ class CDPPage {
         });
         const base64 = isRecord(result) && typeof result.data === 'string' ? result.data : '';
         if (options.path) {
-            const fs = await import('node:fs');
-            const path = await import('node:path');
-            const dir = path.dirname(options.path);
-            await fs.promises.mkdir(dir, { recursive: true });
-            await fs.promises.writeFile(options.path, Buffer.from(base64, 'base64'));
+            await saveBase64ToFile(base64, options.path);
         }
         return base64;
     }
@@ -271,16 +264,18 @@ class CDPPage {
         return Array.isArray(result) ? result : [];
     }
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function isCookie(value) {
     return isRecord(value)
         && typeof value.name === 'string'
         && typeof value.value === 'string'
         && typeof value.domain === 'string';
 }
-// ── CDP target selection (unchanged) ──
+function matchesCookieDomain(cookieDomain, targetDomain) {
+    const normalizedCookieDomain = cookieDomain.replace(/^\./, '').toLowerCase();
+    const normalizedTargetDomain = targetDomain.replace(/^\./, '').toLowerCase();
+    return normalizedTargetDomain === normalizedCookieDomain
+        || normalizedTargetDomain.endsWith(`.${normalizedCookieDomain}`);
+}
 function selectCDPTarget(targets) {
     const preferredPattern = compilePreferredPattern(process.env.OPENCLI_CDP_TARGET);
     const ranked = targets
@@ -366,3 +361,29 @@ export const __test__ = {
     selectCDPTarget,
     scoreCDPTarget,
 };
+function fetchJsonDirect(url) {
+    return new Promise((resolve, reject) => {
+        const parsed = new URL(url);
+        const request = (parsed.protocol === 'https:' ? httpsRequest : httpRequest)(parsed, (res) => {
+            const statusCode = res.statusCode ?? 0;
+            if (statusCode < 200 || statusCode >= 300) {
+                res.resume();
+                reject(new Error(`Failed to fetch CDP targets: HTTP ${statusCode}`));
+                return;
+            }
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+                }
+                catch (error) {
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        });
+        request.on('error', reject);
+        request.setTimeout(10_000, () => request.destroy(new Error('Timed out fetching CDP targets')));
+        request.end();
+    });
+}

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

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

package/dist/browser/cdp.test.js

@@ -0,0 +1,52 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const { MockWebSocket } = vi.hoisted(() => {
+    class MockWebSocket {
+        static OPEN = 1;
+        readyState = 1;
+        handlers = new Map();
+        constructor(_url) {
+            queueMicrotask(() => this.emit('open'));
+        }
+        on(event, handler) {
+            const handlers = this.handlers.get(event) ?? [];
+            handlers.push(handler);
+            this.handlers.set(event, handlers);
+        }
+        send(_message) { }
+        close() {
+            this.readyState = 3;
+        }
+        emit(event, ...args) {
+            for (const handler of this.handlers.get(event) ?? []) {
+                handler(...args);
+            }
+        }
+    }
+    return { MockWebSocket };
+});
+vi.mock('ws', () => ({
+    WebSocket: MockWebSocket,
+}));
+import { CDPBridge } from './cdp.js';
+describe('CDPBridge cookies', () => {
+    beforeEach(() => {
+        vi.unstubAllEnvs();
+    });
+    it('filters cookies by actual domain match instead of substring match', async () => {
+        vi.stubEnv('OPENCLI_CDP_ENDPOINT', 'ws://127.0.0.1:9222/devtools/page/1');
+        const bridge = new CDPBridge();
+        vi.spyOn(bridge, 'send').mockResolvedValue({
+            cookies: [
+                { name: 'good', value: '1', domain: '.example.com' },
+                { name: 'exact', value: '2', domain: 'example.com' },
+                { name: 'bad', value: '3', domain: 'notexample.com' },
+            ],
+        });
+        const page = await bridge.connect();
+        const cookies = await page.getCookies({ domain: 'example.com' });
+        expect(cookies).toEqual([
+            { name: 'good', value: '1', domain: '.example.com' },
+            { name: 'exact', value: '2', domain: 'example.com' },
+        ]);
+    });
+});

package/dist/browser/daemon-client.js

@@ -3,7 +3,8 @@
  *
  * Provides a typed send() function that posts a Command and returns a Result.
  */
-const DAEMON_PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? '19825', 10);
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+const DAEMON_PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
 const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
 let _idCounter = 0;
 function generateId() {

package/dist/browser/discover.js

@@ -4,6 +4,7 @@
  * Only needs to check if the daemon is running. No more file system
  * scanning for @playwright/mcp locations.
  */
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
 import { isDaemonRunning } from './daemon-client.js';
 export { isDaemonRunning };
 /**
@@ -11,7 +12,7 @@ export { isDaemonRunning };
  */
 export async function checkDaemonStatus() {
     try {
-        const port = parseInt(process.env.OPENCLI_DAEMON_PORT ?? '19825', 10);
+        const port = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
         const res = await fetch(`http://127.0.0.1:${port}/status`, {
             headers: { 'X-OpenCLI': '1' },
         });

package/dist/browser/dom-snapshot.d.ts

@@ -23,7 +23,7 @@
  *   - scrollToRefJs(ref) — scroll to a data-opencli-ref element
  *   - getFormStateJs()  — extract all form fields as structured JSON
  */
-export interface SnapshotOptions {
+export interface DomSnapshotOptions {
     /** Extra pixels beyond viewport to include (default 800) */
     viewportExpand?: number;
     /** Maximum DOM depth to traverse (default 50) */
@@ -83,4 +83,4 @@ export declare function getFormStateJs(): string;
  * - `|iframe|` — iframe content
  * - `|table|` — markdown table rendering
  */
-export declare function generateSnapshotJs(opts?: SnapshotOptions): string;
+export declare function generateSnapshotJs(opts?: DomSnapshotOptions): string;

package/dist/browser/dom-snapshot.js

@@ -230,6 +230,13 @@ export function generateSnapshotJs(opts = {}) {
 
   const AD_SELECTOR_RE = /\\b(ad[_-]?(?:banner|container|wrapper|slot|unit|block|frame|leaderboard|sidebar)|google[_-]?ad|sponsored|adsbygoogle|banner[_-]?ad)\\b/i;
 
+  // Search element indicators for heuristic detection
+  const SEARCH_INDICATORS = new Set([
+    'search', 'magnify', 'glass', 'lookup', 'find', 'query',
+    'search-icon', 'search-btn', 'search-button', 'searchbox',
+    'fa-search', 'icon-search', 'btn-search',
+  ]);
+
   // ── Viewport & Layout Helpers ──────────────────────────────────────
 
   const vw = window.innerWidth;
@@ -298,19 +305,65 @@ export function generateSnapshotJs(opts = {}) {
 
   // ── Interactivity Detection ────────────────────────────────────────
 
+  // Check if element contains a form control within limited depth (handles label/span wrappers)
+  function hasFormControlDescendant(el, maxDepth = 2) {
+    if (maxDepth <= 0) return false;
+    for (const child of el.children || []) {
+      const tag = child.tagName?.toLowerCase();
+      if (tag === 'input' || tag === 'select' || tag === 'textarea') return true;
+      if (hasFormControlDescendant(child, maxDepth - 1)) return true;
+    }
+    return false;
+  }
+
   function isInteractive(el) {
     const tag = el.tagName.toLowerCase();
     if (INTERACTIVE_TAGS.has(tag)) {
-      if (tag === 'label' && el.hasAttribute('for')) return false;
+      // Skip labels that proxy via "for" to avoid double-activating external inputs
+      if (tag === 'label') {
+        if (el.hasAttribute('for')) return false;
+        // Detect labels that wrap form controls up to two levels deep (label > span > input)
+        if (hasFormControlDescendant(el, 2)) return true;
+      }
       if (el.disabled && (tag === 'button' || tag === 'input')) return false;
       return true;
     }
+    // Span wrappers for UI components - check if they contain form controls
+    if (tag === 'span') {
+      if (hasFormControlDescendant(el, 2)) return true;
+    }
     const role = el.getAttribute('role');
     if (role && INTERACTIVE_ROLES.has(role)) return true;
     if (el.hasAttribute('onclick') || el.hasAttribute('onmousedown') || el.hasAttribute('ontouchstart')) return true;
     if (el.hasAttribute('tabindex') && el.getAttribute('tabindex') !== '-1') return true;
     try { if (window.getComputedStyle(el).cursor === 'pointer') return true; } catch {}
     if (el.isContentEditable && el.getAttribute('contenteditable') !== 'false') return true;
+    // Search element heuristic detection
+    if (isSearchElement(el)) return true;
+    return false;
+  }
+
+  function isSearchElement(el) {
+    // Check class names for search indicators
+    const className = el.className?.toLowerCase() || '';
+    const classes = className.split(/\\s+/).filter(Boolean);
+    for (const cls of classes) {
+      const cleaned = cls.replace(/[^a-z0-9-]/g, '');
+      if (SEARCH_INDICATORS.has(cleaned)) return true;
+    }
+    // Check id for search indicators
+    const id = el.id?.toLowerCase() || '';
+    const cleanedId = id.replace(/[^a-z0-9-]/g, '');
+    if (SEARCH_INDICATORS.has(cleanedId)) return true;
+    // Check data-* attributes for search functionality
+    for (const attr of el.attributes || []) {
+      if (attr.name.startsWith('data-')) {
+        const value = attr.value.toLowerCase();
+        for (const kw of SEARCH_INDICATORS) {
+          if (value.includes(kw)) return true;
+        }
+      }
+    }
     return false;
   }
 

package/dist/browser/dom-snapshot.test.js

@@ -210,3 +210,39 @@ describe('getFormStateJs', () => {
         expect(js).toContain('data-opencli-ref');
     });
 });
+describe('Search Element Detection', () => {
+    it('includes SEARCH_INDICATORS set', () => {
+        const js = generateSnapshotJs();
+        expect(js).toContain('SEARCH_INDICATORS');
+        expect(js).toContain('search');
+        expect(js).toContain('magnify');
+        expect(js).toContain('glass');
+    });
+    it('includes hasFormControlDescendant function', () => {
+        const js = generateSnapshotJs();
+        expect(js).toContain('hasFormControlDescendant');
+        expect(js).toContain('input');
+        expect(js).toContain('select');
+        expect(js).toContain('textarea');
+    });
+    it('includes isSearchElement function', () => {
+        const js = generateSnapshotJs();
+        expect(js).toContain('isSearchElement');
+        expect(js).toContain('className');
+        expect(js).toContain('data-');
+    });
+    it('checks label wrapper detection in isInteractive', () => {
+        const js = generateSnapshotJs();
+        // Label elements without "for" attribute should check for form control descendants
+        expect(js).toContain('hasFormControlDescendant(el, 2)');
+    });
+    it('checks span wrapper detection in isInteractive', () => {
+        const js = generateSnapshotJs();
+        // Span elements should check for form control descendants
+        expect(js).toContain("tag === 'span'");
+    });
+    it('integrates search element detection into isInteractive', () => {
+        const js = generateSnapshotJs();
+        expect(js).toContain('isSearchElement(el)');
+    });
+});

package/dist/browser/errors.js

@@ -5,13 +5,14 @@
  * The daemon architecture has a single failure mode: daemon not reachable or extension not connected.
  */
 import { BrowserConnectError } from '../errors.js';
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
 export function formatBrowserConnectError(kind, detail) {
     switch (kind) {
         case 'daemon-not-running':
             return new BrowserConnectError('Cannot connect to opencli daemon.' +
                 (detail ? `\n\n${detail}` : ''), 'The daemon should start automatically. If it doesn\'t, try:\n' +
                 '  node dist/daemon.js\n' +
-                'Make sure port 19825 is available.');
+                `Make sure port ${DEFAULT_DAEMON_PORT} is available.`);
         case 'extension-not-connected':
             return new BrowserConnectError('opencli Browser Bridge extension is not connected.' +
                 (detail ? `\n\n${detail}` : ''), 'Please install the extension:\n' +