@browserbasehq/orca 3.1.0-patch.3 → 3.2.0-preview.1

package/dist/cjs/lib/v3/understudy/frameLocator.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrameLocator = void 0;
+exports.frameLocatorFromFrame = frameLocatorFromFrame;
+const executionContextRegistry_js_1 = require("./executionContextRegistry.js");
+const sdkErrors_js_1 = require("../types/public/sdkErrors.js");
+/**
+ * FrameLocator: resolves iframe elements to their child Frames and allows
+ * creating locators scoped to that frame. Supports chaining.
+ */
+class FrameLocator {
+    parent;
+    selector;
+    page;
+    root;
+    constructor(page, selector, parent, root) {
+        this.page = page;
+        this.selector = selector;
+        this.parent = parent;
+        this.root = root;
+    }
+    /** Create a nested FrameLocator under this one. */
+    frameLocator(selector) {
+        return new FrameLocator(this.page, selector, this);
+    }
+    /** Resolve to the concrete Frame for this FrameLocator chain. */
+    async resolveFrame() {
+        const parentFrame = this.parent
+            ? await this.parent.resolveFrame()
+            : (this.root ?? this.page.mainFrame());
+        // Resolve the iframe element inside the parent frame
+        const tmp = parentFrame.locator(this.selector);
+        const parentSession = parentFrame.session;
+        const { objectId } = await tmp.resolveNode();
+        try {
+            await parentSession.send("DOM.enable").catch(() => { });
+            const desc = await parentSession.send("DOM.describeNode", { objectId });
+            const iframeBackendNodeId = desc.node.backendNodeId;
+            // Find direct child frames under the parent by consulting the Page's registry
+            const childIds = await listDirectChildFrameIdsFromRegistry(this.page, parentFrame.frameId, 1000);
+            for (const fid of childIds) {
+                try {
+                    const owner = await parentSession.send("DOM.getFrameOwner", { frameId: fid });
+                    if (owner.backendNodeId === iframeBackendNodeId) {
+                        // Ensure child frame is ready (handles OOPIF adoption or same-process)
+                        await ensureChildFrameReady(this.page, parentFrame, fid, 1200);
+                        return this.page.frameForId(fid);
+                    }
+                }
+                catch {
+                    // ignore and try next
+                }
+            }
+            throw new sdkErrors_js_1.ContentFrameNotFoundError(this.selector);
+        }
+        finally {
+            await parentSession
+                .send("Runtime.releaseObject", { objectId })
+                .catch(() => { });
+        }
+    }
+    /** Return a Locator scoped to this frame. Methods delegate to the frame lazily. */
+    locator(selector) {
+        return new LocatorDelegate(this, selector);
+    }
+}
+exports.FrameLocator = FrameLocator;
+/** A small delegating wrapper that resolves the frame lazily per call. */
+class LocatorDelegate {
+    fl;
+    sel;
+    nthIndex;
+    constructor(fl, sel, nthIndex = -1) {
+        this.fl = fl;
+        this.sel = sel;
+        this.nthIndex = nthIndex;
+    }
+    async real() {
+        const frame = await this.fl.resolveFrame();
+        const locator = frame.locator(this.sel);
+        if (this.nthIndex < 0)
+            return locator;
+        return locator.nth(this.nthIndex);
+    }
+    // Locator API delegates
+    async click(options) {
+        return (await this.real()).click(options);
+    }
+    async hover() {
+        return (await this.real()).hover();
+    }
+    async fill(value) {
+        return (await this.real()).fill(value);
+    }
+    async type(text, options) {
+        return (await this.real()).type(text, options);
+    }
+    async selectOption(values) {
+        return (await this.real()).selectOption(values);
+    }
+    async scrollTo(percent) {
+        return (await this.real()).scrollTo(percent);
+    }
+    async isVisible() {
+        return (await this.real()).isVisible();
+    }
+    async isChecked() {
+        return (await this.real()).isChecked();
+    }
+    async inputValue() {
+        return (await this.real()).inputValue();
+    }
+    async textContent() {
+        return (await this.real()).textContent();
+    }
+    async innerHtml() {
+        return (await this.real()).innerHtml();
+    }
+    async innerText() {
+        return (await this.real()).innerText();
+    }
+    async count() {
+        return (await this.real()).count();
+    }
+    first() {
+        return this.nth(0);
+    }
+    nth(index) {
+        const value = Number(index);
+        if (!Number.isFinite(value) || value < 0) {
+            throw new sdkErrors_js_1.StagehandInvalidArgumentError("locator().nth() expects a non-negative index");
+        }
+        const nextIndex = Math.floor(value);
+        if (nextIndex === this.nthIndex)
+            return this;
+        return new LocatorDelegate(this.fl, this.sel, nextIndex);
+    }
+}
+/** Factory to start a FrameLocator chain from an arbitrary root Frame. */
+function frameLocatorFromFrame(page, root, selector) {
+    return new FrameLocator(page, selector, undefined, root);
+}
+async function listDirectChildFrameIdsFromRegistry(page, parentFrameId, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        try {
+            const tree = page.getFullFrameTree();
+            const node = findFrameNode(tree, parentFrameId);
+            const ids = node?.childFrames?.map((c) => c.frame.id) ?? [];
+            if (ids.length > 0 || Date.now() >= deadline)
+                return ids;
+        }
+        catch {
+            // ignore
+        }
+        await new Promise((r) => setTimeout(r, 50));
+    }
+}
+function findFrameNode(tree, targetId) {
+    if (tree.frame.id === targetId)
+        return tree;
+    for (const c of tree.childFrames ?? []) {
+        const hit = findFrameNode(c, targetId);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/**
+ * Ensure we can evaluate in the child frame with minimal delay.
+ * - If the child is same-process: parent session owns it and main world appears quickly.
+ * - If OOPIF and adoption not finished: wait briefly for ownership change, then main world.
+ */
+async function ensureChildFrameReady(page, parentFrame, childFrameId, budgetMs) {
+    const parentSession = parentFrame.session;
+    const deadline = Date.now() + Math.max(0, budgetMs);
+    // If already owned by a different session (OOPIF adopted), wait briefly there.
+    const owner = page.getSessionForFrame(childFrameId);
+    if (owner && owner !== parentSession) {
+        try {
+            await executionContextRegistry_js_1.executionContexts.waitForMainWorld(owner, childFrameId, 600);
+        }
+        catch {
+            // best effort
+        }
+        return;
+    }
+    const hasMainWorldOnParent = () => {
+        try {
+            return (executionContextRegistry_js_1.executionContexts.getMainWorld(parentSession, childFrameId) !== null);
+        }
+        catch {
+            return false;
+        }
+    };
+    if (hasMainWorldOnParent())
+        return;
+    await parentSession
+        .send("Page.setLifecycleEventsEnabled", { enabled: true })
+        .catch(() => { });
+    await parentSession.send("Runtime.enable").catch(() => { });
+    await new Promise((resolve) => {
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            parentSession.off("Page.lifecycleEvent", onLifecycle);
+            resolve();
+        };
+        const onLifecycle = (evt) => {
+            if (evt.frameId !== childFrameId ||
+                (evt.name !== "DOMContentLoaded" &&
+                    evt.name !== "load" &&
+                    evt.name !== "networkIdle" &&
+                    evt.name !== "networkidle")) {
+                return;
+            }
+            if (hasMainWorldOnParent())
+                return finish();
+            try {
+                const nowOwner = page.getSessionForFrame(childFrameId);
+                if (nowOwner && nowOwner !== parentSession) {
+                    const left = Math.max(150, deadline - Date.now());
+                    executionContextRegistry_js_1.executionContexts
+                        .waitForMainWorld(nowOwner, childFrameId, left)
+                        .finally(finish);
+                }
+            }
+            catch {
+                // ignore
+            }
+        };
+        parentSession.on("Page.lifecycleEvent", onLifecycle);
+        const tick = () => {
+            if (done)
+                return;
+            if (hasMainWorldOnParent())
+                return finish();
+            try {
+                const nowOwner = page.getSessionForFrame(childFrameId);
+                if (nowOwner && nowOwner !== parentSession) {
+                    const left = Math.max(150, deadline - Date.now());
+                    executionContextRegistry_js_1.executionContexts
+                        .waitForMainWorld(nowOwner, childFrameId, left)
+                        .finally(finish);
+                    return;
+                }
+            }
+            catch {
+                // ignore
+            }
+            if (Date.now() >= deadline)
+                return finish();
+            setTimeout(tick, 50);
+        };
+        tick();
+    });
+}
+//# sourceMappingURL=frameLocator.js.map

package/dist/cjs/lib/v3/understudy/frameLocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frameLocator.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/frameLocator.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport { Locator } from \"./locator.js\";\nimport type { Page } from \"./page.js\";\nimport { Frame } from \"./frame.js\";\nimport { executionContexts } from \"./executionContextRegistry.js\";\nimport {\n  ContentFrameNotFoundError,\n  StagehandInvalidArgumentError,\n} from \"../types/public/sdkErrors.js\";\n\n/**\n * FrameLocator: resolves iframe elements to their child Frames and allows\n * creating locators scoped to that frame. Supports chaining.\n */\nexport class FrameLocator {\n  private readonly parent?: FrameLocator;\n  private readonly selector: string;\n  private readonly page: Page;\n  private readonly root?: Frame;\n\n  constructor(\n    page: Page,\n    selector: string,\n    parent?: FrameLocator,\n    root?: Frame,\n  ) {\n    this.page = page;\n    this.selector = selector;\n    this.parent = parent;\n    this.root = root;\n  }\n\n  /** Create a nested FrameLocator under this one. */\n  frameLocator(selector: string): FrameLocator {\n    return new FrameLocator(this.page, selector, this);\n  }\n\n  /** Resolve to the concrete Frame for this FrameLocator chain. */\n  async resolveFrame(): Promise<Frame> {\n    const parentFrame: Frame = this.parent\n      ? await this.parent.resolveFrame()\n      : (this.root ?? this.page.mainFrame());\n\n    // Resolve the iframe element inside the parent frame\n    const tmp = parentFrame.locator(this.selector);\n    const parentSession = parentFrame.session;\n    const { objectId } = await tmp.resolveNode();\n\n    try {\n      await parentSession.send(\"DOM.enable\").catch(() => {});\n      const desc = await parentSession.send<Protocol.DOM.DescribeNodeResponse>(\n        \"DOM.describeNode\",\n        { objectId },\n      );\n      const iframeBackendNodeId = desc.node.backendNodeId;\n\n      // Find direct child frames under the parent by consulting the Page's registry\n      const childIds = await listDirectChildFrameIdsFromRegistry(\n        this.page,\n        parentFrame.frameId,\n        1000,\n      );\n\n      for (const fid of childIds) {\n        try {\n          const owner = await parentSession.send<{\n            backendNodeId: Protocol.DOM.BackendNodeId;\n            nodeId?: Protocol.DOM.NodeId;\n          }>(\"DOM.getFrameOwner\", { frameId: fid as Protocol.Page.FrameId });\n          if (owner.backendNodeId === iframeBackendNodeId) {\n            // Ensure child frame is ready (handles OOPIF adoption or same-process)\n            await ensureChildFrameReady(this.page, parentFrame, fid, 1200);\n            return this.page.frameForId(fid);\n          }\n        } catch {\n          // ignore and try next\n        }\n      }\n      throw new ContentFrameNotFoundError(this.selector);\n    } finally {\n      await parentSession\n        .send(\"Runtime.releaseObject\", { objectId })\n        .catch(() => {});\n    }\n  }\n\n  /** Return a Locator scoped to this frame. Methods delegate to the frame lazily. */\n  locator(selector: string): LocatorDelegate {\n    return new LocatorDelegate(this, selector);\n  }\n}\n\n/** A small delegating wrapper that resolves the frame lazily per call. */\nclass LocatorDelegate {\n  constructor(\n    private readonly fl: FrameLocator,\n    private readonly sel: string,\n    private readonly nthIndex: number = -1,\n  ) {}\n\n  private async real(): Promise<Locator> {\n    const frame = await this.fl.resolveFrame();\n    const locator = frame.locator(this.sel);\n    if (this.nthIndex < 0) return locator;\n    return locator.nth(this.nthIndex);\n  }\n\n  // Locator API delegates\n  async click(options?: {\n    button?: \"left\" | \"right\" | \"middle\";\n    clickCount?: number;\n  }) {\n    return (await this.real()).click(options);\n  }\n  async hover() {\n    return (await this.real()).hover();\n  }\n  async fill(value: string) {\n    return (await this.real()).fill(value);\n  }\n  async type(text: string, options?: { delay?: number }) {\n    return (await this.real()).type(text, options);\n  }\n  async selectOption(values: string | string[]) {\n    return (await this.real()).selectOption(values);\n  }\n  async scrollTo(percent: number | string) {\n    return (await this.real()).scrollTo(percent);\n  }\n  async isVisible() {\n    return (await this.real()).isVisible();\n  }\n  async isChecked() {\n    return (await this.real()).isChecked();\n  }\n  async inputValue() {\n    return (await this.real()).inputValue();\n  }\n  async textContent() {\n    return (await this.real()).textContent();\n  }\n  async innerHtml() {\n    return (await this.real()).innerHtml();\n  }\n  async innerText() {\n    return (await this.real()).innerText();\n  }\n  async count() {\n    return (await this.real()).count();\n  }\n  first(): LocatorDelegate {\n    return this.nth(0);\n  }\n  nth(index: number): LocatorDelegate {\n    const value = Number(index);\n    if (!Number.isFinite(value) || value < 0) {\n      throw new StagehandInvalidArgumentError(\n        \"locator().nth() expects a non-negative index\",\n      );\n    }\n\n    const nextIndex = Math.floor(value);\n    if (nextIndex === this.nthIndex) return this;\n\n    return new LocatorDelegate(this.fl, this.sel, nextIndex);\n  }\n}\n\n/** Factory to start a FrameLocator chain from an arbitrary root Frame. */\nexport function frameLocatorFromFrame(\n  page: Page,\n  root: Frame,\n  selector: string,\n): FrameLocator {\n  return new FrameLocator(page, selector, undefined, root);\n}\n\nasync function listDirectChildFrameIdsFromRegistry(\n  page: Page,\n  parentFrameId: string,\n  timeoutMs: number,\n): Promise<string[]> {\n  const deadline = Date.now() + timeoutMs;\n  while (true) {\n    try {\n      const tree = page.getFullFrameTree();\n      const node = findFrameNode(tree, parentFrameId);\n      const ids = node?.childFrames?.map((c) => c.frame.id as string) ?? [];\n      if (ids.length > 0 || Date.now() >= deadline) return ids;\n    } catch {\n      // ignore\n    }\n    await new Promise((r) => setTimeout(r, 50));\n  }\n}\n\nfunction findFrameNode(\n  tree: Protocol.Page.FrameTree,\n  targetId: string,\n): Protocol.Page.FrameTree | undefined {\n  if (tree.frame.id === targetId) return tree;\n  for (const c of tree.childFrames ?? []) {\n    const hit = findFrameNode(c, targetId);\n    if (hit) return hit;\n  }\n  return undefined;\n}\n\n/**\n * Ensure we can evaluate in the child frame with minimal delay.\n * - If the child is same-process: parent session owns it and main world appears quickly.\n * - If OOPIF and adoption not finished: wait briefly for ownership change, then main world.\n */\nasync function ensureChildFrameReady(\n  page: Page,\n  parentFrame: Frame,\n  childFrameId: string,\n  budgetMs: number,\n): Promise<void> {\n  const parentSession = parentFrame.session;\n  const deadline = Date.now() + Math.max(0, budgetMs);\n\n  // If already owned by a different session (OOPIF adopted), wait briefly there.\n  const owner = page.getSessionForFrame(childFrameId);\n  if (owner && owner !== parentSession) {\n    try {\n      await executionContexts.waitForMainWorld(owner, childFrameId, 600);\n    } catch {\n      // best effort\n    }\n    return;\n  }\n\n  const hasMainWorldOnParent = (): boolean => {\n    try {\n      return (\n        executionContexts.getMainWorld(parentSession, childFrameId) !== null\n      );\n    } catch {\n      return false;\n    }\n  };\n\n  if (hasMainWorldOnParent()) return;\n\n  await parentSession\n    .send(\"Page.setLifecycleEventsEnabled\", { enabled: true })\n    .catch(() => {});\n  await parentSession.send(\"Runtime.enable\").catch(() => {});\n\n  await new Promise<void>((resolve) => {\n    let done = false;\n    const finish = () => {\n      if (done) return;\n      done = true;\n      parentSession.off(\"Page.lifecycleEvent\", onLifecycle);\n      resolve();\n    };\n    const onLifecycle = (evt: Protocol.Page.LifecycleEventEvent) => {\n      if (\n        evt.frameId !== childFrameId ||\n        (evt.name !== \"DOMContentLoaded\" &&\n          evt.name !== \"load\" &&\n          evt.name !== \"networkIdle\" &&\n          evt.name !== \"networkidle\")\n      ) {\n        return;\n      }\n      if (hasMainWorldOnParent()) return finish();\n      try {\n        const nowOwner = page.getSessionForFrame(childFrameId);\n        if (nowOwner && nowOwner !== parentSession) {\n          const left = Math.max(150, deadline - Date.now());\n          executionContexts\n            .waitForMainWorld(nowOwner, childFrameId, left)\n            .finally(finish);\n        }\n      } catch {\n        // ignore\n      }\n    };\n    parentSession.on(\"Page.lifecycleEvent\", onLifecycle);\n\n    const tick = () => {\n      if (done) return;\n      if (hasMainWorldOnParent()) return finish();\n      try {\n        const nowOwner = page.getSessionForFrame(childFrameId);\n        if (nowOwner && nowOwner !== parentSession) {\n          const left = Math.max(150, deadline - Date.now());\n          executionContexts\n            .waitForMainWorld(nowOwner, childFrameId, left)\n            .finally(finish);\n          return;\n        }\n      } catch {\n        // ignore\n      }\n      if (Date.now() >= deadline) return finish();\n      setTimeout(tick, 50);\n    };\n    tick();\n  });\n}\n"]}

