publishport-opencli 1.0.0

package/dist/src/browser/stealth.js

@@ -0,0 +1,391 @@
+let j;const k=`
+    (function () {
+      try {
+        var _ep = EventTarget.prototype;
+        var _nativeAdd = _ep.__buNativeAdd || _ep.addEventListener;
+        try {
+          _nativeAdd.call(window, 'beforeunload', function (e) {
+            try { e.stopImmediatePropagation(); } catch (x) {}
+            try { e.returnValue = ''; } catch (x) {}
+          }, true);
+        } catch (e) {}
+        try { window.onbeforeunload = null; } catch (e) {}
+        try {
+          Object.defineProperty(window, 'onbeforeunload', { get: function () { return null; }, set: function () {}, configurable: true });
+        } catch (e) {}
+        if (!_ep.__buGuard) {
+          var _add = _ep.addEventListener;
+          var _rm = _ep.removeEventListener;
+          var addP = function (type, listener, options) {
+            if (type === 'beforeunload') return;
+            return _add.call(this, type, listener, options);
+          };
+          var rmP = function (type, listener, options) {
+            if (type === 'beforeunload') return;
+            return _rm.call(this, type, listener, options);
+          };
+          try { Object.defineProperty(addP, 'name', { value: 'addEventListener' }); } catch (e) {}
+          try { Object.defineProperty(rmP, 'name', { value: 'removeEventListener' }); } catch (e) {}
+          try { addP.toString = function () { return _add.toString(); }; } catch (e) {}
+          try { rmP.toString = function () { return _rm.toString(); }; } catch (e) {}
+          try { Object.defineProperty(_ep, '__buNativeAdd', { value: _add, enumerable: false, configurable: true }); } catch (e) {}
+          _ep.addEventListener = addP;
+          _ep.removeEventListener = rmP;
+          try { Object.defineProperty(_ep, '__buGuard', { value: true, enumerable: false, configurable: true }); } catch (e) {}
+        }
+      } catch (e) {}
+    })();
+`;export function generateBeforeUnloadGuardJs(){return k}export function generateStealthJs(){if(j!==void 0)return j;return j=`
+    (() => {
+      // Guard: prevent double-injection across separate CDP evaluations.
+      // We cannot use a closure variable (each eval is a fresh scope), and
+      // window properties / Symbols are discoverable by anti-bot scripts.
+      // Instead, stash the flag in a non-enumerable getter on a built-in
+      // prototype that fingerprinters are unlikely to scan.
+      const _gProto = EventTarget.prototype;
+      const _gKey = '__lsn';  // looks like an internal listener cache
+      if (_gProto[_gKey]) return 'skipped';
+      try {
+        Object.defineProperty(_gProto, _gKey, { value: true, enumerable: false, configurable: true });
+      } catch {}
+
+      // 1. navigator.webdriver → false
+      //    Most common check; Playwright/Puppeteer/CDP set this to true.
+      //    Real Chrome returns false (not undefined) — returning undefined is
+      //    itself a detection signal for advanced fingerprinters.
+      try {
+        Object.defineProperty(navigator, 'webdriver', {
+          get: () => false,
+          configurable: true,
+        });
+      } catch {}
+
+      // 2. window.chrome stub
+      //    Real Chrome exposes window.chrome with runtime, loadTimes, csi.
+      //    Headless/automated Chrome may not have it.
+      try {
+        if (!window.chrome) {
+          window.chrome = {
+            runtime: {
+              onConnect: { addListener: () => {}, removeListener: () => {} },
+              onMessage: { addListener: () => {}, removeListener: () => {} },
+            },
+            loadTimes: () => ({}),
+            csi: () => ({}),
+          };
+        }
+      } catch {}
+
+      // 3. navigator.plugins — fake population only if empty
+      //    Real user browser already has plugins; only patch in automated/headless
+      //    contexts where the list is empty (overwriting real plugins with fakes
+      //    would be counterproductive and detectable).
+      try {
+        if (!navigator.plugins || navigator.plugins.length === 0) {
+          const fakePlugins = [
+            { name: 'PDF Viewer', filename: 'internal-pdf-viewer', description: 'Portable Document Format' },
+            { name: 'Chrome PDF Viewer', filename: 'internal-pdf-viewer', description: '' },
+            { name: 'Chromium PDF Viewer', filename: 'internal-pdf-viewer', description: '' },
+            { name: 'Microsoft Edge PDF Viewer', filename: 'internal-pdf-viewer', description: '' },
+            { name: 'WebKit built-in PDF', filename: 'internal-pdf-viewer', description: '' },
+          ];
+          fakePlugins.item = (i) => fakePlugins[i] || null;
+          fakePlugins.namedItem = (n) => fakePlugins.find(p => p.name === n) || null;
+          fakePlugins.refresh = () => {};
+          Object.defineProperty(navigator, 'plugins', {
+            get: () => fakePlugins,
+            configurable: true,
+          });
+        }
+      } catch {}
+
+      // 4. navigator.languages — guarantee non-empty
+      //    Some automated contexts return undefined or empty array.
+      try {
+        if (!navigator.languages || navigator.languages.length === 0) {
+          Object.defineProperty(navigator, 'languages', {
+            get: () => ['en-US', 'en'],
+            configurable: true,
+          });
+        }
+      } catch {}
+
+      // 5. Permissions.query — normalize notification permission
+      //    Headless Chrome throws on Permissions.query({ name: 'notifications' }).
+      try {
+        const origQuery = window.Permissions?.prototype?.query;
+        if (origQuery) {
+          window.Permissions.prototype.query = function (parameters) {
+            if (parameters?.name === 'notifications') {
+              return Promise.resolve({ state: Notification.permission, onchange: null });
+            }
+            return origQuery.call(this, parameters);
+          };
+        }
+      } catch {}
+
+      // 6. Clean automation artifacts
+      //    Remove properties left by Playwright, Puppeteer, or CDP injection.
+      try {
+        delete window.__playwright;
+        delete window.__puppeteer;
+        // ChromeDriver injects cdc_ prefixed globals; the suffix varies by version,
+        // so scan window for any matching property rather than hardcoding names.
+        for (const prop of Object.getOwnPropertyNames(window)) {
+          if (prop.startsWith('cdc_') || prop.startsWith('__cdc_')) {
+            try { delete window[prop]; } catch {}
+          }
+        }
+      } catch {}
+
+      // 7. CDP stack trace cleanup
+      //    Runtime.evaluate injects scripts whose source URLs appear in Error
+      //    stack traces (e.g. __puppeteer_evaluation_script__, pptr:, debugger://).
+      //    Websites detect automation by doing: new Error().stack and inspecting it.
+      //    We override the stack property getter on Error.prototype to filter them.
+      //    Note: Error.prepareStackTrace is V8/Node-only and not available in
+      //    browser page context, so we use a property descriptor approach instead.
+      //    We use generic protocol patterns instead of product-specific names to
+      //    also catch our own injected code frames without leaking identifiers.
+      try {
+        const _origDescriptor = Object.getOwnPropertyDescriptor(Error.prototype, 'stack');
+        const _cdpPatterns = [
+          'puppeteer_evaluation_script',
+          'pptr:',
+          'debugger://',
+          '__playwright',
+          '__puppeteer',
+        ];
+        if (_origDescriptor && _origDescriptor.get) {
+          Object.defineProperty(Error.prototype, 'stack', {
+            get: function () {
+              const raw = _origDescriptor.get.call(this);
+              if (typeof raw !== 'string') return raw;
+              return raw.split('\\n').filter(line =>
+                !_cdpPatterns.some(p => line.includes(p))
+              ).join('\\n');
+            },
+            configurable: true,
+          });
+        }
+      } catch {}
+
+      // ── Shared toString disguise infrastructure ──
+      // Save the pristine Function.prototype.toString BEFORE any patches,
+      // so all subsequent disguises use the real native reference.
+      // Anti-bot scripts detect per-instance toString overrides via:
+      //   Function.hasOwnProperty('toString')          → true if patched
+      //   Function.prototype.toString.call(fn) !== fn.toString()
+      // Instead we patch Function.prototype.toString once with a WeakMap
+      // lookup, making disguised functions indistinguishable from native.
+      const _origToString = Function.prototype.toString;
+      const _disguised = new WeakMap();
+      try {
+        Object.defineProperty(Function.prototype, 'toString', {
+          value: function() {
+            const override = _disguised.get(this);
+            return override !== undefined ? override : _origToString.call(this);
+          },
+          writable: true, configurable: true,
+        });
+      } catch {}
+      const _disguise = (fn, name) => {
+        _disguised.set(fn, 'function ' + name + '() { [native code] }');
+        try { Object.defineProperty(fn, 'name', { value: name, configurable: true }); } catch {}
+        return fn;
+      };
+
+      // 8. Anti-debugger statement trap
+      //    Sites inject debugger statements to detect DevTools/CDP.
+      //    When a CDP debugger is attached, the statement pauses execution
+      //    and the site measures the time gap to confirm automation.
+      //    We neutralize this by overriding the Function constructor and
+      //    eval to strip debugger statements from dynamically created code.
+      //    Note: this does NOT affect static debugger statements in parsed
+      //    scripts — those require CDP Debugger.setBreakpointsActive(false)
+      //    which we handle at the extension level.
+      //    Caveat: the regex targets standalone debugger statements (preceded
+      //    by a statement boundary) to minimise false positives inside string
+      //    literals, but cannot perfectly distinguish all cases without a
+      //    full parser. This is an acceptable trade-off for stealth code.
+      try {
+        const _OrigFunction = Function;
+        // Match standalone debugger statements preceded by a statement
+        // boundary (start of string, semicolon, brace, or newline).
+        // This avoids most false positives inside string literals like
+        // "use debugger mode" while still catching the anti-bot patterns.
+        const _debuggerRe = /(?:^|(?<=[;{}\\n\\r]))\\s*debugger\\s*;?/g;
+        const _cleanDebugger = (src) => typeof src === 'string' ? src.replace(_debuggerRe, '') : src;
+        // Patch Function constructor to strip debugger from dynamic code.
+        // Support both Function('code') and new Function('code') via
+        // new.target / Reflect.construct.
+        const _PatchedFunction = function(...args) {
+          if (args.length > 0) {
+            args[args.length - 1] = _cleanDebugger(args[args.length - 1]);
+          }
+          if (new.target) {
+            return Reflect.construct(_OrigFunction, args, new.target);
+          }
+          return _OrigFunction.apply(this, args);
+        };
+        _PatchedFunction.prototype = _OrigFunction.prototype;
+        Object.setPrototypeOf(_PatchedFunction, _OrigFunction);
+        _disguise(_PatchedFunction, 'Function');
+        try { window.Function = _PatchedFunction; } catch {}
+
+        // Patch eval to strip debugger
+        const _origEval = window.eval;
+        const _patchedEval = function(code) {
+          return _origEval.call(this, _cleanDebugger(code));
+        };
+        _disguise(_patchedEval, 'eval');
+        try { window.eval = _patchedEval; } catch {}
+      } catch {}
+
+      // 9. Console method fingerprinting defense
+      //    When CDP Runtime.enable is called, Chrome replaces console.log etc.
+      //    with CDP-bound versions. These bound functions have a different
+      //    toString() output: "function log() { [native code] }" becomes
+      //    something like "function () { [native code] }" (no name) or the
+      //    bound function signature leaks. Anti-bot scripts check:
+      //      console.log.toString().includes('[native code]')
+      //      console.log.name === 'log'
+      //    We re-wrap console methods and register them via the shared
+      //    _disguise infrastructure so Function.prototype.toString.call()
+      //    also returns the correct native string.
+      try {
+        const _consoleMethods = ['log', 'warn', 'error', 'info', 'debug', 'table', 'trace', 'dir', 'group', 'groupEnd', 'groupCollapsed', 'clear', 'count', 'assert', 'profile', 'profileEnd', 'time', 'timeEnd', 'timeStamp'];
+        for (const _m of _consoleMethods) {
+          if (typeof console[_m] !== 'function') continue;
+          const _origMethod = console[_m];
+          const _nativeStr = 'function ' + _m + '() { [native code] }';
+          // Only patch if toString is wrong (i.e. CDP has replaced it)
+          try {
+            const _currentStr = _origToString.call(_origMethod);
+            if (_currentStr === _nativeStr) continue; // already looks native
+          } catch {}
+          const _wrapper = function() { return _origMethod.apply(console, arguments); };
+          Object.defineProperty(_wrapper, 'length', { value: _origMethod.length || 0, configurable: true });
+          _disguise(_wrapper, _m);
+          try { console[_m] = _wrapper; } catch {}
+        }
+      } catch {}
+
+      // 10. window.outerWidth/outerHeight defense
+      //     When DevTools or CDP debugger is attached, Chrome may alter the
+      //     window dimensions. Anti-bot scripts compare outerWidth/innerWidth
+      //     and outerHeight/innerHeight — a significant difference indicates
+      //     DevTools is open. We freeze the relationship so the delta stays
+      //     consistent with a normal browser window.
+      //     Thresholds: width delta > 100px or height delta > 200px indicates
+      //     a docked DevTools panel. When triggered, we report outerWidth
+      //     equal to innerWidth (normal for maximised windows) and
+      //     outerHeight as innerHeight + the captured "normal" delta (capped
+      //     to a reasonable range), so the result is plausible across OSes.
+      try {
+        const _normalWidthDelta = window.outerWidth - window.innerWidth;
+        const _normalHeightDelta = window.outerHeight - window.innerHeight;
+        // Only patch if the delta looks suspicious (e.g. DevTools docked)
+        if (_normalWidthDelta > 100 || _normalHeightDelta > 200) {
+          Object.defineProperty(window, 'outerWidth', {
+            get: () => window.innerWidth,
+            configurable: true,
+          });
+          // Use a clamped height offset (40-120px covers macOS ~78px,
+          // Windows ~40px, and Linux ~37-50px title bar heights).
+          const _heightOffset = Math.max(40, Math.min(120, _normalHeightDelta));
+          Object.defineProperty(window, 'outerHeight', {
+            get: () => window.innerHeight + _heightOffset,
+            configurable: true,
+          });
+        }
+      } catch {}
+
+      // 11. Performance API cleanup
+      //     CDP injects internal resources and timing entries that don't exist
+      //     in normal browsing. Filter entries with debugger/devtools URLs.
+      try {
+        const _origGetEntries = Performance.prototype.getEntries;
+        const _origGetByType = Performance.prototype.getEntriesByType;
+        const _origGetByName = Performance.prototype.getEntriesByName;
+        const _suspiciousPatterns = ['debugger', 'devtools', '__puppeteer', '__playwright', 'pptr:'];
+        const _filterEntries = (entries) => {
+          if (!Array.isArray(entries)) return entries;
+          return entries.filter(e => {
+            const name = e.name || '';
+            return !_suspiciousPatterns.some(p => name.includes(p));
+          });
+        };
+        Performance.prototype.getEntries = function() {
+          return _filterEntries(_origGetEntries.call(this));
+        };
+        Performance.prototype.getEntriesByType = function(type) {
+          return _filterEntries(_origGetByType.call(this, type));
+        };
+        Performance.prototype.getEntriesByName = function(name, type) {
+          return _filterEntries(_origGetByName.call(this, name, type));
+        };
+      } catch {}
+
+      // 12. WebDriver-related property defense
+      //     Some anti-bot systems check additional navigator properties
+      //     and document properties that may indicate automation.
+      try {
+        // document.$cdc_ properties (ChromeDriver specific, backup for #6)
+        for (const _prop of Object.getOwnPropertyNames(document)) {
+          if (_prop.startsWith('$cdc_') || _prop.startsWith('$chrome_')) {
+            try { delete document[_prop]; } catch {}
+          }
+        }
+      } catch {}
+
+      // 13. Iframe contentWindow.chrome consistency
+      //     Anti-bot scripts create iframes and check if
+      //     iframe.contentWindow.chrome exists and matches the parent.
+      //     CDP-controlled pages may have inconsistent iframe contexts.
+      try {
+        const _origHTMLIFrame = HTMLIFrameElement.prototype;
+        const _origContentWindow = Object.getOwnPropertyDescriptor(_origHTMLIFrame, 'contentWindow');
+        if (_origContentWindow && _origContentWindow.get) {
+          Object.defineProperty(_origHTMLIFrame, 'contentWindow', {
+            get: function() {
+              const _w = _origContentWindow.get.call(this);
+              if (_w) {
+                try {
+                  if (!_w.chrome) {
+                    Object.defineProperty(_w, 'chrome', {
+                      value: window.chrome,
+                      writable: true,
+                      configurable: true,
+                    });
+                  }
+                } catch {}
+              }
+              return _w;
+            },
+            configurable: true,
+          });
+        }
+      } catch {}
+
+      // 14. beforeunload neutralization (x.com "Leave site?" dialog hardening)
+      //     x.com registers an onbeforeunload handler once the composer has
+      //     staged unsaved state (uploaded media, typed text). Under CDP /
+      //     extension automation there is no user to dismiss the resulting
+      //     "Leave site?" dialog, and the CLI side cannot intercept the raw
+      //     CDP Page.javascriptDialogOpening event (the daemon owns the CDP
+      //     session), so the dialog wedges the tab: every subsequent
+      //     navigate/exec aborts with "This operation was aborted" until a
+      //     human manually clicks "Stay". This repeatedly broke twitter
+      //     post/reply on the image->text transition and poisoned later reads.
+      //     Defense (shared BEFOREUNLOAD_NEUTRALIZE): swallow already-armed
+      //     handlers in the capture phase, drop future addEventListener
+      //     registrations at the source, and no-op the onbeforeunload setter —
+      //     so no dialog can ever open. Injected on every navigation, covering
+      //     post, reply, and reads uniformly; page.goto() also runs the same
+      //     snippet before navigating away to cover the current document.
+      ${k}
+
+      return 'applied';
+    })()
+  `}

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

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

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

