@rynx-ai/browser-cdp 0.1.11-beta.37 → 0.1.11-beta.39

package/dist/client.d.ts

@@ -40,7 +40,8 @@ export interface BrowserAutomationSnapshotNode {
     ignored: boolean;
     /**
      * Opaque, process-independent reference valid only for this endpoint's Page
-     * target and current document. A navigation or Browser restart invalidates it.
+     * tree (including OOPIF targets) and current document. A navigation or Browser
+     * restart invalidates it.
      */
     ref?: string;
     properties: Readonly<Record<string, string | number | boolean>>;
@@ -87,13 +88,15 @@ export declare class BrowserAutomationStaleReferenceError extends Error {
  *
  * It does not infer selectors or wait for application-specific readiness.
  * Snapshot refs can cross short-lived CLI processes, but are bound to the
- * endpoint, Page target, and current main-document loader.
+ * endpoint, owning Page/OOPIF target, and that target's current document.
  */
 export declare class BrowserAutomationClient {
     private readonly connection;
     private readonly pageSessionId;
+    private readonly pageTargetId;
     private readonly referenceScope;
     private readonly referenceKey;
+    private readonly iframeSessions;
     private documentGenerationValue;
     private accessibilityEnabled;
     private domEnabled;
@@ -108,12 +111,17 @@ export declare class BrowserAutomationClient {
     screenshot(options?: BrowserAutomationScreenshotOptions): Promise<BrowserAutomationScreenshot>;
     close(): void;
     private pageCall;
+    private targetCall;
+    private initializeIframeTracking;
+    private acceptAttachedIframe;
     private ensureDomEnabled;
     private snapshotNode;
     private resolveElement;
     private resolveObjectId;
     private currentDocumentIdentity;
     private elementCenter;
+    private targetForReference;
+    private pageCoordinates;
     private invalidateDocument;
     private assertOpen;
 }

package/dist/client.js

@@ -7,13 +7,23 @@ const MAX_SNAPSHOT_NODES = 10_000;
 const MAX_SELECTOR_CHARS = 4_096;
 const MAX_INPUT_TEXT_BYTES = 64 * 1024;
 const WEB_SOCKET_OPEN = 1;
-const REFERENCE_VERSION = 1;
+const REFERENCE_VERSION = 2;
 const REFERENCE_DOCUMENT_FINGERPRINT_BYTES = 12;
+const REFERENCE_TARGET_FINGERPRINT_BYTES = 12;
 const REFERENCE_BACKEND_NODE_BYTES = 8;
 const REFERENCE_TAG_BYTES = 16;
-const REFERENCE_PAYLOAD_BYTES = 1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES + REFERENCE_BACKEND_NODE_BYTES;
+const REFERENCE_PAYLOAD_BYTES = 1 +
+    REFERENCE_DOCUMENT_FINGERPRINT_BYTES +
+    REFERENCE_TARGET_FINGERPRINT_BYTES +
+    REFERENCE_BACKEND_NODE_BYTES;
 const REFERENCE_BYTES = REFERENCE_PAYLOAD_BYTES + REFERENCE_TAG_BYTES;
-const REFERENCE_DOMAIN = Buffer.from("rynx-browser-cdp-ref-v1\0", "utf8");
+const REFERENCE_DOMAIN = Buffer.from("rynx-browser-cdp-ref-v2\0", "utf8");
+const IFRAME_AUTO_ATTACH_PARAMS = {
+    autoAttach: true,
+    waitForDebuggerOnStart: false,
+    flatten: true,
+    filter: [{ type: "iframe" }, { exclude: true }],
+};
 export class BrowserAutomationError extends Error {
     code;
     name = "BrowserAutomationError";
@@ -35,24 +45,50 @@ export class BrowserAutomationStaleReferenceError extends Error {
  *
  * It does not infer selectors or wait for application-specific readiness.
  * Snapshot refs can cross short-lived CLI processes, but are bound to the
- * endpoint, Page target, and current main-document loader.
+ * endpoint, owning Page/OOPIF target, and that target's current document.
  */
 export class BrowserAutomationClient {
     connection;
     pageSessionId;
+    pageTargetId;
     referenceScope;
     referenceKey;
+    iframeSessions = new Map();
     documentGenerationValue = 1;
     accessibilityEnabled = false;
     domEnabled = false;
     closed = false;
-    constructor(connection, referenceScope, referenceKey, pageSessionId) {
+    constructor(connection, referenceScope, referenceKey, pageTargetId, pageSessionId) {
         this.connection = connection;
         this.referenceScope = referenceScope;
         this.referenceKey = referenceKey;
+        this.pageTargetId = pageTargetId;
         this.pageSessionId = pageSessionId;
         this.connection.onEvent((method, params, sessionId) => {
-            if (this.pageSessionId && sessionId && sessionId !== this.pageSessionId)
+            if (method === "Target.attachedToTarget") {
+                this.acceptAttachedIframe(params);
+                return;
+            }
+            if (method === "Target.detachedFromTarget") {
+                const detachedSessionId = stringAt(params, "sessionId");
+                if (detachedSessionId) {
+                    for (const [targetId, iframe] of this.iframeSessions) {
+                        if (iframe.sessionId !== detachedSessionId)
+                            continue;
+                        this.iframeSessions.delete(targetId);
+                        this.invalidateDocument();
+                        break;
+                    }
+                }
+                if (detachedSessionId === this.pageSessionId)
+                    this.invalidateDocument();
+                return;
+            }
+            const knownIframeSession = sessionId && [...this.iframeSessions.values()].some((iframe) => iframe.sessionId === sessionId);
+            if (this.pageSessionId &&
+                sessionId &&
+                sessionId !== this.pageSessionId &&
+                !knownIframeSession)
                 return;
             if (method === "DOM.documentUpdated") {
                 this.invalidateDocument();
@@ -64,9 +100,7 @@ export class BrowserAutomationClient {
                     this.invalidateDocument();
                 return;
             }
-            if (method === "Inspector.detached" ||
-                (method === "Target.detachedFromTarget" &&
-                    stringAt(params, "sessionId") === this.pageSessionId)) {
+            if (method === "Inspector.detached") {
                 this.invalidateDocument();
             }
         });
@@ -79,7 +113,9 @@ export class BrowserAutomationClient {
         const connection = await CdpConnection.connect(endpoint.href, timeoutMs, options.createWebSocket ?? defaultWebSocketFactory);
         try {
             if (endpointKind === "page") {
-                return new BrowserAutomationClient(connection, endpoint.href, referenceKey);
+                const client = new BrowserAutomationClient(connection, endpoint.href, referenceKey, pageTargetIdFromEndpoint(endpoint));
+                await client.initializeIframeTracking();
+                return client;
             }
             const targetId = await selectPageTarget(connection, options.pageTargetId);
             const attached = requireRecord(await connection.call("Target.attachToTarget", {
@@ -87,7 +123,9 @@ export class BrowserAutomationClient {
                 flatten: true,
             }), "Target.attachToTarget result");
             const sessionId = requiredString(attached.sessionId, "Target.attachToTarget sessionId");
-            return new BrowserAutomationClient(connection, `${endpoint.href}\0${targetId}`, referenceKey, sessionId);
+            const client = new BrowserAutomationClient(connection, `${endpoint.href}\0${targetId}`, referenceKey, targetId, sessionId);
+            await client.initializeIframeTracking();
+            return client;
         }
         catch (error) {
             connection.close();
@@ -107,20 +145,45 @@ export class BrowserAutomationClient {
             await this.pageCall("Accessibility.enable");
             this.accessibilityEnabled = true;
         }
-        const documentIdentity = await this.currentDocumentIdentity();
-        const result = requireRecord(await this.pageCall("Accessibility.getFullAXTree"), "Accessibility.getFullAXTree result");
-        if (!Array.isArray(result.nodes)) {
-            throw protocolError("Accessibility.getFullAXTree result nodes must be an array");
-        }
-        if (result.nodes.length > MAX_SNAPSHOT_NODES) {
-            throw protocolError(`Accessibility snapshot exceeds ${MAX_SNAPSHOT_NODES} nodes`);
-        }
-        if ((await this.currentDocumentIdentity()) !== documentIdentity) {
-            throw protocolError("Browser document changed while taking the accessibility snapshot");
+        await Promise.all([...this.iframeSessions.values()].map((iframe) => iframe.ready));
+        const targets = [
+            { targetId: this.pageTargetId, sessionId: this.pageSessionId },
+            ...[...this.iframeSessions.values()].map((iframe) => ({
+                targetId: iframe.targetId,
+                sessionId: iframe.sessionId,
+            })),
+        ];
+        const nodes = [];
+        for (const target of targets) {
+            try {
+                const documentIdentity = await this.currentDocumentIdentity(target.sessionId);
+                const result = requireRecord(await this.targetCall("Accessibility.getFullAXTree", {}, target.sessionId), "Accessibility.getFullAXTree result");
+                if (!Array.isArray(result.nodes)) {
+                    throw protocolError("Accessibility.getFullAXTree result nodes must be an array");
+                }
+                if (nodes.length + result.nodes.length > MAX_SNAPSHOT_NODES) {
+                    throw protocolError(`Accessibility snapshot exceeds ${MAX_SNAPSHOT_NODES} nodes`);
+                }
+                if ((await this.currentDocumentIdentity(target.sessionId)) !== documentIdentity) {
+                    throw protocolError("Browser document changed while taking the accessibility snapshot");
+                }
+                nodes.push(...result.nodes.map((value, index) => this.snapshotNode(value, index, documentIdentity, target.targetId)));
+            }
+            catch (error) {
+                if (target.targetId === this.pageTargetId)
+                    throw error;
+                // OOPIFs can detach while their parent remains stable. Skip only that
+                // stale frame; the next snapshot will discover its replacement target.
+                if (!isDetachedIframeError(error))
+                    throw error;
+                if (this.iframeSessions.get(target.targetId)?.sessionId === target.sessionId) {
+                    this.iframeSessions.delete(target.targetId);
+                }
+            }
         }
         return {
             documentGeneration: this.documentGenerationValue,
-            nodes: result.nodes.map((value, index) => this.snapshotNode(value, index, documentIdentity)),
+            nodes,
         };
     }
     async navigate(url) {
@@ -146,7 +209,7 @@ export class BrowserAutomationClient {
         const element = "x" in target ? undefined : await this.resolveElement(target);
         try {
             const point = element
-                ? await this.elementCenter(element)
+                ? await this.pageCoordinates(element, await this.elementCenter(element))
                 : coordinateTarget(target);
             await this.pageCall("Input.dispatchMouseEvent", {
                 type: "mouseMoved",
@@ -174,9 +237,7 @@ export class BrowserAutomationClient {
         }
         finally {
             if (element?.objectId) {
-                await this.pageCall("Runtime.releaseObject", {
-                    objectId: element.objectId,
-                }).catch(() => undefined);
+                await this.targetCall("Runtime.releaseObject", { objectId: element.objectId }, element.sessionId).catch(() => undefined);
             }
         }
     }
@@ -190,18 +251,18 @@ export class BrowserAutomationClient {
         await this.ensureDomEnabled();
         const objectId = element.objectId ?? await this.resolveObjectId(element);
         try {
-            const focused = requireRecord(await this.pageCall("Runtime.callFunctionOn", {
+            const focused = requireRecord(await this.targetCall("Runtime.callFunctionOn", {
                 objectId,
                 functionDeclaration: "function() { this.focus(); }",
                 returnByValue: true,
-            }), "Runtime.callFunctionOn result");
+            }, element.sessionId), "Runtime.callFunctionOn result");
             if (focused.exceptionDetails !== undefined) {
                 throw protocolError("Browser element could not be focused");
             }
             await this.pageCall("Input.insertText", { text });
         }
         finally {
-            await this.pageCall("Runtime.releaseObject", { objectId }).catch(() => undefined);
+            await this.targetCall("Runtime.releaseObject", { objectId }, element.sessionId).catch(() => undefined);
         }
     }
     async screenshot(options = {}) {
@@ -247,15 +308,48 @@ export class BrowserAutomationClient {
     async pageCall(method, params = {}) {
         return await this.connection.call(method, params, this.pageSessionId);
     }
+    async targetCall(method, params, sessionId) {
+        // A browser endpoint needs the attached main Page session on ordinary DOM
+        // operations. Only OOPIF elements override it with their child session.
+        return await this.connection.call(method, params, sessionId ?? this.pageSessionId);
+    }
+    async initializeIframeTracking() {
+        await this.pageCall("Target.setAutoAttach", IFRAME_AUTO_ATTACH_PARAMS);
+        await Promise.all([...this.iframeSessions.values()].map((iframe) => iframe.ready));
+    }
+    acceptAttachedIframe(params) {
+        const targetInfo = recordAt(params, "targetInfo");
+        const targetId = targetInfo && stringAt(targetInfo, "targetId");
+        const childSessionId = stringAt(params, "sessionId");
+        if (!targetInfo || targetInfo.type !== "iframe" || !targetId || !childSessionId)
+            return;
+        const existing = this.iframeSessions.get(targetId);
+        if (existing?.sessionId === childSessionId)
+            return;
+        let iframe;
+        const ready = (async () => {
+            await this.targetCall("DOM.enable", {}, childSessionId);
+            await this.targetCall("Accessibility.enable", {}, childSessionId);
+            await this.targetCall("Target.setAutoAttach", IFRAME_AUTO_ATTACH_PARAMS, childSessionId);
+        })().catch(() => {
+            if (this.iframeSessions.get(targetId) === iframe) {
+                this.iframeSessions.delete(targetId);
+            }
+        });
+        iframe = { targetId, sessionId: childSessionId, ready };
+        this.iframeSessions.set(targetId, iframe);
+        this.invalidateDocument();
+    }
     async ensureDomEnabled() {
         if (this.domEnabled)
             return;
         await this.pageCall("DOM.enable");
         this.domEnabled = true;
     }
-    snapshotNode(value, index, documentIdentity) {
+    snapshotNode(value, index, documentIdentity, targetId) {
         const node = requireRecord(value, `Accessibility node ${index}`);
-        const nodeId = requiredString(node.nodeId, `Accessibility node ${index} nodeId`);
+        const rawNodeId = requiredString(node.nodeId, `Accessibility node ${index} nodeId`);
+        const nodeId = scopedNodeId(targetId, rawNodeId);
         const backendNodeId = positiveInteger(node.backendDOMNodeId);
         const ignored = node.ignored === true;
         const role = axString(node.role);
@@ -264,17 +358,17 @@ export class BrowserAutomationClient {
         const childIds = rawChildIds === undefined
             ? []
             : Array.isArray(rawChildIds)
-                ? rawChildIds.map((child, childIndex) => requiredString(child, `Accessibility node ${index} childIds[${childIndex}]`))
+                ? rawChildIds.map((child, childIndex) => scopedNodeId(targetId, requiredString(child, `Accessibility node ${index} childIds[${childIndex}]`)))
                 : (() => {
                     throw protocolError(`Accessibility node ${index} childIds must be an array`);
                 })();
         const ref = !ignored && backendNodeId !== undefined
-            ? encodeElementReference(this.referenceScope, documentIdentity, backendNodeId, this.referenceKey)
+            ? encodeElementReference(this.referenceScope, targetId, documentIdentity, backendNodeId, this.referenceKey)
             : undefined;
         return {
             nodeId,
             ...(optionalString(node.parentId)
-                ? { parentId: optionalString(node.parentId) }
+                ? { parentId: scopedNodeId(targetId, optionalString(node.parentId)) }
                 : {}),
             childIds,
             role,
@@ -295,12 +389,17 @@ export class BrowserAutomationClient {
         if ("ref" in target) {
             if (typeof target.ref !== "string")
                 throw invalidInput("ref must be a string");
-            const documentIdentity = await this.currentDocumentIdentity();
-            const backendNodeId = decodeElementReference(target.ref, this.referenceScope, documentIdentity, this.referenceKey);
+            const decoded = decodeElementReference(target.ref, this.referenceKey);
+            const targetSession = await this.targetForReference(target.ref, decoded);
             try {
+                const element = {
+                    backendNodeId: decoded.backendNodeId,
+                    targetId: targetSession.targetId,
+                    ...(targetSession.sessionId ? { sessionId: targetSession.sessionId } : {}),
+                };
                 return {
-                    backendNodeId,
-                    objectId: await this.resolveObjectId({ backendNodeId }),
+                    ...element,
+                    objectId: await this.resolveObjectId(element),
                 };
             }
             catch (error) {
@@ -332,12 +431,12 @@ export class BrowserAutomationClient {
         return { nodeId };
     }
     async resolveObjectId(element) {
-        const resolved = requireRecord(await this.pageCall("DOM.resolveNode", domLocator(element)), "DOM.resolveNode result");
+        const resolved = requireRecord(await this.targetCall("DOM.resolveNode", domLocator(element), element.sessionId), "DOM.resolveNode result");
         const object = requireRecord(resolved.object, "DOM.resolveNode object");
         return requiredString(object.objectId, "DOM.resolveNode objectId");
     }
-    async currentDocumentIdentity() {
-        const result = requireRecord(await this.pageCall("Page.getFrameTree"), "Page.getFrameTree result");
+    async currentDocumentIdentity(sessionId = this.pageSessionId) {
+        const result = requireRecord(await this.targetCall("Page.getFrameTree", {}, sessionId), "Page.getFrameTree result");
         const frameTree = requireRecord(result.frameTree, "Page.getFrameTree frameTree");
         const frame = requireRecord(frameTree.frame, "Page.getFrameTree frame");
         return requiredString(frame.loaderId, "Page.getFrameTree loaderId");
@@ -345,8 +444,8 @@ export class BrowserAutomationClient {
     async elementCenter(element) {
         await this.ensureDomEnabled();
         const locator = domLocator(element);
-        await this.pageCall("DOM.scrollIntoViewIfNeeded", locator);
-        const result = requireRecord(await this.pageCall("DOM.getBoxModel", locator), "DOM.getBoxModel result");
+        await this.targetCall("DOM.scrollIntoViewIfNeeded", locator, element.sessionId);
+        const result = requireRecord(await this.targetCall("DOM.getBoxModel", locator, element.sessionId), "DOM.getBoxModel result");
         const model = requireRecord(result.model, "DOM.getBoxModel model");
         const quad = numericQuad(model.content ?? model.border);
         return {
@@ -354,6 +453,60 @@ export class BrowserAutomationClient {
             y: (quad[1] + quad[3] + quad[5] + quad[7]) / 4,
         };
     }
+    async targetForReference(ref, decoded) {
+        await Promise.all([...this.iframeSessions.values()].map((iframe) => iframe.ready));
+        const candidates = [
+            { targetId: this.pageTargetId, sessionId: this.pageSessionId },
+            ...[...this.iframeSessions.values()].map((iframe) => ({
+                targetId: iframe.targetId,
+                sessionId: iframe.sessionId,
+            })),
+        ];
+        const selected = candidates.find((candidate) => timingSafeEqual(targetFingerprint(this.referenceScope, candidate.targetId), decoded.targetFingerprint));
+        if (!selected)
+            throw new BrowserAutomationStaleReferenceError(ref);
+        const documentIdentity = await this.currentDocumentIdentity(selected.sessionId);
+        const expectedDocument = documentFingerprint(this.referenceScope, selected.targetId, documentIdentity);
+        if (!timingSafeEqual(decoded.documentFingerprint, expectedDocument)) {
+            throw new BrowserAutomationStaleReferenceError(ref);
+        }
+        return selected;
+    }
+    async pageCoordinates(element, local) {
+        if (!element.sessionId || !element.targetId)
+            return local;
+        try {
+            const targetInfoResult = requireRecord(await this.pageCall("Target.getTargetInfo", { targetId: element.targetId }), "Target.getTargetInfo result");
+            const targetInfo = requireRecord(targetInfoResult.targetInfo, "Target.getTargetInfo targetInfo");
+            const targetUrl = optionalString(targetInfo.url);
+            const framesResult = requireRecord(await this.pageCall("Runtime.evaluate", {
+                expression: `(() => Array.from(document.querySelectorAll('iframe,frame'), frame => {
+            const rect = frame.getBoundingClientRect();
+            return { x: rect.x, y: rect.y, src: frame.src || '' };
+          }))()`,
+                returnByValue: true,
+            }), "Runtime.evaluate result");
+            const result = requireRecord(framesResult.result, "Runtime.evaluate result result");
+            const frames = Array.isArray(result.value)
+                ? result.value.filter((value) => isRecord(value))
+                : [];
+            const exact = targetUrl
+                ? frames.find((frame) => frame.src === targetUrl)
+                : undefined;
+            const originMatch = !exact && targetUrl
+                ? frames.find((frame) => sameUrlOrigin(optionalString(frame.src), targetUrl))
+                : undefined;
+            const frame = exact ?? originMatch ?? (frames.length === 1 ? frames[0] : undefined);
+            if (frame && typeof frame.x === "number" && typeof frame.y === "number") {
+                return { x: local.x + frame.x, y: local.y + frame.y };
+            }
+        }
+        catch {
+            // The iframe may have navigated while resolving its parent offset. The
+            // local coordinates remain the best bounded fallback.
+        }
+        return local;
+    }
     invalidateDocument() {
         this.documentGenerationValue += 1;
     }
@@ -397,8 +550,8 @@ class CdpConnection {
         }
         await new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
-                socket.close(1000, "connection timeout");
                 reject(new BrowserAutomationError(`CDP WebSocket did not open within ${timeoutMs}ms`, "timeout"));
+                socket.close(1000, "connection timeout");
             }, timeoutMs);
             socket.onopen = () => {
                 clearTimeout(timer);
@@ -571,15 +724,16 @@ function defaultWebSocketFactory(endpoint) {
     }
     return new Constructor(endpoint);
 }
-function encodeElementReference(referenceScope, documentIdentity, backendNodeId, referenceKey) {
+function encodeElementReference(referenceScope, targetId, documentIdentity, backendNodeId, referenceKey) {
     const payload = Buffer.alloc(REFERENCE_PAYLOAD_BYTES);
     payload[0] = REFERENCE_VERSION;
-    documentFingerprint(referenceScope, documentIdentity).copy(payload, 1);
-    payload.writeBigUInt64BE(BigInt(backendNodeId), 1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES);
+    documentFingerprint(referenceScope, targetId, documentIdentity).copy(payload, 1);
+    targetFingerprint(referenceScope, targetId).copy(payload, 1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES);
+    payload.writeBigUInt64BE(BigInt(backendNodeId), 1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES + REFERENCE_TARGET_FINGERPRINT_BYTES);
     const tag = referenceTag(payload, referenceKey);
     return Buffer.concat([payload, tag]).toString("base64url");
 }
-function decodeElementReference(ref, referenceScope, documentIdentity, referenceKey) {
+function decodeElementReference(ref, referenceKey) {
     if (typeof ref !== "string" ||
         ref.length === 0 ||
         !/^[A-Za-z0-9_-]+$/.test(ref)) {
@@ -602,26 +756,38 @@ function decodeElementReference(ref, referenceScope, documentIdentity, reference
     if (!timingSafeEqual(actualTag, referenceTag(payload, referenceKey))) {
         throw new BrowserAutomationStaleReferenceError(ref);
     }
-    const expectedDocument = documentFingerprint(referenceScope, documentIdentity);
-    const actualDocument = payload.subarray(1, 1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES);
-    if (!timingSafeEqual(actualDocument, expectedDocument)) {
-        throw new BrowserAutomationStaleReferenceError(ref);
-    }
-    const rawNodeId = payload.readBigUInt64BE(1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES);
+    const actualDocument = Buffer.from(payload.subarray(1, 1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES));
+    const actualTarget = Buffer.from(payload.subarray(1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES, 1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES + REFERENCE_TARGET_FINGERPRINT_BYTES));
+    const rawNodeId = payload.readBigUInt64BE(1 + REFERENCE_DOCUMENT_FINGERPRINT_BYTES + REFERENCE_TARGET_FINGERPRINT_BYTES);
     if (rawNodeId < 1n || rawNodeId > BigInt(Number.MAX_SAFE_INTEGER)) {
         throw new BrowserAutomationStaleReferenceError(ref);
     }
-    return Number(rawNodeId);
+    return {
+        documentFingerprint: actualDocument,
+        targetFingerprint: actualTarget,
+        backendNodeId: Number(rawNodeId),
+    };
 }
-function documentFingerprint(referenceScope, documentIdentity) {
+function documentFingerprint(referenceScope, targetId, documentIdentity) {
     return createHash("sha256")
-        .update("rynx-browser-cdp-document-v1\0")
+        .update("rynx-browser-cdp-document-v2\0")
         .update(referenceScope)
         .update("\0")
+        .update(targetId)
+        .update("\0")
         .update(documentIdentity)
         .digest()
         .subarray(0, REFERENCE_DOCUMENT_FINGERPRINT_BYTES);
 }
+function targetFingerprint(referenceScope, targetId) {
+    return createHash("sha256")
+        .update("rynx-browser-cdp-target-v2\0")
+        .update(referenceScope)
+        .update("\0")
+        .update(targetId)
+        .digest()
+        .subarray(0, REFERENCE_TARGET_FINGERPRINT_BYTES);
+}
 function referenceTag(payload, referenceKey) {
     return createHmac("sha256", referenceKey)
         .update(REFERENCE_DOMAIN)
@@ -676,6 +842,40 @@ function inferEndpointKind(endpoint) {
         return "page";
     throw invalidInput("endpointKind is required for a non-standard CDP WebSocket path");
 }
+function pageTargetIdFromEndpoint(endpoint) {
+    const prefix = "/devtools/page/";
+    if (!endpoint.pathname.startsWith(prefix)) {
+        throw invalidInput("page endpoint must identify one CDP Page target");
+    }
+    const targetId = endpoint.pathname.slice(prefix.length);
+    if (targetId.length === 0 || targetId.includes("/")) {
+        throw invalidInput("page endpoint must identify one CDP Page target");
+    }
+    return targetId;
+}
+function scopedNodeId(targetId, nodeId) {
+    const target = createHash("sha256")
+        .update("rynx-browser-cdp-node-scope-v1\0")
+        .update(targetId)
+        .digest("base64url")
+        .slice(0, 12);
+    return `${target}:${nodeId}`;
+}
+function sameUrlOrigin(candidate, target) {
+    if (!candidate)
+        return false;
+    try {
+        return new URL(candidate).origin === new URL(target).origin;
+    }
+    catch {
+        return false;
+    }
+}
+function isDetachedIframeError(error) {
+    return error instanceof BrowserAutomationError &&
+        error.code === "protocol" &&
+        /(?:no session|session.*not found|target.*(?:closed|not found)|not attached)/i.test(error.message);
+}
 function parseNavigationUrl(value) {
     if (value === "about:blank")
         return value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/browser-cdp",
-  "version": "0.1.11-beta.37",
+  "version": "0.1.11-beta.39",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rynx-ai/rynx.git",