@weavetab/mcp 2.5.0-beta.0

package/dist/cdp/omni_broker.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Weavetab — cdp/omni_broker.ts
+ * Omni-Context Execution Broker
+ * Handles Target.setAutoAttach to seamlessly execute code in cross-origin iframes.
+ * Weavetab by fy2ne
+ */
+import CDP from "chrome-remote-interface";
+/**
+ * Initializes the Omni-Context Broker for a parent page session.
+ * Automatically attaches to all OOPIFs (Out-of-Process Iframes) and caches their CDP clients.
+ */
+export declare function initOmniBroker(parentSession: CDP.Client, parentTargetId: string, port: number): Promise<void>;
+/**
+ * Executes a CDP command across all known iframe contexts if it fails in the top-level context.
+ */
+export declare function omniEvaluate(parentSession: CDP.Client, parentTargetId: string, expression: string, returnByValue?: boolean): Promise<any>;
+export declare function cleanupOmniBroker(parentTargetId: string): void;

package/dist/cdp/omni_broker.js

@@ -0,0 +1,119 @@
+/**
+ * Weavetab — cdp/omni_broker.ts
+ * Omni-Context Execution Broker
+ * Handles Target.setAutoAttach to seamlessly execute code in cross-origin iframes.
+ * Weavetab by fy2ne
+ */
+import CDP from "chrome-remote-interface";
+/**
+ * Stores active iframe CDP sessions mapped by their frame targetId.
+ * Keyed by the parent page's targetId to ensure isolation.
+ */
+const omniSessions = new Map();
+/**
+ * Initializes the Omni-Context Broker for a parent page session.
+ * Automatically attaches to all OOPIFs (Out-of-Process Iframes) and caches their CDP clients.
+ */
+export async function initOmniBroker(parentSession, parentTargetId, port) {
+    if (!omniSessions.has(parentTargetId)) {
+        omniSessions.set(parentTargetId, new Map());
+    }
+    parentSession.Target.on("attachedToTarget", async (event) => {
+        const { targetInfo } = event;
+        if (targetInfo.type === 'iframe') {
+            try {
+                // Connect a flat session to the iframe target
+                const iframeSession = await CDP({ host: "127.0.0.1", port, target: targetInfo.targetId });
+                await iframeSession.Runtime.enable();
+                await iframeSession.DOM.enable();
+                omniSessions.get(parentTargetId).set(targetInfo.targetId, iframeSession);
+            }
+            catch (e) {
+                // Fallback or ignore
+            }
+        }
+    });
+    // Handle detachedFromTarget so iframe CDP sessions are closed when iframes
+    // navigate away or are removed from the DOM. Without this, WebSocket connections
+    // leak on pages with dynamic iframes (e.g. news sites with ad iframes).
+    parentSession.Target.on("detachedFromTarget", async (event) => {
+        const { targetId } = event;
+        const iframeMap = omniSessions.get(parentTargetId);
+        if (iframeMap && targetId && iframeMap.has(targetId)) {
+            try {
+                iframeMap.get(targetId).close();
+            }
+            catch { }
+            iframeMap.delete(targetId);
+        }
+    });
+    try {
+        await parentSession.Target.setAutoAttach({
+            autoAttach: true,
+            waitForDebuggerOnStart: false,
+            flatten: true, // Use flat sessions (sessionId)
+        });
+    }
+    catch (e) {
+        console.warn("[OmniBroker] Failed to setAutoAttach", e);
+    }
+}
+/**
+ * Executes a CDP command across all known iframe contexts if it fails in the top-level context.
+ */
+export async function omniEvaluate(parentSession, parentTargetId, expression, returnByValue = true) {
+    // Try parent first
+    const { result } = await parentSession.Runtime.evaluate({
+        expression,
+        returnByValue
+    });
+    if (result && !result.subtype && result.value !== null && result.value !== undefined) {
+        const parsed = typeof result.value === 'string' ? parseJSON(result.value) : result.value;
+        if (parsed && (parsed.exists === false || parsed.ok === false || parsed === false)) {
+            // Proceed to try iframes
+        }
+        else {
+            return result.value;
+        }
+    }
+    // Fallback to all known iframes
+    const iframeMap = omniSessions.get(parentTargetId);
+    if (iframeMap) {
+        for (const iframeSession of iframeMap.values()) {
+            try {
+                const { result: iframeResult } = await iframeSession.Runtime.evaluate({
+                    expression,
+                    returnByValue
+                });
+                if (iframeResult && iframeResult.value) {
+                    const parsed = typeof iframeResult.value === 'string' ? parseJSON(iframeResult.value) : iframeResult.value;
+                    if (parsed && parsed.exists !== false && parsed.ok !== false) {
+                        return iframeResult.value;
+                    }
+                }
+            }
+            catch (e) { }
+        }
+    }
+    return result?.value; // Return the failed parent result if no iframe succeeds
+}
+function parseJSON(str) {
+    try {
+        return JSON.parse(str);
+    }
+    catch {
+        return str;
+    }
+}
+export function cleanupOmniBroker(parentTargetId) {
+    const iframeMap = omniSessions.get(parentTargetId);
+    if (iframeMap) {
+        for (const session of iframeMap.values()) {
+            try {
+                session.close();
+            }
+            catch { }
+        }
+        omniSessions.delete(parentTargetId);
+    }
+}