@@ -0,0 +1,13 @@
+/**
+ * Browser tab management helpers: extract, diff, and cleanup tab state.
+ */
+export declare function extractTabEntries(raw: unknown): Array<{
+    index: number;
+    identity: string;
+}>;
+export declare function extractTabIdentities(raw: unknown): string[];
+export declare function diffTabIndexes(initialIdentities: string[], currentTabs: Array<{
+    index: number;
+    identity: string;
+}>): number[];
+export declare function appendLimited(current: string, chunk: string, limit: number): string;

package/dist/src/browser/tabs.js

@@ -0,0 +1,2 @@
+export function extractTabEntries(q){if(Array.isArray(q))return q.map((j,p)=>({index:p,identity:[j?.id??"",j?.url??"",j?.title??"",j?.name??""].join("|")}));if(typeof q==="string")return q.split(`
+`).map((j)=>j.trim()).filter(Boolean).map((j)=>{const p=j.match(/^-\s+(\d+):\s*(.*)$/);if(p)return{index:parseInt(p[1],10),identity:p[2].trim()||`tab-${p[1]}`};const v=j.match(/Tab\s+(\d+)\s*(.*)$/);if(v)return{index:parseInt(v[1],10),identity:v[2].trim()||`tab-${v[1]}`};return null}).filter((j)=>j!==null);return[]}export function extractTabIdentities(q){return extractTabEntries(q).map((j)=>j.identity)}export function diffTabIndexes(q,j){if(q.length===0||j.length===0)return[];const p=new Map;for(const z of q)p.set(z,(p.get(z)??0)+1);const v=[];for(const z of j){const A=p.get(z.identity)??0;if(A>0){p.set(z.identity,A-1);continue}v.push(z.index)}return v.sort((z,A)=>A-z)}export function appendLimited(q,j,p){const v=q+j;if(v.length<=p)return v;return v.slice(-p)}

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

