publishport-opencli 1.0.0

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

@@ -0,0 +1,11 @@
+/**
+ * Tests for dom-snapshot.ts: DOM snapshot engine.
+ *
+ * Since the engine generates JavaScript strings for in-page evaluation,
+ * these tests validate:
+ * 1. The generated code is syntactically valid JS
+ * 2. Options are correctly embedded
+ * 3. The output structure matches expected format
+ * 4. All features are present (Shadow DOM, iframe, table, diff, etc.)
+ */
+export {};

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

@@ -0,0 +1,38 @@
+/**
+ * Browser connection error helpers.
+ *
+ * Simplified — no more token/extension/CDP classification.
+ * The daemon architecture has a single failure mode: daemon not reachable or extension not connected.
+ */
+import { BrowserConnectError, type BrowserConnectKind } from '../errors.js';
+/**
+ * Unified browser error classification.
+ *
+ * All transient error detection lives here — daemon-client, pipeline executor,
+ * and page retry logic all use this single system instead of maintaining
+ * separate pattern lists.
+ */
+/** Error category — determines which layer should retry. */
+export type BrowserErrorKind = 'extension-transient' | 'target-navigation' | 'non-retryable';
+/** How the caller should handle the error. */
+export interface RetryAdvice {
+    /** Error category — callers use this to decide whether *they* should retry. */
+    kind: BrowserErrorKind;
+    /** Whether the error is transient and worth retrying. */
+    retryable: boolean;
+    /** Suggested delay before retry (ms). */
+    delayMs: number;
+}
+/**
+ * Classify a browser error and return retry advice.
+ *
+ * Single source of truth for "is this error transient?" across all layers.
+ */
+export declare function classifyBrowserError(err: unknown): RetryAdvice;
+/**
+ * Check if an error is a transient browser error worth retrying.
+ * Convenience wrapper around classifyBrowserError().
+ */
+export declare function isTransientBrowserError(err: unknown): boolean;
+export type ConnectFailureKind = BrowserConnectKind;
+export declare function formatBrowserConnectError(kind: ConnectFailureKind, detail?: string): BrowserConnectError;

package/dist/src/browser/errors.js

@@ -0,0 +1,5 @@
+import{BrowserConnectError as z}from"../errors.js";import{DEFAULT_DAEMON_PORT as J}from"../constants.js";const K=["Extension disconnected","Extension not connected","attach failed","Detached while handling command","Debugger is not attached to the tab","no longer exists","No tab with id","CDP connection","Daemon command failed","No window with id"],Q=["Inspected target navigated or closed"];function W(q){return q instanceof Error?q.message:String(q)}export function classifyBrowserError(q){const x=W(q);if(K.some((H)=>x.includes(H)))return{kind:"extension-transient",retryable:!0,delayMs:1500};if(Q.some((H)=>x.includes(H)))return{kind:"target-navigation",retryable:!0,delayMs:200};if(x.includes("-32000")&&/target|context/i.test(x))return{kind:"target-navigation",retryable:!0,delayMs:200};return{kind:"non-retryable",retryable:!1,delayMs:0}}export function isTransientBrowserError(q){return classifyBrowserError(q).retryable}export function formatBrowserConnectError(q,x){switch(q){case"daemon-not-running":return new z("Cannot connect to opencli daemon."+(x?`
+
+${x}`:""),`Run \`opencli doctor\` to diagnose, or \`opencli daemon restart\` to force a fresh daemon. Default port is ${J}.`,q);case"extension-not-connected":return new z("Browser Bridge extension is not connected."+(x?`
+
+${x}`:""),"Install the extension from GitHub Releases, then reload.",q);case"command-failed":return new z(`Browser command failed: ${x??"unknown error"}`,void 0,q);default:return new z(x??"Failed to connect to browser",void 0,q)}}

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

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

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

