perf(geometry): batch iframe owner size measurements

CHANGELOG.md

@@ -5,24 +5,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 Starting from 0.2.0, CLI / Extension / DSH Plugin share the same version number.
 
-## [0.2.1] - 2026-09-09
-
-### Changed
-- DSH Plugin: clarified installation, configuration, profile restart, and upgrade instructions
-
-### Fixed
-- CLI: reliable Windows self-updates, including executable replacement and daemon restart
-- CLI: Windows named-pipe connection continuity and stale daemon process detection
-- Windows installer: PowerShell 5.1 compatibility, path quoting, and staged executable replacement
-- CLI / DSH Plugin: cancellation propagation and upload/download cleanup when the parent process exits
-- Extension: tab ownership and session cleanup when agent tabs fail to open or borrowed tabs are returned or closed
-- Extension: navigation recovery when other extensions restrict Chrome DevTools Protocol access
-- Extension: background input filling, automatic append behavior, and verification of field values before reporting success
-- Extension: match observed form state to the correct element after page changes
-- Extension: UUID generation fallback for recording and overlays on insecure origins
-- Browser locale matching for regional language variants
-- DSH Plugin: observation state synchronization, thumbnail capture lifecycle, and stale preview cleanup
-- DSH Plugin: removed the obsolete client runtime host dependency
+## [Unreleased]
 
 ## [0.2.0] - 2026-09-02
 

Cargo.lock