@@ -0,0 +1,39 @@
+/**
+ * Structured error types for the target resolution system.
+ *
+ * Every browser action (click, type, select, get) that targets a DOM element
+ * goes through the unified resolver. When resolution fails, one of these
+ * structured errors is thrown so that AI agents and adapter authors get
+ * actionable diagnostics instead of a generic "Element not found".
+ *
+ * Numeric-ref codes (from snapshot indices):
+ *   - not_found: the ref no longer exists in the DOM
+ *   - stale_ref: the ref still exists but points to a different element
+ *
+ * CSS-selector codes (from `--selector <css>` entrypoints):
+ *   - invalid_selector:       selector syntax rejected by querySelectorAll
+ *   - selector_not_found:     0 matches
+ *   - 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' | 'not_checkable' | 'not_file_input';
+export interface TargetErrorInfo {
+    code: TargetErrorCode;
+    message: string;
+    hint: string;
+    candidates?: string[];
+    /** CSS-path match count, when the error was raised mid-resolution */
+    matches_n?: number;
+}
+export declare class TargetError extends Error {
+    readonly code: TargetErrorCode;
+    readonly hint: string;
+    readonly candidates?: string[];
+    readonly matches_n?: number;
+    constructor(info: TargetErrorInfo);
+    /** Serialize for structured output to AI agents */
+    toJSON(): TargetErrorInfo;
+}

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