@@ -0,0 +1,69 @@
+/**
+ * `browser extract` — agent-native article/content reading channel.
+ *
+ * Pipeline (from first principles — agents want the *content*, not the DOM):
+ *   1. Scope:    select `--selector` (default: document.body or <main>/<article>)
+ *   2. Denoise:  strip script/style/nav/header/footer/aside/iframe/svg/form, inline noise
+ *   3. Convert:  HTML → Markdown via shared `htmlToMarkdown` (turndown)
+ *   4. Chunk:    paragraph-boundary-aware slicing with `next_start_char` cursor
+ *
+ * Why a separate command:
+ * - `get html --as json` returns tree structure; useless for "read the article".
+ * - `get text` flattens everything; loses headings, lists, links.
+ * - Markdown is the agent-readable middle ground: structure preserved, noise gone.
+ *
+ * Continuation contract: the envelope always carries `start`, `end`,
+ * `total_chars`, and `next_start_char` (null when the last chunk was emitted).
+ * Agents pass `--start <next>` to continue. No session state required.
+ */
+/**
+ * Returns the JS expression string used with `page.evaluate` to produce the
+ * cleaned HTML subtree that we then hand to `htmlToMarkdown`. We do the
+ * denoise/clone inside the page so we can use DOM APIs (querySelectorAll,
+ * cloneNode) rather than regex on serialized HTML.
+ */
+export declare function buildExtractHtmlJs(selector: string | null): string;
+export interface ExtractChunkOptions {
+    content: string;
+    start: number;
+    chunkSize: number;
+}
+export interface ExtractChunkResult {
+    content: string;
+    start: number;
+    end: number;
+    nextStartChar: number | null;
+}
+/**
+ * Slice `content` into one chunk starting at `start` with target size
+ * `chunkSize`. When the chunk would land mid-paragraph, we pull the break
+ * back to the nearest `\n\n` (or `\n`) within a small window to keep the
+ * output readable. If no boundary is found, we hard-cut at `start+chunkSize`.
+ */
+export declare function chunkMarkdown(opts: ExtractChunkOptions): ExtractChunkResult;
+export interface RunExtractOptions {
+    html: string;
+    url: string;
+    title: string;
+    selector: string | null;
+    start: number;
+    chunkSize: number;
+}
+export interface RunExtractResult {
+    url: string;
+    title: string;
+    selector: string | null;
+    total_chars: number;
+    chunk_size: number;
+    start: number;
+    end: number;
+    next_start_char: number | null;
+    content: string;
+}
+/** End-to-end host-side pipeline: HTML → markdown → chunked envelope. */
+export declare function runExtractFromHtml(opts: RunExtractOptions): RunExtractResult;
+export declare const __extractInternals: {
+    DEFAULT_CHUNK_SIZE: number;
+    MIN_CHUNK_SIZE: number;
+    MAX_CHUNK_SIZE: number;
+};

package/dist/src/browser/extract.js

@@ -0,0 +1,42 @@
+import{htmlToMarkdown as Y}from"../utils.js";const V=20000,$=100,j=200000,F=0.15;export function buildExtractHtmlJs(f){return`(() => {
+  const sel = ${f?JSON.stringify(f):"null"};
+  let root = null;
+  if (sel) {
+    try { root = document.querySelector(sel); }
+    catch (e) {
+      return { invalidSelector: true, reason: (e && e.message) || String(e) };
+    }
+    if (!root) return { notFound: true };
+  } else {
+    root = document.querySelector('main') || document.querySelector('article') || document.body || document.documentElement;
+  }
+  if (!root) return { notFound: true };
+  const clone = root.cloneNode(true);
+  const drop = [
+    'script', 'style', 'noscript', 'template',
+    'nav', 'header', 'footer', 'aside',
+    'iframe', 'svg', 'canvas',
+    'form', 'button', 'input', 'select', 'textarea',
+    '[role="navigation"]', '[role="banner"]', '[role="contentinfo"]', '[role="complementary"]',
+    '[aria-hidden="true"]',
+  ];
+  for (const q of drop) {
+    for (const n of clone.querySelectorAll(q)) n.remove();
+  }
+  // Also strip event-handler and style attributes that bloat markdown output.
+  const walker = document.createTreeWalker(clone, NodeFilter.SHOW_ELEMENT);
+  let n = walker.currentNode;
+  while (n) {
+    if (n.nodeType === 1) {
+      const el = n;
+      for (const a of [...el.attributes]) {
+        if (a.name.startsWith('on') || a.name === 'style' || a.name.startsWith('data-')) el.removeAttribute(a.name);
+      }
+    }
+    n = walker.nextNode();
+  }
+  return { ok: true, url: location.href, title: document.title || '', html: clone.outerHTML || '' };
+})()`}export function chunkMarkdown(f){const{content:g,start:b}=f,G=Math.max($,Math.min(j,f.chunkSize));if(b>=g.length)return{content:"",start:b,end:b,nextStartChar:null};const q=Math.min(g.length,b+G);if(q===g.length)return{content:g.slice(b,q),start:b,end:q,nextStartChar:null};const v=Math.max(1,Math.floor(G*F)),y=Math.max(b+1,q-v),J=g.slice(y,q),P=J.lastIndexOf(`
+
+`);let x=q;if(P>=0)x=y+P+2;else{const Q=J.lastIndexOf(`
+`);if(Q>=0)x=y+Q+1}return{content:g.slice(b,x),start:b,end:x,nextStartChar:x}}export function runExtractFromHtml(f){const g=Y(f.html),b=chunkMarkdown({content:g,start:Math.max(0,f.start),chunkSize:f.chunkSize||V});return{url:f.url,title:f.title,selector:f.selector,total_chars:g.length,chunk_size:b.end-b.start,start:b.start,end:b.end,next_start_char:b.nextStartChar,content:b.content}}export const __extractInternals={DEFAULT_CHUNK_SIZE:V,MIN_CHUNK_SIZE:$,MAX_CHUNK_SIZE:j};

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

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

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

