Fix OOPIF invalidation fallback and add frame collection docs

Author: cursoragent

packages/agent/src/translator/browser-frame-collection.ts

@@ -1,12 +1,21 @@
 import { CdpProtocolError } from "./cdp";
 
+/**
+ * Wraps unexpected iframe collection failures with context about which frame
+ * and collection stage failed.
+ */
 export class FrameCollectionError extends Error {
 	constructor(message: string, cause: unknown) {
 		super(message, { cause });
 		this.name = "FrameCollectionError";
 	}
 }
 
+/**
+ * True when a CDP error is one of the known transient "frame disappeared"
+ * variants that should mark the frame as incomplete instead of failing the
+ * whole observation.
+ */
 export function isExpectedFrameCollectionError(
 	error: unknown,
 	method: "DOM.describeNode" | "Accessibility.getFullAXTree",
@@ -21,6 +30,10 @@ export function isExpectedFrameCollectionError(
 	);
 }
 
+/**
+ * Build a contextual {@link FrameCollectionError} for an unexpected iframe
+ * collection failure.
+ */
 export function frameCollectionError(
 	backendNodeId: number,
 	frameId: string | undefined,

packages/agent/src/translator/browser.ts

@@ -142,7 +142,7 @@ export class BrowserExecutor {
 				if (this.frameTargets.has(sessionTargetId)) {
 					// The OOPIF tree and any same-process descendants fetched through
 					// its session share the OOPIF generation key.
-					const owner = this.frameOwners.get(sessionTargetId);
+					const owner = this.ownerForFrameTarget(sessionTargetId);
 					if (owner) {
 						this.lifecycle.invalidateFrame(owner, sessionTargetId);
 						if (frame.loaderId) this.lifecycle.recordDocument(sessionTargetId, owner, frame.loaderId);
@@ -168,7 +168,7 @@ export class BrowserExecutor {
 				const sessionTargetId = this.targetsBySession.get(event.sessionId);
 				if (!frameId || !sessionTargetId) return;
 				if (this.frameTargets.has(sessionTargetId)) {
-					const owner = this.frameOwners.get(sessionTargetId);
+					const owner = this.ownerForFrameTarget(sessionTargetId);
 					if (owner) this.lifecycle.invalidateFrame(owner, sessionTargetId);
 				} else {
 					this.lifecycle.removeFrame(sessionTargetId, frameId);
@@ -218,7 +218,7 @@ export class BrowserExecutor {
 				this.targetsBySession.delete(sessionId);
 				if (!targetId) return;
 				if (this.frameTargets.has(targetId)) {
-					const owner = this.frameOwners.get(targetId);
+					const owner = this.ownerForFrameTarget(targetId);
 					if (owner) this.lifecycle.removeFrame(owner, targetId);
 					this.frameSessions.delete(targetId);
 					this.frameOwners.delete(targetId);
@@ -967,6 +967,17 @@ export class BrowserExecutor {
 		return entry;
 	}
 
+	private ownerForFrameTarget(frameTargetId: string): string | undefined {
+		const mapped = this.frameOwners.get(frameTargetId);
+		if (mapped) return mapped;
+		for (const entry of this.refs.values()) {
+			if (entry.frameId !== frameTargetId) continue;
+			this.frameOwners.set(frameTargetId, entry.targetId);
+			return entry.targetId;
+		}
+		return undefined;
+	}
+
 	private dropTarget(targetId: string): void {
 		this.lifecycle.dropTarget(targetId);
 		this.selfNavigations.delete(targetId);

packages/agent/test/translator-browser.test.ts

@@ -783,6 +783,26 @@ describe("BrowserExecutor iframe stitching", () => {
 		fake.setSessionTree("session-oop", OOPIF_CHILD);
 		return fake;
 	};
+	const importOopifRefWithoutOwner = async () => {
+		const source = setupOopif();
+		const mint = new BrowserExecutor(source.cdp);
+		await snapshotText(mint);
+		const state = mint.exportRefState();
+
+		const fake = createFakeCdp(OOPIF_PAGE);
+		fake.setIframeFrame(50, "FRAME-OOP");
+		fake.setSessionTree("session-oop", OOPIF_CHILD);
+		const executor = new BrowserExecutor(fake.cdp);
+		executor.importRefState(state);
+		// Simulate a frame session that attached without a parent session id, so
+		// the target->owner mapping is absent until a later observation rebuilds it.
+		fake.emit({
+			method: "Target.attachedToTarget",
+			params: { sessionId: "session-oop", targetInfo: { targetId: "FRAME-OOP", type: "iframe" } },
+		});
+		expect([...refsOf(executor).keys()].sort()).toEqual(["e1", "e2", "e3"]);
+		return { executor, fake };
+	};
 
 	it("resolves an OOPIF ref's node through the child session but dispatches input on the page session", async () => {
 		const { cdp, sent } = setupOopif();
@@ -900,6 +920,16 @@ describe("BrowserExecutor iframe stitching", () => {
 		expect(text).toContain('button "Pay" [e');
 	});
 
+	it.each([
+		{ label: "Page.frameNavigated", event: { method: "Page.frameNavigated", params: { frame: { id: "FRAME-OOP" } }, sessionId: "session-oop" } },
+		{ label: "Page.frameDetached", event: { method: "Page.frameDetached", params: { frameId: "FRAME-OOP", reason: "swap" }, sessionId: "session-oop" } },
+		{ label: "Target.detachedFromTarget", event: { method: "Target.detachedFromTarget", params: { sessionId: "session-oop" } } },
+	] as const)("drops imported OOPIF refs when $label fires before owner mapping is known", async ({ event }) => {
+		const { fake, executor } = await importOopifRefWithoutOwner();
+		fake.emit(event);
+		expect([...refsOf(executor).keys()].sort()).toEqual(["e1", "e2"]);
+	});
+
 	it("invalidates and releases a same-process frame when it detaches and rotates", async () => {
 		const root = [
 			ax({ nodeId: "1", role: "RootWebArea", name: "Page", childIds: ["2"] }),