@vforsh/argus-watcher 0.1.9 → 0.1.11

package/dist/cdp/authState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authState.d.ts","sourceRoot":"","sources":["../../src/cdp/authState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyD,KAAK,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC9I,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEvD,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,GAAU,OAAO;IACpD,OAAO,EAAE,gBAAgB,CAAA;IACzB,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B,KAAG,OAAO,CAAC,qBAAqB,CAqD9B,CAAA"}

package/dist/cdp/authState.js

@@ -0,0 +1,44 @@
+import { buildAuthStateStorageSeedExpression, hydrateAuthState } from '@vforsh/argus-core';
+/** Apply an auth-state snapshot to the currently attached watcher target. */
+export const applyAuthStateToSession = async (input) => hydrateAuthState({
+    driver: {
+        setCookies: async (cookies) => {
+            await input.session.sendAndWait('Network.setCookies', {
+                cookies: cookies.map((cookie) => ({
+                    name: cookie.name,
+                    value: cookie.value,
+                    domain: cookie.domain,
+                    path: cookie.path,
+                    secure: cookie.secure,
+                    httpOnly: cookie.httpOnly,
+                    sameSite: cookie.sameSite ?? undefined,
+                    expires: cookie.session ? undefined : (cookie.expires ?? undefined),
+                })),
+            }, { timeoutMs: 5_000 });
+        },
+        navigateAndWait: async (url) => {
+            await input.session.sendAndWait('Page.navigate', { url }, { timeoutMs: 5_000 });
+            await input.session.sendAndWait('Runtime.evaluate', {
+                expression: `new Promise((resolve) => {
+							if (document.readyState === 'complete') {
+								resolve(true)
+								return
+							}
+							addEventListener('load', () => resolve(true), { once: true })
+						})`,
+                awaitPromise: true,
+                returnByValue: true,
+            }, { timeoutMs: 10_000 });
+        },
+        seedStorage: async (originState) => {
+            await input.session.sendAndWait('Runtime.evaluate', {
+                expression: buildAuthStateStorageSeedExpression(originState),
+                awaitPromise: false,
+                returnByValue: true,
+            }, { timeoutMs: 5_000 });
+        },
+    },
+    snapshot: input.snapshot,
+    startupUrl: input.startupUrl ?? null,
+});
+//# sourceMappingURL=authState.js.map

package/dist/cdp/authState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authState.js","sourceRoot":"","sources":["../../src/cdp/authState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mCAAmC,EAAE,gBAAgB,EAAsD,MAAM,oBAAoB,CAAA;AAG9I,6EAA6E;AAC7E,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,EAAE,KAI7C,EAAkC,EAAE,CACpC,gBAAgB,CAAC;IAChB,MAAM,EAAE;QACP,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YAC7B,MAAM,KAAK,CAAC,OAAO,CAAC,WAAW,CAC9B,oBAAoB,EACpB;gBACC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;oBACjC,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,MAAM,EAAE,MAAM,CAAC,MAAM;oBACrB,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,MAAM,EAAE,MAAM,CAAC,MAAM;oBACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,SAAS;oBACtC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,IAAI,SAAS,CAAC;iBACnE,CAAC,CAAC;aACH,EACD,EAAE,SAAS,EAAE,KAAK,EAAE,CACpB,CAAA;QACF,CAAC;QACD,eAAe,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YAC9B,MAAM,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAA;YAC/E,MAAM,KAAK,CAAC,OAAO,CAAC,WAAW,CAC9B,kBAAkB,EAClB;gBACC,UAAU,EAAE;;;;;;SAMT;gBACH,YAAY,EAAE,IAAI;gBAClB,aAAa,EAAE,IAAI;aACnB,EACD,EAAE,SAAS,EAAE,MAAM,EAAE,CACrB,CAAA;QACF,CAAC;QACD,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE;YAClC,MAAM,KAAK,CAAC,OAAO,CAAC,WAAW,CAC9B,kBAAkB,EAClB;gBACC,UAAU,EAAE,mCAAmC,CAAC,WAAW,CAAC;gBAC5D,YAAY,EAAE,KAAK;gBACnB,aAAa,EAAE,IAAI;aACnB,EACD,EAAE,SAAS,EAAE,KAAK,EAAE,CACpB,CAAA;QACF,CAAC;KACD;IACD,QAAQ,EAAE,KAAK,CAAC,QAAQ;IACxB,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;CACpC,CAAC,CAAA"}

package/dist/cdp/browserCookies.d.ts