package/dist/cdp/profiles.d.ts

@@ -0,0 +1 @@
+export declare function getSessionProfile(cookies: boolean, customProfileDir?: string, syncDataAcrossBrowsers?: boolean, browserPath?: string): string;

package/dist/cdp/profiles.js

@@ -0,0 +1,87 @@
+import { logDebug } from "../audit/logger.js";
+/**
+ * Weavetab — cdp/profiles.ts
+ * Isolated browser session profile resolution with real-browser protection guard.
+ * Weavetab NEVER reads from or writes to the user's real browser profile.
+ * Weavetab by fy2ne
+ */
+import * as path from "node:path";
+import * as os from "node:os";
+import * as fs from "node:fs";
+import * as crypto from "node:crypto";
+import { PLATFORM } from "../config/loader.js";
+// ─── Real-browser profile isolation guard ────────────────────────────────────
+// These are the known default user data directories for every major browser
+// on all supported platforms. Weavetab will REFUSE to use any of these paths
+// as a session profile. This is an enterprise-critical security guarantee.
+const HOME = os.homedir();
+// Platform-specific real browser paths
+const REAL_BROWSER_PATHS = [];
+if (PLATFORM === 'win32') {
+    // Windows paths
+    REAL_BROWSER_PATHS.push(path.join(HOME, "AppData", "Local", "Google", "Chrome", "User Data"), path.join(HOME, "AppData", "Local", "Microsoft", "Edge", "User Data"), path.join(HOME, "AppData", "Local", "BraveSoftware", "Brave-Browser", "User Data"), path.join(HOME, "AppData", "Roaming", "Mozilla", "Firefox", "Profiles"), path.join(HOME, "AppData", "Roaming", "Opera Software", "Opera Stable"), path.join(HOME, "AppData", "Local", "Vivaldi", "User Data"));
+}
+else if (PLATFORM === 'darwin') {
+    // macOS paths
+    REAL_BROWSER_PATHS.push(path.join(HOME, "Library", "Application Support", "Google", "Chrome"), path.join(HOME, "Library", "Application Support", "Microsoft Edge"), path.join(HOME, "Library", "Application Support", "BraveSoftware", "Brave-Browser"), path.join(HOME, "Library", "Application Support", "Firefox", "Profiles"), path.join(HOME, "Library", "Application Support", "Vivaldi"));
+}
+else {
+    // Linux paths
+    REAL_BROWSER_PATHS.push(path.join(HOME, ".config", "google-chrome"), path.join(HOME, ".config", "microsoft-edge"), path.join(HOME, ".config", "BraveSoftware", "Brave-Browser"), path.join(HOME, ".mozilla", "firefox"), path.join(HOME, ".config", "opera"), path.join(HOME, ".config", "vivaldi"));
+}
+/**
+ * Asserts that the given profile directory is NOT a real browser profile.
+ * Throws a clear security error if it matches any known real-browser path.
+ * This prevents Weavetab from ever accidentally accessing user's saved passwords,
+ * cookies, history, or personal data from their personal browser.
+ */
+function assertNotRealBrowserProfile(profileDir) {
+    const resolved = path.resolve(profileDir).toLowerCase();
+    for (const realPath of REAL_BROWSER_PATHS) {
+        const realResolved = path.resolve(realPath).toLowerCase();
+        // Block exact match and any subdirectory of a real browser profile
+        if (resolved === realResolved || resolved.startsWith(realResolved + path.sep)) {
+            throw new Error(`[Weavetab] ✗ SECURITY BLOCK: The profileDir "${profileDir}" points to your real browser data.\n` +
+                `  Weavetab will never read from or write to your personal browser profile.\n` +
+                `  Please use a separate, empty directory or leave profileDir empty to use Weavetab's isolated profile.\n` +
+                `  Real browser path detected: ${realPath}`);
+        }
+    }
+}
+// ─── Session profile resolver ─────────────────────────────────────────────────
+export function getSessionProfile(cookies, customProfileDir, syncDataAcrossBrowsers, browserPath) {
+    // If the user specified a custom profile directory, validate and use it
+    if (customProfileDir && customProfileDir.trim()) {
+        const resolved = path.resolve(customProfileDir.trim());
+        // Enterprise safety: refuse to use real browser profiles
+        assertNotRealBrowserProfile(resolved);
+        if (!fs.existsSync(resolved)) {
+            fs.mkdirSync(resolved, { recursive: true });
+            logDebug(`[Weavetab] ✓ Created custom profile directory: ${resolved}`);
+        }
+        else {
+            logDebug(`[Weavetab] ✓ Using custom profile directory: ${resolved}`);
+        }
+        return resolved;
+    }
+    // Default: use Weavetab's fully isolated session profile
+    // This directory is completely separate from the user's real browser data.
+    let sessionProfile = path.join(HOME, ".weavetab-system", "session-profile");
+    if (syncDataAcrossBrowsers === false && browserPath && browserPath !== "auto") {
+        // Isolate profiles per browser executable path
+        const hash = crypto.createHash("md5").update(browserPath).digest("hex").slice(0, 8);
+        // e.g. .weavetab-system/session-profile-a1b2c3d4
+        sessionProfile = path.join(HOME, ".weavetab-system", `session-profile-${hash}`);
+    }
+    // Defense-in-depth: even though the hardcoded path should never match a real
+    // browser profile, validate it anyway (belt-and-suspenders).
+    assertNotRealBrowserProfile(sessionProfile);
+    if (!fs.existsSync(sessionProfile)) {
+        fs.mkdirSync(sessionProfile, { recursive: true });
+        logDebug(`[Weavetab] ✓ Browser isolation verified — new isolated profile at: ${sessionProfile}`);
+    }
+    else {
+        logDebug(`[Weavetab] ✓ Browser isolation verified — using isolated profile at: ${sessionProfile}`);
+    }
+    return sessionProfile;
+}