@@ -0,0 +1,84 @@
+/**
+ * `browser find --css <sel>` — structured CSS query.
+ *
+ * Returns every match of a selector as a JSON envelope agents can read
+ * without parsing free-text snapshot output. Each entry carries two
+ * identifiers — a numeric `ref` (matching the snapshot contract) and a
+ * stable 0-based `nth` — so the agent can act on a specific result via
+ * either path:
+ *
+ *   browser click <ref>              // when ref is numeric
+ *   browser click "<sel>" --nth <n>  // always works
+ *
+ * Refs are *allocated on the spot* for matched elements that were not
+ * tagged by a prior snapshot: `data-opencli-ref` is set on the element
+ * and a fingerprint is written into `window.__opencli_ref_identity`
+ * (same shape the snapshot uses). That makes `find` a first-class entry
+ * point to the ref system — agents can skip running `browser state`
+ * when they already know the selector.
+ *
+ * Attributes are whitelisted to keep output small and high-signal.
+ * Invisible elements are still returned so agents can reason about
+ * offscreen vs truly-missing targets.
+ *
+ * When a matched element is a compound form control (date-like input,
+ * select, file input), the entry gains a `compound` field with the
+ * rich view from `compound.ts`. This is what kills the three biggest
+ * agent-fail modes on form pages (wrong date format, guessed options,
+ * re-uploaded files) without forcing agents to probe further.
+ */
+import { type CompoundInfo } from './compound.js';
+/** Whitelist of attributes surfaced per entry. Keep small; agents do not need full DOM dumps. */
+export declare const FIND_ATTR_WHITELIST: readonly ["id", "class", "name", "type", "placeholder", "aria-label", "title", "href", "value", "role", "data-testid"];
+export interface FindEntry {
+    /** Zero-based position within the match set — pair with `--nth` on downstream commands. */
+    nth: number;
+    /**
+     * Numeric data-opencli-ref. Find assigns one if the element was not
+     * tagged by a prior snapshot, so downstream `browser click <ref>` works
+     * directly off the find output without requiring `browser state` first.
+     */
+    ref: number;
+    tag: string;
+    role: string;
+    text: string;
+    attrs: Record<string, string>;
+    visible: boolean;
+    /**
+     * Rich view for date / time / datetime-local / month / week / select /
+     * file inputs. Omitted (undefined) for all other element types. See
+     * `compound.ts` for the shape.
+     */
+    compound?: CompoundInfo;
+}
+export interface FindResult {
+    matches_n: number;
+    entries: FindEntry[];
+}
+export interface FindError {
+    error: {
+        code: 'invalid_selector' | 'selector_not_found' | 'semantic_not_found';
+        message: string;
+        hint?: string;
+    };
+}
+export interface FindOptions {
+    /** Max entries returned. Default 50 — enough to pick from without flooding context. */
+    limit?: number;
+    /** 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

@@ -0,0 +1,328 @@
+import{COMPOUND_INFO_JS as V}from"./compound.js";export const FIND_ATTR_WHITELIST=["id","class","name","type","placeholder","aria-label","title","href","value","role","data-testid"];export function buildFindJs(k,z={}){const G=JSON.stringify(k),K=z.limit??50,Q=z.textMax??120,X=JSON.stringify(FIND_ATTR_WHITELIST);return`
+    (() => {
+      const sel = ${G};
+      const LIMIT = ${K};
+      const TEXT_MAX = ${Q};
+      const ATTR_WHITELIST = ${X};
+
+      ${V}
+
+      let matches;
+      try {
+        matches = document.querySelectorAll(sel);
+      } catch (e) {
+        return {
+          error: {
+            code: 'invalid_selector',
+            message: 'Invalid CSS selector: ' + sel + ' (' + ((e && e.message) || String(e)) + ')',
+            hint: 'Check the selector syntax.',
+          },
+        };
+      }
+
+      if (matches.length === 0) {
+        return {
+          error: {
+            code: 'selector_not_found',
+            message: 'CSS selector ' + sel + ' matched 0 elements',
+            hint: 'Use browser state to inspect the page, or try a less specific selector.',
+          },
+        };
+      }
+
+      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;
+      }
+
+      // Ref allocation: reuse \`window.__opencli_ref_identity\` (the same map
+      // snapshot populates) as the source of truth. For matched elements that
+      // don't already carry a \`data-opencli-ref\`, assign the next free numeric
+      // ref and write the fingerprint so the target resolver can verify it on
+      // downstream click/type/get calls.
+      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;
+      }
+      // Also walk any \`data-opencli-ref\` already in the DOM in case the identity
+      // map was cleared but annotations remain (e.g. soft navigation without a
+      // fresh snapshot). Guarantees allocated refs don't collide.
+      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 (_) {}
+
+      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') || '',
+        };
+      }
+
+      const take = Math.min(matches.length, LIMIT);
+      const entries = [];
+      for (let i = 0; i < take; i++) {
+        const el = matches[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]) {
+          // Ref annotation survived but identity map was cleared — repopulate so the
+          // target resolver's fingerprint check passes on downstream calls.
+          identity['' + refNum] = fingerprintOf(el);
+        }
+        const text = (el.textContent || '').trim();
+        const entry = {
+          nth: i,
+          ref: refNum,
+          tag: el.tagName.toLowerCase(),
+          role: el.getAttribute('role') || '',
+          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: matches.length,
+        entries,
+      };
+    })()
+  `}export function buildSemanticFindJs(k){const z=JSON.stringify({role:k.role??"",name:k.name??"",label:k.label??"",text:k.text??"",testid:k.testid??""}),G=k.limit??50,K=k.textMax??120,Q=JSON.stringify(FIND_ATTR_WHITELIST);return`
+    (() => {
+      const CRITERIA = ${z};
+      const LIMIT = ${G};
+      const TEXT_MAX = ${K};
+      const ATTR_WHITELIST = ${Q};
+
+      ${V}
+
+      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(k){return!!k&&typeof k==="object"&&"error"in k}

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

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

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

@@ -0,0 +1,44 @@
+/**
+ * [pp-only] 每环境指纹：确定性解析 + 注入 JS 生成。
+ *
+ * 设计取舍（与产品「真实指纹 = 反风控根基」哲学对齐）：
+ *  - 默认不伪造 UA / platform。伪造的 UA 主版本一旦与真实 Chrome 对不上，
+ *    就是比「不伪造」更强的自动化信号；真实 UA 通常已经足够干净。
+ *  - 只改写「跨账号去关联」真正相关、且不易穿帮的软信号：Canvas/WebGL 读像素
+ *    噪声、WebGL vendor/renderer、hardwareConcurrency、deviceMemory、屏幕分辨率。
+ *  - 时区 / 语言跟随代理出口 geo（一致性卫生，不是伪造）。
+ *  - 全部由 seed 一次性确定，跨启动稳定——指纹漂移本身就是红旗。
+ */
+import type { FingerprintConfig } from './profile.js';
+export type ResolveFingerprintOpts = {
+    timezone?: string;
+    locale?: string;
+    userAgent?: string;
+    platform?: string;
+    /** 显式软信号（对话框里逐项可调 / 预设填充）——优先于随机生成 */
+    hardwareConcurrency?: number;
+    deviceMemory?: number;
+    screen?: {
+        width: number;
+        height: number;
+    };
+    webglVendor?: string;
+    webglRenderer?: string;
+    canvasNoise?: boolean;
+    /** true = 软信号里没显式给的项用 seed 随机补全；false = 只用显式给的项 */
+    spoof?: boolean;
+};
+/**
+ * 用 seed 把一套指纹解析成确定值。显式传入的字段永远优先；只有 spoof=true 时，
+ * 没显式给的软信号才用 seed 随机补全（保证多环境不撞成同一套 = 反而成特征）。
+ * 同一 seed + 同一 opts → 同一结果，存盘后每次启动稳定。
+ */
+export declare function resolveFingerprint(seed: number, opts?: ResolveFingerprintOpts): FingerprintConfig;
+/** 随机 32 位种子（仅用于创建那一刻确定一套指纹）。 */
+export declare function randomSeed(): number;
+/**
+ * 生成注入页面（MAIN world / document_start）的指纹改写 JS 字符串。
+ * 幂等：靠 EventTarget 原型上的隐藏 flag 防重复注入。
+ * 所有改写都被 try/catch 包住，任何一项失败都不影响其余项。
+ */
+export declare function generateFingerprintJs(fp: FingerprintConfig): string;