package/dist/cjs/lib/v3/understudy/frameRegistry.js

@@ -0,0 +1,302 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrameRegistry = void 0;
+/** Minimal “shell” CDP frame used when we haven’t yet seen a real Frame from events. */
+function shellFrame(id) {
+    return {
+        id,
+        loaderId: "",
+        url: "",
+        domainAndRegistry: "",
+        securityOrigin: "",
+        mimeType: "text/html",
+        secureContextType: "InsecureScheme",
+        crossOriginIsolatedContextType: "NotIsolated",
+        gatedAPIFeatures: [],
+    };
+}
+class FrameRegistry {
+    /** Owner target id (top-level target); informational only */
+    ownerTargetId;
+    /** Current main/root frame id (changes on root swaps) */
+    rootFrameId;
+    /** frameId → FrameInfo */
+    frames = new Map();
+    /** sessionId → Set<frameId> (inverse map for diagnostics/fast membership checks) */
+    framesBySession = new Map();
+    constructor(ownerTargetId, mainFrameId) {
+        this.ownerTargetId = ownerTargetId;
+        this.rootFrameId = mainFrameId;
+        this.ensureNode(mainFrameId);
+    }
+    // ---------------------- Mutators (called by Context/Page bridges) ----------------------
+    /**
+     * Record that a frame attached. If `parentId` is null and `frameId` differs from the current
+     * root, this is a root swap and we rename the root id.
+     *
+     * IMPORTANT: The emitter's `sessionId` is the **owner** for the new/attached frame.
+     */
+    onFrameAttached(frameId, parentId, sessionId) {
+        // Root swap (parentId === null for main frames).
+        if (!parentId && frameId !== this.rootFrameId) {
+            this.renameNodeId(this.rootFrameId, frameId);
+            this.rootFrameId = frameId;
+            // ownership moves to this session as well
+            this.setOwnerSessionIdInternal(frameId, sessionId);
+            return;
+        }
+        // Normal attach
+        this.ensureNode(frameId);
+        if (parentId)
+            this.ensureNode(parentId);
+        const info = this.frames.get(frameId);
+        info.parentId = parentId ?? null;
+        if (parentId) {
+            this.frames.get(parentId).children.add(frameId);
+        }
+        // Ownership: the session that emitted frameAttached owns this frame.
+        this.setOwnerSessionIdInternal(frameId, sessionId);
+    }
+    /**
+     * Record a navigation with the full CDP `Frame`. Also updates ownership based on the emitting
+     * session id. Handles root swap if the navigated frame is the new main (no parentId).
+     */
+    onFrameNavigated(frame, sessionId) {
+        this.ensureNode(frame.id);
+        const info = this.frames.get(frame.id);
+        info.lastSeen = frame;
+        // Ownership follows the session that reported the navigation
+        this.setOwnerSessionIdInternal(frame.id, sessionId);
+        // If this frame has no parent, it might be the (new) main/root
+        if (!("parentId" in frame) || !frame.parentId) {
+            if (frame.id !== this.rootFrameId) {
+                // carry ordinal semantics by renaming the root id
+                this.renameNodeId(this.rootFrameId, frame.id);
+                this.rootFrameId = frame.id;
+            }
+        }
+    }
+    onNavigatedWithinDocument(frameId, url, sessionId) {
+        this.ensureNode(frameId);
+        const info = this.frames.get(frameId);
+        const lastSeen = info.lastSeen ?? shellFrame(frameId);
+        info.lastSeen = { ...lastSeen, url };
+        this.setOwnerSessionIdInternal(frameId, sessionId);
+    }
+    /**
+     * Record that a frame detached. If `reason !== "swap"`, remove the subtree from the graph,
+     * and clean the inverse maps. For “swap” we keep the node to preserve continuity.
+     */
+    onFrameDetached(frameId, reason = "remove") {
+        if (reason === "swap")
+            return;
+        // Collect subtree starting from frameId.
+        const toRemove = [];
+        const collect = (fid) => {
+            toRemove.push(fid);
+            const kids = this.frames.get(fid)?.children ?? new Set();
+            for (const k of kids)
+                collect(k);
+        };
+        collect(frameId);
+        // Remove nodes, fix parents and inverse maps
+        for (const fid of toRemove) {
+            const info = this.frames.get(fid);
+            if (!info)
+                continue;
+            // unlink from parent
+            if (info.parentId) {
+                const p = this.frames.get(info.parentId);
+                p?.children.delete(fid);
+            }
+            // unlink inverse session map
+            if (info.ownerSessionId) {
+                const bag = this.framesBySession.get(info.ownerSessionId);
+                bag?.delete(fid);
+                if (bag && bag.size === 0)
+                    this.framesBySession.delete(info.ownerSessionId);
+            }
+            this.frames.delete(fid);
+        }
+        // Guard root if we removed it; assign a placeholder root if needed
+        if (!this.frames.has(this.rootFrameId)) {
+            // Choose an arbitrary remaining node as root
+            const iter = this.frames.keys().next();
+            if (!iter.done)
+                this.rootFrameId = iter.value;
+        }
+    }
+    /**
+     * An adopted OOPIF child session was created whose **main** frame id equals the parent iframe’s frameId.
+     * We mark the entire child subtree as owned by `childSessionId`.
+     * (Topology edges remain aligned by the parent session’s `frameAttached` events.)
+     */
+    adoptChildSession(childSessionId, childMainFrameId) {
+        // The child session will emit its own navigations/attachments; as a seed,
+        // mark the root frame as owned by the child session.
+        this.setOwnerSessionIdInternal(childMainFrameId, childSessionId);
+    }
+    /**
+     * Seed topology and ownership from an existing `Page.getFrameTree` snapshot, typically right after
+     * a session is attached. This is a best-effort: we record frames and set the provided `sessionId`
+     * as owner for the subtree **if** an owner isn't already set.
+     */
+    seedFromFrameTree(sessionId, frameTree) {
+        const walk = (tree, parent) => {
+            this.ensureNode(tree.frame.id);
+            // topology
+            this.frames.get(tree.frame.id).parentId = parent;
+            if (parent)
+                this.frames.get(parent).children.add(tree.frame.id);
+            // last-seen frame
+            this.frames.get(tree.frame.id).lastSeen = tree.frame;
+            // ownership (only if unknown)
+            if (!this.frames.get(tree.frame.id).ownerSessionId) {
+                this.setOwnerSessionIdInternal(tree.frame.id, sessionId);
+            }
+            for (const c of tree.childFrames ?? [])
+                walk(c, tree.frame.id);
+        };
+        walk(frameTree, null);
+    }
+    /**
+     * Set the backendNodeId of the `<iframe>` element for a child frame **as seen from its parent**.
+     * This is useful for building absolute XPath prefixes later (from the parent document).
+     */
+    setOwnerBackendNodeId(childFrameId, backendNodeId) {
+        this.ensureNode(childFrameId);
+        this.frames.get(childFrameId).ownerBackendNodeId = backendNodeId;
+    }
+    // ---------------------- Readers (consumed by Page/snapshot/locators) ----------------------
+    mainFrameId() {
+        return this.rootFrameId;
+    }
+    /**
+     * Return the owner session id for this frame. If unknown, returns `undefined`.
+     */
+    getOwnerSessionId(frameId) {
+        return this.frames.get(frameId)?.ownerSessionId;
+    }
+    /**
+     * Return the owner backendNodeId (iframe element) if recorded.
+     * This is in the **parent** document; pair it with `getParent`.
+     */
+    getOwnerBackendNodeId(frameId) {
+        return this.frames.get(frameId)?.ownerBackendNodeId;
+    }
+    /**
+     * Return the parent frame id, or null for root/unknown.
+     */
+    getParent(frameId) {
+        return this.frames.get(frameId)?.parentId ?? null;
+    }
+    /**
+     * List frame ids in root-first DFS order (same shape as CDP’s FrameTree traversal).
+     */
+    listAllFrames() {
+        const out = [];
+        const dfs = (fid) => {
+            out.push(fid);
+            const kids = this.frames.get(fid)?.children ?? new Set();
+            for (const k of kids)
+                dfs(k);
+        };
+        if (this.frames.has(this.rootFrameId))
+            dfs(this.rootFrameId);
+        return out;
+    }
+    /**
+     * Serialize to `Protocol.Page.FrameTree` starting at the given root id (typically mainFrameId()).
+     */
+    asProtocolFrameTree(rootId) {
+        const build = (fid) => {
+            const info = this.frames.get(fid);
+            const frame = info?.lastSeen ?? shellFrame(fid);
+            const kids = info?.children ?? new Set();
+            const childFrames = kids.size
+                ? [...kids].map((k) => build(k))
+                : undefined;
+            return childFrames ? { frame, childFrames } : { frame };
+        };
+        return build(rootId);
+    }
+    /**
+     * For diagnostics: return the current owner sessions for a frame id (0..n),
+     * usually 0 or 1, but helpful to see potential inconsistencies during wiring.
+     */
+    sessionsForFrame(frameId) {
+        const info = this.frames.get(frameId);
+        return info?.ownerSessionId ? [info.ownerSessionId] : [];
+    }
+    /**
+     * For diagnostics: return current frame set per session.
+     */
+    framesForSession(sessionId) {
+        return [...(this.framesBySession.get(sessionId) ?? new Set())];
+    }
+    // ---------------------- Internal helpers ----------------------
+    ensureNode(fid) {
+        if (this.frames.has(fid))
+            return;
+        this.frames.set(fid, {
+            parentId: null,
+            children: new Set(),
+            lastSeen: shellFrame(fid),
+            ownerSessionId: undefined,
+            ownerBackendNodeId: undefined,
+        });
+    }
+    renameNodeId(oldId, newId) {
+        if (oldId === newId)
+            return;
+        this.ensureNode(oldId);
+        const info = this.frames.get(oldId);
+        // Move info under new id
+        this.frames.delete(oldId);
+        this.frames.set(newId, { ...info });
+        // Fix parent’s children set
+        if (info.parentId) {
+            const p = this.frames.get(info.parentId);
+            if (p) {
+                p.children.delete(oldId);
+                p.children.add(newId);
+            }
+        }
+        // Fix children’s parent pointers
+        for (const c of info.children) {
+            const ci = this.frames.get(c);
+            if (ci)
+                ci.parentId = newId;
+        }
+        // Fix inverse map (session -> frames)
+        if (info.ownerSessionId) {
+            const bag = this.framesBySession.get(info.ownerSessionId);
+            if (bag) {
+                bag.delete(oldId);
+                bag.add(newId);
+            }
+        }
+        // If root moved, keep the root id updated is handled by caller
+    }
+    setOwnerSessionIdInternal(frameId, sessionId) {
+        this.ensureNode(frameId);
+        const info = this.frames.get(frameId);
+        // If the owner is unchanged, do nothing
+        if (info.ownerSessionId === sessionId)
+            return;
+        // Remove from previous owner bag
+        if (info.ownerSessionId) {
+            const prev = this.framesBySession.get(info.ownerSessionId);
+            prev?.delete(frameId);
+            if (prev && prev.size === 0)
+                this.framesBySession.delete(info.ownerSessionId);
+        }
+        // Set new owner and update bag
+        info.ownerSessionId = sessionId;
+        const bag = this.framesBySession.get(sessionId) ?? new Set();
+        bag.add(frameId);
+        this.framesBySession.set(sessionId, bag);
+    }
+}
+exports.FrameRegistry = FrameRegistry;
+//# sourceMappingURL=frameRegistry.js.map