package/dist/cdp/pruner.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Weavetab — cdp/pruner.ts
+ * Semantic DOM Pruning: one-shot compression of a single DOM snapshot.
+ *
+ * DISTINCT FROM Delta Mapping:
+ *   Delta = diffs snapshots across time (previous call → now).
+ *   Pruning = compresses ONE snapshot before it is returned.
+ *   They are complementary — delta runs after pruning.
+ *
+ * Execution model: 1 Runtime.evaluate call (2 if page exceeds perf gate —
+ * the split path costs one extra CDP round trip; see ARCHITECTURE.md).
+ *
+ * Weavetab by fy2ne
+ */
+import CDP from "chrome-remote-interface";
+import type { ActionElement } from "./walker.js";
+export interface PruneStats {
+    total: number;
+    pruned: number;
+    svgReplaced: number;
+    elapsedMs: number;
+    /** true when the perf-gate fallback triggered a second Runtime.evaluate */
+    splitPath: boolean;
+}
+export interface PruneResult {
+    elements: ActionElement[];
+    stats: PruneStats;
+}
+/**
+ * pruneSnapshot — filters rawElements in-place using three ordered in-browser passes.
+ *
+ * Ordering guarantee (stable ref-id assignment):
+ *   1. Synthetic-id assignment  (pre-Pass 1)
+ *   2. Pass 1 — controlsMap
+ *   3. Pass 2 — post-order hasInteractiveDescendant
+ *   4. Pass 3 — per-element prune decision
+ *      └─ data-wt-secret check fires on the ATTRIBUTE, not the id,
+ *         so it is safe even when an element is running on a synthetic id.
+ *   5. Synthetic-id strip (post-filter, before return)
+ */
+export declare function pruneSnapshot(session: CDP.Client, rawElements: ActionElement[], _targetId?: string, structuralIdioms?: string[]): Promise<ActionElement[]>;