@@ -134,7 +134,7 @@ dependencies = [
 
 [[package]]
 name = "bsk"
-version = "0.2.1"
+version = "0.2.0"
 dependencies = [
  "anyhow",
  "base64",
@@ -169,7 +169,7 @@ dependencies = [
 
 [[package]]
 name = "bsk-protocol"
-version = "0.2.1"
+version = "0.2.0"
 dependencies = [
  "schemars",
  "semver",

Cargo.toml

@@ -7,7 +7,7 @@ members = [
 default-members = ["crates/bsk-cli"]
 
 [workspace.package]
-version = "0.2.1"
+version = "0.2.0"
 edition = "2024"
 rust-version = "1.85"
 license = "MIT"
@@ -43,7 +43,7 @@ rand = "0.8"
 uuid = { version = "1", features = ["v4", "serde"] }
 
 # Workspace crates (version required for `cargo publish` of dependents)
-bsk-protocol = { version = "0.2.1", path = "crates/bsk-protocol" }
+bsk-protocol = { version = "0.2.0", path = "crates/bsk-protocol" }
 
 [profile.release]
 strip = "symbols"

apps/extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browser-skill/extension",
-  "version": "0.2.1",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "scripts": {

apps/extension/src/tools/__tests__/frame-geometry.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { resolveFrameProjection, resolveNodeGeometry } from "../frame-geometry";
+import { resolveNodeGeometry } from "../frame-geometry";
 import {
   clipPolygon,
   polygonArea,
@@ -10,6 +10,7 @@ import {
   rectPolygon,
   regionBounds,
 } from "../geometry";
+import { GeometryContext } from "../geometry/frame-context";
 import type { CdpRunner } from "../shared";
 
 describe("frame geometry projection", () => {
@@ -82,28 +83,24 @@ describe("frame geometry projection", () => {
         throw new Error(`unexpected child command ${method}`);
       }) as CdpRunner["sendToTarget"],
     };
-    const projection = await resolveFrameProjection(
-      cdp,
-      {
-        rootFrameId: "main",
-        frames: [
-          { frameId: "main", target: { tabId: 4 } },
-          {
-            frameId: "same-process-parent",
-            parentFrameId: "main",
-            ownerBackendNodeId: 10,
-            target: { tabId: 4 },
-          },
-          {
-            frameId: "oopif",
-            parentFrameId: "same-process-parent",
-            ownerBackendNodeId: 20,
-            target: { tabId: 4, sessionId: "oopif-session" },
-          },
-        ],
-      },
-      "oopif",
-    );
+    const projection = await new GeometryContext(cdp, 4, {
+      rootFrameId: "main",
+      frames: [
+        { frameId: "main", target: { tabId: 4 } },
+        {
+          frameId: "same-process-parent",
+          parentFrameId: "main",
+          ownerBackendNodeId: 10,
+          target: { tabId: 4 },
+        },
+        {
+          frameId: "oopif",
+          parentFrameId: "same-process-parent",
+          ownerBackendNodeId: 20,
+          target: { tabId: 4, sessionId: "oopif-session" },
+        },
+      ],
+    }).targetProjection("oopif");
 
     expect(projection?.edges).toEqual([
       {

apps/extension/src/tools/__tests__/geometry-context.test.ts

@@ -0,0 +1,380 @@
+import { describe, expect, it, vi } from "vitest";
+import type { CdpFrameGraph } from "@/browser-driver/frame-graph";
+import { resolveNodeGeometry } from "../frame-geometry";
+import { rectPolygon } from "../geometry";
+import {
+  projectSnapshotRect,
+  screenshotPageRect,
+  snapshotViewportRect,
+} from "../geometry/coordinate-types";
+import { GeometryContext } from "../geometry/frame-context";
+import type { CdpRunner } from "../shared";
+
+const target = { tabId: 4 };
+const graph: CdpFrameGraph = {
+  rootFrameId: "main",
+  frames: [
+    { frameId: "main", target },
+    { frameId: "child", parentFrameId: "main", ownerBackendNodeId: 10, target },
+  ],
+};
+
+function driver() {
+  const send = vi.fn(async (_tab: number, method: string): Promise<object> => {
+    if (method === "Page.getLayoutMetrics")
+      return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 1000 } };
+    if (method === "DOM.getBoxModel")
+      return { model: { content: [52.5, 612.5, 427.5, 612.5, 427.5, 862.5, 52.5, 862.5] } };
+    if (method === "DOM.resolveNode") return { object: { objectId: "owner" } };
+    if (method === "Runtime.callFunctionOn")
+      return { result: { value: { width: 300, height: 200 } } };
+    if (method === "Runtime.releaseObject") return {};
+    throw new Error(method);
+  });
+  return { send: send as CdpRunner["send"], getFrameGraph: vi.fn(async () => graph), calls: send };
+}
+
+describe("measurement geometry context", () => {
+  it("shares in-flight frame measurements, but never shares them with the next context", async () => {
+    const cdp = driver();
+    const context = new GeometryContext(cdp, 4);
+    const results = await Promise.all(
+      Array.from({ length: 20 }, () => context.targetProjection("child")),
+    );
+    expect(results.every((value) => value === results[0])).toBe(true);
+    expect(cdp.getFrameGraph).toHaveBeenCalledTimes(1);
+    expect(cdp.calls.mock.calls.map(([, method]) => method)).toEqual([
+      "Page.getLayoutMetrics",
+      "DOM.getBoxModel",
+    ]);
+    await new GeometryContext(cdp, 4).targetProjection("child");
+    expect(cdp.getFrameGraph).toHaveBeenCalledTimes(2);
+    expect(cdp.calls.mock.calls).toHaveLength(4);
+  });
+
+  it("projects frame-local snapshot CSS bounds through the scaled owner content quad", async () => {
+    const cdp = driver();
+    const context = new GeometryContext(cdp, 4);
+    const source = { target, frameId: "child" };
+    const projection = await context.snapshotProjection(source, 10, [], {
+      width: 1000,
+      height: 1000,
+    });
+    if (projection.status !== "available") throw new Error("expected available projection");
+    const input = snapshotViewportRect([17, 23, 120, 40], source, { x: 0, y: 0 });
+    expect(projectSnapshotRect(input!, projection.projection)).toEqual({
+      x: 73.75,
+      y: 641.25,
+      width: 150,
+      height: 50,
+    });
+    const scrolled = snapshotViewportRect([17, 23, 120, 40], source, { x: 0, y: 10 });
+    expect(projectSnapshotRect(scrolled!, projection.projection)?.y).toBe(628.75);
+    await context.snapshotProjection(source, 10, [], { width: 1000, height: 1000 });
+    expect(cdp.calls.mock.calls.filter(([, method]) => method === "DOM.resolveNode")).toHaveLength(
+      1,
+    );
+    expect(
+      cdp.calls.mock.calls.filter(([, method]) => method === "Runtime.releaseObject"),
+    ).toHaveLength(1);
+  });
+
+  it("falls back only for missing or invalid batch entries and does not reuse sizes across contexts", async () => {
+    const cdp = driver();
+    const original = cdp.send;
+    const calls: string[] = [];
+    cdp.send = async (tabId, method, params) => {
+      calls.push(method);
+      if (method === "Runtime.evaluate")
+        return {
+          result: {
+            deepSerializedValue: {
+              type: "array",
+              value: [
+                {
+                  type: "array",
+                  value: [
+                    { type: "node", value: { backendNodeId: 10 } },
+                    { type: "string", value: '{"width":300,"height":200}' },
+                  ],
+                },
+                {
+                  type: "array",
+                  value: [
+                    { type: "node", value: { backendNodeId: 11 } },
+                    { type: "string", value: '{"width":0,"height":200}' },
+                  ],
+                },
+              ],
+            },
+          },
+        } as never;
+      if (method === "Runtime.releaseObjectGroup") return {} as never;
+      return original(tabId, method, params);
+    };
+    const context = new GeometryContext(cdp, 4);
+    context.registerSnapshotOwners(target, new Set([10, 11]));
+    const values = await Promise.all(
+      [10, 11].map((id) =>
+        context.snapshotProjection({ target, frameId: String(id) }, id, [], {
+          width: 1000,
+          height: 1000,
+        }),
+      ),
+    );
+    expect(values.every((value) => value.status === "available")).toBe(true);
+    expect(calls.filter((method) => method === "DOM.resolveNode")).toHaveLength(1);
+    expect(calls.filter((method) => method === "Runtime.evaluate")).toHaveLength(1);
+    await new GeometryContext(cdp, 4).snapshotProjection({ target, frameId: "child" }, 10, [], {
+      width: 1000,
+      height: 1000,
+    });
+    expect(calls.filter((method) => method === "DOM.resolveNode")).toHaveLength(2);
+  });
+
+  it("waits for batch object cleanup and propagates cancellation", async () => {
+    const cdp = driver();
+    const original = cdp.send;
+    const controller = new AbortController();
+    let release!: () => void;
+    let cleanup!: () => void;
+    const started = new Promise<void>((resolve) => {
+      cleanup = resolve;
+    });
+    cdp.send = async (tabId, method, params) => {
+      if (method === "Runtime.evaluate") return {} as never;
+      if (method === "Runtime.releaseObjectGroup") {
+        cleanup();
+        await new Promise<void>((resolve) => {
+          release = resolve;
+        });
+        return {} as never;
+      }
+      return original(tabId, method, params);
+    };
+    const context = new GeometryContext(cdp, 4, undefined, controller.signal);
+    context.registerSnapshotOwners(target, new Set([10, 11]));
+    let settled = false;
+    const operation = context
+      .snapshotProjection({ target, frameId: "child" }, 10, [], { width: 1000, height: 1000 })
+      .finally(() => {
+        settled = true;
+      });
+    const rejected = expect(operation).rejects.toMatchObject({ name: "AbortError" });
+    await started;
+    controller.abort();
+    expect(settled).toBe(false);
+    release();
+    await rejected;
+    expect(cdp.calls.mock.calls.some(([, method]) => method === "DOM.resolveNode")).toBe(false);
+  });
+
+  it("rejects owner mismatches and invalid numeric bounds", () => {
+    const input = snapshotViewportRect(
+      [30, 50, 120, 40],
+      { target, frameId: "main" },
+      { x: 10, y: 20 },
+    )!;
+    const projection = {
+      source: { target, frameId: "main" },
+      geometry: { sourceClips: [], edges: [], topViewport: { width: 800, height: 600 } },
+    };
+    expect(projectSnapshotRect(input, projection)).toEqual({
+      x: 20,
+      y: 30,
+      width: 120,
+      height: 40,
+    });
+    expect(
+      projectSnapshotRect(input, { ...projection, source: { target, frameId: "other" } }),
+    ).toBeNull();
+    expect(
+      projectSnapshotRect(input, {
+        ...projection,
+        source: { target: { tabId: 5 }, frameId: "main" },
+      }),
+    ).toBeNull();
+    expect(snapshotViewportRect([0, 0, NaN, 40], { target }, { x: 0, y: 0 })).toBeNull();
+    expect(snapshotViewportRect([0, 0, 10, 40], { target }, { x: Infinity, y: 0 })).toBeNull();
+  });
+
+  it("does not turn a border quad or a failed owner read into a content projection", async () => {
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({
+        model: { border: [0, 0, 100, 0, 100, 100, 0, 100] },
+      })) as CdpRunner["send"],
+    };
+    expect(
+      await new GeometryContext(cdp, 4).snapshotProjection({ target, frameId: "child" }, 10, [], {
+        width: 100,
+        height: 100,
+      }),
+    ).toEqual({
+      status: "unavailable",
+      source: { target, frameId: "child" },
+      ownerBackendNodeId: 10,
+    });
+  });
+
+  it("keeps ancestor clips in target coordinates instead of applying nested offsets twice", async () => {
+    const cdp = driver();
+    const projection = await new GeometryContext(cdp, 4).snapshotProjection(
+      { target, frameId: "nested" },
+      10,
+      [rectPolygon({ x: 60, y: 620, w: 100, h: 100 })],
+      { width: 1000, height: 1000 },
+    );
+    if (projection.status !== "available") throw new Error("expected available projection");
+    const input = snapshotViewportRect(
+      [0, 0, 300, 200],
+      { target, frameId: "nested" },
+      { x: 0, y: 0 },
+    );
+    expect(projectSnapshotRect(input!, projection.projection)).toEqual({
+      x: 60,
+      y: 620,
+      width: 100,
+      height: 100,
+    });
+  });
+
+  it("rejects malformed frame ancestry without looping", async () => {
+    const cdp = driver();
+    const cycle: CdpFrameGraph = {
+      rootFrameId: "a",
+      frames: [
+        { frameId: "a", parentFrameId: "b", target },
+        { frameId: "b", parentFrameId: "a", target },
+      ],
+    };
+    expect(await new GeometryContext(cdp, 4, cycle).targetProjection("a")).toBeNull();
+    expect(cdp.calls).not.toHaveBeenCalled();
+    const orphan: CdpFrameGraph = {
+      rootFrameId: "a",
+      frames: [{ frameId: "a", parentFrameId: "missing", target }],
+    };
+    expect(await new GeometryContext(cdp, 4, orphan).targetProjection("a")).toBeNull();
+  });
+
+  it("rejects a live node whose frame belongs to another target before any DOM input", async () => {
+    const cdp = driver();
+    expect(
+      await resolveNodeGeometry(
+        cdp,
+        4,
+        { target: { tabId: 4, sessionId: "wrong" }, frameId: "child", backendNodeId: 20 },
+        { scrollIntoView: true },
+      ),
+    ).toMatchObject({ code: "cdp_failed" });
+    expect(cdp.calls).not.toHaveBeenCalled();
+  });
+
+  it("bounds concurrent measurements and does not dispatch queued reads after cancellation", async () => {
+    let active = 0;
+    let peak = 0;
+    const release: Array<() => void> = [];
+    const send = vi.fn(async () => {
+      active++;
+      peak = Math.max(peak, active);
+      await new Promise<void>((resolve) => release.push(resolve));
+      active--;
+      return { cssLayoutViewport: { clientWidth: 100, clientHeight: 100 } };
+    });
+    const controller = new AbortController();
+    const context = new GeometryContext(
+      { send: send as CdpRunner["send"] },
+      4,
+      undefined,
+      controller.signal,
+    );
+    const tasks = Array.from({ length: 8 }, (_, index) =>
+      context.viewport({ tabId: 4, sessionId: String(index) }),
+    );
+    const settled = Promise.allSettled(tasks);
+    expect(send).toHaveBeenCalledTimes(4);
+    controller.abort();
+    for (const done of release) done();
+    const results = await settled;
+    expect(peak).toBe(4);
+    expect(send).toHaveBeenCalledTimes(4);
+    expect(results.filter((item) => item.status === "rejected")).toHaveLength(4);
+  });
+
+  it("releases an owner object even when cancellation arrives before its viewport read", async () => {
+    const controller = new AbortController();
+    const cdp = driver();
+    const original = cdp.calls.getMockImplementation()!;
+    cdp.calls.mockImplementation(async (tab, method) => {
+      const result = await original(tab, method);
+      if (method === "DOM.resolveNode") controller.abort();
+      return result;
+    });
+    const context = new GeometryContext(cdp, 4, undefined, controller.signal);
+    await expect(
+      context.snapshotProjection({ target, frameId: "child" }, 10, [], {
+        width: 1000,
+        height: 1000,
+      }),
+    ).rejects.toMatchObject({ name: "AbortError" });
+    expect(cdp.calls.mock.calls.map(([, method]) => method)).toEqual([
+      "DOM.getBoxModel",
+      "DOM.resolveNode",
+      "Runtime.releaseObject",
+    ]);
+  });
+
+  it("reads live owner geometry only after scrolling", async () => {
+    const cdp = driver();
+    const original = cdp.calls.getMockImplementation()!;
+    let scrolled = false;
+    cdp.calls.mockImplementation(async (tab, method) => {
+      if (method === "DOM.scrollIntoViewIfNeeded") {
+        scrolled = true;
+        return {};
+      }
+      if (method === "DOM.getContentQuads") {
+        expect(scrolled).toBe(true);
+        return { quads: [[60, 620, 100, 620, 100, 640, 60, 640]] };
+      }
+      if (method === "DOM.getBoxModel") expect(scrolled).toBe(true);
+      return original(tab, method);
+    });
+    expect(
+      await resolveNodeGeometry(
+        cdp,
+        4,
+        { target, frameId: "child", backendNodeId: 20 },
+        { scrollIntoView: true },
+      ),
+    ).toMatchObject({ topBounds: { x: 60, y: 620, width: 40, height: 20 } });
+    expect(cdp.getFrameGraph).toHaveBeenCalledTimes(1);
+    expect(cdp.calls.mock.calls.filter(([, method]) => method === "DOM.getBoxModel")).toHaveLength(
+      1,
+    );
+  });
+
+  it("adapts viewport CSS bounds to page DIP with scroll and browser zoom, never raster DPR", () => {
+    const viewport = { width: 1600, height: 1000, scrollX: 10, scrollY: 100, cssToDip: 0.9 };
+    const clip = screenshotPageRect({ x: 20, y: 30, width: 120, height: 40 }, viewport);
+    expect(clip).toEqual({ space: "page-dip", rect: { x: 27, y: 117, width: 108, height: 36 } });
+    expect(
+      screenshotPageRect({ x: 20, y: 30, width: 120, height: 40 }, { ...viewport, cssToDip: NaN }),
+    ).toBeNull();
+    expect(
+      screenshotPageRect({ x: 20, y: 30, width: 120, height: 40 }, { ...viewport, cssToDip: 0 }),
+    ).toBeNull();
+  });
+
+  it("retries a rejected measurement only in a new operation", async () => {
+    const cdp = driver();
+    cdp.calls.mockRejectedValueOnce(new Error("unavailable"));
+    const context = new GeometryContext(cdp, 4);
+    await expect(context.viewport(target)).rejects.toThrow("unavailable");
+    await expect(context.viewport(target)).rejects.toThrow("unavailable");
+    expect(cdp.calls).toHaveBeenCalledTimes(1);
+    expect(await new GeometryContext(cdp, 4).viewport(target)).toEqual({
+      width: 1000,
+      height: 1000,
+    });
+  });
+});

apps/extension/src/tools/__tests__/observation.test.ts

@@ -266,7 +266,15 @@ describe("handleScreenshot", () => {
     expect(sent.find((c) => c.method === "Page.captureScreenshot")).toBeUndefined();
   });
 
-  it("captures a clipped PNG when ref is given", async () => {
+  it.each([
+    { zoom: 1, scroll: 0, expected: { x: 10, y: 20, width: 100, height: 40 } },
+    { zoom: 0.9, scroll: 100, expected: { x: 9, y: 108, width: 90, height: 36 } },
+    { zoom: 1.25, scroll: 100, expected: { x: 12.5, y: 150, width: 125, height: 50 } },
+  ])("captures a ref in page DIP at zoom $zoom and scroll $scroll", async ({
+    zoom,
+    scroll,
+    expected,
+  }) => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");
     ctx.refStore.set("e5", 999, { tabId: 7 });
@@ -274,6 +282,10 @@ describe("handleScreenshot", () => {
       "DOM.scrollIntoViewIfNeeded": () => ({}),
       "DOM.getContentQuads": () => ({ quads: [[10, 20, 110, 20, 110, 60, 10, 60]] }),
       "Page.captureScreenshot": () => ({ data: TINY_PNG }),
+      "Page.getLayoutMetrics": () => ({
+        cssLayoutViewport: { clientWidth: 1280, clientHeight: 720, pageX: 0, pageY: scroll },
+        cssVisualViewport: { zoom },
+      }),
     });
     const captureVisibleTab = vi.fn();
     const res = await handleScreenshot(
@@ -297,7 +309,8 @@ describe("handleScreenshot", () => {
         clip?: { x: number; y: number; width: number; height: number };
       }
     )?.clip;
-    expect(clip).toMatchObject({ x: 10, y: 20, width: 100, height: 40 });
+    expect(clip).toMatchObject(expected);
+    expect(sent.filter((c) => c.method === "Page.getLayoutMetrics")).toHaveLength(1);
   });
 
   it("returns not_found for unknown ref", async () => {
@@ -3134,7 +3147,9 @@ describe("handleSnapshot", () => {
     cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
   };
 
-  function makeFrameAwareDeps() {
+  function makeFrameAwareDeps(
+    ownerGeometry: "unavailable" | "available" | "clipped" = "unavailable",
+  ) {
     const strings = ["html", "body", "iframe", "button", "title", "Remote", "static", "auto"];
     const i = (value: string) => strings.indexOf(value);
     const styles = [i("static"), i("auto"), i("auto")];
@@ -3214,6 +3229,16 @@ describe("handleSnapshot", () => {
     ];
     const send = vi.fn(async (_tabId: number, method: string) => {
       if (method === "Page.getLayoutMetrics") return VP_METRICS;
+      if (ownerGeometry !== "unavailable") {
+        if (method === "DOM.getBoxModel") {
+          const x = ownerGeometry === "clipped" ? 10000 : 100;
+          return { model: { content: [x, 100, x + 400, 100, x + 400, 400, x, 400] } };
+        }
+        if (method === "DOM.resolveNode") return { object: { objectId: "owner" } };
+        if (method === "Runtime.callFunctionOn")
+          return { result: { value: { width: 400, height: 300 } } };
+        if (method === "Runtime.releaseObject") return {};
+      }
       if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
       if (method === "DOMSnapshot.captureSnapshot") return snapshot;
       if (method === "Accessibility.getFullAXTree") return { nodes: mainAx };
@@ -3454,6 +3479,43 @@ describe("handleSnapshot", () => {
     expect(result.text).toContain("•••");
   });
 
+  it.each([
+    undefined,
+    100,
+    0,
+  ])("reports unavailable iframe geometry within the observation budget %s", async (maxTokens) => {
+    const result = await captureVomObservation(makeFrameAwareDeps().cdp, 4, "https://example.com", {
+      maxTokens,
+    });
+    expect(result.text.match(/@warning/g)).toHaveLength(1);
+    expect(result.text).toContain("iframe geometry incomplete");
+    expect(result.text.startsWith("@vom 1\n")).toBe(true);
+    if (maxTokens === undefined) {
+      expect(result.truncated).toBe(false);
+      expect(result.text).toContain("Frame action");
+      expect(result.matchNodes.find((node) => node.backendNodeId === 22)).toMatchObject({
+        rect: null,
+        localRect: { x: 20, y: 30, w: 120, h: 40 },
+      });
+    }
+    if (maxTokens === 100) expect(Math.ceil(result.text.length / 4)).toBeLessThanOrEqual(maxTokens);
+  });
+
+  it.each([
+    "available",
+    "clipped",
+  ] as const)("does not report successful %s geometry as an observation failure", async (ownerGeometry) => {
+    const result = await captureVomObservation(
+      makeFrameAwareDeps(ownerGeometry).cdp,
+      4,
+      "https://example.com",
+    );
+    expect(result.text).not.toContain("@warning");
+    const node = result.matchNodes.find((item) => item.backendNodeId === 22);
+    if (ownerGeometry === "clipped") expect(node?.rect).toBeNull();
+    else expect(node?.rect).toEqual({ x: 120, y: 130, w: 120, h: 40 });
+  });
+
   it("keeps frames and rendered refs on the same frame identity", async () => {
     const deps = makeFrameAwareDeps();
 

apps/extension/src/tools/frame-geometry.ts

@@ -1,24 +1,21 @@
-import { type CdpFrame, type CdpFrameGraph, type CdpTarget } from "@/browser-driver/frame-graph";
+import { type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
 import type { RpcError } from "@/transport/types";
 import { nodeContentRegion, scrollNodeIntoView } from "./element-geometry";
 import {
   clipPolygon,
-  type GeometryProjection,
   type Point,
   type Polygon,
-  type ProjectiveEdge,
-  parseCdpQuad,
   polygonArea,
   polygonCentroid,
   projectRegionToViewport,
-  type Quad,
   type Region,
   rectPolygon,
   regionBounds,
-  type Size,
   type ViewportRect,
 } from "./geometry";
-import { type CdpRunner, cdpRunnerForTarget, isRpcError, sendToCdpTarget } from "./shared";
+import type { CssViewport } from "./geometry/coordinate-types";
+import { cssViewport, GeometryContext } from "./geometry/frame-context";
+import { type CdpRunner, cdpRunnerForTarget, isRpcError } from "./shared";
 
 export interface NodeAddress {
   target: CdpTarget;
@@ -27,6 +24,8 @@ export interface NodeAddress {
 }
 
 export interface ResolvedNodeGeometry {
+  /** The same top-level measurement used by projection, for screenshot coordinate adaptation. */
+  topViewport: CssViewport;
   topVisibleRegions: Region;
   topBounds: ViewportRect;
   /** Point in the top-level tab viewport, used by root-target input events. */
@@ -39,145 +38,16 @@ function geometryError(message: string): RpcError {
   return { code: "cdp_failed", message };
 }
 
-function frameMap(graph: CdpFrameGraph): Map<string, CdpFrame> {
-  return new Map(graph.frames.map((frame) => [frame.frameId, frame]));
-}
-
-function targetRootFrame(byId: Map<string, CdpFrame>, frame: CdpFrame): CdpFrame | null {
-  const seen = new Set<string>();
-  let current = frame;
-  while (current.parentFrameId) {
-    if (seen.has(current.frameId)) return null;
-    seen.add(current.frameId);
-    const parent = byId.get(current.parentFrameId);
-    if (!parent || parent.target.sessionId !== current.target.sessionId) break;
-    current = parent;
-  }
-  return current;
-}
-
-function frameAncestry(graph: CdpFrameGraph, frameId: string): CdpFrame[] | null {
-  const byId = frameMap(graph);
-  const path: CdpFrame[] = [];
-  const seen = new Set<string>();
-  let current = byId.get(frameId);
-  if (!current) return null;
-  while (current.parentFrameId) {
-    if (seen.has(current.frameId)) return null;
-    seen.add(current.frameId);
-    path.push(current);
-    const parent = byId.get(current.parentFrameId);
-    if (!parent) return null;
-    current = parent;
-  }
-  return path;
-}
-
-async function targetViewport(cdp: CdpRunner, target: CdpTarget): Promise<Size | null> {
-  const metrics = await sendToCdpTarget<{
-    cssLayoutViewport?: { clientWidth?: number; clientHeight?: number };
-    layoutViewport?: { clientWidth?: number; clientHeight?: number };
-  }>(cdp, target, "Page.getLayoutMetrics", {});
-  const viewport = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
-  const width = viewport.clientWidth ?? 0;
-  const height = viewport.clientHeight ?? 0;
-  return width > 0 && height > 0 ? { width, height } : null;
-}
-
-async function ownerContentQuad(
-  cdp: CdpRunner,
-  parent: CdpFrame,
-  ownerBackendNodeId: number,
-): Promise<Quad | null> {
-  const result = await sendToCdpTarget<{ model?: { content?: number[] } }>(
-    cdp,
-    parent.target,
-    "DOM.getBoxModel",
-    { backendNodeId: ownerBackendNodeId },
-  );
-  return parseCdpQuad(result.model?.content);
-}
-
-async function sameTargetFrameClips(
-  cdp: CdpRunner,
-  byId: Map<string, CdpFrame>,
-  frame: CdpFrame,
-  targetRoot: CdpFrame,
-): Promise<Polygon[] | null> {
-  const clips: Polygon[] = [];
-  let current = frame;
-  const seen = new Set<string>();
-  while (current.frameId !== targetRoot.frameId) {
-    if (seen.has(current.frameId) || !current.parentFrameId) return null;
-    seen.add(current.frameId);
-    const parent = byId.get(current.parentFrameId);
-    if (!parent || current.ownerBackendNodeId === undefined) return null;
-    const clip = await ownerContentQuad(cdp, parent, current.ownerBackendNodeId);
-    if (!clip) return null;
-    clips.push(clip);
-    current = parent;
-  }
-  return clips;
-}
-
-export async function resolveFrameProjection(
-  cdp: CdpRunner,
-  graph: CdpFrameGraph,
-  frameId: string,
-): Promise<GeometryProjection | null> {
-  const byId = frameMap(graph);
-  const frame = byId.get(frameId);
-  if (!frame) return null;
-  let targetRoot = targetRootFrame(byId, frame);
-  if (!targetRoot) return null;
-  const sourceViewport = await targetViewport(cdp, targetRoot.target);
-  if (!sourceViewport) return null;
-  const sourceClips = await sameTargetFrameClips(cdp, byId, frame, targetRoot);
-  if (!sourceClips) return null;
-
-  const edges: ProjectiveEdge[] = [];
-  while (targetRoot.parentFrameId) {
-    const parent = byId.get(targetRoot.parentFrameId);
-    if (!parent || targetRoot.ownerBackendNodeId === undefined) return null;
-    const destinationQuad = await ownerContentQuad(cdp, parent, targetRoot.ownerBackendNodeId);
-    if (!destinationQuad) return null;
-    const source =
-      edges.length === 0 ? sourceViewport : await targetViewport(cdp, targetRoot.target);
-    if (!source) return null;
-    const parentTargetRoot = targetRootFrame(byId, parent);
-    if (!parentTargetRoot) return null;
-    const destinationClips = await sameTargetFrameClips(cdp, byId, parent, parentTargetRoot);
-    if (!destinationClips) return null;
-    edges.push({ sourceViewport: source, destinationQuad, destinationClips });
-    targetRoot = parentTargetRoot;
-  }
-
-  const topViewport =
-    edges.length === 0 ? sourceViewport : await targetViewport(cdp, targetRoot.target);
-  return topViewport ? { sourceClips, edges, topViewport } : null;
-}
-
-async function loadFrameGraph(cdp: CdpRunner, tabId: number): Promise<CdpFrameGraph | null> {
-  if (!cdp.getFrameGraph) return null;
-  try {
-    return await cdp.getFrameGraph(tabId);
-  } catch (error) {
-    console.debug("[bsk frame-geometry] frame graph resolution failed", error);
-    return null;
-  }
-}
-
 async function scrollFrameOwners(
   cdp: CdpRunner,
   tabId: number,
-  graph: CdpFrameGraph,
+  context: GeometryContext,
   frameId: string,
 ): Promise<RpcError | null> {
-  const byId = frameMap(graph);
-  const ancestry = frameAncestry(graph, frameId);
+  const ancestry = await context.ancestry(frameId);
   if (!ancestry) return geometryError(`could not resolve frame ancestry for ${frameId}`);
   for (const child of [...ancestry].reverse()) {
-    const parent = child.parentFrameId ? byId.get(child.parentFrameId) : undefined;
+    const parent = child.parentFrameId ? await context.frame(child.parentFrameId) : undefined;
     if (!parent || child.ownerBackendNodeId === undefined) {
       return geometryError(`could not resolve frame owner for ${child.frameId}`);
     }
@@ -191,17 +61,20 @@ async function scrollFrameOwners(
   return null;
 }
 
-async function scrollElementWithFrameGraph(
+async function scrollElementWithContext(
   cdp: CdpRunner,
   tabId: number,
   target: CdpTarget,
   backendNodeId: number,
   frameId: string | undefined,
-  graph: CdpFrameGraph | null,
+  context: GeometryContext,
 ): Promise<RpcError | null> {
   if (frameId) {
-    if (!graph) return geometryError(`could not resolve frame graph for ${frameId}`);
-    const error = await scrollFrameOwners(cdp, tabId, graph, frameId);
+    const frame = await context.frame(frameId);
+    if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(target)) {
+      return geometryError("node frame does not belong to its target");
+    }
+    const error = await scrollFrameOwners(cdp, tabId, context, frameId);
     if (error) return error;
   } else if (target.sessionId) {
     return geometryError("an OOPIF node address requires frameId");
@@ -216,8 +89,15 @@ export async function scrollElementAndFramesIntoView(
   backendNodeId: number,
   frameId?: string,
 ): Promise<RpcError | null> {
-  const graph = frameId ? await loadFrameGraph(cdp, tabId) : null;
-  return scrollElementWithFrameGraph(cdp, tabId, target, backendNodeId, frameId, graph);
+  if (target.tabId !== tabId) return geometryError("node target belongs to another tab");
+  return scrollElementWithContext(
+    cdp,
+    tabId,
+    target,
+    backendNodeId,
+    frameId,
+    new GeometryContext(cdp, tabId),
+  );
 }
 
 function largestRegion(regions: Region): Polygon | null {
@@ -240,23 +120,32 @@ export async function resolveNodeGeometry(
     if (address.target.sessionId && !address.frameId) {
       return geometryError("an OOPIF node address requires frameId");
     }
-    const graph = address.frameId ? await loadFrameGraph(cdp, tabId) : null;
+    if (address.target.tabId !== tabId) return geometryError("node target belongs to another tab");
+    const context = new GeometryContext(cdp, tabId);
+    const graph = address.frameId ? await context.graph() : null;
+    if (address.frameId && graph) {
+      const frame = await context.frame(address.frameId);
+      if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(address.target)) {
+        return geometryError("node frame does not belong to its target");
+      }
+    }
     if (address.frameId && !graph) {
       return geometryError(`could not resolve frame graph for ${address.frameId}`);
     }
 
     if (options.scrollIntoView) {
-      const scrollError = await scrollElementWithFrameGraph(
+      const scrollError = await scrollElementWithContext(
         cdp,
         tabId,
         address.target,
         address.backendNodeId,
         address.frameId,
-        graph,
+        context,
       );
       if (scrollError) return scrollError;
     }
 
+    // Only topology was read above. Begin live measurements after scrolling.
     const localRegion = await nodeContentRegion(
       cdpRunnerForTarget(cdp, address.target),
       tabId,
@@ -267,7 +156,7 @@ export async function resolveNodeGeometry(
     let topVisibleRegions: Region;
     let targetActionPoint: Point | null = null;
     if (address.frameId && graph) {
-      const projection = await resolveFrameProjection(cdp, graph, address.frameId);
+      const projection = await context.targetProjection(address.frameId);
       if (!projection)
         return geometryError(`could not resolve frame geometry for ${address.frameId}`);
       topVisibleRegions = projectRegionToViewport(localRegion, projection);
@@ -290,7 +179,7 @@ export async function resolveNodeGeometry(
         targetActionPoint = localActionRegion ? polygonCentroid(localActionRegion) : null;
       }
     } else {
-      const viewport = await targetViewport(cdp, address.target);
+      const viewport = await context.viewport(address.target);
       if (!viewport) return geometryError("could not resolve top viewport geometry");
       topVisibleRegions = localRegion
         .map((polygon) =>
@@ -309,7 +198,13 @@ export async function resolveNodeGeometry(
       return { code: "permission_denied", message: "element not visible in its target" };
     }
     targetActionPoint ??= actionPoint;
-    return { topVisibleRegions, topBounds, actionPoint, targetActionPoint };
+    return {
+      topVisibleRegions,
+      topBounds,
+      actionPoint,
+      targetActionPoint,
+      topViewport: cssViewport(await context.layoutMetrics({ tabId })),
+    };
   } catch (error) {
     return geometryError(error instanceof Error ? error.message : String(error));
   }

apps/extension/src/tools/geometry.ts

@@ -245,22 +245,3 @@ export function projectRectToViewport(
   if (!rect) return null;
   return regionBounds(projectRegionToViewport([rectPolygon(rect)], projection));
 }
-
-export function childFrameProjection(
-  parent: GeometryProjection,
-  ownerRectInParent: { x: number; y: number; w: number; h: number },
-): GeometryProjection {
-  const destinationQuad = rectPolygon(ownerRectInParent);
-  return {
-    sourceClips: [],
-    edges: [
-      {
-        sourceViewport: { width: ownerRectInParent.w, height: ownerRectInParent.h },
-        destinationQuad,
-        destinationClips: parent.sourceClips,
-      },
-      ...parent.edges,
-    ],
-    topViewport: parent.topViewport,
-  };
-}

apps/extension/src/tools/geometry/coordinate-types.ts

@@ -0,0 +1,102 @@
+import { type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
+import type { GeometryProjection, ViewportRect } from "../geometry";
+import { projectRectToViewport } from "../geometry";
+
+export interface CoordinateOwner {
+  target: CdpTarget;
+  frameId?: string;
+}
+
+export interface FrameViewportRect {
+  space: "frame-viewport-css";
+  owner: CoordinateOwner;
+  rect: ViewportRect;
+}
+
+export interface SnapshotProjection {
+  source: CoordinateOwner;
+  geometry: GeometryProjection;
+}
+
+/** A failed owner read is different from a successfully projected, clipped-out rect. */
+export interface UnavailableFrameProjection {
+  status: "unavailable";
+  source: CoordinateOwner;
+  ownerBackendNodeId: number;
+}
+
+export type SnapshotProjectionResult =
+  | { status: "available"; projection: SnapshotProjection }
+  | UnavailableFrameProjection;
+
+/** Descendants inherit the failed boundary without attempting another owner read. */
+export type FrameProjectionIssue =
+  | UnavailableFrameProjection
+  | { status: "blocked"; source: CoordinateOwner; cause: UnavailableFrameProjection };
+
+export type FrameProjectionState = SnapshotProjectionResult | FrameProjectionIssue;
+
+/** DOMSnapshot bounds are document-relative CSS pixels, independent of raster DPR. */
+export function snapshotViewportRect(
+  bounds: number[],
+  owner: CoordinateOwner,
+  scroll: { x: number; y: number },
+): FrameViewportRect | null {
+  if (bounds.length < 4 || !bounds.slice(0, 4).every(Number.isFinite)) return null;
+  const [x, y, width, height] = bounds;
+  if (width <= 0 || height <= 0 || !Number.isFinite(scroll.x) || !Number.isFinite(scroll.y)) {
+    return null;
+  }
+  return {
+    space: "frame-viewport-css",
+    owner,
+    rect: { x: x - scroll.x, y: y - scroll.y, width, height },
+  };
+}
+
+export function projectSnapshotRect(
+  input: FrameViewportRect,
+  projection: SnapshotProjection,
+): ViewportRect | null {
+  if (
+    input.owner.frameId !== projection.source.frameId ||
+    cdpTargetKey(input.owner.target) !== cdpTargetKey(projection.source.target)
+  ) {
+    return null;
+  }
+  const { x, y, width: w, height: h } = input.rect;
+  return projectRectToViewport({ x, y, w, h }, projection.geometry);
+}
+
+/** CSS viewport metadata; browser zoom is distinct from raster devicePixelRatio. */
+export interface CssViewport {
+  width: number;
+  height: number;
+  scrollX: number;
+  scrollY: number;
+  cssToDip: number;
+}
+
+/** Page.captureScreenshot takes page-relative DIP, not viewport-relative CSS pixels. */
+export function screenshotPageRect(
+  rect: ViewportRect,
+  viewport: CssViewport,
+): { space: "page-dip"; rect: ViewportRect } | null {
+  const { cssToDip, scrollX, scrollY } = viewport;
+  if (
+    ![rect.x, rect.y, rect.width, rect.height, cssToDip, scrollX, scrollY].every(Number.isFinite) ||
+    cssToDip <= 0 ||
+    rect.width <= 0 ||
+    rect.height <= 0
+  )
+    return null;
+  return {
+    space: "page-dip",
+    rect: {
+      x: (rect.x + scrollX) * cssToDip,
+      y: (rect.y + scrollY) * cssToDip,
+      width: rect.width * cssToDip,
+      height: rect.height * cssToDip,
+    },
+  };
+}

apps/extension/src/tools/geometry/frame-context.ts

@@ -0,0 +1,333 @@
+import {
+  type CdpFrame,
+  type CdpFrameGraph,
+  type CdpTarget,
+  cdpTargetKey,
+} from "@/browser-driver/frame-graph";
+import {
+  type GeometryProjection,
+  type Polygon,
+  type ProjectiveEdge,
+  parseCdpQuad,
+  type Quad,
+  type Size,
+} from "../geometry";
+import { type CdpRunner, sendToCdpTarget } from "../shared";
+import type { CoordinateOwner, CssViewport, SnapshotProjectionResult } from "./coordinate-types";
+
+import { readSnapshotOwnerSizes } from "./snapshot-owner-sizes";
+
+export interface LayoutMetrics {
+  cssVisualViewport?: { zoom?: number };
+  visualViewport?: { zoom?: number };
+  cssLayoutViewport?: {
+    clientWidth?: number;
+    clientHeight?: number;
+    pageX?: number;
+    pageY?: number;
+  };
+  layoutViewport?: { clientWidth?: number; clientHeight?: number; pageX?: number; pageY?: number };
+}
+
+/** The legacy field is a compatibility fallback, never a source of raster DPR. */
+export function cssViewport(metrics: LayoutMetrics): CssViewport {
+  const value = metrics.cssLayoutViewport ?? metrics.layoutViewport;
+  return {
+    width: value?.clientWidth ?? 0,
+    height: value?.clientHeight ?? 0,
+    scrollX: value?.pageX ?? 0,
+    scrollY: value?.pageY ?? 0,
+    cssToDip: metrics.cssVisualViewport?.zoom ?? metrics.visualViewport?.zoom ?? 1,
+  };
+}
+
+/** One read-only measurement phase. Discard after scrolling or any later operation. */
+export class GeometryContext {
+  private readonly metrics = new Map<string, Promise<LayoutMetrics>>();
+  private readonly owners = new Map<string, Promise<Quad | null>>();
+  private readonly projections = new Map<string, Promise<GeometryProjection | null>>();
+  private readonly snapshotOwners = new Map<string, Promise<{ quad: Quad; size: Size } | null>>();
+  private readonly sizeBatches = new Map<string, () => Promise<Map<number, Size>>>();
+  private active = 0;
+  private readonly waiting: Array<() => void> = [];
+  private graphPromise?: Promise<CdpFrameGraph | null>;
+  private framesPromise?: Promise<Map<string, CdpFrame>>;
+
+  constructor(
+    private readonly cdp: CdpRunner,
+    private readonly tabId: number,
+    graph?: CdpFrameGraph,
+    private readonly signal?: AbortSignal,
+  ) {
+    if (graph) this.graphPromise = Promise.resolve(graph);
+  }
+
+  private async request<T>(
+    target: CdpTarget,
+    method: string,
+    params: object,
+    cleanup = false,
+  ): Promise<T> {
+    if (!cleanup && this.signal?.aborted) throw new DOMException("geometry aborted", "AbortError");
+    if (this.active >= 4) await new Promise<void>((resolve) => this.waiting.push(resolve));
+    else this.active++;
+    try {
+      if (!cleanup && this.signal?.aborted)
+        throw new DOMException("geometry aborted", "AbortError");
+      return await sendToCdpTarget<T>(this.cdp, target, method, params);
+    } finally {
+      const next = this.waiting.shift();
+      if (next) next();
+      else this.active--;
+    }
+  }
+
+  graph(): Promise<CdpFrameGraph | null> {
+    this.graphPromise ??=
+      this.cdp.getFrameGraph?.(this.tabId).catch(() => null) ?? Promise.resolve(null);
+    return this.graphPromise;
+  }
+
+  private frames(): Promise<Map<string, CdpFrame>> {
+    this.framesPromise ??= this.graph().then(
+      (graph) => new Map(graph?.frames.map((frame) => [frame.frameId, frame]) ?? []),
+    );
+    return this.framesPromise;
+  }
+
+  async frame(frameId: string): Promise<CdpFrame | undefined> {
+    return (await this.frames()).get(frameId);
+  }
+
+  /** Topology only: safe to resolve before the caller scrolls frame owners. */
+  async ancestry(frameId: string): Promise<CdpFrame[] | null> {
+    const frames = await this.frames();
+    const path: CdpFrame[] = [];
+    const seen = new Set<string>();
+    let current = frames.get(frameId);
+    if (!current) return null;
+    while (current.parentFrameId) {
+      if (seen.has(current.frameId)) return null;
+      seen.add(current.frameId);
+      path.push(current);
+      const parent = frames.get(current.parentFrameId);
+      if (!parent) return null;
+      current = parent;
+    }
+    return path;
+  }
+
+  layoutMetrics(target: CdpTarget): Promise<LayoutMetrics> {
+    const key = cdpTargetKey(target);
+    let promise = this.metrics.get(key);
+    if (!promise) {
+      promise = this.request<LayoutMetrics>(target, "Page.getLayoutMetrics", {});
+      this.metrics.set(key, promise);
+    }
+    return promise;
+  }
+
+  async viewport(target: CdpTarget): Promise<Size | null> {
+    const { width, height } = cssViewport(await this.layoutMetrics(target));
+    return Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0
+      ? { width, height }
+      : null;
+  }
+
+  ownerContent(target: CdpTarget, backendNodeId: number): Promise<Quad | null> {
+    const key = `${cdpTargetKey(target)}:${backendNodeId}`;
+    let promise = this.owners.get(key);
+    if (!promise) {
+      promise = this.request<{ model?: { content?: number[] } }>(target, "DOM.getBoxModel", {
+        backendNodeId,
+      }).then((reply) => parseCdpQuad(reply.model?.content));
+      this.owners.set(key, promise);
+    }
+    return promise;
+  }
+
+  /** Same-target owner quads are already target-relative, including nested owners. */
+  async snapshotProjection(
+    source: CoordinateOwner,
+    ownerBackendNodeId: number,
+    ancestorClips: Polygon[],
+    viewport: Size,
+  ): Promise<SnapshotProjectionResult> {
+    const key = `${cdpTargetKey(source.target)}:${ownerBackendNodeId}`;
+    let promise = this.snapshotOwners.get(key);
+    if (!promise) {
+      promise = this.snapshotOwner(source.target, ownerBackendNodeId);
+      this.snapshotOwners.set(key, promise);
+    }
+    let owner: { quad: Quad; size: Size } | null;
+    try {
+      owner = await promise;
+    } catch (error) {
+      if (error && typeof error === "object" && "name" in error && error.name === "AbortError")
+        throw error;
+      console.debug("[bsk geometry] frame owner unavailable", error);
+      owner = null;
+    }
+    return owner
+      ? {
+          status: "available",
+          projection: {
+            source,
+            geometry: {
+              sourceClips: [],
+              edges: [
+                {
+                  sourceViewport: owner.size,
+                  destinationQuad: owner.quad,
+                  destinationClips: ancestorClips,
+                },
+              ],
+              topViewport: viewport,
+            },
+          },
+        }
+      : { status: "unavailable", source, ownerBackendNodeId };
+  }
+
+  /** Register one target's snapshot owners; the batch starts only when a
+   * projection actually needs a size. Single owners keep the cheaper old path. */
+  registerSnapshotOwners(target: CdpTarget, owners: ReadonlySet<number>): void {
+    const key = cdpTargetKey(target);
+    if (owners.size < 2 || this.sizeBatches.has(key)) return;
+    let pending: Promise<Map<number, Size>> | undefined;
+    this.sizeBatches.set(key, () => {
+      pending ??= readSnapshotOwnerSizes(
+        (method, params, cleanup) => this.request(target, method, params, cleanup),
+        owners,
+      ).catch((error) => {
+        if (error && typeof error === "object" && "name" in error && error.name === "AbortError")
+          throw error;
+        return new Map<number, Size>();
+      });
+      return pending;
+    });
+  }
+
+  private async snapshotOwner(
+    target: CdpTarget,
+    backendNodeId: number,
+  ): Promise<{ quad: Quad; size: Size } | null> {
+    const quad = await this.ownerContent(target, backendNodeId);
+    if (!quad) return null;
+    const batchSize = (await this.sizeBatches.get(cdpTargetKey(target))?.())?.get(backendNodeId);
+    if (this.signal?.aborted) throw new DOMException("geometry aborted", "AbortError");
+    if (batchSize) return { quad, size: batchSize };
+    const resolved = await this.request<{ object?: { objectId?: string } }>(
+      target,
+      "DOM.resolveNode",
+      { backendNodeId },
+    );
+    const objectId = resolved.object?.objectId;
+    if (!objectId) return null;
+    try {
+      const reply = await this.request<{ result?: { value?: Size }; exceptionDetails?: unknown }>(
+        target,
+        "Runtime.callFunctionOn",
+        {
+          objectId,
+          functionDeclaration: `function() {
+          if (!this.isConnected) return null;
+          const style = getComputedStyle(this);
+          return {
+            width: this.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight),
+            height: this.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom)
+          };
+        }`,
+          returnByValue: true,
+        },
+      );
+      const size = reply.result?.value;
+      return !reply.exceptionDetails &&
+        size &&
+        Number.isFinite(size.width) &&
+        Number.isFinite(size.height) &&
+        size.width > 0 &&
+        size.height > 0
+        ? { quad, size }
+        : null;
+    } finally {
+      // Cleanup must still run if cancellation arrived after resolving the object.
+      await this.request(target, "Runtime.releaseObject", { objectId }, true).catch(() => {});
+    }
+  }
+
+  private targetRoot(frames: Map<string, CdpFrame>, frame: CdpFrame): CdpFrame | null {
+    const seen = new Set<string>();
+    let current = frame;
+    while (current.parentFrameId) {
+      if (seen.has(current.frameId)) return null;
+      seen.add(current.frameId);
+      const parent = frames.get(current.parentFrameId);
+      if (!parent) return null;
+      if (cdpTargetKey(parent.target) !== cdpTargetKey(current.target)) break;
+      current = parent;
+    }
+    return current;
+  }
+
+  private async clips(
+    frames: Map<string, CdpFrame>,
+    frame: CdpFrame,
+    root: CdpFrame,
+  ): Promise<Polygon[] | null> {
+    const clips: Polygon[] = [];
+    let current = frame;
+    const seen = new Set<string>();
+    while (current.frameId !== root.frameId) {
+      if (seen.has(current.frameId) || !current.parentFrameId) return null;
+      seen.add(current.frameId);
+      const parent = frames.get(current.parentFrameId);
+      if (!parent || current.ownerBackendNodeId === undefined) return null;
+      const quad = await this.ownerContent(parent.target, current.ownerBackendNodeId);
+      if (!quad) return null;
+      clips.push(quad);
+      current = parent;
+    }
+    return clips;
+  }
+
+  /** Input is already in the frame's CDP target viewport, not its local viewport. */
+  targetProjection(frameId: string): Promise<GeometryProjection | null> {
+    let promise = this.projections.get(frameId);
+    if (!promise) {
+      promise = this.buildTargetProjection(frameId);
+      this.projections.set(frameId, promise);
+    }
+    return promise;
+  }
+
+  private async buildTargetProjection(frameId: string): Promise<GeometryProjection | null> {
+    const frames = await this.frames();
+    const frame = frames.get(frameId);
+    if (!frame) return null;
+    let root = this.targetRoot(frames, frame);
+    if (!root) return null;
+    const sourceViewport = await this.viewport(root.target);
+    if (!sourceViewport) return null;
+    const sourceClips = await this.clips(frames, frame, root);
+    if (!sourceClips) return null;
+    const edges: ProjectiveEdge[] = [];
+    const seen = new Set<string>();
+    while (root.parentFrameId) {
+      if (seen.has(root.frameId)) return null;
+      seen.add(root.frameId);
+      const parent = frames.get(root.parentFrameId);
+      if (!parent || root.ownerBackendNodeId === undefined) return null;
+      const destinationQuad = await this.ownerContent(parent.target, root.ownerBackendNodeId);
+      const source = await this.viewport(root.target);
+      const parentRoot = this.targetRoot(frames, parent);
+      if (!destinationQuad || !source || !parentRoot) return null;
+      const destinationClips = await this.clips(frames, parent, parentRoot);
+      if (!destinationClips) return null;
+      edges.push({ sourceViewport: source, destinationQuad, destinationClips });
+      root = parentRoot;
+    }
+    const topViewport = await this.viewport(root.target);
+    return topViewport ? { sourceClips, edges, topViewport } : null;
+  }
+}

apps/extension/src/tools/geometry/snapshot-owner-sizes.ts

@@ -0,0 +1,74 @@
+import type { Size } from "../geometry";
+
+interface SerializedValue {
+  type: string;
+  value?: unknown;
+}
+
+type Send = <T>(method: string, params: object, cleanup?: boolean) => Promise<T>;
+
+/** Batch only accessible frame owners. Missing/shadow/cross-origin owners keep
+ * the existing node-scoped read; no page-wide style columns are requested. */
+export async function readSnapshotOwnerSizes(
+  send: Send,
+  owners: ReadonlySet<number>,
+): Promise<Map<number, Size>> {
+  const sizes = new Map<number, Size>();
+  const objectGroup = `bsk-frame-sizes-${crypto.randomUUID()}`;
+  try {
+    const reply = await send<{ result?: { deepSerializedValue?: SerializedValue } }>(
+      "Runtime.evaluate",
+      {
+        expression: `(() => {
+          const result = [];
+          const documents = [document];
+          for (let i = 0; i < documents.length && result.length < ${owners.size}; i++) {
+            for (const owner of documents[i].querySelectorAll('iframe,frame')) {
+              if (result.length >= ${owners.size}) break;
+              if (!owner.isConnected) continue;
+              const style = getComputedStyle(owner);
+              result.push([owner, JSON.stringify({
+                width: owner.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight),
+                height: owner.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom)
+              })]);
+              try { if (owner.contentDocument) documents.push(owner.contentDocument); } catch {}
+            }
+          }
+          return result;
+        })()`,
+        objectGroup,
+        serializationOptions: {
+          serialization: "deep",
+          maxDepth: 3,
+          additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
+        },
+      },
+    );
+    const result = reply.result?.deepSerializedValue;
+    if (result?.type !== "array" || !Array.isArray(result.value)) return sizes;
+    for (const entry of result.value as SerializedValue[]) {
+      if (entry.type !== "array" || !Array.isArray(entry.value)) continue;
+      const [node, data] = entry.value as SerializedValue[];
+      if (node?.type !== "node" || data?.type !== "string" || typeof data.value !== "string")
+        continue;
+      const id = (node.value as { backendNodeId?: number } | undefined)?.backendNodeId;
+      if (id === undefined || !owners.has(id)) continue;
+      try {
+        const size = JSON.parse(data.value) as Size;
+        if (
+          size &&
+          Number.isFinite(size.width) &&
+          Number.isFinite(size.height) &&
+          size.width > 0 &&
+          size.height > 0
+        )
+          sizes.set(id, size);
+      } catch {
+        /* An invalid entry uses the existing individual read. */
+      }
+    }
+  } finally {
+    await send("Runtime.releaseObjectGroup", { objectGroup }, true).catch(() => {});
+  }
+  return sizes;
+}

apps/extension/src/tools/observation.ts

@@ -34,6 +34,8 @@ import type {
 import { attachDialogs, markDialogCursor } from "./dialogs";
 import { rpcError } from "./errors";
 import { resolveNodeGeometry } from "./frame-geometry";
+import { screenshotPageRect } from "./geometry/coordinate-types";
+import { cssViewport, GeometryContext } from "./geometry/frame-context";
 import {
   type ChromeTabsApi,
   enforceToolTargetScope,
@@ -197,15 +199,14 @@ async function captureElementScreenshot(
   if (isRpcError(geometry)) return geometry;
   if (signal?.aborted) return cancelled("screenshot");
   const rect = geometry.topBounds;
+  const clip = screenshotPageRect(rect, geometry.topViewport);
+  if (!clip) return { code: "cdp_failed", message: "invalid screenshot coordinate space" };
 
   try {
     const shot = await cdp.send<{ data?: string }>(tabId, "Page.captureScreenshot", {
       format: "png",
       clip: {
-        x: rect.x,
-        y: rect.y,
-        width: rect.width,
-        height: rect.height,
+        ...clip.rect,
         scale: 1,
       },
     });
@@ -984,26 +985,19 @@ function emptyCapturedViewModel(viewport = { width: 0, height: 0 }): CapturedVie
   return { viewport, nodes: [], iframeNodes: new Map(), excludedBackendNodeIds: new Set() };
 }
 
-interface LayoutMetricsViewportReply {
-  cssLayoutViewport?: { clientWidth?: number; clientHeight?: number };
-  layoutViewport?: { clientWidth?: number; clientHeight?: number };
-}
-
 async function fallbackCapturedViewModel(
   cdp: CdpRunner,
   tabId: number,
+  geometry: GeometryContext,
   signal?: AbortSignal,
 ): Promise<CapturedViewModel> {
   throwIfAborted(signal, "observation");
   let viewport = { width: 0, height: 0 };
   try {
-    const metrics = await cdp.send<LayoutMetricsViewportReply>(tabId, "Page.getLayoutMetrics", {});
+    const metrics = await geometry.layoutMetrics({ tabId });
     throwIfAborted(signal, "observation");
-    const source = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
-    viewport = {
-      width: source.clientWidth ?? 0,
-      height: source.clientHeight ?? 0,
-    };
+    const source = cssViewport(metrics);
+    viewport = { width: source.width, height: source.height };
   } catch (error) {
     if (isAbortError(error)) throw error;
   }
@@ -1016,12 +1010,13 @@ async function captureForVom(
   cdp: CdpRunner,
   tabId: number,
   options: CaptureVomObservationOptions,
+  geometry: GeometryContext,
 ): Promise<CapturedViewModel> {
   try {
-    return await captureViewModel(cdp, tabId, { signal: options.signal });
+    return await captureViewModel(cdp, tabId, { signal: options.signal, geometry });
   } catch (error) {
     if (isAbortError(error)) throw error;
-    return fallbackCapturedViewModel(cdp, tabId, options.signal);
+    return fallbackCapturedViewModel(cdp, tabId, geometry, options.signal);
   }
 }
 
@@ -1096,9 +1091,16 @@ export async function captureVomObservation(
   throwIfAborted(options.signal, "observation");
   await cdp.ensureAttachedToUrl?.(tabId, url);
   throwIfAborted(options.signal, "observation");
-  const captured = await captureForVom(cdp, tabId, options);
+  const geometry = new GeometryContext(cdp, tabId, undefined, options.signal);
+  const captured = await captureForVom(cdp, tabId, options, geometry);
   throwIfAborted(options.signal, "observation");
-  const documents = await captureFrameData<CdpAxNode>(cdp, tabId, captured, options.signal);
+  const documents = await captureFrameData<CdpAxNode>(
+    cdp,
+    tabId,
+    captured,
+    options.signal,
+    geometry,
+  );
   throwIfAborted(options.signal, "observation");
   const normalizedDocuments =
     documents.length === 1 && captured.iframeNodes.size > 0
@@ -1131,12 +1133,21 @@ export async function captureVomObservation(
     captured,
     hoverProbes.surfaceProbes,
   );
+  // Reserve space using the renderer's character-based token estimate. Like VOM
+  // headers, this integrity notice remains visible even under a tiny token budget.
+  const geometryNotice = captured.frameGeometryIssues?.length
+    ? "@warning iframe geometry incomplete: some frame content has no top-level coordinates.\n"
+    : "";
   const rendered = renderVom(decoratedScene, {
     maxDepth: options.maxDepth,
-    maxTokens: options.maxTokens,
+    maxTokens:
+      !geometryNotice || options.maxTokens === undefined
+        ? options.maxTokens
+        : Math.max(0, options.maxTokens - Math.ceil(geometryNotice.length / 4)),
     redactValues: options.redactValues,
     activeRegionPolicy: options.activeRegionPolicy,
   });
+  if (geometryNotice) rendered.text += `\n${geometryNotice.trimEnd()}`;
   throwIfAborted(options.signal, "observation");
   return projectRecordSafeObservation({
     rootFrameId: captured.rootFrameId ?? normalizedDocuments[0]?.frameId ?? "root",

apps/extension/src/tools/vom/__tests__/capture.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import { OVERLAY_HOST_MARKER_ATTR, OVERLAY_HOST_NAME } from "../../../lib/overlay-bridge";
+import type { CdpRunner } from "../../shared";
 import { captureViewModel, collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";
 
 // Minimal but format-accurate captureSnapshot reply: a body with one
@@ -754,7 +755,7 @@ describe("captureViewModel", () => {
     expect(div?.rect).toMatchObject({ y: 0, h: 600 });
   });
 
-  it("normalizes device-pixel bounds by devicePixelRatio", async () => {
+  it("keeps CSS snapshot bounds independent of legacy metrics ratio", async () => {
     const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
     const i = (s: string) => S.indexOf(s);
     const snapshot = {
@@ -802,6 +803,12 @@ describe("captureViewModel", () => {
       w: 1000,
       h: 800,
     });
+    expect(nodes.find((n) => n.backendNodeId === 12)?.localRect).toEqual({
+      x: 0,
+      y: 0,
+      w: 2000,
+      h: 1600,
+    });
   });
 
   it("extracts textContent from #text child nodes via nodeValue", async () => {
@@ -950,6 +957,12 @@ describe("captureViewModel", () => {
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
+        if (method === "DOM.getBoxModel")
+          return { model: { content: [100, 300, 900, 300, 900, 700, 100, 700] } };
+        if (method === "DOM.resolveNode") return { object: { objectId: "owner" } };
+        if (method === "Runtime.callFunctionOn")
+          return { result: { value: { width: 800, height: 400 } } };
+        if (method === "Runtime.releaseObject") return {};
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
@@ -979,7 +992,7 @@ describe("captureViewModel", () => {
     expect(frameParentIds?.get("child-frame")).toBe("main-frame");
   });
 
-  it("captures iframe documents without requiring owner-frame geometry", async () => {
+  it("projects iframe documents independently of owner snapshot geometry", async () => {
     const S = [
       "html",
       "body",
@@ -1040,6 +1053,12 @@ describe("captureViewModel", () => {
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
+        if (method === "DOM.getBoxModel")
+          return { model: { content: [100, 300, 900, 300, 900, 700, 100, 700] } };
+        if (method === "DOM.resolveNode") return { object: { objectId: "owner" } };
+        if (method === "Runtime.callFunctionOn")
+          return { result: { value: { width: 800, height: 400 } } };
+        if (method === "Runtime.releaseObject") return {};
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
@@ -1048,7 +1067,7 @@ describe("captureViewModel", () => {
     const input = iframeNodes.get(13)?.find((n) => n.backendNodeId === 101);
 
     expect(input?.localRect).toEqual({ x: 20, y: 20, w: 120, h: 60 });
-    expect(input?.rect).toBeNull();
+    expect(input?.rect).toEqual({ x: 120, y: 320, w: 120, h: 60 });
   });
 
   it("recursively normalizes nested iframe sub-documents", async () => {
@@ -1127,16 +1146,43 @@ describe("captureViewModel", () => {
       ],
     };
     const cdp = {
-      send: vi.fn(async (_t: number, method: string) => {
-        if (method === "DOMSnapshot.enable") return {};
-        if (method === "DOMSnapshot.captureSnapshot") return snapshot;
-        if (method === "Page.getLayoutMetrics") {
-          return {
-            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
-          };
-        }
-        throw new Error(method);
-      }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
+      send: vi.fn(
+        async (
+          _t: number,
+          method: string,
+          params?: { backendNodeId?: number; objectId?: string },
+        ) => {
+          if (method === "DOMSnapshot.enable") return {};
+          if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+          if (method === "Page.getLayoutMetrics") {
+            return {
+              cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+            };
+          }
+          if (method === "DOM.getBoxModel")
+            return {
+              model: {
+                content:
+                  params?.backendNodeId === 13
+                    ? [10, 20, 310, 20, 310, 220, 10, 220]
+                    : [15, 26, 115, 26, 115, 106, 15, 106],
+              },
+            };
+          if (method === "DOM.resolveNode")
+            return { object: { objectId: String(params?.backendNodeId) } };
+          if (method === "Runtime.callFunctionOn")
+            return {
+              result: {
+                value:
+                  params?.objectId === "13"
+                    ? { width: 300, height: 200 }
+                    : { width: 100, height: 80 },
+              },
+            };
+          if (method === "Runtime.releaseObject") return {};
+          throw new Error(method);
+        },
+      ) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
     const { iframeNodes } = await captureViewModel(cdp, 4);
@@ -1150,7 +1196,7 @@ describe("captureViewModel", () => {
     expect(input?.rect).toEqual({ x: 16, y: 28, w: 40, h: 20 });
   });
 
-  it("normalizes bounds then subtracts CSS scroll at dpr>1", async () => {
+  it("subtracts CSS scroll once without dividing snapshot bounds by a metrics ratio", async () => {
     const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
     const i = (s: string) => S.indexOf(s);
     const snapshot = {
@@ -1192,7 +1238,7 @@ describe("captureViewModel", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
     const { nodes } = await captureViewModel(cdp, 4);
-    expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 / 2 - 100);
+    expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 - 100);
   });
 
   it("collectOverlayExcludedBackendIds walks the pierced overlay host subtree", async () => {
@@ -1217,3 +1263,194 @@ describe("captureViewModel", () => {
     expect(excluded).toEqual(new Set([200, 201, 202]));
   });
 });
+
+// Six sibling frames and one nested frame exercise scheduling through the real capture entry.
+function siblingCaptureFixture(
+  beforeReply: (method: string, params: Record<string, unknown>) => Promise<void> = async () => {},
+) {
+  const document = (id: number, owners: number[], childIndexes: number[]) => ({
+    frameId: `frame-${id}`,
+    nodes: {
+      parentIndex: [-1, ...owners.map(() => 0)],
+      nodeName: [0, ...owners.map(() => 1)],
+      backendNodeId: [1000 + id, ...owners],
+      attributes: [[], ...owners.map(() => [])],
+      contentDocumentIndex: { index: owners.map((_, i) => i + 1), value: childIndexes },
+    },
+    layout: {
+      nodeIndex: [0, ...owners.map((_, i) => i + 1)],
+      bounds: [[0, 0, 200, 100], ...owners.map(() => [0, 0, 200, 100])],
+    },
+  });
+  const snapshot = {
+    strings: ["body", "iframe"],
+    documents: [
+      document(0, [100, 101, 102, 103, 104, 105], [1, 2, 3, 4, 5, 6]),
+      document(1, [200], [7]),
+      ...Array.from({ length: 6 }, (_, i) => document(i + 2, [], [])),
+    ],
+  };
+  let active = 0;
+  let peak = 0;
+  const send = vi.fn(async (_tabId: number, method: string, params: object = {}) => {
+    const args = params as Record<string, unknown>;
+    active++;
+    peak = Math.max(peak, active);
+    try {
+      await beforeReply(method, args);
+      if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+      if (method === "Page.getLayoutMetrics")
+        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
+      if (method === "DOM.getBoxModel")
+        return { model: { content: [0, 0, 200, 0, 200, 100, 0, 100] } };
+      if (method === "DOM.resolveNode") return { object: { objectId: String(args.backendNodeId) } };
+      if (method === "Runtime.callFunctionOn")
+        return { result: { value: { width: 200, height: 100 } } };
+      return {};
+    } finally {
+      active--;
+    }
+  });
+  return {
+    cdp: { send: send as CdpRunner["send"] },
+    send,
+    peak: () => peak,
+    active: () => active,
+    measured: () =>
+      send.mock.calls
+        .filter(([, method]) => method === "DOM.getBoxModel")
+        .map(([, , params]) => (params as { backendNodeId: number }).backendNodeId),
+  };
+}
+
+describe("sibling frame measurement scheduling", () => {
+  it("batches same-target owner sizes without changing projected results", async () => {
+    const fixture = siblingCaptureFixture();
+    const original = fixture.cdp.send;
+    const methods: string[] = [];
+    fixture.cdp.send = async (tabId, method, params) => {
+      methods.push(method);
+      if (method === "Runtime.evaluate")
+        return {
+          result: {
+            deepSerializedValue: {
+              type: "array",
+              value: [100, 101, 102, 103, 104, 105, 200].map((backendNodeId) => ({
+                type: "array",
+                value: [
+                  { type: "node", value: { backendNodeId } },
+                  { type: "string", value: JSON.stringify({ width: 200, height: 100 }) },
+                ],
+              })),
+            },
+          },
+        } as never;
+      return original(tabId, method, params);
+    };
+    const captured = await captureViewModel(fixture.cdp, 4);
+    expect(captured.frameGeometryIssues).toEqual([]);
+    expect([...captured.iframeNodes.keys()]).toEqual([100, 200, 101, 102, 103, 104, 105]);
+    expect(captured.iframeNodes.get(200)?.[0].rect).toEqual({ x: 0, y: 0, w: 200, h: 100 });
+    expect(methods.filter((method) => method === "DOM.getBoxModel")).toHaveLength(7);
+    expect(methods.filter((method) => method === "Runtime.evaluate")).toHaveLength(1);
+    expect(methods.filter((method) => method === "Runtime.releaseObjectGroup")).toHaveLength(1);
+    expect(methods).not.toContain("DOM.resolveNode");
+    expect(methods).not.toContain("Runtime.callFunctionOn");
+  });
+
+  it("bounds concurrent reads, fills free slots and preserves depth-first output despite reordered replies", async () => {
+    const pending = new Map<number, () => void>();
+    const fixture = siblingCaptureFixture(async (method, params) => {
+      if (method === "DOM.getBoxModel" && Number(params.backendNodeId) < 200)
+        await new Promise<void>((resolve) => pending.set(Number(params.backendNodeId), resolve));
+    });
+    const capture = captureViewModel(fixture.cdp, 4);
+    await vi.waitFor(() => expect(pending.size).toBe(4));
+    expect(fixture.measured()).toEqual([100, 101, 102, 103]);
+    pending.get(103)!();
+    await vi.waitFor(() => expect(pending.has(104)).toBe(true));
+    pending.get(104)!();
+    await vi.waitFor(() => expect(pending.has(105)).toBe(true));
+    expect(fixture.measured()).not.toContain(200);
+    for (const id of [105, 102, 101, 100]) pending.get(id)!();
+    const captured = await capture;
+    expect(captured.frameGeometryIssues).toEqual([]);
+    expect(fixture.peak()).toBe(4);
+    expect(fixture.active()).toBe(0);
+    expect(fixture.measured()).toEqual([100, 101, 102, 103, 104, 105, 200]);
+    expect([...captured.iframeNodes.keys()]).toEqual([100, 200, 101, 102, 103, 104, 105]);
+    expect(captured.iframeNodes.get(200)?.[0].rect).toEqual({ x: 0, y: 0, w: 200, h: 100 });
+    for (const method of [
+      "DOM.getBoxModel",
+      "DOM.resolveNode",
+      "Runtime.callFunctionOn",
+      "Runtime.releaseObject",
+    ])
+      expect(fixture.send.mock.calls.filter(([, name]) => name === method)).toHaveLength(7);
+  });
+
+  it("does not measure descendants of a failed owner and retains sibling geometry and local nodes", async () => {
+    const fixture = siblingCaptureFixture(async (method, params) => {
+      if (method === "DOM.resolveNode" && params.backendNodeId === 100)
+        throw new Error("owner replaced");
+    });
+    const captured = await captureViewModel(fixture.cdp, 4);
+    expect(captured.frameGeometryIssues).toEqual([
+      {
+        status: "unavailable",
+        source: { target: { tabId: 4 }, frameId: "frame-1" },
+        ownerBackendNodeId: 100,
+      },
+      {
+        status: "blocked",
+        source: { target: { tabId: 4 }, frameId: "frame-7" },
+        cause: captured.frameGeometryIssues?.[0],
+      },
+    ]);
+    expect(fixture.measured()).not.toContain(200);
+    expect(captured.iframeNodes.get(200)?.[0]).toMatchObject({
+      tag: "body",
+      rect: null,
+      localRect: { x: 0, y: 0, w: 200, h: 100 },
+    });
+    expect(captured.iframeNodes.get(101)?.[0].rect).toEqual({ x: 0, y: 0, w: 200, h: 100 });
+    expect([...captured.iframeNodes.keys()]).toEqual([100, 200, 101, 102, 103, 104, 105]);
+  });
+
+  it("stops scheduling on cancellation and waits for resolved objects to be released", async () => {
+    const controller = new AbortController();
+    const resolutions = new Map<string, () => void>();
+    const releases = new Map<string, () => void>();
+    const fixture = siblingCaptureFixture(async (method, params) => {
+      if (method === "DOM.resolveNode")
+        await new Promise<void>((resolve) =>
+          resolutions.set(String(params.backendNodeId), resolve),
+        );
+      if (method === "Runtime.releaseObject")
+        await new Promise<void>((resolve) => releases.set(String(params.objectId), resolve));
+    });
+    let settled = false;
+    const capture = captureViewModel(fixture.cdp, 4, { signal: controller.signal });
+    const rejected = expect(capture).rejects.toMatchObject({ name: "AbortError" });
+    void capture.then(
+      () => {
+        settled = true;
+      },
+      () => {
+        settled = true;
+      },
+    );
+    await vi.waitFor(() => expect(resolutions.size).toBe(4));
+    controller.abort();
+    for (const resolve of resolutions.values()) resolve();
+    await vi.waitFor(() => expect(releases.size).toBe(4));
+    expect(settled).toBe(false);
+    expect(fixture.measured()).toEqual([100, 101, 102, 103]);
+    for (const release of releases.values()) release();
+    await rejected;
+    expect(fixture.active()).toBe(0);
+    expect(fixture.send.mock.calls.some(([, method]) => method === "Runtime.callFunctionOn")).toBe(
+      false,
+    );
+  });
+});

apps/extension/src/tools/vom/__tests__/frame-capture.test.ts

@@ -50,6 +50,68 @@ function childSnapshot(frameId: string, backendNodeId: number) {
 }
 
 describe("captureFrameData", () => {
+  it("retains nested owner failures when merging a captured OOPIF", async () => {
+    const owner = ownerNode(10, 50);
+    const captured: CapturedViewModel = {
+      nodes: [owner],
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map(),
+      frameNodes: new Map([["main", [owner]]]),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    const child = childSnapshot("child", 101);
+    const nested = childSnapshot("nested", 201);
+    const document = child.documents[0];
+    const snapshot = {
+      strings: child.strings,
+      documents: [
+        {
+          ...document,
+          nodes: { ...document.nodes, contentDocumentIndex: { index: [1], value: [1] } },
+        },
+        nested.documents[0],
+      ],
+    };
+    const reply = async (_target: unknown, method: string) => {
+      if (method === "Page.getLayoutMetrics")
+        return { cssLayoutViewport: { clientWidth: 300, clientHeight: 200 } };
+      if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+      if (method === "DOM.getBoxModel")
+        return { model: { content: [50, 100, 350, 100, 350, 300, 50, 300] } };
+      if (method === "DOM.resolveNode") throw new Error("nested owner replaced");
+      return {};
+    };
+    const cdp: CdpRunner = {
+      send: vi.fn(reply) as CdpRunner["send"],
+      sendToTarget: vi.fn(reply) as NonNullable<CdpRunner["sendToTarget"]>,
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4, sessionId: "child-session" },
+          },
+        ],
+      })),
+    };
+    await captureFrameData(cdp, 4, captured);
+    expect(captured.frameGeometryIssues).toEqual([
+      {
+        status: "unavailable",
+        source: { target: { tabId: 4, sessionId: "child-session" }, frameId: "nested" },
+        ownerBackendNodeId: 101,
+      },
+    ]);
+    expect(captured.frameNodes?.get("nested")?.[1]).toMatchObject({
+      rect: null,
+      localRect: { x: 10, y: 20, w: 100, h: 40 },
+    });
+  });
+
   it("captures and positions multiple OOPIF documents missing from the root snapshot", async () => {
     const leftOwner = ownerNode(10, 50);
     const rightOwner = ownerNode(20, 500);

apps/extension/src/tools/vom/capture.ts

@@ -5,9 +5,16 @@
 // STYLE_COL so capture and visibility policy share one explicit contract.
 
 import type { Rect, Viewport } from "@browser-skill/vom";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
 import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
 import { isOverlayHostNode, OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
-import { childFrameProjection, type GeometryProjection, projectRectToViewport } from "../geometry";
+import {
+  type FrameProjectionIssue,
+  type FrameProjectionState,
+  projectSnapshotRect,
+  snapshotViewportRect,
+} from "../geometry/coordinate-types";
+import { cssViewport, GeometryContext, type LayoutMetrics } from "../geometry/frame-context";
 import type { CdpRunner } from "../shared";
 import { clearHover, ProbeBudget, waitForHover } from "./hover-perception";
 
@@ -71,12 +78,16 @@ export interface CapturedViewModel {
   /** Explicit DOMSnapshot frame ancestry; never inferred from backend node ids. */
   frameParentIds?: Map<string, string>;
   rootFrameId?: string;
+  /** Failed boundaries and descendants blocked by them; clipping is not a failure. */
+  frameGeometryIssues?: FrameProjectionIssue[];
   /** Backend node ids belonging to the agent overlay host + its shadow subtree. */
   excludedBackendNodeIds: Set<number>;
 }
 
 export interface CaptureViewModelOptions {
   signal?: AbortSignal;
+  geometry?: GeometryContext;
+  target?: CdpTarget;
 }
 
 function captureAbortError(): Error {
@@ -147,16 +158,6 @@ interface SnapshotReply {
   documents?: SnapshotDocument[];
 }
 
-interface LayoutMetricsReply {
-  cssLayoutViewport?: {
-    clientWidth?: number;
-    clientHeight?: number;
-    pageX?: number;
-    pageY?: number;
-  };
-  layoutViewport?: { clientWidth?: number; clientHeight?: number; pageX?: number; pageY?: number };
-}
-
 function isFormControlTag(tag: string): boolean {
   return tag === "input" || tag === "textarea" || tag === "select";
 }
@@ -353,7 +354,8 @@ interface ParseDocumentResult {
 interface FrameContext {
   frameId?: string;
   ownerFrameBackendNodeId: number | null;
-  projection: GeometryProjection | null;
+  projection: FrameProjectionState;
+  target: CdpTarget;
   scrollX: number;
   scrollY: number;
 }
@@ -363,15 +365,6 @@ function str(strings: string[], idx: number | undefined): string {
   return strings[idx] ?? "";
 }
 
-function devicePixelRatio(metrics: LayoutMetricsReply): number {
-  const layoutW = metrics.layoutViewport?.clientWidth ?? 0;
-  const cssW = metrics.cssLayoutViewport?.clientWidth ?? 0;
-  if (!layoutW || !cssW) return 1;
-  const dpr = layoutW / cssW;
-  if (!Number.isFinite(dpr) || dpr <= 0) return 1;
-  return dpr >= 1 ? dpr : 1;
-}
-
 function sparseIndexMap(sparse: SparseArray | undefined): Map<number, number> {
   const out = new Map<number, number>();
   if (!sparse?.index || !sparse.value) return out;
@@ -797,13 +790,11 @@ export async function collectOverlayExcludedBackendIds(
  *
  * @param doc   - the raw DOMSnapshot document object
  * @param strings - the shared string table for the whole snapshot
- * @param dpr   - device-pixel-ratio from Page.getLayoutMetrics
  * @param context - frame coordinate context; output rects are top viewport-relative
  */
 function parseDocumentNodes(
   doc: SnapshotDocument,
   strings: string[],
-  dpr: number,
   context: FrameContext,
 ): ParseDocumentResult {
   const dn = doc.nodes;
@@ -898,15 +889,19 @@ function parseDocumentNodes(
     if (li !== undefined) {
       const b = dl?.bounds?.[li];
       if (b && b.length >= 4 && b[2] > 0 && b[3] > 0) {
-        localRect = {
-          x: b[0] / dpr - context.scrollX,
-          y: b[1] / dpr - context.scrollY,
-          w: b[2] / dpr,
-          h: b[3] / dpr,
-        };
-        const bounds = context.projection
-          ? projectRectToViewport(localRect, context.projection)
-          : null;
+        const input = snapshotViewportRect(
+          b,
+          { target: context.target, frameId: context.frameId },
+          { x: context.scrollX, y: context.scrollY },
+        );
+        if (input) {
+          const { x, y, width: w, height: h } = input.rect;
+          localRect = { x, y, w, h };
+        }
+        const bounds =
+          input && context.projection.status === "available"
+            ? projectSnapshotRect(input, context.projection.projection)
+            : null;
         rect = bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
       }
       paintOrder = dl?.paintOrders?.[li] ?? 0;
@@ -974,21 +969,23 @@ function parseDocumentNodes(
 }
 
 interface ParseFrameDocumentsResult {
+  frameGeometryIssues: FrameProjectionIssue[];
   iframeNodes: CapturedIframeNodes;
   frameOwnerBackendNodeIds: Map<string, number>;
   frameParentIds: Map<string, string>;
   excludedBackendNodeIds: Set<number>;
 }
 
-function parseChildFrameDocuments(
+async function parseChildFrameDocuments(
   documents: SnapshotDocument[],
   strings: string[],
-  dpr: number,
   parentDocIndex: number,
-  parentNodes: CapturedNode[],
   parentContext: FrameContext,
+  geometry: GeometryContext,
+  signal?: AbortSignal,
   visited = new Set<number>(),
-): ParseFrameDocumentsResult {
+): Promise<ParseFrameDocumentsResult> {
+  const frameGeometryIssues: FrameProjectionIssue[] = [];
   const iframeNodes: CapturedIframeNodes = new Map();
   const frameOwnerBackendNodeIds = new Map<string, number>();
   const frameParentIds = new Map<string, string>();
@@ -996,26 +993,80 @@ function parseChildFrameDocuments(
   const parentDoc = documents[parentDocIndex];
   const cdi = sparseIndexMap(parentDoc?.nodes?.contentDocumentIndex);
   if (cdi.size === 0) {
-    return { iframeNodes, frameOwnerBackendNodeIds, frameParentIds, excludedBackendNodeIds };
+    return {
+      iframeNodes,
+      frameOwnerBackendNodeIds,
+      frameParentIds,
+      excludedBackendNodeIds,
+      frameGeometryIssues,
+    };
   }
 
   const parentBackendIds = parentDoc?.nodes?.backendNodeId ?? [];
-  const parentNodeByBackendId = new Map(parentNodes.map((node) => [node.backendNodeId, node]));
 
-  for (const [nodeArrayIdx, childDocIndex] of cdi) {
-    if (visited.has(childDocIndex)) continue;
+  const children = [...cdi].flatMap(([nodeArrayIdx, childDocIndex]) => {
     const childDoc = documents[childDocIndex];
-    if (!childDoc) continue;
     const iframeBackendId = parentBackendIds[nodeArrayIdx];
-    if (iframeBackendId === undefined) continue;
-    const iframeNode = parentNodeByBackendId.get(iframeBackendId);
-    const projection =
-      parentContext.projection && iframeNode?.localRect
-        ? childFrameProjection(parentContext.projection, iframeNode.localRect)
-        : null;
+    if (visited.has(childDocIndex) || !childDoc || iframeBackendId === undefined) return [];
+    const source = { target: parentContext.target, frameId: snapshotFrameId(childDoc, strings) };
+    const parent = parentContext.projection;
+    const projection: FrameProjectionState =
+      parent.status === "available"
+        ? { status: "unavailable", source, ownerBackendNodeId: iframeBackendId }
+        : { status: "blocked", source, cause: parent.status === "blocked" ? parent.cause : parent };
+    return [
+      {
+        childDocIndex,
+        childDoc,
+        iframeBackendId,
+        source,
+        projection: projection as FrameProjectionState,
+      },
+    ];
+  });
+  const parentProjection =
+    parentContext.projection.status === "available"
+      ? parentContext.projection.projection.geometry
+      : null;
+  if (parentProjection) {
+    // Measure only direct siblings. Recursion starts after these workers finish,
+    // so descendants never hold or recursively acquire a measurement slot.
+    const edge = parentProjection.edges[0];
+    const clips = edge
+      ? [edge.destinationQuad, ...(edge.destinationClips ?? [])]
+      : parentProjection.sourceClips;
+    let cursor = 0;
+    let failure: unknown;
+    await Promise.all(
+      Array.from({ length: Math.min(4, children.length) }, async () => {
+        while (cursor < children.length && !signal?.aborted && !failure) {
+          const child = children[cursor++];
+          try {
+            // Owner quads are target-relative; do not apply the parent transform twice.
+            child.projection = await geometry.snapshotProjection(
+              child.source,
+              child.iframeBackendId,
+              clips,
+              parentProjection.topViewport,
+            );
+          } catch (error) {
+            failure ??= error;
+          }
+        }
+      }),
+    );
+    // Join all active reads, including object cleanup, before propagating abort.
+    if (failure) throw failure;
+  }
+  throwIfAborted(signal);
 
+  // Completion order must not change document traversal or result insertion order.
+  for (const { childDocIndex, childDoc, iframeBackendId, source, projection } of children) {
+    throwIfAborted(signal);
+    if (projection.status !== "available") frameGeometryIssues.push(projection);
     const childContext: FrameContext = {
-      frameId: snapshotFrameId(childDoc, strings),
+      frameId: source.frameId,
+      target: source.target,
       ownerFrameBackendNodeId: iframeBackendId,
       projection,
       scrollX: childDoc.scrollOffsetX ?? 0,
@@ -1023,7 +1074,7 @@ function parseChildFrameDocuments(
     };
     const nextVisited = new Set(visited);
     nextVisited.add(childDocIndex);
-    const parsed = parseDocumentNodes(childDoc, strings, dpr, childContext);
+    const parsed = parseDocumentNodes(childDoc, strings, childContext);
     iframeNodes.set(iframeBackendId, parsed.nodes);
     if (childContext.frameId) {
       frameOwnerBackendNodeIds.set(childContext.frameId, iframeBackendId);
@@ -1031,15 +1082,16 @@ function parseChildFrameDocuments(
     }
     for (const id of parsed.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
 
-    const nested = parseChildFrameDocuments(
+    const nested = await parseChildFrameDocuments(
       documents,
       strings,
-      dpr,
       childDocIndex,
-      parsed.nodes,
       childContext,
+      geometry,
+      signal,
       nextVisited,
     );
+    frameGeometryIssues.push(...nested.frameGeometryIssues);
     for (const [nestedFrameId, nestedNodes] of nested.iframeNodes) {
       iframeNodes.set(nestedFrameId, nestedNodes);
     }
@@ -1052,7 +1104,13 @@ function parseChildFrameDocuments(
     for (const id of nested.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
   }
 
-  return { iframeNodes, frameOwnerBackendNodeIds, frameParentIds, excludedBackendNodeIds };
+  return {
+    iframeNodes,
+    frameOwnerBackendNodeIds,
+    frameParentIds,
+    excludedBackendNodeIds,
+    frameGeometryIssues,
+  };
 }
 
 export async function captureViewModel(
@@ -1061,22 +1119,20 @@ export async function captureViewModel(
   options: CaptureViewModelOptions = {},
 ): Promise<CapturedViewModel> {
   throwIfAborted(options.signal);
-  let metrics: LayoutMetricsReply = {};
+  const target = options.target ?? { tabId };
+  const geometry = options.geometry ?? new GeometryContext(cdp, tabId, undefined, options.signal);
+  let metrics: LayoutMetrics = {};
   try {
-    metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
+    metrics = await geometry.layoutMetrics(target);
   } catch (error) {
     if (isAbortError(error)) throw error;
     console.debug("[bsk capture] layout metrics unavailable", error);
   }
   throwIfAborted(options.signal);
-  const dpr = devicePixelRatio(metrics);
-  const vpSrc = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
-  const viewport: Viewport = {
-    width: vpSrc.clientWidth ?? 0,
-    height: vpSrc.clientHeight ?? 0,
-  };
-  const scrollX = vpSrc.pageX ?? 0;
-  const scrollY = vpSrc.pageY ?? 0;
+  const measured = cssViewport(metrics);
+  const viewport: Viewport = { width: measured.width, height: measured.height };
+  const scrollX = measured.scrollX;
+  const scrollY = measured.scrollY;
 
   await cdp.send(tabId, "DOMSnapshot.enable", {});
   throwIfAborted(options.signal);
@@ -1102,19 +1158,37 @@ export async function captureViewModel(
   const topContext: FrameContext = {
     frameId: snapshotFrameId(doc0, strings),
     ownerFrameBackendNodeId: null,
+    target,
     projection: {
-      sourceClips: [],
-      edges: [],
-      topViewport: viewport,
+      status: "available",
+      projection: {
+        source: { target, frameId: snapshotFrameId(doc0, strings) },
+        geometry: { sourceClips: [], edges: [], topViewport: viewport },
+      },
     },
     scrollX,
     scrollY,
   };
-  const mainParsed = parseDocumentNodes(doc0, strings, dpr, topContext);
+  const mainParsed = parseDocumentNodes(doc0, strings, topContext);
   const nodes = mainParsed.nodes;
   const excludedBackendNodeIds = new Set(mainParsed.excludedBackendNodeIds);
 
-  const frameParsed = parseChildFrameDocuments(documents, strings, dpr, 0, nodes, topContext);
+  const ownerIds = new Set<number>();
+  for (const document of documents) {
+    for (const index of document.nodes?.contentDocumentIndex?.index ?? []) {
+      const id = document.nodes?.backendNodeId?.[index];
+      if (id !== undefined) ownerIds.add(id);
+    }
+  }
+  geometry.registerSnapshotOwners(target, ownerIds);
+  const frameParsed = await parseChildFrameDocuments(
+    documents,
+    strings,
+    0,
+    topContext,
+    geometry,
+    options.signal,
+  );
   const iframeNodes = frameParsed.iframeNodes;
   for (const id of frameParsed.excludedBackendNodeIds) {
     excludedBackendNodeIds.add(id);
@@ -1140,6 +1214,7 @@ export async function captureViewModel(
     viewport,
     iframeNodes,
     frameNodes,
+    frameGeometryIssues: frameParsed.frameGeometryIssues,
     frameOwnerBackendNodeIds: frameParsed.frameOwnerBackendNodeIds,
     frameParentIds: frameParsed.frameParentIds,
     ...(topContext.frameId ? { rootFrameId: topContext.frameId } : {}),

apps/extension/src/tools/vom/frame-capture.ts

@@ -1,6 +1,6 @@
 import type { CdpFrame, CdpFrameGraph } from "@/browser-driver/frame-graph";
-import { resolveFrameProjection } from "../frame-geometry";
 import { type GeometryProjection, projectRectToViewport } from "../geometry";
+import { GeometryContext } from "../geometry/frame-context";
 import { type CdpRunner, cdpRunnerForTarget, sendToCdpTarget } from "../shared";
 import { type CapturedNode, type CapturedViewModel, captureViewModel } from "./capture";
 import {
@@ -21,16 +21,6 @@ function isAbortError(err: unknown): boolean {
   return err instanceof Error && err.name === "AbortError";
 }
 
-async function discoverFrameGraph(cdp: CdpRunner, tabId: number): Promise<CdpFrameGraph | null> {
-  if (!cdp.getFrameGraph) return null;
-  try {
-    return await cdp.getFrameGraph(tabId);
-  } catch (err) {
-    console.debug("[bsk observation] frame graph capture failed", err);
-    return null;
-  }
-}
-
 function transformFrameNodes(
   nodes: CapturedNode[],
   projection: GeometryProjection | null,
@@ -51,6 +41,7 @@ async function captureMissingFrameDocuments(
   tabId: number,
   graph: CdpFrameGraph,
   captured: CapturedViewModel,
+  geometry: GeometryContext,
   signal?: AbortSignal,
 ): Promise<void> {
   if (!captured.frameNodes) captured.frameNodes = new Map();
@@ -62,10 +53,15 @@ async function captureMissingFrameDocuments(
     try {
       const child = await captureViewModel(cdpRunnerForTarget(cdp, frame.target), tabId, {
         signal,
+        geometry,
+        target: frame.target,
       });
+      if (child.frameGeometryIssues?.length) {
+        (captured.frameGeometryIssues ??= []).push(...child.frameGeometryIssues);
+      }
       let projection: GeometryProjection | null = null;
       try {
-        projection = await resolveFrameProjection(cdp, graph, frame.frameId);
+        projection = await geometry.targetProjection(frame.frameId);
       } catch (err) {
         if (isAbortError(err)) throw err;
         console.debug("[bsk observation] child frame geometry projection failed", {
@@ -171,10 +167,11 @@ export async function captureFrameData<T extends FrameAxNode>(
   tabId: number,
   captured: CapturedViewModel,
   signal?: AbortSignal,
+  geometry = new GeometryContext(cdp, tabId, undefined, signal),
 ): Promise<CapturedFrameDocument<T>[]> {
-  const graph = await discoverFrameGraph(cdp, tabId);
+  const graph = await geometry.graph();
   const frames = graph?.frames ?? [];
-  if (graph) await captureMissingFrameDocuments(cdp, tabId, graph, captured, signal);
+  if (graph) await captureMissingFrameDocuments(cdp, tabId, graph, captured, geometry, signal);
   throwIfAborted(signal);
   const batches = await captureAxTrees<T>(cdp, tabId, frames, captured, signal);
   return buildFrameDocuments(graph, batches, captured);

packages/dsh-plugin-browserskill/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wxg-prc-cpg/browser-skill-dsh-plugin",
   "description": "DeepSeek Harness tool plugin that exposes BrowserSkill browser automation (browser_* tools) to the model",
-  "version": "0.2.1",
+  "version": "0.2.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

scripts/release.mjs

@@ -174,22 +174,16 @@ function updateChangelog(version) {
 
   const today = new Date().toISOString().slice(0, 10);
   const escapedVer = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const versionHeading = new RegExp(`^## \\[${escapedVer}\\](?:\\s|$)`, "m");
 
   // First: fill in any date-placeholder line for this version (e.g. "## [0.2.0] - 2026-09-XX")
   const versionPlaceholder = new RegExp(`^## \\[${escapedVer}\\]\\s*-\\s*\\d{4}-\\d{2}-XX`, "m");
   if (versionPlaceholder.test(content)) {
     content = content.replace(versionPlaceholder, `## [${version}] - ${today}`);
-  } else if (!versionHeading.test(content)) {
-    // Preserve prepared release entries; new versions go before the release history.
-    const heading = `## [${version}] - ${today}`;
+  } else {
+    // Otherwise: insert a new section after [Unreleased]
     const unreleased = /^## \[Unreleased\]/m;
     if (unreleased.test(content)) {
-      content = content.replace(unreleased, `## [Unreleased]\n\n${heading}`);
-    } else if (/^## /m.test(content)) {
-      content = content.replace(/^## /m, `${heading}\n\n## `);
-    } else {
-      content = `${content.trimEnd()}\n\n${heading}\n`;
+      content = content.replace(unreleased, `## [Unreleased]\n\n## [${version}] - ${today}`);
     }
   }