@@ -0,0 +1,8 @@
+import type { AuthStateCookie, WatcherChrome } from '@vforsh/argus-core';
+import type { CdpSourceCookieQuery } from '../sources/types.js';
+/**
+ * Browser-target cookies are the only reliable way to capture sibling subdomain auth in CDP mode.
+ * Page-target `Network.getCookies` only sees the current document's request scope.
+ */
+export declare const createCdpBrowserCookieReader: (chrome: WatcherChrome, getTargetId: () => string | null) => (query: CdpSourceCookieQuery) => Promise<AuthStateCookie[]>;
+//# sourceMappingURL=browserCookies.d.ts.map

package/dist/cdp/browserCookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserCookies.d.ts","sourceRoot":"","sources":["../../src/cdp/browserCookies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAExE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAkC/D;;;GAGG;AACH,eAAO,MAAM,4BAA4B,GACvC,QAAQ,aAAa,EAAE,aAAa,MAAM,MAAM,GAAG,IAAI,MACjD,OAAO,oBAAoB,KAAG,OAAO,CAAC,eAAe,EAAE,CAc7D,CAAA"}

package/dist/cdp/browserCookies.js

@@ -0,0 +1,160 @@
+import { matchesCookieDomain, normalizeCookieDomainFilter } from '@vforsh/argus-core';
+const TARGET_INFO_REQUEST_ID = 1;
+const STORAGE_GET_COOKIES_REQUEST_ID = 2;
+const STORAGE_GET_COOKIES_FALLBACK_REQUEST_ID = 3;
+/**
+ * Browser-target cookies are the only reliable way to capture sibling subdomain auth in CDP mode.
+ * Page-target `Network.getCookies` only sees the current document's request scope.
+ */
+export const createCdpBrowserCookieReader = (chrome, getTargetId) => async (query) => {
+    const host = chrome.host ?? '127.0.0.1';
+    const port = chrome.port ?? 9222;
+    const version = await fetchChromeVersion(host, port);
+    const wsUrl = version.webSocketDebuggerUrl;
+    if (!wsUrl) {
+        throw new Error(`Chrome browser websocket missing at ${host}:${port}`);
+    }
+    const browserContextId = await readTargetBrowserContextId(wsUrl, getTargetId());
+    const payload = await readBrowserCookiesPayload(wsUrl, browserContextId);
+    const normalizedDomain = normalizeCookieDomainFilter(query.domain ?? null);
+    return (payload.cookies ?? []).map(normalizeBrowserCookie).filter((cookie) => matchesCookieDomain(cookie.domain, normalizedDomain));
+};
+const fetchChromeVersion = async (host, port) => {
+    const response = await fetch(`http://${host}:${port}/json/version`, {
+        signal: AbortSignal.timeout(5_000),
+    });
+    if (!response.ok) {
+        throw new Error(`Chrome version endpoint failed with ${response.status}`);
+    }
+    return (await response.json());
+};
+const normalizeBrowserCookie = (cookie) => ({
+    name: cookie.name ?? '',
+    value: cookie.value ?? '',
+    domain: cookie.domain ?? '',
+    path: cookie.path ?? '/',
+    secure: cookie.secure === true,
+    httpOnly: cookie.httpOnly === true,
+    session: cookie.session === true,
+    expires: typeof cookie.expires === 'number' && Number.isFinite(cookie.expires) ? cookie.expires : null,
+    sameSite: cookie.sameSite ?? null,
+});
+const readTargetBrowserContextId = async (wsUrl, targetId) => {
+    if (!targetId) {
+        return null;
+    }
+    const response = await sendBrowserCommand(wsUrl, {
+        id: TARGET_INFO_REQUEST_ID,
+        method: 'Target.getTargetInfo',
+        params: { targetId },
+    });
+    return response.targetInfo?.browserContextId ?? null;
+};
+const readBrowserCookiesPayload = async (wsUrl, browserContextId) => {
+    try {
+        return await sendBrowserCommand(wsUrl, {
+            id: STORAGE_GET_COOKIES_REQUEST_ID,
+            method: 'Storage.getCookies',
+            params: browserContextId ? { browserContextId } : undefined,
+        });
+    }
+    catch (error) {
+        if (!browserContextId || !isMissingBrowserContextError(error)) {
+            throw error;
+        }
+        return await sendBrowserCommand(wsUrl, {
+            id: STORAGE_GET_COOKIES_FALLBACK_REQUEST_ID,
+            method: 'Storage.getCookies',
+        });
+    }
+};
+const isMissingBrowserContextError = (error) => error instanceof Error && /browser context/i.test(error.message);
+const sendBrowserCommand = async (wsUrl, payload, timeoutMs = 5_000) => {
+    const WebSocketConstructor = getWebSocketCtor();
+    if (!WebSocketConstructor) {
+        throw new Error('WebSocket unavailable. Node 18+ required.');
+    }
+    const ws = new WebSocketConstructor(wsUrl);
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => finish(undefined, new Error(`CDP command timed out after ${timeoutMs}ms`)), timeoutMs);
+        const cleanup = () => {
+            clearTimeout(timer);
+            ws.removeEventListener?.('open', onOpen);
+            ws.removeEventListener?.('message', onMessage);
+            ws.removeEventListener?.('error', onError);
+            ws.removeEventListener?.('close', onClose);
+        };
+        const finish = (result, error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            try {
+                ws.close();
+            }
+            catch { }
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve(result);
+        };
+        const onOpen = () => {
+            try {
+                ws.send(JSON.stringify(payload));
+            }
+            catch (error) {
+                finish(undefined, error instanceof Error ? error : new Error(String(error)));
+            }
+        };
+        const onMessage = (event) => {
+            const text = toMessageText(event.data);
+            if (!text) {
+                return;
+            }
+            try {
+                const message = JSON.parse(text);
+                if (message.id !== payload.id) {
+                    return;
+                }
+                if (message.error?.message) {
+                    finish(undefined, new Error(message.error.message));
+                    return;
+                }
+                finish(message.result);
+            }
+            catch (error) {
+                finish(undefined, error instanceof Error ? error : new Error(String(error)));
+            }
+        };
+        const onError = () => {
+            finish(undefined, new Error('WebSocket error'));
+        };
+        const onClose = () => {
+            finish(undefined, new Error('WebSocket closed before response'));
+        };
+        ws.addEventListener('open', onOpen);
+        ws.addEventListener('message', onMessage);
+        ws.addEventListener('error', onError);
+        ws.addEventListener('close', onClose);
+    });
+};
+const getWebSocketCtor = () => {
+    const ctor = globalThis.WebSocket;
+    return ctor ?? null;
+};
+const toMessageText = (data) => {
+    if (typeof data === 'string') {
+        return data;
+    }
+    if (data instanceof ArrayBuffer) {
+        return Buffer.from(data).toString('utf8');
+    }
+    if (Buffer.isBuffer(data)) {
+        return data.toString('utf8');
+    }
+    return null;
+};
+//# sourceMappingURL=browserCookies.js.map

