@fusengine/browser-mcp 0.1.14 → 0.1.15

package/README.md

@@ -78,6 +78,10 @@ Install the binaries once: `npm i -g @fusengine/browser-mcp` (provides `fuse-bro
 # One-shot probe of a real page
 fuse-browser probe https://example.com --extract-prices --observe-visual
 
+# HTTP fast-path — browser TLS impersonation, NO browser launch (~10x faster)
+# For server-rendered HTML (price lists, indexes). Falls back to probe for JS/SPA.
+fuse-browser fetch https://books.toscrape.com/ --extract-prices --proxy http://user:pass@host:port
+
 # Hotels with country identity, proxy routing, replay
 fuse-browser probe 'https://www.booking.com/searchresults.html?ss=Tokyo' \
   --country JP --proxy-map proxies.json --replay --auto-consent --extract-prices
@@ -146,7 +150,10 @@ Key agentic patterns:
 
 - **`browser_snapshot` → `browser_act`** — snapshot tags each interactive element with a
   stable `ref`; act on a `ref` deterministically (or by text fallback). `browser_act`
-  returns a **diff** of what changed (added/removed/text/url).
+  returns a **diff** of what changed (added/removed/text/url). The walk **pierces open
+  Shadow DOM and traverses iframes** (same- and cross-origin): elements inside a sub-frame
+  get a frame-scoped ref like `"3:4"`, so web-components, consent frames and embedded
+  checkouts are visible and actionable.
 - **`browser_wait_for`** — wait on a condition (`text` / `selector` / `gone` / `urlContains`),
   not a fixed delay.
 - **`browser_run`** — execute an ordered plan (navigate/act/wait/extract) in one call,

package/dist/actions/act-by-ref.d.ts

@@ -8,6 +8,6 @@ import type { Page } from "playwright";
 import type { ActionResult } from "../interfaces/types.js";
 /** Action kinds that can target a snapshot ref. */
 export type RefActionKind = "click" | "fill" | "select" | "pick";
-/** Run `kind` on the element carrying `data-fuse-ref="ref"`. */
-export declare function actByRef(page: Page, ref: number, kind: RefActionKind, value?: string, option?: string): Promise<ActionResult>;
+/** Run `kind` on the element carrying the frame-scoped `ref`. */
+export declare function actByRef(page: Page, ref: string | number, kind: RefActionKind, value?: string, option?: string): Promise<ActionResult>;
 //# sourceMappingURL=act-by-ref.d.ts.map

package/dist/actions/act-by-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act-by-ref.d.ts","sourceRoot":"","sources":["../../src/actions/act-by-ref.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI3D,mDAAmD;AACnD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjE,gEAAgE;AAChE,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,EACnB,KAAK,SAAK,EACV,MAAM,SAAK,GACV,OAAO,CAAC,YAAY,CAAC,CAmBvB"}
+{"version":3,"file":"act-by-ref.d.ts","sourceRoot":"","sources":["../../src/actions/act-by-ref.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI3D,mDAAmD;AACnD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjE,iEAAiE;AACjE,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,IAAI,EAAE,aAAa,EACnB,KAAK,SAAK,EACV,MAAM,SAAK,GACV,OAAO,CAAC,YAAY,CAAC,CAkBvB"}

package/dist/actions/act-by-ref.js

@@ -1,11 +1,10 @@
-import { REF_ATTRIBUTE } from "../extraction/snapshot.js";
 import { pickAutocomplete } from "./autocomplete.js";
-/** Run `kind` on the element carrying `data-fuse-ref="ref"`. */
+import { refLocator } from "./ref-locator.js";
+/** Run `kind` on the element carrying the frame-scoped `ref`. */
 export async function actByRef(page, ref, kind, value = "", option = "") {
-    const selector = `[${REF_ATTRIBUTE}="${ref}"]`;
-    const locator = page.locator(selector).first();
+    const locator = refLocator(page, ref);
     try {
-        if ((await locator.count()) === 0) {
+        if (!locator || (await locator.count()) === 0) {
             return { type: kind, ok: false, ref, error: "ref_not_found" };
         }
         if (kind === "pick")

package/dist/actions/act-by-ref.js.map

@@ -1 +1 @@
-{"version":3,"file":"act-by-ref.js","sourceRoot":"","sources":["../../src/actions/act-by-ref.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAKrD,gEAAgE;AAChE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAU,EACV,GAAW,EACX,IAAmB,EACnB,KAAK,GAAG,EAAE,EACV,MAAM,GAAG,EAAE;IAEX,MAAM,QAAQ,GAAG,IAAI,aAAa,KAAK,GAAG,IAAI,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,CAAC;IAC/C,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;QAChE,CAAC;QACD,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,EAAE,GAAG,CAAC,MAAM,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;QAC/F,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrB,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1C,CAAC;aAAM,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACxD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IACtF,CAAC;AACH,CAAC"}
+{"version":3,"file":"act-by-ref.js","sourceRoot":"","sources":["../../src/actions/act-by-ref.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAK9C,iEAAiE;AACjE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAU,EACV,GAAoB,EACpB,IAAmB,EACnB,KAAK,GAAG,EAAE,EACV,MAAM,GAAG,EAAE;IAEX,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACtC,IAAI,CAAC;QACH,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;QAChE,CAAC;QACD,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,EAAE,GAAG,CAAC,MAAM,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;QAC/F,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrB,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1C,CAAC;aAAM,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACxD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IACtF,CAAC;AACH,CAAC"}

package/dist/actions/ref-locator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolve a snapshot `ref` to a Playwright locator, honoring the frame-scoped
+ * ref scheme produced by {@link captureSnapshot}: `"<frame>:<local>"` targets
+ * `page.frames()[frame]`, a bare `"<local>"` targets the main frame.
+ * @module actions/ref-locator
+ */
+import type { Locator, Page } from "playwright";
+/** A ref split into its frame ordinal and frame-local index. */
+export interface ParsedRef {
+    frame: number;
+    local: string;
+}
+/** Parse a ref string/number into `{ frame, local }` (bare value → main frame). */
+export declare function parseRef(ref: string | number): ParsedRef;
+/** Locator for `ref`, scoped to its owning frame; `null` if the frame is gone. */
+export declare function refLocator(page: Page, ref: string | number): Locator | null;
+//# sourceMappingURL=ref-locator.d.ts.map

package/dist/actions/ref-locator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-locator.d.ts","sourceRoot":"","sources":["../../src/actions/ref-locator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGhD,gEAAgE;AAChE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKxD;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAK3E"}

package/dist/actions/ref-locator.js

@@ -0,0 +1,18 @@
+import { REF_ATTRIBUTE } from "../extraction/snapshot.js";
+/** Parse a ref string/number into `{ frame, local }` (bare value → main frame). */
+export function parseRef(ref) {
+    const s = String(ref);
+    const sep = s.indexOf(":");
+    if (sep === -1)
+        return { frame: 0, local: s };
+    return { frame: Number(s.slice(0, sep)), local: s.slice(sep + 1) };
+}
+/** Locator for `ref`, scoped to its owning frame; `null` if the frame is gone. */
+export function refLocator(page, ref) {
+    const { frame, local } = parseRef(ref);
+    const target = page.frames()[frame];
+    if (!target)
+        return null;
+    return target.locator(`[${REF_ATTRIBUTE}="${local}"]`).first();
+}
+//# sourceMappingURL=ref-locator.js.map

package/dist/actions/ref-locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-locator.js","sourceRoot":"","sources":["../../src/actions/ref-locator.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAQ1D,mFAAmF;AACnF,MAAM,UAAU,QAAQ,CAAC,GAAoB;IAC3C,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC;AACrE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,UAAU,CAAC,IAAU,EAAE,GAAoB;IACzD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,aAAa,KAAK,KAAK,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;AACjE,CAAC"}

package/dist/extraction/snapshot-walk.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Browser-side snapshot walk: collects interactive elements, piercing OPEN
+ * Shadow DOM recursively. Iframes are NOT descended here — each frame is walked
+ * separately on the Node side via {@link captureSnapshot} (cross-origin frames
+ * are unreadable from the parent context, and same-origin ones would duplicate).
+ * Closed shadow roots are inaccessible by browser SOP and stay opaque.
+ * @module extraction/snapshot-walk
+ */
+/** Attribute injected on each interactive element to anchor a stable ref. */
+export declare const REF_ATTRIBUTE = "data-fuse-ref";
+/**
+ * Arrow-function source (run via `evalScript` in each frame). Stamps a LOCAL
+ * `data-fuse-ref` (per-frame index) and returns elements in visitation order;
+ * the Node side rewrites `index` to a global counter and adds the frame-scoped
+ * `ref`. Capped at 200 elements per frame.
+ */
+export declare const SNAPSHOT_SCRIPT = "() => {\n  const SEL = 'button,a,input,select,textarea,[role=button],[role=combobox],[role=checkbox],[role=radio],[role=switch],[role=tab],[role=menuitem],[role=option],[contenteditable=true]';\n  const obscured = (el, r) => {\n    const cx = r.x + r.width / 2, cy = r.y + r.height / 2;\n    if (r.width === 0 || cx < 0 || cy < 0 || cx > innerWidth || cy > innerHeight) return false;\n    const top = document.elementFromPoint(cx, cy);\n    return !!top && top !== el && !el.contains(top) && !top.contains(el);\n  };\n  const out = [];\n  const describe = (el, index) => {\n    const r = el.getBoundingClientRect();\n    const val = typeof el.value === 'string' ? el.value : null;\n    const isCheck = el.type === 'checkbox' || el.type === 'radio';\n    return {\n      index,\n      tag: el.tagName.toLowerCase(),\n      text: (el.innerText || el.getAttribute('aria-label') || el.getAttribute('placeholder') || '').trim().slice(0, 120),\n      role: el.getAttribute('role'), id: el.id || null, name: el.getAttribute('name'),\n      type: el.getAttribute('type'), href: el.getAttribute('href'),\n      value: val ? val.slice(0, 120) : null, placeholder: el.getAttribute('placeholder'),\n      disabled: !!el.disabled || el.getAttribute('aria-disabled') === 'true',\n      checked: isCheck ? !!el.checked : undefined,\n      options: el.tagName === 'SELECT' ? [...el.options].slice(0, 12).map((o) => o.label || o.value) : undefined,\n      ariaExpanded: el.getAttribute('aria-expanded'), ariaControls: el.getAttribute('aria-controls'),\n      visible: r.width > 0 && r.height > 0, obscured: obscured(el, r),\n      box: {x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height)}\n    };\n  };\n  const visit = (root) => {\n    if (out.length >= 200) return;\n    for (const el of root.querySelectorAll(SEL)) {\n      if (out.length >= 200) return;\n      const i = out.length;\n      el.setAttribute('data-fuse-ref', String(i));\n      out.push(describe(el, i));\n    }\n    for (const host of root.querySelectorAll('*')) {\n      if (host.shadowRoot) visit(host.shadowRoot);\n    }\n  };\n  visit(document);\n  return out;\n}";
+//# sourceMappingURL=snapshot-walk.d.ts.map

package/dist/extraction/snapshot-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-walk.d.ts","sourceRoot":"","sources":["../../src/extraction/snapshot-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAK7C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,0nEA0C1B,CAAC"}

package/dist/extraction/snapshot-walk.js

@@ -0,0 +1,61 @@
+/**
+ * Browser-side snapshot walk: collects interactive elements, piercing OPEN
+ * Shadow DOM recursively. Iframes are NOT descended here — each frame is walked
+ * separately on the Node side via {@link captureSnapshot} (cross-origin frames
+ * are unreadable from the parent context, and same-origin ones would duplicate).
+ * Closed shadow roots are inaccessible by browser SOP and stay opaque.
+ * @module extraction/snapshot-walk
+ */
+/** Attribute injected on each interactive element to anchor a stable ref. */
+export const REF_ATTRIBUTE = "data-fuse-ref";
+const SELECTOR = "button,a,input,select,textarea,[role=button],[role=combobox],[role=checkbox],[role=radio],[role=switch],[role=tab],[role=menuitem],[role=option],[contenteditable=true]";
+/**
+ * Arrow-function source (run via `evalScript` in each frame). Stamps a LOCAL
+ * `data-fuse-ref` (per-frame index) and returns elements in visitation order;
+ * the Node side rewrites `index` to a global counter and adds the frame-scoped
+ * `ref`. Capped at 200 elements per frame.
+ */
+export const SNAPSHOT_SCRIPT = `() => {
+  const SEL = '${SELECTOR}';
+  const obscured = (el, r) => {
+    const cx = r.x + r.width / 2, cy = r.y + r.height / 2;
+    if (r.width === 0 || cx < 0 || cy < 0 || cx > innerWidth || cy > innerHeight) return false;
+    const top = document.elementFromPoint(cx, cy);
+    return !!top && top !== el && !el.contains(top) && !top.contains(el);
+  };
+  const out = [];
+  const describe = (el, index) => {
+    const r = el.getBoundingClientRect();
+    const val = typeof el.value === 'string' ? el.value : null;
+    const isCheck = el.type === 'checkbox' || el.type === 'radio';
+    return {
+      index,
+      tag: el.tagName.toLowerCase(),
+      text: (el.innerText || el.getAttribute('aria-label') || el.getAttribute('placeholder') || '').trim().slice(0, 120),
+      role: el.getAttribute('role'), id: el.id || null, name: el.getAttribute('name'),
+      type: el.getAttribute('type'), href: el.getAttribute('href'),
+      value: val ? val.slice(0, 120) : null, placeholder: el.getAttribute('placeholder'),
+      disabled: !!el.disabled || el.getAttribute('aria-disabled') === 'true',
+      checked: isCheck ? !!el.checked : undefined,
+      options: el.tagName === 'SELECT' ? [...el.options].slice(0, 12).map((o) => o.label || o.value) : undefined,
+      ariaExpanded: el.getAttribute('aria-expanded'), ariaControls: el.getAttribute('aria-controls'),
+      visible: r.width > 0 && r.height > 0, obscured: obscured(el, r),
+      box: {x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height)}
+    };
+  };
+  const visit = (root) => {
+    if (out.length >= 200) return;
+    for (const el of root.querySelectorAll(SEL)) {
+      if (out.length >= 200) return;
+      const i = out.length;
+      el.setAttribute('${REF_ATTRIBUTE}', String(i));
+      out.push(describe(el, i));
+    }
+    for (const host of root.querySelectorAll('*')) {
+      if (host.shadowRoot) visit(host.shadowRoot);
+    }
+  };
+  visit(document);
+  return out;
+}`;
+//# sourceMappingURL=snapshot-walk.js.map

package/dist/extraction/snapshot-walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-walk.js","sourceRoot":"","sources":["../../src/extraction/snapshot-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C,MAAM,QAAQ,GACZ,yKAAyK,CAAC;AAE5K;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;iBACd,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yBAgCA,aAAa;;;;;;;;;EASpC,CAAC"}

package/dist/extraction/snapshot.d.ts

@@ -1,14 +1,20 @@
 /**
  * Accessibility-style snapshot: tag each interactive element with a stable
- * `data-fuse-ref` and return an indexed list the LLM can reason about.
- * The ref survives until the page re-renders, enabling deterministic
- * `browser_act` targeting via `[data-fuse-ref="N"]`.
+ * `data-fuse-ref` and return an indexed list the LLM can reason about. The walk
+ * runs in EVERY frame (`page.frames()`) and pierces open Shadow DOM, so refs
+ * cover iframes (same- and cross-origin) and web components. Each element's
+ * `ref` is frame-scoped (`"<frame>:<local>"`, bare `"<local>"` for the main
+ * frame) and resolves via {@link refLocator}.
  * @module extraction/snapshot
  */
 import type { Page } from "playwright";
 import type { InteractiveElement } from "../interfaces/extraction.js";
-/** Attribute injected on each interactive element to anchor a stable ref. */
-export declare const REF_ATTRIBUTE = "data-fuse-ref";
-/** Capture the indexed interactive snapshot, tagging each element with a ref. */
+export { REF_ATTRIBUTE } from "./snapshot-walk.js";
+/**
+ * Capture the indexed interactive snapshot across all frames, tagging each
+ * element with a (frame-local) ref attribute and exposing a frame-scoped `ref`.
+ * Detached frames and frames that reject evaluation (e.g. mid-navigation) are
+ * skipped rather than aborting the whole snapshot.
+ */
 export declare function captureSnapshot(page: Page): Promise<InteractiveElement[]>;
 //# sourceMappingURL=snapshot.d.ts.map

package/dist/extraction/snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/extraction/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAGtE,6EAA6E;AAC7E,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAwC7C,iFAAiF;AACjF,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAE/E"}
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/extraction/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAItE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKnD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAsB/E"}

package/dist/extraction/snapshot.js

@@ -1,43 +1,39 @@
 import { evalScript } from "../lib/evaluate.js";
-/** Attribute injected on each interactive element to anchor a stable ref. */
-export const REF_ATTRIBUTE = "data-fuse-ref";
-const SELECTOR = "button,a,input,select,textarea,[role=button],[role=combobox],[role=checkbox],[role=radio],[role=switch],[role=tab],[role=menuitem],[role=option],[contenteditable=true]";
-const SNAPSHOT_SCRIPT = `() => {
-  const obscured = (el, r) => {
-    const cx = r.x + r.width / 2, cy = r.y + r.height / 2;
-    if (r.width === 0 || cx < 0 || cy < 0 || cx > innerWidth || cy > innerHeight) return false;
-    const top = document.elementFromPoint(cx, cy);
-    return !!top && top !== el && !el.contains(top) && !top.contains(el);
-  };
-  return [...document.querySelectorAll('${SELECTOR}')].slice(0, 200).map((el, index) => {
-    el.setAttribute('${REF_ATTRIBUTE}', String(index));
-    const r = el.getBoundingClientRect();
-    const val = typeof el.value === 'string' ? el.value : null;
-    const isCheck = el.type === 'checkbox' || el.type === 'radio';
-    return {
-      index,
-      tag: el.tagName.toLowerCase(),
-      text: (el.innerText || el.getAttribute('aria-label') || el.getAttribute('placeholder') || '').trim().slice(0, 120),
-      role: el.getAttribute('role'),
-      id: el.id || null,
-      name: el.getAttribute('name'),
-      type: el.getAttribute('type'),
-      href: el.getAttribute('href'),
-      value: val ? val.slice(0, 120) : null,
-      placeholder: el.getAttribute('placeholder'),
-      disabled: !!el.disabled || el.getAttribute('aria-disabled') === 'true',
-      checked: isCheck ? !!el.checked : undefined,
-      options: el.tagName === 'SELECT' ? [...el.options].slice(0, 12).map((o) => o.label || o.value) : undefined,
-      ariaExpanded: el.getAttribute('aria-expanded'),
-      ariaControls: el.getAttribute('aria-controls'),
-      visible: r.width > 0 && r.height > 0,
-      obscured: obscured(el, r),
-      box: {x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height)}
-    };
-  });
-}`;
-/** Capture the indexed interactive snapshot, tagging each element with a ref. */
+import { SNAPSHOT_SCRIPT } from "./snapshot-walk.js";
+export { REF_ATTRIBUTE } from "./snapshot-walk.js";
+/** Soft cap on total elements across all frames, to bound output size. */
+const MAX_ELEMENTS = 400;
+/**
+ * Capture the indexed interactive snapshot across all frames, tagging each
+ * element with a (frame-local) ref attribute and exposing a frame-scoped `ref`.
+ * Detached frames and frames that reject evaluation (e.g. mid-navigation) are
+ * skipped rather than aborting the whole snapshot.
+ */
 export async function captureSnapshot(page) {
-    return evalScript(page, SNAPSHOT_SCRIPT);
+    const frames = page.frames();
+    const all = [];
+    let global = 0;
+    for (let f = 0; f < frames.length && all.length < MAX_ELEMENTS; f++) {
+        const frame = frames[f];
+        if (!frame || frame.isDetached())
+            continue;
+        let local;
+        try {
+            local = await evalScript(frame, SNAPSHOT_SCRIPT);
+        }
+        catch {
+            continue;
+        }
+        for (const el of local) {
+            if (all.length >= MAX_ELEMENTS)
+                break;
+            el.ref = f === 0 ? String(el.index) : `${f}:${el.index}`;
+            if (f > 0)
+                el.frame = f;
+            el.index = global++;
+            all.push(el);
+        }
+    }
+    return all;
 }
 //# sourceMappingURL=snapshot.js.map

package/dist/extraction/snapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/extraction/snapshot.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C,MAAM,QAAQ,GACZ,yKAAyK,CAAC;AAE5K,MAAM,eAAe,GAAG;;;;;;;0CAOkB,QAAQ;uBAC3B,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;EAyBlC,CAAC;AAEH,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAU;IAC9C,OAAO,UAAU,CAAuB,IAAI,EAAE,eAAe,CAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/extraction/snapshot.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,0EAA0E;AAC1E,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAU;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAyB,EAAE,CAAC;IACrC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;QACpE,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,EAAE;YAAE,SAAS;QAC3C,IAAI,KAA2B,CAAC;QAChC,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,UAAU,CAAuB,KAAK,EAAE,eAAe,CAAC,CAAC;QACzE,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;YACvB,IAAI,GAAG,CAAC,MAAM,IAAI,YAAY;gBAAE,MAAM;YACtC,EAAE,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;YACzD,IAAI,CAAC,GAAG,CAAC;gBAAE,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC;YACxB,EAAE,CAAC,KAAK,GAAG,MAAM,EAAE,CAAC;YACpB,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/interfaces/extraction.d.ts

@@ -36,6 +36,10 @@ export interface Challenges {
 /** An interactive element observed visually. Optional fields enrich snapshots. */
 export interface InteractiveElement {
     index: number;
+    /** Frame-scoped ref for targeting: `"<frame>:<local>"`, or `"<local>"` for the main frame. */
+    ref?: string;
+    /** Owning frame ordinal in `page.frames()` (omitted for the main frame). */
+    frame?: number;
     tag: string;
     text: string;
     role: string | null;
@@ -68,34 +72,5 @@ export interface Visual {
     };
     interactiveElements?: InteractiveElement[];
 }
-/** A single Google SERP entry (organic result or ad). */
-export interface SerpResult {
-    position: number;
-    title: string;
-    url: string;
-    displayUrl?: string;
-    snippet?: string;
-}
-/** Where a domain ranks within a SERP. */
-export interface DomainRank {
-    domain: string;
-    organic: number[];
-    ads: number[];
-    best: number | null;
-    found: boolean;
-}
-/** Parsed Google search results page. */
-export interface Serp {
-    organic: SerpResult[];
-    ads: SerpResult[];
-    related: string[];
-    rank?: DomainRank;
-}
-/** One query's outcome in a SERP batch. */
-export interface SerpBatchRow {
-    query: string;
-    rank?: DomainRank;
-    results: SerpResult[];
-    error?: string;
-}
+export type { DomainRank, Serp, SerpBatchRow, SerpResult } from "./serp.js";
 //# sourceMappingURL=extraction.d.ts.map

package/dist/interfaces/extraction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../../src/interfaces/extraction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../../src/interfaces/extraction.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,yCAAyC;AACzC,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtD,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,SAAS,EAAE,UAAU,GAAG,IAAI,CAAC;CAC9B;AAED,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;CACd;AAED,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,8FAA8F;IAC9F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,8DAA8D;AAC9D,MAAM,WAAW,MAAM;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,mBAAmB,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAC5C;AAED,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/interfaces/serp.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Types for Google SERP parsing and rank tracking.
+ * @module interfaces/serp
+ */
+/** A single Google SERP entry (organic result or ad). */
+export interface SerpResult {
+    position: number;
+    title: string;
+    url: string;
+    displayUrl?: string;
+    snippet?: string;
+}
+/** Where a domain ranks within a SERP. */
+export interface DomainRank {
+    domain: string;
+    organic: number[];
+    ads: number[];
+    best: number | null;
+    found: boolean;
+}
+/** Parsed Google search results page. */
+export interface Serp {
+    organic: SerpResult[];
+    ads: SerpResult[];
+    related: string[];
+    rank?: DomainRank;
+}
+/** One query's outcome in a SERP batch. */
+export interface SerpBatchRow {
+    query: string;
+    rank?: DomainRank;
+    results: SerpResult[];
+    error?: string;
+}
+//# sourceMappingURL=serp.d.ts.map

package/dist/interfaces/serp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serp.d.ts","sourceRoot":"","sources":["../../src/interfaces/serp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,yCAAyC;AACzC,MAAM,WAAW,IAAI;IACnB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,GAAG,EAAE,UAAU,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/interfaces/serp.js

@@ -0,0 +1,6 @@
+/**
+ * Types for Google SERP parsing and rank tracking.
+ * @module interfaces/serp
+ */
+export {};
+//# sourceMappingURL=serp.js.map

package/dist/interfaces/serp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serp.js","sourceRoot":"","sources":["../../src/interfaces/serp.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/lib/evaluate.d.ts

@@ -9,9 +9,12 @@
  * `(arg) => {...}` scripts while staying isolated from Node DOM typing.
  * @module lib/evaluate
  */
-import type { Page } from "playwright";
+import type { Frame, Page } from "playwright";
+/** A context that can evaluate browser scripts — a page or one of its frames. */
+type EvalTarget = Pick<Page, "evaluate"> | Pick<Frame, "evaluate">;
 /** Evaluate an arrow-function browser script with no argument; returns `R`. */
-export declare function evalScript<R>(page: Page, script: string): Promise<R>;
+export declare function evalScript<R>(ctx: EvalTarget, script: string): Promise<R>;
 /** Evaluate an arrow-function browser script with one serializable argument. */
-export declare function evalScriptArg<R, A>(page: Page, script: string, arg: A): Promise<R>;
+export declare function evalScriptArg<R, A>(ctx: EvalTarget, script: string, arg: A): Promise<R>;
+export {};
 //# sourceMappingURL=evaluate.d.ts.map

package/dist/lib/evaluate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/lib/evaluate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAEpE;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAGlF"}
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/lib/evaluate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE9C,iFAAiF;AACjF,KAAK,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AAEnE,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAEzE;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAGvF"}

package/dist/lib/evaluate.js

@@ -1,10 +1,10 @@
 /** Evaluate an arrow-function browser script with no argument; returns `R`. */
-export function evalScript(page, script) {
-    return page.evaluate(`(${script})()`);
+export function evalScript(ctx, script) {
+    return ctx.evaluate(`(${script})()`);
 }
 /** Evaluate an arrow-function browser script with one serializable argument. */
-export function evalScriptArg(page, script, arg) {
+export function evalScriptArg(ctx, script, arg) {
     const expression = `(${script})(${JSON.stringify(arg)})`;
-    return page.evaluate(expression);
+    return ctx.evaluate(expression);
 }
 //# sourceMappingURL=evaluate.js.map

package/dist/lib/evaluate.js.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate.js","sourceRoot":"","sources":["../../src/lib/evaluate.ts"],"names":[],"mappings":"AAaA,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CAAI,IAAU,EAAE,MAAc;IACtD,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,MAAM,KAA2B,CAAC,CAAC;AAC9D,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAO,IAAU,EAAE,MAAc,EAAE,GAAM;IACpE,MAAM,UAAU,GAAG,IAAI,MAAM,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;IACzD,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAgC,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"evaluate.js","sourceRoot":"","sources":["../../src/lib/evaluate.ts"],"names":[],"mappings":"AAgBA,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CAAI,GAAe,EAAE,MAAc;IAC3D,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,MAAM,KAA2B,CAAC,CAAC;AAC7D,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAO,GAAe,EAAE,MAAc,EAAE,GAAM;IACzE,MAAM,UAAU,GAAG,IAAI,MAAM,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;IACzD,OAAO,GAAG,CAAC,QAAQ,CAAC,UAAgC,CAAC,CAAC;AACxD,CAAC"}

package/dist/server/tools/screenshot.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { REF_ATTRIBUTE } from "../../extraction/snapshot.js";
+import { refLocator } from "../../actions/ref-locator.js";
 import { resolveViewport, viewportLabel } from "../../engine/viewport.js";
 import { settleForCapture } from "../../state/settle-capture.js";
 import { errorResult, imageResult, multiImageResult } from "../result.js";
@@ -16,16 +16,16 @@ export function registerScreenshotTool(server, sessions) {
         inputSchema: {
             sessionId: z.string(),
             fullPage: z.boolean().optional(),
-            ref: z.number().int().optional(),
+            ref: z.union([z.number().int(), z.string()]).optional(),
             viewport: VIEWPORT_SCHEMA.optional(),
             viewports: z.array(VIEWPORT_SCHEMA).optional(),
         },
     }, async (args) => {
         const a = args;
         return withSession(sessions, String(a.sessionId), async (s) => {
-            if (typeof a.ref === "number") {
-                const locator = s.page.locator(`[${REF_ATTRIBUTE}="${a.ref}"]`).first();
-                if ((await locator.count()) === 0)
+            if (typeof a.ref === "number" || typeof a.ref === "string") {
+                const locator = refLocator(s.page, a.ref);
+                if (!locator || (await locator.count()) === 0)
                     return errorResult("ref_not_found");
                 const buf = await locator.screenshot({ timeout: 5_000 });
                 return imageResult(buf.toString("base64"), `element ref=${a.ref}`);

package/dist/server/tools/screenshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../../../src/server/tools/screenshot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../../../src/server/tools/screenshot.ts"],"names":[],"mappings":"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"}

package/dist/server/tools/snapshot.js

@@ -13,7 +13,7 @@ async function runAct(page, a, human) {
     const kind = a.kind;
     const value = a.value ? String(a.value) : "";
     const option = a.option ? String(a.option) : "";
-    if (typeof a.ref === "number")
+    if (typeof a.ref === "number" || typeof a.ref === "string")
         return actByRef(page, a.ref, kind, value, option);
     if (typeof a.target !== "string")
         return null;
@@ -27,7 +27,7 @@ async function runAct(page, a, human) {
 export function registerSnapshotTools(server, sessions) {
     server.registerTool("browser_snapshot", {
         title: "Snapshot",
-        description: "Return the indexed interactive elements of the live page. Each element gets a stable `ref` to use with browser_act for deterministic targeting.",
+        description: "Return the indexed interactive elements of the live page, including those inside open Shadow DOM and iframes (same- and cross-origin). Use each element's `ref` (e.g. \"12\" or \"3:4\" for a sub-frame) with browser_act for deterministic targeting.",
         inputSchema: { sessionId: z.string() },
     }, async (args) => {
         const a = args;
@@ -42,7 +42,7 @@ export function registerSnapshotTools(server, sessions) {
         inputSchema: {
             sessionId: z.string(),
             kind: KIND,
-            ref: z.number().int().optional(),
+            ref: z.union([z.number().int(), z.string()]).optional(),
             target: z.string().optional(),
             value: z.string().optional(),
             option: z.string().optional(),

package/dist/server/tools/snapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../src/server/tools/snapshot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../src/server/tools/snapshot.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusengine/browser-mcp",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "MCP server + CLI giving AI agents a real, stealth browser (Patchright/Playwright) — per-country identity, self-healing actions, snapshots, multi-step plans, structured extraction, CDP attach.",
   "license": "MIT",
   "author": "Fusengine",
@@ -54,7 +54,7 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "bun test tests/unit",
-    "test:integration": "node --test --import tsx tests/integration/mcp.test.ts tests/integration/probe.test.ts tests/integration/snapshot.test.ts tests/integration/run.test.ts tests/integration/extract-schema.test.ts",
+    "test:integration": "node --test --import tsx tests/integration/mcp.test.ts tests/integration/probe.test.ts tests/integration/snapshot.test.ts tests/integration/snapshot-frames.test.ts tests/integration/run.test.ts tests/integration/extract-schema.test.ts",
     "browsers": "patchright install chromium",
     "mcp": "node --import tsx src/bin/mcp.ts",
     "cli": "node --import tsx src/bin/cli.ts"