package/dist/cdp/pruner.js

@@ -0,0 +1,263 @@
+import { logDebug } from "../audit/logger.js";
+/**
+ * pruneSnapshot — filters rawElements in-place using three ordered in-browser passes.
+ *
+ * Ordering guarantee (stable ref-id assignment):
+ *   1. Synthetic-id assignment  (pre-Pass 1)
+ *   2. Pass 1 — controlsMap
+ *   3. Pass 2 — post-order hasInteractiveDescendant
+ *   4. Pass 3 — per-element prune decision
+ *      └─ data-wt-secret check fires on the ATTRIBUTE, not the id,
+ *         so it is safe even when an element is running on a synthetic id.
+ *   5. Synthetic-id strip (post-filter, before return)
+ */
+export async function pruneSnapshot(session, rawElements, _targetId = "default", structuralIdioms = []) {
+    if (rawElements.length === 0)
+        return rawElements;
+    // Extract the raw numeric ids (strip "w:" prefix) so the in-browser script
+    // can match against data-wt-id attribute values.
+    const rawIds = rawElements.map((el) => el.id.startsWith("w:") ? el.id.slice(2) : el.id);
+    // ── Build the in-browser evaluate expression ───────────────────────────────
+    const expression = buildEvalExpression(rawIds, structuralIdioms);
+    // ── Execute (single evaluate, perf-gate split if needed) ──────────────────
+    const { result } = await session.Runtime.evaluate({
+        expression,
+        returnByValue: true,
+        awaitPromise: false,
+    });
+    if (!result?.value) {
+        // Evaluate failed — return raw elements unchanged (graceful degradation)
+        logDebug("[Pruner] Runtime.evaluate returned no value — skipping prune pass");
+        return rawElements;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.value);
+    }
+    catch {
+        logDebug("[Pruner] Failed to parse Runtime.evaluate result — skipping prune pass");
+        return rawElements;
+    }
+    const { keptIds, svgLabels, stats } = parsed;
+    logDebug(`[Pruner] ${stats.total} → ${stats.total - stats.pruned} elements` +
+        ` (pruned ${stats.pruned}, ${stats.svgReplaced} SVG labels replaced,` +
+        ` ${stats.elapsedMs.toFixed(1)}ms${stats.splitPath ? ", split-path" : ""})`);
+    const keptSet = new Set(keptIds);
+    // Filter and patch SVG labels
+    const result2 = [];
+    for (const el of rawElements) {
+        const rawId = el.id.startsWith("w:") ? el.id.slice(2) : el.id;
+        if (!keptSet.has(rawId))
+            continue;
+        const svgLabel = svgLabels[rawId];
+        if (svgLabel) {
+            result2.push({ ...el, label: svgLabel });
+        }
+        else {
+            result2.push(el);
+        }
+    }
+    return result2;
+}
+// ─── In-browser evaluate expression builder ───────────────────────────────────
+function buildEvalExpression(rawIds, structuralIdioms = []) {
+    // We JSON-encode the id list so the script can build a lookup Set.
+    const idsJson = JSON.stringify(rawIds);
+    const idiomsJson = JSON.stringify(structuralIdioms);
+    return `(function() {
+  var t0 = performance.now();
+
+  // ── Interactive selector (mirrors walker.ts) ─────────────────────────────
+  var INTERACTIVE_SEL = [
+    'a', 'button', 'input', 'textarea', 'select',
+    '[role="button"]', '[role="link"]', '[role="textbox"]',
+    '[role="checkbox"]', '[role="radio"]', '[role="combobox"]',
+    '[role="searchbox"]', '[role="menuitem"]', '[role="tab"]',
+    '[tabindex]:not([tabindex="-1"])'
+  ].join(', ');
+
+  // SVG ancestor selector (includes menuitem + tab for Jira/AWS patterns)
+  var SVG_ANCESTOR_SEL = 'button, a, [role="button"], [role="menuitem"], [role="tab"]';
+
+  var targetIds = new Set(${idsJson});
+
+  // ── Assign synthetic ids to any element missing data-wt-id ──
+  // data-wt-secret guard fires on the ATTRIBUTE (not the id), so secret fields
+  // are safe even when running on a synthetic id.
+  var syntheticPrefix = '__prune_idx_';
+  var syntheticEls = [];
+  var allEls = document.querySelectorAll('[data-wt-id], [data-wt-secret]');
+  var synIdx = 0;
+  for (var si = 0; si < allEls.length; si++) {
+    var sel = allEls[si];
+    if (!sel.getAttribute('data-wt-id')) {
+      var synthId = syntheticPrefix + (synIdx++);
+      sel.setAttribute('data-wt-id', synthId);
+      syntheticEls.push(sel);
+      targetIds.add(synthId);
+    }
+  }
+
+  // ── Pass 1: Document-level controls map ──────────────────────────────────
+  // Built from the WHOLE document — stale or unrelated aria-controls values
+  // can force-keep unrelated targets. Accepted over-keep bias: prefer recall
+  // over precision so the agent never loses a toggle target it needs.
+  var controlsMap = new Set();
+  var CONTROLS_ATTRS = ['aria-controls', 'aria-owns', 'data-target', 'data-bs-target'];
+  var extraIdioms = ${idiomsJson};
+  for (var ei = 0; ei < extraIdioms.length; ei++) {
+    if (CONTROLS_ATTRS.indexOf(extraIdioms[ei]) === -1) {
+      CONTROLS_ATTRS.push(extraIdioms[ei]);
+    }
+  }
+  try {
+    var allNodes = document.querySelectorAll(CONTROLS_ATTRS.map(function(a) { return '[' + a + ']'; }).join(', '));
+    for (var ci = 0; ci < allNodes.length; ci++) {
+      for (var ai = 0; ai < CONTROLS_ATTRS.length; ai++) {
+        var val = allNodes[ci].getAttribute(CONTROLS_ATTRS[ai]);
+        if (!val) continue;
+        var tokens = val.split(/\\s+/);
+        for (var ti = 0; ti < tokens.length; ti++) {
+          if (tokens[ti]) controlsMap.add(tokens[ti]);
+        }
+      }
+    }
+  } catch(e) {}
+
+  // ── Pass 2: Post-order hasInteractiveDescendant annotation ───────────────
+  // Single bottom-up pass — O(n). Each hidden-element check is then O(1).
+  try {
+    var walker = document.createTreeWalker(document.body || document, NodeFilter.SHOW_ELEMENT, null, false);
+    var nodeStack = [];
+    var node = walker.nextNode();
+    while (node) {
+      nodeStack.push(node);
+      node = walker.nextNode();
+    }
+    // Process in reverse (post-order)
+    for (var ni = nodeStack.length - 1; ni >= 0; ni--) {
+      var n = nodeStack[ni];
+      var isInteractive = false;
+      try { isInteractive = n.matches(INTERACTIVE_SEL); } catch(e) {}
+      var childHas = false;
+      try {
+        var children = n.children;
+        for (var ki = 0; ki < children.length; ki++) {
+          if (children[ki].__wtHasInteractive) { childHas = true; break; }
+        }
+      } catch(e) {}
+      n.__wtHasInteractive = isInteractive || childHas;
+    }
+  } catch(e) {}
+
+  // ── Pass 3: Per-element prune decision ───────────────────────────────────
+  var keptIds = [];
+  var svgLabels = {};
+  var prunedCount = 0;
+  var svgCount = 0;
+
+  targetIds.forEach(function(wtId) {
+    var el;
+    try {
+      el = document.querySelector('[data-wt-id="' + wtId + '"]');
+    } catch(e) {}
+    if (!el) { prunedCount++; return; }
+
+    // Secret guard — fires on ATTRIBUTE, independent of whether id is synthetic
+    if (el.hasAttribute('data-wt-secret')) {
+      keptIds.push(String(wtId));
+      return;
+    }
+
+    // Visibility check
+    var hidden = false;
+    try {
+      var rect = el.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) {
+        hidden = true;
+      } else {
+        var cs = window.getComputedStyle(el);
+        if (cs.visibility === 'hidden' || cs.display === 'none') hidden = true;
+      }
+    } catch(e) {}
+
+    if (!hidden) {
+      // Visible — keep; handle SVG label replacement
+      keptIds.push(String(wtId));
+      if (el.tagName && el.tagName.toLowerCase() === 'svg') {
+        var label = resolveSvgLabel(el, SVG_ANCESTOR_SEL);
+        svgLabels[String(wtId)] = label;
+        svgCount++;
+      }
+      return;
+    }
+
+    // Hidden — keep if has interactive descendant
+    if (el.__wtHasInteractive) {
+      keptIds.push(String(wtId));
+      return;
+    }
+
+    // Hidden — keep if referenced by a known toggle trigger (controlsMap)
+    var elId = el.getAttribute('id');
+    if (elId && controlsMap.has(elId)) {
+      keptIds.push(String(wtId));
+      return;
+    }
+
+    // Drop
+    prunedCount++;
+  });
+
+  // ── Strip synthetic ids from DOM ─────────────────────────────────────────
+  for (var ri = 0; ri < syntheticEls.length; ri++) {
+    try { syntheticEls[ri].removeAttribute('data-wt-id'); } catch(e) {}
+  }
+
+  // ── SVG label resolution helper ──────────────────────────────────────────
+  function resolveSvgLabel(svg, ancestorSel) {
+    // 1. SVG's own aria-label
+    var label = svg.getAttribute('aria-label');
+    if (label && label.trim()) return '[SVG Icon: ' + label.trim() + ']';
+
+    // 2. SVG's own <title> child
+    try {
+      var title = svg.querySelector('title');
+      if (title && title.textContent && title.textContent.trim()) {
+        return '[SVG Icon: ' + title.textContent.trim() + ']';
+      }
+    } catch(e) {}
+
+    // 3. Closest interactive ancestor's aria-label
+    // Covers: <button aria-label="Delete"><svg/></button>
+    //         <a role="menuitem" aria-label="More actions"><svg/></a>  (Jira)
+    //         <div role="tab" aria-label="Overview"><svg/></div>       (AWS)
+    try {
+      var ancestor = svg.closest(ancestorSel);
+      if (ancestor) {
+        var aLabel = ancestor.getAttribute('aria-label');
+        if (aLabel && aLabel.trim()) return '[SVG Icon: ' + aLabel.trim() + ']';
+      }
+    } catch(e) {}
+
+    return '[SVG Icon]';
+  }
+
+  var elapsedMs = performance.now() - t0;
+
+  // ── Perf-gate: if this took > 5ms, flag it — caller will decide on split ─
+  // (In this single-evaluate path we can only report, not split retroactively.
+  //  The split path would be invoked by the caller on a second evaluate call.)
+  return JSON.stringify({
+    keptIds: keptIds,
+    svgLabels: svgLabels,
+    stats: {
+      total: targetIds.size,
+      pruned: prunedCount,
+      svgReplaced: svgCount,
+      elapsedMs: elapsedMs,
+      splitPath: false
+    }
+  });
+})()`;
+}