package/dist/cjs/lib/v3/understudy/frameRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frameRegistry.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/frameRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["// lib/v3/understudy/frameRegistry.ts\nimport type { Protocol } from \"devtools-protocol\";\n\n/**\n * FrameRegistry\n *\n * Purpose:\n * A single, authoritative source of truth for **both**:\n *   1) Frame topology (parent/children, current main/root id, last-seen CDP `Frame`)\n *   2) Frame → Session ownership (which CDP session owns a given frameId)\n *   3) Optional iframe-owner metadata (backendNodeId of the <iframe> element in the parent doc)\n *\n *\n * Model:\n *  - This class is **CDP-agnostic**; it stores **sessionId strings** (not session objects).\n *  - Context bridges (wiring Target/Page events) must call the mutators below (onAttached,\n *    onNavigated, onDetached, adoptChildSession, seedFromFrameTree, setOwnerBackendNodeId).\n *  - Consumers ask read APIs (getOwnerSessionId, getParent, asProtocolFrameTree, listAll, …)\n *    and never probe ownership at run time.\n */\n\ntype FrameId = string;\ntype SessionId = string;\n\ntype FrameInfo = {\n  /** Parent frame id, or null for root */\n  parentId: FrameId | null;\n  /** Children frame ids (direct) */\n  children: Set<FrameId>;\n  /** Last-seen CDP Frame metadata for this id (may be a shell if never seen) */\n  lastSeen?: Protocol.Page.Frame;\n\n  /** Owning session id (CDP child session for OOPIF, top-level session for same-process) */\n  ownerSessionId?: SessionId;\n\n  /**\n   * The backendNodeId of the <iframe> element **in the parent document** that hosts this frame.\n   * Useful for building absolute XPath prefixes or DOM scoping in the parent session.\n   */\n  ownerBackendNodeId?: number;\n};\n\n/** Minimal “shell” CDP frame used when we haven’t yet seen a real Frame from events. */\nfunction shellFrame(id: FrameId): Protocol.Page.Frame {\n  return {\n    id,\n    loaderId: \"\",\n    url: \"\",\n    domainAndRegistry: \"\",\n    securityOrigin: \"\",\n    mimeType: \"text/html\",\n    secureContextType: \"InsecureScheme\",\n    crossOriginIsolatedContextType: \"NotIsolated\",\n    gatedAPIFeatures: [],\n  } as Protocol.Page.Frame;\n}\n\nexport class FrameRegistry {\n  /** Owner target id (top-level target); informational only */\n  private readonly ownerTargetId: string;\n\n  /** Current main/root frame id (changes on root swaps) */\n  private rootFrameId: FrameId;\n\n  /** frameId → FrameInfo */\n  private frames = new Map<FrameId, FrameInfo>();\n\n  /** sessionId → Set<frameId> (inverse map for diagnostics/fast membership checks) */\n  private framesBySession = new Map<SessionId, Set<FrameId>>();\n\n  constructor(ownerTargetId: string, mainFrameId: FrameId) {\n    this.ownerTargetId = ownerTargetId;\n    this.rootFrameId = mainFrameId;\n    this.ensureNode(mainFrameId);\n  }\n\n  // ---------------------- Mutators (called by Context/Page bridges) ----------------------\n\n  /**\n   * Record that a frame attached. If `parentId` is null and `frameId` differs from the current\n   * root, this is a root swap and we rename the root id.\n   *\n   * IMPORTANT: The emitter's `sessionId` is the **owner** for the new/attached frame.\n   */\n  onFrameAttached(\n    frameId: FrameId,\n    parentId: FrameId | null,\n    sessionId: SessionId,\n  ): void {\n    // Root swap (parentId === null for main frames).\n    if (!parentId && frameId !== this.rootFrameId) {\n      this.renameNodeId(this.rootFrameId, frameId);\n      this.rootFrameId = frameId;\n      // ownership moves to this session as well\n      this.setOwnerSessionIdInternal(frameId, sessionId);\n      return;\n    }\n\n    // Normal attach\n    this.ensureNode(frameId);\n    if (parentId) this.ensureNode(parentId);\n\n    const info = this.frames.get(frameId)!;\n    info.parentId = parentId ?? null;\n\n    if (parentId) {\n      this.frames.get(parentId)!.children.add(frameId);\n    }\n\n    // Ownership: the session that emitted frameAttached owns this frame.\n    this.setOwnerSessionIdInternal(frameId, sessionId);\n  }\n\n  /**\n   * Record a navigation with the full CDP `Frame`. Also updates ownership based on the emitting\n   * session id. Handles root swap if the navigated frame is the new main (no parentId).\n   */\n  onFrameNavigated(frame: Protocol.Page.Frame, sessionId: SessionId): void {\n    this.ensureNode(frame.id);\n    const info = this.frames.get(frame.id)!;\n    info.lastSeen = frame;\n\n    // Ownership follows the session that reported the navigation\n    this.setOwnerSessionIdInternal(frame.id, sessionId);\n\n    // If this frame has no parent, it might be the (new) main/root\n    if (!(\"parentId\" in frame) || !frame.parentId) {\n      if (frame.id !== this.rootFrameId) {\n        // carry ordinal semantics by renaming the root id\n        this.renameNodeId(this.rootFrameId, frame.id);\n        this.rootFrameId = frame.id;\n      }\n    }\n  }\n\n  onNavigatedWithinDocument(\n    frameId: FrameId,\n    url: string,\n    sessionId: SessionId,\n  ): void {\n    this.ensureNode(frameId);\n    const info = this.frames.get(frameId)!;\n    const lastSeen = info.lastSeen ?? shellFrame(frameId);\n    info.lastSeen = { ...lastSeen, url };\n    this.setOwnerSessionIdInternal(frameId, sessionId);\n  }\n\n  /**\n   * Record that a frame detached. If `reason !== \"swap\"`, remove the subtree from the graph,\n   * and clean the inverse maps. For “swap” we keep the node to preserve continuity.\n   */\n  onFrameDetached(\n    frameId: FrameId,\n    reason: \"remove\" | \"swap\" | string = \"remove\",\n  ): void {\n    if (reason === \"swap\") return;\n\n    // Collect subtree starting from frameId.\n    const toRemove: FrameId[] = [];\n    const collect = (fid: FrameId) => {\n      toRemove.push(fid);\n      const kids = this.frames.get(fid)?.children ?? new Set<FrameId>();\n      for (const k of kids) collect(k);\n    };\n    collect(frameId);\n\n    // Remove nodes, fix parents and inverse maps\n    for (const fid of toRemove) {\n      const info = this.frames.get(fid);\n      if (!info) continue;\n\n      // unlink from parent\n      if (info.parentId) {\n        const p = this.frames.get(info.parentId);\n        p?.children.delete(fid);\n      }\n\n      // unlink inverse session map\n      if (info.ownerSessionId) {\n        const bag = this.framesBySession.get(info.ownerSessionId);\n        bag?.delete(fid);\n        if (bag && bag.size === 0)\n          this.framesBySession.delete(info.ownerSessionId);\n      }\n\n      this.frames.delete(fid);\n    }\n\n    // Guard root if we removed it; assign a placeholder root if needed\n    if (!this.frames.has(this.rootFrameId)) {\n      // Choose an arbitrary remaining node as root\n      const iter = this.frames.keys().next();\n      if (!iter.done) this.rootFrameId = iter.value;\n    }\n  }\n\n  /**\n   * An adopted OOPIF child session was created whose **main** frame id equals the parent iframe’s frameId.\n   * We mark the entire child subtree as owned by `childSessionId`.\n   * (Topology edges remain aligned by the parent session’s `frameAttached` events.)\n   */\n  adoptChildSession(\n    childSessionId: SessionId,\n    childMainFrameId: FrameId,\n  ): void {\n    // The child session will emit its own navigations/attachments; as a seed,\n    // mark the root frame as owned by the child session.\n    this.setOwnerSessionIdInternal(childMainFrameId, childSessionId);\n  }\n\n  /**\n   * Seed topology and ownership from an existing `Page.getFrameTree` snapshot, typically right after\n   * a session is attached. This is a best-effort: we record frames and set the provided `sessionId`\n   * as owner for the subtree **if** an owner isn't already set.\n   */\n  seedFromFrameTree(\n    sessionId: SessionId,\n    frameTree: Protocol.Page.FrameTree,\n  ): void {\n    const walk = (tree: Protocol.Page.FrameTree, parent: FrameId | null) => {\n      this.ensureNode(tree.frame.id);\n      // topology\n      this.frames.get(tree.frame.id)!.parentId = parent;\n      if (parent) this.frames.get(parent)!.children.add(tree.frame.id);\n      // last-seen frame\n      this.frames.get(tree.frame.id)!.lastSeen = tree.frame;\n      // ownership (only if unknown)\n      if (!this.frames.get(tree.frame.id)!.ownerSessionId) {\n        this.setOwnerSessionIdInternal(tree.frame.id, sessionId);\n      }\n      for (const c of tree.childFrames ?? []) walk(c, tree.frame.id);\n    };\n    walk(frameTree, null);\n  }\n\n  /**\n   * Set the backendNodeId of the `<iframe>` element for a child frame **as seen from its parent**.\n   * This is useful for building absolute XPath prefixes later (from the parent document).\n   */\n  setOwnerBackendNodeId(childFrameId: FrameId, backendNodeId: number): void {\n    this.ensureNode(childFrameId);\n    this.frames.get(childFrameId)!.ownerBackendNodeId = backendNodeId;\n  }\n\n  // ---------------------- Readers (consumed by Page/snapshot/locators) ----------------------\n\n  mainFrameId(): FrameId {\n    return this.rootFrameId;\n  }\n\n  /**\n   * Return the owner session id for this frame. If unknown, returns `undefined`.\n   */\n  getOwnerSessionId(frameId: FrameId): SessionId | undefined {\n    return this.frames.get(frameId)?.ownerSessionId;\n  }\n\n  /**\n   * Return the owner backendNodeId (iframe element) if recorded.\n   * This is in the **parent** document; pair it with `getParent`.\n   */\n  getOwnerBackendNodeId(frameId: FrameId): number | undefined {\n    return this.frames.get(frameId)?.ownerBackendNodeId;\n  }\n\n  /**\n   * Return the parent frame id, or null for root/unknown.\n   */\n  getParent(frameId: FrameId): FrameId | null {\n    return this.frames.get(frameId)?.parentId ?? null;\n  }\n\n  /**\n   * List frame ids in root-first DFS order (same shape as CDP’s FrameTree traversal).\n   */\n  listAllFrames(): FrameId[] {\n    const out: FrameId[] = [];\n    const dfs = (fid: FrameId) => {\n      out.push(fid);\n      const kids = this.frames.get(fid)?.children ?? new Set<FrameId>();\n      for (const k of kids) dfs(k);\n    };\n    if (this.frames.has(this.rootFrameId)) dfs(this.rootFrameId);\n    return out;\n  }\n\n  /**\n   * Serialize to `Protocol.Page.FrameTree` starting at the given root id (typically mainFrameId()).\n   */\n  asProtocolFrameTree(rootId: FrameId): Protocol.Page.FrameTree {\n    const build = (fid: FrameId): Protocol.Page.FrameTree => {\n      const info = this.frames.get(fid);\n      const frame = info?.lastSeen ?? shellFrame(fid);\n\n      const kids = info?.children ?? new Set<FrameId>();\n      const childFrames = kids.size\n        ? [...kids].map((k) => build(k))\n        : undefined;\n\n      return childFrames ? { frame, childFrames } : { frame };\n    };\n\n    return build(rootId);\n  }\n\n  /**\n   * For diagnostics: return the current owner sessions for a frame id (0..n),\n   * usually 0 or 1, but helpful to see potential inconsistencies during wiring.\n   */\n  sessionsForFrame(frameId: FrameId): SessionId[] {\n    const info = this.frames.get(frameId);\n    return info?.ownerSessionId ? [info.ownerSessionId] : [];\n  }\n\n  /**\n   * For diagnostics: return current frame set per session.\n   */\n  framesForSession(sessionId: SessionId): FrameId[] {\n    return [...(this.framesBySession.get(sessionId) ?? new Set())];\n  }\n\n  // ---------------------- Internal helpers ----------------------\n\n  private ensureNode(fid: FrameId): void {\n    if (this.frames.has(fid)) return;\n    this.frames.set(fid, {\n      parentId: null,\n      children: new Set<FrameId>(),\n      lastSeen: shellFrame(fid),\n      ownerSessionId: undefined,\n      ownerBackendNodeId: undefined,\n    });\n  }\n\n  private renameNodeId(oldId: FrameId, newId: FrameId): void {\n    if (oldId === newId) return;\n    this.ensureNode(oldId);\n\n    const info = this.frames.get(oldId)!;\n\n    // Move info under new id\n    this.frames.delete(oldId);\n    this.frames.set(newId, { ...info });\n\n    // Fix parent’s children set\n    if (info.parentId) {\n      const p = this.frames.get(info.parentId);\n      if (p) {\n        p.children.delete(oldId);\n        p.children.add(newId);\n      }\n    }\n\n    // Fix children’s parent pointers\n    for (const c of info.children) {\n      const ci = this.frames.get(c);\n      if (ci) ci.parentId = newId;\n    }\n\n    // Fix inverse map (session -> frames)\n    if (info.ownerSessionId) {\n      const bag = this.framesBySession.get(info.ownerSessionId);\n      if (bag) {\n        bag.delete(oldId);\n        bag.add(newId);\n      }\n    }\n\n    // If root moved, keep the root id updated is handled by caller\n  }\n\n  private setOwnerSessionIdInternal(\n    frameId: FrameId,\n    sessionId: SessionId,\n  ): void {\n    this.ensureNode(frameId);\n    const info = this.frames.get(frameId)!;\n\n    // If the owner is unchanged, do nothing\n    if (info.ownerSessionId === sessionId) return;\n\n    // Remove from previous owner bag\n    if (info.ownerSessionId) {\n      const prev = this.framesBySession.get(info.ownerSessionId);\n      prev?.delete(frameId);\n      if (prev && prev.size === 0)\n        this.framesBySession.delete(info.ownerSessionId);\n    }\n\n    // Set new owner and update bag\n    info.ownerSessionId = sessionId;\n    const bag = this.framesBySession.get(sessionId) ?? new Set<FrameId>();\n    bag.add(frameId);\n    this.framesBySession.set(sessionId, bag);\n  }\n}\n"]}