package/dist/cdp/browserCookies.js.map

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

package/dist/cdp/dom/fill.d.ts

@@ -1,4 +1,5 @@
 import type { CdpSessionHandle } from '../connection.js';
+import { type DomNodeHandle } from './selector.js';
 /** Options for filling input/textarea/contenteditable elements. */
 export type FillElementsOptions = {
     selector: string;
@@ -12,7 +13,7 @@ export type FillElementsResult = {
     filledCount: number;
 };
 /** Fill pre-resolved node IDs with a value. Skips selector resolution. */
-export declare const fillResolvedNodes: (session: CdpSessionHandle, nodeIds: number[], value: string) => Promise<number>;
+export declare const fillResolvedNodes: (session: CdpSessionHandle, handles: DomNodeHandle[], value: string) => Promise<number>;
 /**
  * Fill input/textarea/contenteditable element(s) with a value.
  * Uses the native setter trick to bypass framework property wrappers,

package/dist/cdp/dom/fill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fill.d.ts","sourceRoot":"","sources":["../../../src/cdp/dom/fill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAGxD,mEAAmE;AACnE,MAAM,MAAM,mBAAmB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,wCAAwC;AACxC,MAAM,MAAM,kBAAkB,GAAG;IAChC,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;CACnB,CAAA;AA6BD,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,GAAU,SAAS,gBAAgB,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,MAAM,KAAG,OAAO,CAAC,MAAM,CAkBnH,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAU,SAAS,gBAAgB,EAAE,SAAS,mBAAmB,KAAG,OAAO,CAAC,kBAAkB,CAQtH,CAAA"}
+{"version":3,"file":"fill.d.ts","sourceRoot":"","sources":["../../../src/cdp/dom/fill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,EAA6D,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7G,mEAAmE;AACnE,MAAM,MAAM,mBAAmB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,wCAAwC;AACxC,MAAM,MAAM,kBAAkB,GAAG;IAChC,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;CACnB,CAAA;AA6BD,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,GAAU,SAAS,gBAAgB,EAAE,SAAS,aAAa,EAAE,EAAE,OAAO,MAAM,KAAG,OAAO,CAAC,MAAM,CAkB1H,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAU,SAAS,gBAAgB,EAAE,SAAS,mBAAmB,KAAG,OAAO,CAAC,kBAAkB,CAYtH,CAAA"}

package/dist/cdp/dom/fill.js

@@ -1,4 +1,4 @@
-import { getDomRootId, resolveSelectorMatches } from './selector.js';
+import { getDomRootId, resolveSelectorMatches, toDomNodeDescriptor } from './selector.js';
 /**
  * Browser-context function that sets the element value using the native
  * prototype setter (to bypass React/Vue/Angular property wrappers) and
@@ -26,11 +26,11 @@ const FILL_FUNCTION = `function(value) {
 	el.dispatchEvent(new Event('change', { bubbles: true }));
 }`;
 /** Fill pre-resolved node IDs with a value. Skips selector resolution. */
-export const fillResolvedNodes = async (session, nodeIds, value) => {
-    if (nodeIds.length === 0)
+export const fillResolvedNodes = async (session, handles, value) => {
+    if (handles.length === 0)
         return 0;
-    for (const nodeId of nodeIds) {
-        const resolved = (await session.sendAndWait('DOM.resolveNode', { nodeId }));
+    for (const handle of handles) {
+        const resolved = (await session.sendAndWait('DOM.resolveNode', toDomNodeDescriptor(handle)));
         const objectId = resolved.object?.objectId;
         if (!objectId)
             continue;
@@ -42,7 +42,7 @@ export const fillResolvedNodes = async (session, nodeIds, value) => {
             returnByValue: true,
         });
     }
-    return nodeIds.length;
+    return handles.length;
 };
 /**
  * Fill input/textarea/contenteditable element(s) with a value.
@@ -53,7 +53,7 @@ export const fillElements = async (session, options) => {
     await session.sendAndWait('DOM.enable');
     const rootId = await getDomRootId(session);
     const { allNodeIds, nodeIds } = await resolveSelectorMatches(session, rootId, options.selector, options.all ?? false, options.text);
-    const filledCount = await fillResolvedNodes(session, nodeIds, options.value);
+    const filledCount = await fillResolvedNodes(session, nodeIds.map((nodeId) => ({ nodeId })), options.value);
     return { allNodeIds, filledCount };
 };
 //# sourceMappingURL=fill.js.map

package/dist/cdp/dom/fill.js.map

@@ -1 +1 @@
-{"version":3,"file":"fill.js","sourceRoot":"","sources":["../../../src/cdp/dom/fill.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAgBpE;;;;GAIG;AACH,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;EAoBpB,CAAA;AAEF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EAAE,OAAyB,EAAE,OAAiB,EAAE,KAAa,EAAmB,EAAE;IACvH,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAElC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAuC,CAAA;QACjH,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;QAC1C,IAAI,CAAC,QAAQ;YAAE,SAAQ;QAEvB,MAAM,OAAO,CAAC,WAAW,CAAC,wBAAwB,EAAE;YACnD,QAAQ;YACR,mBAAmB,EAAE,aAAa;YAClC,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC;YACtB,YAAY,EAAE,KAAK;YACnB,aAAa,EAAE,IAAI;SACnB,CAAC,CAAA;IACH,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,CAAA;AACtB,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAAE,OAAyB,EAAE,OAA4B,EAA+B,EAAE;IAC1H,MAAM,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAA;IAEvC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAA;IAC1C,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,MAAM,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,IAAI,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAEnI,MAAM,WAAW,GAAG,MAAM,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;IAC5E,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAA;AACnC,CAAC,CAAA"}
+{"version":3,"file":"fill.js","sourceRoot":"","sources":["../../../src/cdp/dom/fill.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAsB,MAAM,eAAe,CAAA;AAgB7G;;;;GAIG;AACH,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;EAoBpB,CAAA;AAEF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EAAE,OAAyB,EAAE,OAAwB,EAAE,KAAa,EAAmB,EAAE;IAC9H,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAElC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAuC,CAAA;QAClI,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;QAC1C,IAAI,CAAC,QAAQ;YAAE,SAAQ;QAEvB,MAAM,OAAO,CAAC,WAAW,CAAC,wBAAwB,EAAE;YACnD,QAAQ;YACR,mBAAmB,EAAE,aAAa;YAClC,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC;YACtB,YAAY,EAAE,KAAK;YACnB,aAAa,EAAE,IAAI;SACnB,CAAC,CAAA;IACH,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,CAAA;AACtB,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAAE,OAAyB,EAAE,OAA4B,EAA+B,EAAE;IAC1H,MAAM,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAA;IAEvC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAA;IAC1C,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,MAAM,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,IAAI,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAEnI,MAAM,WAAW,GAAG,MAAM,iBAAiB,CAC1C,OAAO,EACP,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EACrC,OAAO,CAAC,KAAK,CACb,CAAA;IACD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAA;AACnC,CAAC,CAAA"}

package/dist/cdp/dom/info.d.ts

@@ -1,8 +1,10 @@
 import type { DomInfoResponse } from '@vforsh/argus-core';
 import type { CdpSessionHandle } from '../connection.js';
+import type { ElementRefRegistry } from '../elementRefs.js';
 /** Options for fetching DOM element info by selector. */
 export type FetchDomInfoOptions = {
-    selector: string;
+    selector?: string;
+    ref?: string;
     all?: boolean;
     outerHtmlMaxChars?: number;
     text?: string;
@@ -10,5 +12,5 @@ export type FetchDomInfoOptions = {
 /**
  * Fetch detailed info for element(s) matching a CSS selector.
  */
-export declare const fetchDomInfoBySelector: (session: CdpSessionHandle, options: FetchDomInfoOptions) => Promise<DomInfoResponse>;
+export declare const fetchDomInfoBySelector: (session: CdpSessionHandle, elementRefs: ElementRefRegistry, options: FetchDomInfoOptions) => Promise<DomInfoResponse>;
 //# sourceMappingURL=info.d.ts.map

package/dist/cdp/dom/info.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"info.d.ts","sourceRoot":"","sources":["../../../src/cdp/dom/info.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAWxD,yDAAyD;AACzD,MAAM,MAAM,mBAAmB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,GAAU,SAAS,gBAAgB,EAAE,SAAS,mBAAmB,KAAG,OAAO,CAAC,eAAe,CAuD7H,CAAA"}
+{"version":3,"file":"info.d.ts","sourceRoot":"","sources":["../../../src/cdp/dom/info.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAW3D,yDAAyD;AACzD,MAAM,MAAM,mBAAmB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,GAClC,SAAS,gBAAgB,EACzB,aAAa,kBAAkB,EAC/B,SAAS,mBAAmB,KAC1B,OAAO,CAAC,eAAe,CA+DzB,CAAA"}

package/dist/cdp/dom/info.js

@@ -1,22 +1,30 @@
-import { getDomRootId, resolveSelectorMatches, toAttributesRecord, countElementChildren, clamp } from './selector.js';
+import { clamp, countElementChildren, resolveElementTargets, toAttributesRecord, toDomNodeDescriptor } from './selector.js';
 const DEFAULT_OUTER_HTML_MAX_CHARS = 50_000;
 const MAX_OUTER_HTML_CHARS = 500_000;
 /**
  * Fetch detailed info for element(s) matching a CSS selector.
  */
-export const fetchDomInfoBySelector = async (session, options) => {
+export const fetchDomInfoBySelector = async (session, elementRefs, options) => {
     const all = options.all ?? false;
     const maxChars = clamp(options.outerHtmlMaxChars ?? DEFAULT_OUTER_HTML_MAX_CHARS, 0, MAX_OUTER_HTML_CHARS);
-    await session.sendAndWait('DOM.enable');
-    const rootId = await getDomRootId(session);
-    const { allNodeIds, nodeIds } = await resolveSelectorMatches(session, rootId, options.selector, all, options.text);
-    if (allNodeIds.length === 0) {
+    const resolved = await resolveElementTargets(session, elementRefs, {
+        selector: options.selector,
+        ref: options.ref,
+        all,
+        text: options.text,
+    });
+    if (resolved.missingRef && options.ref) {
+        throw Object.assign(new Error(`Unknown or stale element ref: ${options.ref}`), { code: 'invalid_ref' });
+    }
+    const { allHandles, handles } = resolved;
+    if (allHandles.length === 0) {
         return { ok: true, matches: 0, elements: [] };
     }
     const elements = [];
-    for (const nodeId of nodeIds) {
+    for (const handle of handles) {
+        const descriptor = toDomNodeDescriptor(handle);
         const describeResult = (await session.sendAndWait('DOM.describeNode', {
-            nodeId,
+            ...descriptor,
             depth: 1, // Just enough to get child count
         }));
         if (!describeResult.node) {
@@ -28,7 +36,7 @@ export const fetchDomInfoBySelector = async (session, options) => {
         let outerHTML = null;
         let outerHTMLTruncated = false;
         try {
-            const htmlResult = (await session.sendAndWait('DOM.getOuterHTML', { nodeId }));
+            const htmlResult = (await session.sendAndWait('DOM.getOuterHTML', descriptor));
             outerHTML = htmlResult.outerHTML ?? null;
             if (outerHTML && outerHTML.length > maxChars) {
                 outerHTML = outerHTML.slice(0, maxChars);
@@ -39,7 +47,8 @@ export const fetchDomInfoBySelector = async (session, options) => {
             // getOuterHTML can fail for certain nodes; leave as null
         }
         elements.push({
-            nodeId,
+            ref: node.backendNodeId != null ? elementRefs.getOrCreate(node.backendNodeId) : undefined,
+            nodeId: node.nodeId,
             tag: (node.localName ?? node.nodeName).toLowerCase(),
             attributes,
             childElementCount,
@@ -47,6 +56,6 @@ export const fetchDomInfoBySelector = async (session, options) => {
             outerHTMLTruncated,
         });
     }
-    return { ok: true, matches: allNodeIds.length, elements };
+    return { ok: true, matches: allHandles.length, elements };
 };
 //# sourceMappingURL=info.js.map

package/dist/cdp/dom/info.js.map

@@ -1 +1 @@
-{"version":3,"file":"info.js","sourceRoot":"","sources":["../../../src/cdp/dom/info.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAErH,MAAM,4BAA4B,GAAG,MAAM,CAAA;AAC3C,MAAM,oBAAoB,GAAG,OAAO,CAAA;AAcpC;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,EAAE,OAAyB,EAAE,OAA4B,EAA4B,EAAE;IACjI,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,KAAK,CAAA;IAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,iBAAiB,IAAI,4BAA4B,EAAE,CAAC,EAAE,oBAAoB,CAAC,CAAA;IAE1G,MAAM,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAA;IAEvC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAA;IAC1C,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,MAAM,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAElH,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAA;IAC9C,CAAC;IAED,MAAM,QAAQ,GAAqB,EAAE,CAAA;IAErC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,MAAM,cAAc,GAAG,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE;YACrE,MAAM;YACN,KAAK,EAAE,CAAC,EAAE,iCAAiC;SAC3C,CAAC,CAAsB,CAAA;QAExB,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;YAC1B,SAAQ;QACT,CAAC;QAED,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAA;QAChC,MAAM,UAAU,GAAG,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACtD,MAAM,iBAAiB,GAAG,oBAAoB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAE7D,IAAI,SAAS,GAAkB,IAAI,CAAA;QACnC,IAAI,kBAAkB,GAAG,KAAK,CAAA;QAE9B,IAAI,CAAC;YACJ,MAAM,UAAU,GAAG,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAuB,CAAA;YACpG,SAAS,GAAG,UAAU,CAAC,SAAS,IAAI,IAAI,CAAA;YAExC,IAAI,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;gBAC9C,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;gBACxC,kBAAkB,GAAG,IAAI,CAAA;YAC1B,CAAC;QACF,CAAC;QAAC,MAAM,CAAC;YACR,yDAAyD;QAC1D,CAAC;QAED,QAAQ,CAAC,IAAI,CAAC;YACb,MAAM;YACN,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE;YACpD,UAAU;YACV,iBAAiB;YACjB,SAAS;YACT,kBAAkB;SAClB,CAAC,CAAA;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAA;AAC1D,CAAC,CAAA"}
+{"version":3,"file":"info.js","sourceRoot":"","sources":["../../../src/cdp/dom/info.ts"],"names":[],"mappings":"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"}

package/dist/cdp/dom/selector.d.ts

@@ -1,5 +1,6 @@
 import type { CdpNode } from './types.js';
 import type { CdpSessionHandle } from '../connection.js';
+import type { ElementRefRegistry } from '../elementRefs.js';
 export type SelectorMatchResult = {
     /** All matched node IDs. */
     allNodeIds: number[];
@@ -12,6 +13,29 @@ export type ResolveSelectorTargetOptions = {
     text?: string;
     waitMs?: number;
 };
+export type ResolveElementTargetOptions = {
+    selector?: string;
+    ref?: string;
+    all: boolean;
+    text?: string;
+    waitMs?: number;
+};
+export type DomNodeHandle = {
+    nodeId?: number;
+    backendNodeId?: number;
+};
+export type ResolvedElementTarget = SelectorMatchResult & {
+    allHandles: DomNodeHandle[];
+    handles: DomNodeHandle[];
+    target: {
+        kind: 'selector';
+        value: string;
+    } | {
+        kind: 'ref';
+        value: string;
+    };
+    missingRef?: boolean;
+};
 export declare const getDomRootId: (session: CdpSessionHandle) => Promise<number>;
 export declare const resolveSelectorMatches: (session: CdpSessionHandle, rootId: number, selector: string, all: boolean, text?: string) => Promise<SelectorMatchResult>;
 /**
@@ -23,6 +47,17 @@ export declare const waitForSelectorMatches: (session: CdpSessionHandle, selecto
  * Enable the DOM domain, then resolve selector matches immediately or by polling for a bounded wait.
  */
 export declare const resolveSelectorTargets: (session: CdpSessionHandle, options: ResolveSelectorTargetOptions) => Promise<SelectorMatchResult>;
+export declare const resolveElementTargets: (session: CdpSessionHandle, elementRefs: ElementRefRegistry, options: ResolveElementTargetOptions) => Promise<ResolvedElementTarget>;
+/** Resolve the first node id matching a selector, or null when no match exists. */
+export declare const resolveFirstSelectorNodeId: (session: CdpSessionHandle, selector: string, text?: string) => Promise<number | null>;
+export declare const describeNodeByBackendId: (session: CdpSessionHandle, backendNodeId: number) => Promise<CdpNode | null>;
+export declare const resolveNodeIdByBackendId: (session: CdpSessionHandle, backendNodeId: number) => Promise<number | null>;
+export declare const resolveNodeIdForRef: (session: CdpSessionHandle, elementRefs: ElementRefRegistry, ref: string) => Promise<number | null>;
+export declare const toDomNodeDescriptor: (handle: DomNodeHandle) => {
+    nodeId: number;
+} | {
+    backendNodeId: number;
+};
 export declare const toAttributesRecord: (attributes?: string[]) => Record<string, string>;
 export declare const countElementChildren: (children?: CdpNode[]) => number;
 export declare const clamp: (value: number, min: number, max: number) => number;

package/dist/cdp/dom/selector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../../src/cdp/dom/selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAmBxD,MAAM,MAAM,mBAAmB,GAAG;IACjC,4BAA4B;IAC5B,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,iDAAiD;IACjD,OAAO,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,EAAE,OAAO,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,eAAO,MAAM,YAAY,GAAU,SAAS,gBAAgB,KAAG,OAAO,CAAC,MAAM,CAkC5E,CAAA;AAED,eAAO,MAAM,sBAAsB,GAClC,SAAS,gBAAgB,EACzB,QAAQ,MAAM,EACd,UAAU,MAAM,EAChB,KAAK,OAAO,EACZ,OAAO,MAAM,KACX,OAAO,CAAC,mBAAmB,CAa7B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAClC,SAAS,gBAAgB,EACzB,UAAU,MAAM,EAChB,KAAK,OAAO,EACZ,MAAM,MAAM,GAAG,SAAS,EACxB,QAAQ,MAAM,EACd,mBAAgB,KACd,OAAO,CAAC,mBAAmB,CAU7B,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,GAAU,SAAS,gBAAgB,EAAE,SAAS,4BAA4B,KAAG,OAAO,CAAC,mBAAmB,CAU1I,CAAA;AAMD,eAAO,MAAM,kBAAkB,GAAI,aAAa,MAAM,EAAE,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAc/E,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,WAAW,OAAO,EAAE,KAAG,MAK3D,CAAA;AAED,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,MAE/D,CAAA"}
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../../src/cdp/dom/selector.ts"],"names":[],"mappings":"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"}

package/dist/cdp/dom/selector.js

@@ -2,32 +2,9 @@ import { filterNodesByText } from '../text-filter.js';
 export const getDomRootId = async (session) => {
     const targetContext = session.getTargetContext?.();
     if (targetContext?.kind === 'frame') {
-        // Extension mode keeps one tab-level debugger session and switches the active frame via
-        // executionContextId. Resolving `document` in that context gives us the right DOM root.
-        if (targetContext.executionContextId == null) {
-            throw new Error(`Selected frame is not ready yet: ${targetContext.frameId}`);
-        }
-        const evaluated = (await session.sendAndWait('Runtime.evaluate', {
-            expression: 'document',
-            contextId: targetContext.executionContextId,
-            returnByValue: false,
-        }));
-        const objectId = evaluated.result?.objectId;
-        if (!objectId) {
-            throw new Error(`Unable to resolve document root for frame: ${targetContext.frameId}`);
-        }
-        const requested = (await session.sendAndWait('DOM.requestNode', { objectId }));
-        if (!requested.nodeId) {
-            throw new Error(`Unable to resolve DOM root for frame: ${targetContext.frameId}`);
-        }
-        return requested.nodeId;
-    }
-    const result = (await session.sendAndWait('DOM.getDocument', { depth: 1 }));
-    const rootId = result.root?.nodeId;
-    if (!rootId) {
-        throw new Error('Unable to resolve DOM root');
+        return getFrameDomRootId(session, targetContext);
     }
-    return rootId;
+    return getDocumentRootId(session);
 };
 export const resolveSelectorMatches = async (session, rootId, selector, all, text) => {
     // Always use querySelectorAll to get the true match count
@@ -69,6 +46,122 @@ export const resolveSelectorTargets = async (session, options) => {
     const rootId = await getDomRootId(session);
     return resolveSelectorMatches(session, rootId, options.selector, options.all, options.text);
 };
+export const resolveElementTargets = async (session, elementRefs, options) => {
+    await session.sendAndWait('DOM.enable');
+    if (options.ref) {
+        const backendNodeId = elementRefs.resolve(options.ref);
+        if (backendNodeId == null) {
+            return {
+                target: { kind: 'ref', value: options.ref },
+                allNodeIds: [],
+                nodeIds: [],
+                allHandles: [],
+                handles: [],
+                missingRef: true,
+            };
+        }
+        return {
+            target: { kind: 'ref', value: options.ref },
+            allNodeIds: [],
+            nodeIds: [],
+            allHandles: [{ backendNodeId }],
+            handles: [{ backendNodeId }],
+        };
+    }
+    if (!options.selector) {
+        throw new Error('selector or ref is required');
+    }
+    const result = (options.waitMs ?? 0) > 0
+        ? await waitForSelectorMatches(session, options.selector, options.all, options.text, options.waitMs ?? 0)
+        : await resolveSelectorMatches(session, await getDomRootId(session), options.selector, options.all, options.text);
+    return {
+        target: { kind: 'selector', value: options.selector },
+        allHandles: result.allNodeIds.map((nodeId) => ({ nodeId })),
+        handles: result.nodeIds.map((nodeId) => ({ nodeId })),
+        ...result,
+    };
+};
+/** Resolve the first node id matching a selector, or null when no match exists. */
+export const resolveFirstSelectorNodeId = async (session, selector, text) => {
+    const { nodeIds } = await resolveSelectorTargets(session, {
+        selector,
+        all: false,
+        text,
+    });
+    return nodeIds[0] ?? null;
+};
+export const describeNodeByBackendId = async (session, backendNodeId) => {
+    const described = (await session.sendAndWait('DOM.describeNode', {
+        backendNodeId,
+        depth: 0,
+    }));
+    return described.node ?? null;
+};
+export const resolveNodeIdByBackendId = async (session, backendNodeId) => {
+    const describedNode = await describeNodeByBackendId(session, backendNodeId);
+    if (describedNode?.nodeId) {
+        return describedNode.nodeId;
+    }
+    // Prime the document tree first so CDP can map backend ids back into frontend node ids.
+    await getDomRootId(session);
+    const pushed = (await session.sendAndWait('DOM.pushNodesByBackendIdsToFrontend', {
+        backendNodeIds: [backendNodeId],
+    }));
+    const nodeId = pushed.nodeIds?.[0];
+    return typeof nodeId === 'number' && nodeId > 0 ? nodeId : null;
+};
+export const resolveNodeIdForRef = async (session, elementRefs, ref) => {
+    const backendNodeId = elementRefs.resolve(ref);
+    if (backendNodeId == null) {
+        return null;
+    }
+    return resolveNodeIdByBackendId(session, backendNodeId);
+};
+export const toDomNodeDescriptor = (handle) => {
+    if (handle.nodeId != null) {
+        return { nodeId: handle.nodeId };
+    }
+    if (handle.backendNodeId != null) {
+        return { backendNodeId: handle.backendNodeId };
+    }
+    throw new Error('DOM node handle is missing both nodeId and backendNodeId');
+};
+/**
+ * Frame-scoped DOM commands are most reliable when they stay inside the frame's child CDP session.
+ * Extension mode already tracks that session id on the active target context, so prefer the normal
+ * DOM root lookup in that routed session and only fall back to the older Runtime/DOM bridge when a
+ * child session is not available.
+ */
+const getFrameDomRootId = async (session, targetContext) => {
+    if (targetContext.sessionId) {
+        return getDocumentRootId(session);
+    }
+    if (targetContext.executionContextId == null) {
+        throw new Error(`Selected frame is not ready yet: ${targetContext.frameId}`);
+    }
+    const evaluated = (await session.sendAndWait('Runtime.evaluate', {
+        expression: 'document',
+        contextId: targetContext.executionContextId,
+        returnByValue: false,
+    }));
+    const objectId = evaluated.result?.objectId;
+    if (!objectId) {
+        throw new Error(`Unable to resolve DOM root for frame: ${targetContext.frameId}`);
+    }
+    const requested = (await session.sendAndWait('DOM.requestNode', { objectId }));
+    if (!requested.nodeId) {
+        throw new Error(`Unable to resolve DOM root for frame: ${targetContext.frameId}`);
+    }
+    return requested.nodeId;
+};
+const getDocumentRootId = async (session) => {
+    const result = (await session.sendAndWait('DOM.getDocument', { depth: 1 }));
+    const rootId = result.root?.nodeId;
+    if (!rootId) {
+        throw new Error('Unable to resolve DOM root');
+    }
+    return rootId;
+};
 // ─────────────────────────────────────────────────────────────────────────────
 // Shared helpers
 // ─────────────────────────────────────────────────────────────────────────────