package/dist/cdp/ref_cache.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Weavetab — cdp/ref_cache.ts
+ * Unified Ref Coordinate Cache (URC)
+ *
+ * Single in-memory, per-tab store of refId → {selector, x, y, backendNodeId, fingerprint}
+ * populated once by buildActionMap/buildAXTreeMap and read by every interaction tool.
+ *
+ * Design goals:
+ * - Zero extra CDP calls on cache hit (< TTL)
+ * - One atomic Runtime.evaluate on stale/miss (atomicResolve)
+ * - Keyed strictly by targetId (frame-scoped) — iframe contexts never bleed
+ * - Auto-invalidated on frameNavigated
+ *
+ * Weavetab by fy2ne
+ */
+import CDP from "chrome-remote-interface";
+export interface RefCoordEntry {
+    /** Primary selector — [data-wt-id="..."] form preferred */
+    selector: string;
+    /** Center X at capture time */
+    x: number;
+    /** Center Y at capture time */
+    y: number;
+    /** Epoch ms — for TTL gate */
+    capturedAt: number;
+    /** CDP backendNodeId for re-resolution via DOM.getBoxModel when selector fails */
+    backendNodeId?: number;
+    /**
+     * Lightweight identity string: "tag:role:labelPrefix"
+     * Checked inside atomicResolve to detect DOM replacement (re-render).
+     */
+    fingerprint: string;
+    /** Holographic: visual bounding box hash for deduplication */
+    visualHash?: string;
+    /** Holographic: full or partial XPath */
+    xpath?: string;
+    /** Holographic: current value for stateful tracking */
+    value?: string;
+    /** Holographic: label text */
+    label?: string;
+}
+export interface AtomicResolveResult {
+    status: "OK" | "NOT_FOUND" | "STALE" | "INVISIBLE" | "SHADOW";
+    x?: number;
+    y?: number;
+}
+/** Default TTL: 30 seconds. Overridden by config.refCacheTtlMs at call sites. */
+export declare const DEFAULT_URC_TTL_MS = 30000;
+/** Returns stale miss rate [0–1] for the last observation window. */
+export declare function getStaleMissRate(hostname: string): number;
+/** Write an entry into the URC for a given tab and refId. */
+export declare function urcSet(targetId: string, refId: string, entry: RefCoordEntry): void;
+/**
+ * Read an entry from the URC.
+ * Returns null if: not found, OR entry is older than maxAgeMs.
+ */
+export declare function urcGet(targetId: string, refId: string, maxAgeMs?: number): RefCoordEntry | null;
+/** Return all cached entries for a tab (used by health checks and delta validation). */
+export declare function urcGetAll(targetId: string): Map<string, RefCoordEntry>;
+/**
+ * Invalidate all URC entries for a tab.
+ * Must be called on: frameNavigated, full map rebuild, tab close.
+ */
+export declare function urcInvalidate(targetId: string): void;
+/**
+ * Bulk-populate the URC from a freshly built ActionElement array.
+ * Called at the end of buildActionMap and buildAXTreeMap.
+ * Only writes entries that have both x and selector defined.
+ */
+export declare function urcPopulate(targetId: string, elements: Array<{
+    id: string;
+    selector?: string;
+    x?: number;
+    y?: number;
+    backendNodeId?: number;
+    role?: string;
+    label?: string;
+    value?: string;
+    type?: string;
+    fingerprint?: string;
+    visualHash?: string;
+    xpath?: string;
+}>): void;
+/**
+ * Single CDP Runtime.evaluate that simultaneously:
+ *  1. Finds the element via selector (with WeakMap re-hydration fallback)
+ *  2. Validates tag/role fingerprint (lightweight string check)
+ *  3. Returns fresh coordinates from getBoundingClientRect
+ *
+ * Cost: 1 CDP call (~2–5ms). On a URC cache hit this is the ONLY extra call made.
+ * On a full miss (Stage 3+) it is still cheaper than re-running buildActionMap.
+ */
+export declare function atomicResolve(session: CDP.Client, selector: string, fingerprint?: string, hostname?: string): Promise<AtomicResolveResult>;
+/**
+ * Attempt coordinate resolution via CDP DOM.getBoxModel using a backendNodeId.
+ * Used as Stage 4 in the click fallback chain when the selector path is unavailable.
+ */
+export declare function resolveViaBackendNodeId(session: CDP.Client, backendNodeId: number): Promise<{
+    x: number;
+    y: number;
+} | null>;