@@ -0,0 +1 @@
+export class TargetError extends Error{code;hint;candidates;matches_n;constructor(b){super(b.message);this.name="TargetError";this.code=b.code;this.hint=b.hint;this.candidates=b.candidates;this.matches_n=b.matches_n}toJSON(){return{code:this.code,message:this.message,hint:this.hint,...this.candidates&&{candidates:this.candidates},...this.matches_n!==void 0&&{matches_n:this.matches_n}}}}

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

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

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

@@ -0,0 +1,158 @@
+/**
+ * Unified target resolver for browser actions.
+ *
+ * Resolution pipeline:
+ *
+ * 1. Input classification: all-digit → numeric ref path, otherwise → CSS path.
+ *    The CSS path passes the raw string to `querySelectorAll` and lets the
+ *    browser parser decide what's valid. No frontend regex whitelist — the
+ *    goal is that any selector accepted by `browser find --css` is accepted
+ *    by the same selector on `get/click/type/select`.
+ * 2. Ref path: cascading match levels (see below), using data-opencli-ref
+ *    plus the fingerprint map populated by snapshot + find.
+ * 3. CSS path: querySelectorAll + match-count policy (see ResolveOptions)
+ * 4. Structured errors:
+ *    - numeric: not_found / stale_ref
+ *    - CSS:     invalid_selector / selector_not_found / selector_ambiguous
+ *               / selector_nth_out_of_range
+ *
+ * All JS is generated as strings for page.evaluate() — runs in the browser.
+ *
+ * ── Cascading stale-ref (browser-use style) ──────────────────────────
+ * Strict equality on the fingerprint rejected too many live pages — SPA
+ * re-renders swap text / role while keeping id + testId. The resolver
+ * now walks three tiers before giving up:
+ *
+ *   1. EXACT        — tag + strong id (id or testId) agree, ≤1 soft mismatch
+ *   2. STABLE       — tag + strong id agree, soft signals drifted (aria-label,
+ *                     role, text) — agent gets a warning but the action
+ *                     proceeds so dynamic pages don't stall
+ *   3. REIDENTIFIED — original ref either missing from the DOM or fully
+ *                     mismatched, but the fingerprint uniquely identifies
+ *                     a single other live element via id / testId /
+ *                     aria-label. Re-tag that element with the old ref and
+ *                     surface match_level so the caller knows we swapped.
+ *
+ * Only when all three fail do we emit `stale_ref`. Every success envelope
+ * carries `match_level` so downstream CLIs can surface the weakest tier
+ * a caller actually traversed.
+ */
+export interface ResolveOptions {
+    /**
+     * When CSS matches multiple elements, pick the element at this 0-based
+     * index instead of raising `selector_ambiguous`. Raises
+     * `selector_nth_out_of_range` if `nth >= matches.length`.
+     */
+    nth?: number;
+    /**
+     * When CSS matches multiple elements, pick the first match instead of
+     * raising `selector_ambiguous`. Used by read commands (get text / value /
+     * attributes) to deliver a best-effort answer + matches_n in the envelope.
+     * Ignored when `nth` is also set (nth wins).
+     */
+    firstOnMulti?: boolean;
+}
+/** Tier the resolver traversed to land the target. Callers may surface this to agents. */
+export type TargetMatchLevel = 'exact' | 'stable' | 'reidentified';
+/**
+ * Generate JS that resolves a target to a single DOM element.
+ *
+ * Returns a JS expression that evaluates to:
+ *   { ok: true, matches_n, match_level }            — success (el stored in `__resolved`)
+ *   { ok: false, code, message, hint, candidates, matches_n? }  — structured error
+ *
+ * `match_level` is always set on success:
+ *   - CSS path → 'exact'
+ *   - numeric ref path → whichever tier matched ('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;
+}): string;
+/**
+ * Generate JS for type that uses the unified resolver.
+ */
+export declare function typeResolvedJs(text: string): string;
+export type FillResolvedResult = {
+    ok: true;
+    actual: string;
+    expected: string;
+    length: number;
+    mode: 'input' | 'textarea' | 'contenteditable';
+} | {
+    ok: false;
+    actual: string;
+    expected: string;
+    length: number;
+    mode: 'input' | 'textarea' | 'contenteditable';
+} | {
+    ok: false;
+    reason: string;
+    tag?: string;
+    type?: string;
+    role?: string;
+};
+/**
+ * Prepare the resolved element for native CDP Input.insertText.
+ *
+ * This preserves `browser type`'s existing "replace current text" semantics:
+ * focus the editable target, select its current contents, then let CDP insert
+ * real browser text input so rich editors can update their internal state.
+ */
+export declare function prepareNativeTypeResolvedJs(opts?: {
+    skipScroll?: boolean;
+    skipFocus?: boolean;
+}): string;
+/**
+ * Verify the exact value/text currently held by the resolved editable target.
+ * Assumes resolveTargetJs and prepareNativeTypeResolvedJs have already set
+ * `window.__resolved` to the normalized editable host.
+ */
+export declare function verifyFilledResolvedJs(expected: string): string;
+/**
+ * Generate JS for scrollTo that uses the unified resolver.
+ * Assumes resolveTargetJs has been called and __resolved is set.
+ */
+export declare function scrollResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
+/**
+ * Generate JS to get text content of resolved element.
+ */
+export declare function getTextResolvedJs(): string;
+/**
+ * Generate JS to get value of resolved input/textarea element.
+ */
+export declare function getValueResolvedJs(): string;
+/**
+ * Generate JS to get all attributes of resolved element.
+ */
+export declare function getAttributesResolvedJs(): string;
+/**
+ * Generate JS to select an option on a resolved <select> element.
+ */
+export declare function selectResolvedJs(option: string): string;
+/**
+ * Generate JS to check if resolved element is an autocomplete/combobox field.
+ */
+export declare function isAutocompleteResolvedJs(): string;