mirror of
https://github.com/Tencent/BrowserSkill.git
synced 2026-09-10 13:01:23 +08:00
Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
d7b2c6cccd | ||
|
|
1f6faa7a0a | ||
|
|
27dba3c57f |
No files matched your search
@@ -38,7 +38,7 @@ jobs:
|
||||
run: cargo test --workspace --locked
|
||||
|
||||
windows-daemon:
|
||||
name: Windows daemon, installer and cancellation regression tests
|
||||
name: Windows daemon and update regression tests
|
||||
runs-on: windows-latest
|
||||
|
||||
steps:
|
||||
@@ -55,16 +55,8 @@ jobs:
|
||||
- name: Run Windows update tests
|
||||
run: cargo test -p bsk --lib --locked cli::update::tests
|
||||
|
||||
- name: Run Windows update and cancellation process tests
|
||||
run: cargo test -p bsk --test windows_update --test windows_parent_cancel --locked
|
||||
|
||||
- name: Run installer tests (Windows PowerShell 5.1)
|
||||
shell: powershell
|
||||
run: ./scripts/install-windows.test.ps1
|
||||
|
||||
- name: Run installer tests (PowerShell 7)
|
||||
shell: pwsh
|
||||
run: ./scripts/install-windows.test.ps1
|
||||
- name: Run Windows update process tests
|
||||
run: cargo test -p bsk --test windows_update --locked
|
||||
|
||||
frontend:
|
||||
name: Frontend lint, typecheck, tests, build
|
||||
|
||||
+1
-18
@@ -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
|
||||
|
||||
|
||||
Generated
+2
-2
@@ -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",
|
||||
|
||||
+2
-2
@@ -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"
|
||||
|
||||
@@ -47,17 +47,14 @@ extension.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Install the CLI and skill
|
||||
|
||||
<details open>
|
||||
<summary><b>Install with your Agent (recommended)</b></summary>
|
||||
|
||||
<br>
|
||||
|
||||
Already using Cursor, Claude Code, Codex, WorkBuddy, or another shell-capable
|
||||
agent? Just copy this one line and send it to your agent — it will install the
|
||||
CLI and skill for you. You will install the browser extension yourself in step 2
|
||||
below.
|
||||
Already using Cursor, Claude Code, Codex, or another shell-capable agent? Just
|
||||
copy this one line and send it to your agent — it will install the CLI and skill
|
||||
for you, then walk you through loading the extension:
|
||||
|
||||
```text
|
||||
Set up browser-skill on this machine by following https://raw.githubusercontent.com/Tencent/BrowserSkill/main/AGENT_INSTALL.md
|
||||
@@ -70,9 +67,10 @@ Set up browser-skill on this machine by following https://raw.githubusercontent.
|
||||
|
||||
<br>
|
||||
|
||||
Install the CLI and skill with the commands below.
|
||||
Install the CLI, then install the extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi)
|
||||
or [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg).
|
||||
|
||||
#### Install the `bsk` CLI
|
||||
#### 1. Install the `bsk` CLI
|
||||
|
||||
**macOS / Linux** (recommended — installs to `~/.local/bin`):
|
||||
|
||||
@@ -92,7 +90,18 @@ Verify the binary:
|
||||
bsk --version
|
||||
```
|
||||
|
||||
#### Install the skill
|
||||
#### 2. Install the browser extension
|
||||
|
||||
Install BrowserSkill from your browser's store:
|
||||
|
||||
| Browser | Store listing |
|
||||
| --- | --- |
|
||||
| Chrome | [Chrome Web Store](https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi) |
|
||||
| Microsoft Edge | [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg) |
|
||||
|
||||
On other Chromium-based browsers, install the Chrome Web Store build.
|
||||
|
||||
#### 3. Install the skill
|
||||
|
||||
BrowserSkill ships a skill that teaches your agent harness how to use `bsk`. For
|
||||
these harnesses, install it in one step:
|
||||
@@ -127,21 +136,6 @@ dedicated plugin instead — see [DeepSeek Harness plugin](#deepseek-harness-plu
|
||||
|
||||
</details>
|
||||
|
||||
### 2. Install the browser extension
|
||||
|
||||
Due to current browser security policies, you still need to manually install
|
||||
the extension for your browser.
|
||||
Open the store link for your browser and confirm the extension installation:
|
||||
|
||||
| Browser | Store listing |
|
||||
| --- | --- |
|
||||
| Chrome | [Chrome Web Store](https://chromewebstore.google.com/detail/browserskill/hhcmgoofomhgciiibhipgmgkgnoenaoi) |
|
||||
| Microsoft Edge | [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg) |
|
||||
|
||||
On other Chromium-based browsers, install the Chrome Web Store build.
|
||||
|
||||
### 3. Start using BrowserSkill
|
||||
|
||||
Start a new Agent session and write a prompt that needs the browser, for example:
|
||||
|
||||
```text
|
||||
@@ -153,26 +147,20 @@ Start a new Agent session and write a prompt that needs the browser, for example
|
||||
Using [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`)?
|
||||
BrowserSkill ships a first-class dsh plugin on npm as
|
||||
[`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin).
|
||||
It gives the agent native `browser_*` tools and a live view of its browser sessions
|
||||
in the Web UI. The plugin runs `bsk` on the agent's behalf.
|
||||
It injects native `browser_*` tools (no shelling out to `bsk`) and a live Web UI
|
||||
overlay of each Agent Window.
|
||||
|
||||
Install the `bsk` CLI and connect the browser extension first. Then add the plugin
|
||||
to a dsh profile and start it (replace `web` with your profile name):
|
||||
Add it to a dsh profile, then start that profile:
|
||||
|
||||
```sh
|
||||
dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
|
||||
dsh --profile web
|
||||
```
|
||||
|
||||
The plugin includes the `browser-skill` skill, so `bsk install-skill` is not needed
|
||||
for dsh. Installed plugins do not update automatically. To upgrade this plugin:
|
||||
|
||||
```sh
|
||||
dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest
|
||||
```
|
||||
|
||||
Restart the profile after upgrading. See the
|
||||
[plugin README](packages/dsh-plugin-browserskill/README.md) for usage and configuration.
|
||||
The plugin carries its own copy of the skill, so `bsk install-skill` is not needed
|
||||
for dsh — but the `bsk` CLI and the browser extension are still prerequisites. See
|
||||
the [plugin README](packages/dsh-plugin-browserskill/README.md) for the tool list,
|
||||
configuration, and the observation overlay.
|
||||
|
||||
## How It Works
|
||||
|
||||
|
||||
+19
-29
@@ -36,14 +36,12 @@ BrowserSkill 由两个本地运行组件组成:`bsk` CLI/daemon 和浏览器
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 安装 CLI 和 skill
|
||||
|
||||
<details open>
|
||||
<summary><b>让 Agent 帮你安装(推荐)</b></summary>
|
||||
|
||||
<br>
|
||||
|
||||
已经在用 Cursor、Claude Code、Codex、WorkBuddy 或其他支持 Shell 的 Agent?只需复制下面这句话发给 Agent,它会帮你安装 CLI 和 skill。浏览器扩展仍需你按下方第 2 步自行安装。
|
||||
已经在用 Cursor、Claude Code、Codex 或其他支持 Shell 的 Agent?只需复制下面这句话发给 Agent,它会帮你安装 CLI 和 skill,并引导你加载浏览器扩展:
|
||||
|
||||
```text
|
||||
按照 https://raw.githubusercontent.com/Tencent/BrowserSkill/main/AGENT_INSTALL.md 的说明,在本机安装并配置 browser-skill
|
||||
@@ -56,9 +54,10 @@ BrowserSkill 由两个本地运行组件组成:`bsk` CLI/daemon 和浏览器
|
||||
|
||||
<br>
|
||||
|
||||
按以下命令安装 CLI 和 skill。
|
||||
先安装 CLI,再从 [Chrome Web Store](https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi)
|
||||
或 [Edge 加载项商店](https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg) 安装浏览器扩展。
|
||||
|
||||
#### 安装 `bsk` CLI
|
||||
#### 1. 安装 `bsk` CLI
|
||||
|
||||
**macOS / Linux**(推荐,安装到 `~/.local/bin`):
|
||||
|
||||
@@ -78,7 +77,18 @@ irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | ie
|
||||
bsk --version
|
||||
```
|
||||
|
||||
#### 安装 skill
|
||||
#### 2. 安装浏览器扩展
|
||||
|
||||
在对应浏览器的商店安装 BrowserSkill:
|
||||
|
||||
| 浏览器 | 商店页面 |
|
||||
| --- | --- |
|
||||
| Chrome | [Chrome Web Store](https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi) |
|
||||
| Microsoft Edge | [Edge 加载项商店](https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg) |
|
||||
|
||||
其他基于 Chromium 的浏览器,安装 Chrome Web Store 版本即可。
|
||||
|
||||
#### 3. 安装 skill
|
||||
|
||||
BrowserSkill 自带 skill,用于教 Agent harness 如何使用 `bsk`。以下 harness 可一键安装:
|
||||
|
||||
@@ -107,20 +117,6 @@ bsk install-skill
|
||||
|
||||
</details>
|
||||
|
||||
### 2. 安装浏览器扩展
|
||||
|
||||
目前由于浏览器的安全策略,您还需要手动安装对应的浏览器扩展。
|
||||
点击对应浏览器的商店链接,并在浏览器中确认安装扩展:
|
||||
|
||||
| 浏览器 | 商店页面 |
|
||||
| --- | --- |
|
||||
| Chrome | [Chrome Web Store](https://chromewebstore.google.com/detail/browserskill/hhcmgoofomhgciiibhipgmgkgnoenaoi) |
|
||||
| Microsoft Edge | [Edge 加载项商店](https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg) |
|
||||
|
||||
其他基于 Chromium 的浏览器,安装 Chrome Web Store 版本即可。
|
||||
|
||||
### 3. 开始使用 BrowserSkill
|
||||
|
||||
启动一个新的 Agent 会话,写一条需要使用浏览器的 prompt,例如:
|
||||
|
||||
```text
|
||||
@@ -129,22 +125,16 @@ bsk install-skill
|
||||
|
||||
## DeepSeek Harness 插件
|
||||
|
||||
在用 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`)?BrowserSkill 提供了官方 dsh 插件,已发布到 npm:[`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)。它为 Agent 提供原生 `browser_*` 工具,由插件代为调用 `bsk`,并在 Web UI 中实时展示浏览器会话。
|
||||
在用 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`)?BrowserSkill 提供了官方 dsh 插件,已发布到 npm:[`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)。它会注入原生 `browser_*` 工具(无需再通过 Shell 调用 `bsk`),并在 Web UI 中实时观察每个 Agent Window。
|
||||
|
||||
先安装 `bsk` CLI 并连接浏览器扩展,再将插件装进 dsh profile 并启动(将 `web` 替换为你的 profile 名称):
|
||||
把它装进某个 dsh profile,然后启动该 profile:
|
||||
|
||||
```sh
|
||||
dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
|
||||
dsh --profile web
|
||||
```
|
||||
|
||||
插件自带 `browser-skill` skill,所以在 dsh 下无需执行 `bsk install-skill`。已安装的插件不会自动更新;升级此插件请运行:
|
||||
|
||||
```sh
|
||||
dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest
|
||||
```
|
||||
|
||||
升级后重启该 profile。用法与配置见[插件 README](packages/dsh-plugin-browserskill/README.md)。
|
||||
插件自带 skill,所以在 dsh 下无需执行 `bsk install-skill`;但 `bsk` CLI 和浏览器扩展仍是前置条件。工具清单、配置项与观察浮层见[插件 README](packages/dsh-plugin-browserskill/README.md)。
|
||||
|
||||
## 工作原理
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@browser-skill/extension",
|
||||
"version": "0.2.1",
|
||||
"version": "0.2.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
|
||||
@@ -29,6 +29,24 @@ function fakeApi() {
|
||||
}
|
||||
|
||||
describe("ChromiumCdp", () => {
|
||||
it("changes attachment identity only across real debugger attachments", async () => {
|
||||
const { api, onEvent, onDetach } = fakeApi();
|
||||
const cdp = new ChromiumCdp(api);
|
||||
expect(cdp.getAttachmentId(4)).toBeUndefined();
|
||||
await cdp.ensureAttached(4);
|
||||
const first = cdp.getAttachmentId(4);
|
||||
expect(first).toBeTruthy();
|
||||
await cdp.ensureAttached(4);
|
||||
onEvent.fire({ tabId: 4 }, "Target.attachedToTarget", { sessionId: "child" });
|
||||
expect(cdp.getAttachmentId(4)).toBe(first);
|
||||
onDetach.fire({ tabId: 4 }, "target_closed");
|
||||
expect(cdp.getAttachmentId(4)).toBeUndefined();
|
||||
await cdp.ensureAttached(4);
|
||||
expect(cdp.getAttachmentId(4)).not.toBe(first);
|
||||
await cdp.detach(4);
|
||||
expect(cdp.getAttachmentId(4)).toBeUndefined();
|
||||
});
|
||||
|
||||
it("discovers multiple iframe targets and recursively routes nested OOPIF commands", async () => {
|
||||
const { api, onEvent } = fakeApi();
|
||||
(api.sendCommand as ReturnType<typeof vi.fn>).mockImplementation(
|
||||
|
||||
@@ -2,6 +2,24 @@ import { describe, expect, it } from "vitest";
|
||||
import { buildFrameGraph, type CdpFrameTreeNode, type CdpFrameTreeSource } from "../frame-graph";
|
||||
|
||||
describe("buildFrameGraph", () => {
|
||||
it("preserves the owning target's loader identity", () => {
|
||||
const graph = buildFrameGraph([
|
||||
{
|
||||
target: { tabId: 4 },
|
||||
tree: {
|
||||
frame: { id: "root", loaderId: "root-loader" },
|
||||
childFrames: [{ frame: { id: "child", loaderId: "stale-placeholder" } }],
|
||||
},
|
||||
},
|
||||
{
|
||||
target: { tabId: 4, sessionId: "child-session" },
|
||||
tree: { frame: { id: "child", loaderId: "child-loader" } },
|
||||
},
|
||||
]);
|
||||
expect(graph?.frames.find((frame) => frame.frameId === "root")?.loaderId).toBe("root-loader");
|
||||
expect(graph?.frames.find((frame) => frame.frameId === "child")?.loaderId).toBe("child-loader");
|
||||
});
|
||||
|
||||
it("keeps sibling frames distinct and routes nested OOPIFs to their child sessions", () => {
|
||||
const graph = buildFrameGraph([
|
||||
{
|
||||
|
||||
@@ -164,6 +164,7 @@ async function settleBeforeDeadline(promises: Promise<void>[], deadline: number)
|
||||
export class ChromiumCdp {
|
||||
private readonly api: CdpDebuggerApi;
|
||||
private readonly attachedTabs = new Set<number>();
|
||||
private readonly attachmentIds = new Map<number, string>();
|
||||
private readonly attachInFlight = new Map<number, Promise<void>>();
|
||||
private readonly detachInFlight = new Map<number, Promise<void>>();
|
||||
private readonly tabOwners = new Map<number, Set<string>>();
|
||||
@@ -198,6 +199,11 @@ export class ChromiumCdp {
|
||||
this.bindFrameTargetHandler();
|
||||
}
|
||||
|
||||
/** Identity of this actual debugger attachment, independent of frame topology. */
|
||||
getAttachmentId(tabId: number): string | undefined {
|
||||
return this.attachmentIds.get(tabId);
|
||||
}
|
||||
|
||||
/** Attach to `tabId` if we haven't already in this driver. */
|
||||
async ensureAttached(tabId: number): Promise<void> {
|
||||
// Returning a tab clears the cache before Chrome finishes detaching.
|
||||
@@ -217,6 +223,7 @@ export class ChromiumCdp {
|
||||
await this.enableConsoleDomains(tabId);
|
||||
await this.enableNetworkDomainBestEffort(tabId);
|
||||
this.attachedTabs.add(tabId);
|
||||
this.attachmentIds.set(tabId, crypto.randomUUID());
|
||||
await this.enableFrameDiscovery({ tabId }).catch((err) => {
|
||||
console.debug("[bsk cdp] frame discovery unavailable", { tabId, err });
|
||||
});
|
||||
@@ -444,6 +451,7 @@ export class ChromiumCdp {
|
||||
this.attachInFlight.delete(tabId);
|
||||
if (!this.attachedTabs.has(tabId)) return;
|
||||
this.attachedTabs.delete(tabId);
|
||||
this.attachmentIds.delete(tabId);
|
||||
this.clearDialogState(tabId);
|
||||
this.clearConsoleState(tabId);
|
||||
this.clearNetworkState(tabId);
|
||||
@@ -502,6 +510,7 @@ export class ChromiumCdp {
|
||||
this.attachInFlight.clear();
|
||||
this.tabOwners.clear();
|
||||
this.attachedTabs.clear();
|
||||
this.attachmentIds.clear();
|
||||
this.dialogBuffers.clear();
|
||||
this.dialogSequences.clear();
|
||||
this.consoleBuffers.clear();
|
||||
@@ -848,6 +857,7 @@ export class ChromiumCdp {
|
||||
const listener = (source: chrome.debugger.Debuggee, _reason: string) => {
|
||||
if (typeof source.tabId === "number") {
|
||||
this.attachedTabs.delete(source.tabId);
|
||||
this.attachmentIds.delete(source.tabId);
|
||||
this.attachInFlight.delete(source.tabId);
|
||||
this.tabOwners.delete(source.tabId);
|
||||
this.clearDialogState(source.tabId);
|
||||
|
||||
@@ -8,6 +8,7 @@ export interface CdpFrame {
|
||||
parentFrameId?: string;
|
||||
ownerBackendNodeId?: number;
|
||||
url?: string;
|
||||
loaderId?: string;
|
||||
target: CdpTarget;
|
||||
}
|
||||
|
||||
@@ -21,6 +22,7 @@ export interface CdpFrameTreeNode {
|
||||
id: string;
|
||||
parentId?: string;
|
||||
url?: string;
|
||||
loaderId?: string;
|
||||
};
|
||||
childFrames?: CdpFrameTreeNode[];
|
||||
}
|
||||
@@ -48,6 +50,7 @@ function mergeFrame(
|
||||
frameId: node.frame.id,
|
||||
...(parentFrameId ? { parentFrameId } : {}),
|
||||
...(url ? { url } : {}),
|
||||
...(node.frame.loaderId ? { loaderId: node.frame.loaderId } : {}),
|
||||
target,
|
||||
});
|
||||
}
|
||||
|
||||
@@ -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([
|
||||
{
|
||||
|
||||
@@ -0,0 +1,284 @@
|
||||
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,
|
||||
});
|
||||
const input = snapshotViewportRect([17, 23, 120, 40], source, { x: 0, y: 0 });
|
||||
expect(projectSnapshotRect(input!, 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!)?.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("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,
|
||||
}),
|
||||
).toBeNull();
|
||||
});
|
||||
|
||||
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 },
|
||||
);
|
||||
const input = snapshotViewportRect(
|
||||
[0, 0, 300, 200],
|
||||
{ target, frameId: "nested" },
|
||||
{ x: 0, y: 0 },
|
||||
);
|
||||
expect(projectSnapshotRect(input!, 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,
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -4,9 +4,9 @@ import { CAPTURE_SUPPRESS, type CaptureSuppressMessage } from "@/lib/capture-sup
|
||||
import { OVERLAY_HOST_MARKER_ATTR, OVERLAY_HOST_NAME } from "@/lib/overlay-bridge";
|
||||
import { SessionManager } from "@/session-manager/manager";
|
||||
import type { CdpRunner } from "@/tools/shared";
|
||||
import type { BuildVomSceneOptions, VomFrameDocument } from "../observation";
|
||||
import {
|
||||
buildFrameVomScene,
|
||||
buildVomScene,
|
||||
type CdpAxNode,
|
||||
captureVomObservation,
|
||||
handleGetHtml,
|
||||
@@ -17,7 +17,35 @@ import {
|
||||
type ScreenshotDeps,
|
||||
stripDataUrlPrefix,
|
||||
} from "../observation";
|
||||
import type { CapturedNode, CapturedViewModel } from "../vom/capture";
|
||||
import type { CapturedNode, CapturedSceneInput } from "../vom/facts";
|
||||
|
||||
interface SceneFixture extends CapturedSceneInput {
|
||||
documents?: VomFrameDocument[];
|
||||
}
|
||||
|
||||
// Only supplies the common root fixture; child documents declare their own ownership.
|
||||
function buildTestScene(
|
||||
axNodes: CdpAxNode[],
|
||||
captured: SceneFixture,
|
||||
options: BuildVomSceneOptions = {},
|
||||
) {
|
||||
const rootFrameId = captured.rootFrameId ?? "root";
|
||||
return buildFrameVomScene(
|
||||
[
|
||||
{
|
||||
frameId: rootFrameId,
|
||||
contextScopeId: rootFrameId,
|
||||
target: { tabId: 7 },
|
||||
url: options.pageUrl,
|
||||
domNodes: captured.nodes,
|
||||
axNodes,
|
||||
},
|
||||
...(captured.documents ?? []),
|
||||
],
|
||||
captured,
|
||||
options,
|
||||
);
|
||||
}
|
||||
|
||||
function fakeAgentWindow(ids: number[]) {
|
||||
let i = 0;
|
||||
@@ -266,7 +294,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 +310,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 +337,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 () => {
|
||||
@@ -509,10 +550,10 @@ describe("handleScreenshot overlay suppression", () => {
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// buildVomScene
|
||||
// Semantic scene fixtures
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe("buildVomScene", () => {
|
||||
describe("buildFrameVomScene", () => {
|
||||
it("merges multiple sibling and nested frames without mixing their targets", () => {
|
||||
const node = (
|
||||
backendNodeId: number,
|
||||
@@ -550,25 +591,10 @@ describe("buildVomScene", () => {
|
||||
node(300, null, "nested", "body"),
|
||||
node(301, 300, "nested", "input", { placeholder: "Nested field" }),
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1200, height: 800 },
|
||||
nodes: mainNodes,
|
||||
iframeNodes: new Map([
|
||||
[10, firstNodes],
|
||||
[20, secondNodes],
|
||||
[210, nestedNodes],
|
||||
]),
|
||||
frameNodes: new Map([
|
||||
["main", mainNodes],
|
||||
["first", firstNodes],
|
||||
["second", secondNodes],
|
||||
["nested", nestedNodes],
|
||||
]),
|
||||
frameOwnerBackendNodeIds: new Map([
|
||||
["first", 10],
|
||||
["second", 20],
|
||||
["nested", 210],
|
||||
]),
|
||||
|
||||
rootFrameId: "main",
|
||||
excludedBackendNodeIds: new Set(),
|
||||
};
|
||||
@@ -667,11 +693,10 @@ describe("buildVomScene", () => {
|
||||
position: "static",
|
||||
pointerEvents: "auto",
|
||||
};
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 800, height: 600 },
|
||||
nodes: [],
|
||||
iframeNodes: new Map(),
|
||||
frameNodes: new Map([["child", [childNode]]]),
|
||||
|
||||
rootFrameId: "main",
|
||||
excludedBackendNodeIds: new Set(),
|
||||
};
|
||||
@@ -733,14 +758,10 @@ describe("buildVomScene", () => {
|
||||
pointerEvents: "auto",
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 800, height: 600 },
|
||||
nodes: mainNodes,
|
||||
iframeNodes: new Map(),
|
||||
frameNodes: new Map([
|
||||
["main", mainNodes],
|
||||
["child", []],
|
||||
]),
|
||||
|
||||
rootFrameId: "main",
|
||||
excludedBackendNodeIds: new Set(),
|
||||
};
|
||||
@@ -816,9 +837,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 200,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -844,11 +864,11 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const scene = buildVomScene(axNodes, captured);
|
||||
const scene = buildTestScene(axNodes, captured);
|
||||
expect(scene.viewport).toEqual({ width: 1000, height: 800 });
|
||||
expect(scene.nodes[0]).toEqual(
|
||||
expect.objectContaining({
|
||||
id: 100,
|
||||
backendNodeId: 100,
|
||||
parentId: null,
|
||||
role: "RootWebArea",
|
||||
name: "Example",
|
||||
@@ -860,14 +880,14 @@ describe("buildVomScene", () => {
|
||||
);
|
||||
expect(scene.nodes[1]).toEqual(
|
||||
expect.objectContaining({
|
||||
id: 200,
|
||||
parentId: 100,
|
||||
backendNodeId: 200,
|
||||
parentId: scene.nodes.find((node) => node.backendNodeId === 100)!.id,
|
||||
role: "button",
|
||||
name: "Submit",
|
||||
tag: "button",
|
||||
rect: { x: 20, y: 20, w: 120, h: 40 },
|
||||
domParentId: 100,
|
||||
domAncestorIds: [100],
|
||||
domParentId: scene.nodes.find((node) => node.backendNodeId === 100)!.id,
|
||||
domAncestorIds: [scene.nodes.find((node) => node.backendNodeId === 100)!.id],
|
||||
attrs: {},
|
||||
}),
|
||||
);
|
||||
@@ -896,9 +916,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 300,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -934,10 +953,10 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const scene = buildVomScene(axNodes, captured, { pageUrl: "https://app.example.test/home" });
|
||||
const scene = buildTestScene(axNodes, captured, { pageUrl: "https://app.example.test/home" });
|
||||
|
||||
expect(scene.nodes.find((node) => node.id === 200)?.href).toBe("docs.example.org");
|
||||
expect(scene.nodes.find((node) => node.id === 300)?.href).toBeUndefined();
|
||||
expect(scene.nodes.find((node) => node.backendNodeId === 200)?.href).toBe("docs.example.org");
|
||||
expect(scene.nodes.find((node) => node.backendNodeId === 300)?.href).toBeUndefined();
|
||||
});
|
||||
|
||||
it("uses the nearest backend AX ancestor as parentId", () => {
|
||||
@@ -962,9 +981,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 30,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 400, height: 300 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -990,10 +1008,12 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const scene = buildVomScene(axNodes, captured);
|
||||
const scene = buildTestScene(axNodes, captured);
|
||||
|
||||
expect(scene.nodes.map((node) => node.id)).toEqual([10, 30]);
|
||||
expect(scene.nodes.find((node) => node.id === 30)?.parentId).toBe(10);
|
||||
expect(scene.nodes.map((node) => node.backendNodeId)).toEqual([10, 30]);
|
||||
expect(scene.nodes.find((node) => node.backendNodeId === 30)?.parentId).toBe(
|
||||
scene.nodes.find((node) => node.backendNodeId === 10)!.id,
|
||||
);
|
||||
});
|
||||
|
||||
it("maps iframe sub-document controls to VomNodes", () => {
|
||||
@@ -1011,7 +1031,7 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 20,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
nodes: [
|
||||
{
|
||||
@@ -1035,10 +1055,15 @@ describe("buildVomScene", () => {
|
||||
pointerEvents: "auto",
|
||||
},
|
||||
],
|
||||
iframeNodes: new Map([
|
||||
[
|
||||
20,
|
||||
[
|
||||
documents: [
|
||||
{
|
||||
frameId: "child",
|
||||
contextScopeId: "child",
|
||||
parentFrameId: "root",
|
||||
ownerBackendNodeId: 20,
|
||||
target: { tabId: 7 },
|
||||
axNodes: [],
|
||||
domNodes: [
|
||||
{
|
||||
backendNodeId: 101,
|
||||
parentBackendNodeId: null,
|
||||
@@ -1060,26 +1085,25 @@ describe("buildVomScene", () => {
|
||||
pointerEvents: "auto",
|
||||
},
|
||||
],
|
||||
],
|
||||
]),
|
||||
},
|
||||
],
|
||||
excludedBackendNodeIds: new Set(),
|
||||
};
|
||||
|
||||
const iframeControls = buildVomScene(axNodes, captured).nodes.filter((node) =>
|
||||
[101, 102].includes(node.id),
|
||||
);
|
||||
const scene = buildTestScene(axNodes, captured);
|
||||
const iframeControls = scene.nodes.filter((node) => [101, 102].includes(node.backendNodeId!));
|
||||
|
||||
expect(iframeControls).toEqual([
|
||||
expect.objectContaining({
|
||||
id: 101,
|
||||
parentId: 20,
|
||||
backendNodeId: 101,
|
||||
parentId: scene.nodes.find((node) => node.backendNodeId === 20)!.id,
|
||||
role: "textbox",
|
||||
name: "请输入手机号",
|
||||
sensitive: false,
|
||||
}),
|
||||
expect.objectContaining({
|
||||
id: 102,
|
||||
parentId: 20,
|
||||
backendNodeId: 102,
|
||||
parentId: scene.nodes.find((node) => node.backendNodeId === 20)!.id,
|
||||
role: "textbox",
|
||||
name: "密码",
|
||||
sensitive: true,
|
||||
@@ -1100,11 +1124,9 @@ describe("buildVomScene", () => {
|
||||
parentId: "1",
|
||||
role: { type: "role", value: "Iframe" },
|
||||
backendDOMNodeId: 20,
|
||||
childIds: ["3"],
|
||||
},
|
||||
{
|
||||
nodeId: "3",
|
||||
parentId: "2",
|
||||
role: { type: "role", value: "textbox" },
|
||||
name: { type: "x", value: "输入密码" },
|
||||
value: { value: "iframe-secret" },
|
||||
@@ -1112,7 +1134,7 @@ describe("buildVomScene", () => {
|
||||
properties: [{ name: "inputType", value: { value: "password" } }],
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
nodes: [
|
||||
{
|
||||
@@ -1136,10 +1158,15 @@ describe("buildVomScene", () => {
|
||||
pointerEvents: "auto",
|
||||
},
|
||||
],
|
||||
iframeNodes: new Map([
|
||||
[
|
||||
20,
|
||||
[
|
||||
documents: [
|
||||
{
|
||||
frameId: "child",
|
||||
contextScopeId: "child",
|
||||
parentFrameId: "root",
|
||||
ownerBackendNodeId: 20,
|
||||
target: { tabId: 7 },
|
||||
axNodes: [axNodes[2]],
|
||||
domNodes: [
|
||||
{
|
||||
backendNodeId: 102,
|
||||
parentBackendNodeId: null,
|
||||
@@ -1151,25 +1178,27 @@ describe("buildVomScene", () => {
|
||||
pointerEvents: "auto",
|
||||
},
|
||||
],
|
||||
],
|
||||
]),
|
||||
},
|
||||
],
|
||||
excludedBackendNodeIds: new Set(),
|
||||
};
|
||||
|
||||
const passwordNodes = buildVomScene(axNodes, captured).nodes.filter(
|
||||
const passwordNodes = buildTestScene(axNodes.slice(0, 2), captured).nodes.filter(
|
||||
(node) => node.role === "textbox" && node.name === "输入密码",
|
||||
);
|
||||
|
||||
expect(passwordNodes).toHaveLength(1);
|
||||
expect(passwordNodes[0]).toEqual(expect.objectContaining({ id: 202, sensitive: true }));
|
||||
expect(passwordNodes[0]).toEqual(
|
||||
expect.objectContaining({ backendNodeId: 202, sensitive: true }),
|
||||
);
|
||||
expect(passwordNodes[0].value).toBeUndefined();
|
||||
const rendered = renderVom(buildVomScene(axNodes, captured)).text;
|
||||
const rendered = renderVom(buildTestScene(axNodes.slice(0, 2), captured)).text;
|
||||
expect(rendered).toContain('textbox "输入密码" [filled] ="•••"');
|
||||
expect(rendered).not.toContain("iframe-secret");
|
||||
});
|
||||
|
||||
it("keeps unnamed iframe controls but skips unnamed iframe links", () => {
|
||||
const scene = buildVomScene(
|
||||
const scene = buildTestScene(
|
||||
[
|
||||
{
|
||||
nodeId: "1",
|
||||
@@ -1208,10 +1237,15 @@ describe("buildVomScene", () => {
|
||||
pointerEvents: "auto",
|
||||
},
|
||||
],
|
||||
iframeNodes: new Map([
|
||||
[
|
||||
20,
|
||||
[
|
||||
documents: [
|
||||
{
|
||||
frameId: "child",
|
||||
contextScopeId: "child",
|
||||
parentFrameId: "root",
|
||||
ownerBackendNodeId: 20,
|
||||
target: { tabId: 7 },
|
||||
axNodes: [],
|
||||
domNodes: [
|
||||
{
|
||||
backendNodeId: 201,
|
||||
parentBackendNodeId: null,
|
||||
@@ -1233,25 +1267,25 @@ describe("buildVomScene", () => {
|
||||
pointerEvents: "auto",
|
||||
},
|
||||
],
|
||||
],
|
||||
]),
|
||||
},
|
||||
],
|
||||
excludedBackendNodeIds: new Set(),
|
||||
},
|
||||
);
|
||||
|
||||
expect(scene.nodes.find((node) => node.id === 201)).toEqual(
|
||||
expect(scene.nodes.find((node) => node.backendNodeId === 201)).toEqual(
|
||||
expect.objectContaining({
|
||||
id: 201,
|
||||
parentId: 20,
|
||||
backendNodeId: 201,
|
||||
parentId: scene.nodes.find((node) => node.backendNodeId === 20)!.id,
|
||||
role: "button",
|
||||
}),
|
||||
);
|
||||
expect(scene.nodes.find((node) => node.id === 201)).not.toHaveProperty("name");
|
||||
expect(scene.nodes.find((node) => node.id === 202)).toBeUndefined();
|
||||
expect(scene.nodes.find((node) => node.backendNodeId === 201)).not.toHaveProperty("name");
|
||||
expect(scene.nodes.find((node) => node.backendNodeId === 202)).toBeUndefined();
|
||||
});
|
||||
|
||||
it("preserves captured-only iframe anchors for iframe sub-document controls", () => {
|
||||
const scene = buildVomScene(
|
||||
const scene = buildTestScene(
|
||||
[
|
||||
{
|
||||
nodeId: "1",
|
||||
@@ -1284,10 +1318,15 @@ describe("buildVomScene", () => {
|
||||
pointerEvents: "auto",
|
||||
},
|
||||
],
|
||||
iframeNodes: new Map<number, CapturedNode[]>([
|
||||
[
|
||||
20,
|
||||
[
|
||||
documents: [
|
||||
{
|
||||
frameId: "child",
|
||||
contextScopeId: "child",
|
||||
parentFrameId: "root",
|
||||
ownerBackendNodeId: 20,
|
||||
target: { tabId: 7 },
|
||||
axNodes: [],
|
||||
domNodes: [
|
||||
{
|
||||
backendNodeId: 201,
|
||||
parentBackendNodeId: null,
|
||||
@@ -1309,16 +1348,16 @@ describe("buildVomScene", () => {
|
||||
pointerEvents: "auto",
|
||||
},
|
||||
],
|
||||
],
|
||||
]),
|
||||
},
|
||||
],
|
||||
excludedBackendNodeIds: new Set(),
|
||||
},
|
||||
);
|
||||
|
||||
expect(scene.nodes.find((node) => node.id === 20)).toEqual(
|
||||
expect(scene.nodes.find((node) => node.backendNodeId === 20)).toEqual(
|
||||
expect.objectContaining({
|
||||
id: 20,
|
||||
parentId: 10,
|
||||
backendNodeId: 20,
|
||||
parentId: scene.nodes.find((node) => node.backendNodeId === 10)!.id,
|
||||
role: "Iframe",
|
||||
name: "支付验证",
|
||||
}),
|
||||
@@ -1339,9 +1378,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 10,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 320, height: 240 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -1362,9 +1400,9 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
expect(buildVomScene(axNodes, captured).nodes[0]).toEqual(
|
||||
expect(buildTestScene(axNodes, captured).nodes[0]).toEqual(
|
||||
expect.objectContaining({
|
||||
id: 10,
|
||||
backendNodeId: 10,
|
||||
sensitive: true,
|
||||
}),
|
||||
);
|
||||
@@ -1379,9 +1417,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 10,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -1398,9 +1435,9 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
expect(buildVomScene(axNodes, captured).nodes[0]).toEqual(
|
||||
expect(buildTestScene(axNodes, captured).nodes[0]).toEqual(
|
||||
expect.objectContaining({
|
||||
id: 10,
|
||||
backendNodeId: 10,
|
||||
role: "textbox",
|
||||
name: "+86",
|
||||
placeholder: "输入手机号",
|
||||
@@ -1418,9 +1455,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 10,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -1437,8 +1473,13 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
expect(buildVomScene(axNodes, captured).nodes[0]).toEqual(
|
||||
expect.objectContaining({ id: 10, role: "textbox", name: "Email", value: "a@b.com" }),
|
||||
expect(buildTestScene(axNodes, captured).nodes[0]).toEqual(
|
||||
expect.objectContaining({
|
||||
backendNodeId: 10,
|
||||
role: "textbox",
|
||||
name: "Email",
|
||||
value: "a@b.com",
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
@@ -1457,9 +1498,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 20,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -1497,9 +1537,9 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
expect(buildVomScene(axNodes, captured).nodes.find((node) => node.id === 20)).toEqual(
|
||||
expect.objectContaining({ role: "textbox", name: "验证码" }),
|
||||
);
|
||||
expect(
|
||||
buildTestScene(axNodes, captured).nodes.find((node) => node.backendNodeId === 20),
|
||||
).toEqual(expect.objectContaining({ role: "textbox", name: "验证码" }));
|
||||
});
|
||||
|
||||
it("uses preceding AX static text as a form control label", () => {
|
||||
@@ -1523,9 +1563,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 20,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -1542,13 +1581,13 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
expect(buildVomScene(axNodes, captured).nodes.find((node) => node.id === 20)).toEqual(
|
||||
expect.objectContaining({ role: "textbox", name: "验证码", inputState: "empty" }),
|
||||
);
|
||||
expect(
|
||||
buildTestScene(axNodes, captured).nodes.find((node) => node.backendNodeId === 20),
|
||||
).toEqual(expect.objectContaining({ role: "textbox", name: "验证码", inputState: "empty" }));
|
||||
});
|
||||
|
||||
it("marks runtime default input values without treating them as ordinary filled input", () => {
|
||||
const scene = buildVomScene(
|
||||
const scene = buildTestScene(
|
||||
[
|
||||
{
|
||||
nodeId: "1",
|
||||
@@ -1558,7 +1597,6 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
{
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -1602,9 +1640,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 20,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -1654,9 +1691,14 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const scene = buildVomScene(axNodes, captured);
|
||||
expect(scene.nodes.find((n) => n.id === 20)).toEqual(
|
||||
expect.objectContaining({ id: 20, role: "button", name: "close", cursor: "pointer" }),
|
||||
const scene = buildTestScene(axNodes, captured);
|
||||
expect(scene.nodes.find((n) => n.backendNodeId === 20)).toEqual(
|
||||
expect.objectContaining({
|
||||
backendNodeId: 20,
|
||||
role: "button",
|
||||
name: "close",
|
||||
cursor: "pointer",
|
||||
}),
|
||||
);
|
||||
const rendered = renderVom(scene);
|
||||
expect(rendered.text).toContain('@e1 button "close"');
|
||||
@@ -1690,9 +1732,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 30,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -1731,9 +1772,9 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const scene = buildVomScene(axNodes, captured);
|
||||
expect(scene.nodes.find((n) => n.id === 20)).toBeUndefined();
|
||||
expect(scene.nodes.find((n) => n.id === 30)?.role).toBe("link");
|
||||
const scene = buildTestScene(axNodes, captured);
|
||||
expect(scene.nodes.find((n) => n.backendNodeId === 20)).toBeUndefined();
|
||||
expect(scene.nodes.find((n) => n.backendNodeId === 30)?.role).toBe("link");
|
||||
});
|
||||
|
||||
it("promotes only the outermost clickable in a nested pointer chain", () => {
|
||||
@@ -1758,9 +1799,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 30,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -1799,11 +1839,15 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const scene = buildVomScene(axNodes, captured);
|
||||
expect(scene.nodes.find((n) => n.id === 20)).toEqual(
|
||||
expect.objectContaining({ id: 20, role: "button", attrs: { "aria-label": "收藏" } }),
|
||||
const scene = buildTestScene(axNodes, captured);
|
||||
expect(scene.nodes.find((n) => n.backendNodeId === 20)).toEqual(
|
||||
expect.objectContaining({
|
||||
backendNodeId: 20,
|
||||
role: "button",
|
||||
attrs: { "aria-label": "收藏" },
|
||||
}),
|
||||
);
|
||||
expect(scene.nodes.find((n) => n.id === 30)).toBeUndefined();
|
||||
expect(scene.nodes.find((n) => n.backendNodeId === 30)).toBeUndefined();
|
||||
const rendered = renderVom(scene);
|
||||
expect(rendered.text).toContain('@e1 button "收藏"');
|
||||
expect(rendered.refs.map(({ ref, backendNodeId }) => ({ ref, backendNodeId }))).toEqual([
|
||||
@@ -1827,9 +1871,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 20,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -1877,10 +1920,10 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const scene = buildVomScene(axNodes, captured);
|
||||
const scene = buildTestScene(axNodes, captured);
|
||||
expect(scene.activeScopeBlocks).toEqual([
|
||||
{
|
||||
triggerId: 20,
|
||||
triggerId: scene.nodes.find((node) => node.backendNodeId === 20)!.id,
|
||||
label: "Reviews (12)",
|
||||
lines: ["Jane - ear cups are small", "Bob - great sound"],
|
||||
},
|
||||
@@ -1904,11 +1947,10 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 20,
|
||||
},
|
||||
];
|
||||
const scene = buildVomScene(
|
||||
const scene = buildTestScene(
|
||||
axNodes,
|
||||
{
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -1941,7 +1983,11 @@ describe("buildVomScene", () => {
|
||||
);
|
||||
|
||||
expect(scene.surfaces).toEqual([
|
||||
{ triggerId: 20, triggerAction: "hover", subItems: ["Shoes", "Bags"] },
|
||||
{
|
||||
triggerId: scene.nodes.find((node) => node.backendNodeId === 20)!.id,
|
||||
triggerAction: "hover",
|
||||
subItems: ["Shoes", "Bags"],
|
||||
},
|
||||
]);
|
||||
expect(renderVom(scene).text).toContain('@e1 button "Products" [hover first: Shoes | Bags]');
|
||||
});
|
||||
@@ -1962,11 +2008,10 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 21,
|
||||
},
|
||||
];
|
||||
const scene = buildVomScene(
|
||||
const scene = buildTestScene(
|
||||
axNodes,
|
||||
{
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -2027,11 +2072,10 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 21,
|
||||
},
|
||||
];
|
||||
const scene = buildVomScene(
|
||||
const scene = buildTestScene(
|
||||
axNodes,
|
||||
{
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -2076,7 +2120,11 @@ describe("buildVomScene", () => {
|
||||
);
|
||||
|
||||
expect(scene.surfaces).toEqual([
|
||||
{ triggerId: 21, triggerAction: "hover", subItems: ["My profile"] },
|
||||
{
|
||||
triggerId: scene.nodes.find((node) => node.backendNodeId === 21)!.id,
|
||||
triggerAction: "hover",
|
||||
subItems: ["My profile"],
|
||||
},
|
||||
]);
|
||||
});
|
||||
|
||||
@@ -2096,11 +2144,10 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 21,
|
||||
},
|
||||
];
|
||||
const scene = buildVomScene(
|
||||
const scene = buildTestScene(
|
||||
axNodes,
|
||||
{
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -2151,7 +2198,11 @@ describe("buildVomScene", () => {
|
||||
);
|
||||
|
||||
expect(scene.surfaces).toEqual([
|
||||
{ triggerId: 20, triggerAction: "hover", subItems: ["My profile", "Sign out"] },
|
||||
{
|
||||
triggerId: scene.nodes.find((node) => node.backendNodeId === 20)!.id,
|
||||
triggerAction: "hover",
|
||||
subItems: ["My profile", "Sign out"],
|
||||
},
|
||||
]);
|
||||
expect(renderVom(scene).text).toContain(
|
||||
'@e1 button "image" [hover first: My profile | Sign out]',
|
||||
@@ -2174,11 +2225,10 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 42,
|
||||
},
|
||||
];
|
||||
const scene = buildVomScene(
|
||||
const scene = buildTestScene(
|
||||
axNodes,
|
||||
{
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -2248,9 +2298,8 @@ describe("buildVomScene", () => {
|
||||
properties: [{ name: "inputType", value: { value: "credit-card" } }],
|
||||
},
|
||||
];
|
||||
const scene = buildVomScene(axNodes, {
|
||||
const scene = buildTestScene(axNodes, {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -2297,7 +2346,7 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
});
|
||||
|
||||
expect(scene.nodes.find((node) => node.id === 20)).toEqual(
|
||||
expect(scene.nodes.find((node) => node.backendNodeId === 20)).toEqual(
|
||||
expect.objectContaining({
|
||||
name: "Products [expanded]",
|
||||
attrs: expect.objectContaining({
|
||||
@@ -2307,13 +2356,17 @@ describe("buildVomScene", () => {
|
||||
}),
|
||||
);
|
||||
expect(scene.activeScopeBlocks).toEqual([
|
||||
{ triggerId: 20, label: "Products [expanded]", lines: ["Shoes Bags"] },
|
||||
{
|
||||
triggerId: scene.nodes.find((node) => node.backendNodeId === 20)!.id,
|
||||
label: "Products [expanded]",
|
||||
lines: ["Shoes Bags"],
|
||||
},
|
||||
]);
|
||||
expect(scene.nodes.find((node) => node.id === 30)?.sensitive).toBe(true);
|
||||
expect(scene.nodes.find((node) => node.backendNodeId === 30)?.sensitive).toBe(true);
|
||||
});
|
||||
|
||||
it("aggregates AX virtual text into unnamed structural nodes", () => {
|
||||
const scene = buildVomScene(
|
||||
const scene = buildTestScene(
|
||||
[
|
||||
{
|
||||
nodeId: "1",
|
||||
@@ -2337,7 +2390,6 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
{
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -2364,13 +2416,12 @@ describe("buildVomScene", () => {
|
||||
},
|
||||
);
|
||||
|
||||
expect(scene.nodes.find((node) => node.id === 20)?.name).toBe("Inline only text");
|
||||
expect(scene.nodes.find((node) => node.backendNodeId === 20)?.name).toBe("Inline only text");
|
||||
});
|
||||
|
||||
it("marks captured dialog elements as modal without AX role or aria-modal", () => {
|
||||
const scene = buildVomScene([], {
|
||||
const scene = buildTestScene([], {
|
||||
viewport: { width: 640, height: 480 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
nodes: [
|
||||
{
|
||||
@@ -2388,7 +2439,7 @@ describe("buildVomScene", () => {
|
||||
|
||||
expect(scene.nodes[0]).toEqual(
|
||||
expect.objectContaining({
|
||||
id: 50,
|
||||
backendNodeId: 50,
|
||||
modal: true,
|
||||
}),
|
||||
);
|
||||
@@ -2417,9 +2468,8 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 202,
|
||||
},
|
||||
];
|
||||
const captured: CapturedViewModel = {
|
||||
const captured: SceneFixture = {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set([200, 201, 202]),
|
||||
nodes: [
|
||||
{
|
||||
@@ -2435,9 +2485,9 @@ describe("buildVomScene", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const scene = buildVomScene(axNodes, captured);
|
||||
expect(scene.nodes.find((n) => n.id === 202)).toBeUndefined();
|
||||
expect(scene.nodes.find((n) => n.id === 2)).toEqual(
|
||||
const scene = buildTestScene(axNodes, captured);
|
||||
expect(scene.nodes.find((n) => n.backendNodeId === 202)).toBeUndefined();
|
||||
expect(scene.nodes.find((n) => n.backendNodeId === 2)).toEqual(
|
||||
expect.objectContaining({ role: "button", name: "Real Button" }),
|
||||
);
|
||||
});
|
||||
@@ -2465,13 +2515,12 @@ describe("buildVomScene", () => {
|
||||
backendDOMNodeId: 203,
|
||||
},
|
||||
];
|
||||
const scene = buildVomScene(axNodes, {
|
||||
const scene = buildTestScene(axNodes, {
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set([200]),
|
||||
nodes: [],
|
||||
});
|
||||
expect(scene.nodes.find((n) => n.id === 203)).toBeUndefined();
|
||||
expect(scene.nodes.find((n) => n.backendNodeId === 203)).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
@@ -2576,6 +2625,7 @@ describe("handleSnapshot", () => {
|
||||
strings,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0],
|
||||
nodeName: [i("body"), i("button")],
|
||||
@@ -2667,6 +2717,7 @@ describe("handleSnapshot", () => {
|
||||
strings,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0],
|
||||
nodeName: [i("body"), i("button")],
|
||||
@@ -2761,6 +2812,7 @@ describe("handleSnapshot", () => {
|
||||
strings,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0],
|
||||
nodeName: [i("body"), i("button")],
|
||||
@@ -3025,6 +3077,7 @@ describe("handleSnapshot", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1, 2],
|
||||
nodeName: [i("html"), i("body"), i("div"), i("input")],
|
||||
@@ -3082,6 +3135,7 @@ describe("handleSnapshot", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1, 1, 1, 1],
|
||||
nodeName: [i("html"), i("body"), i("input"), i("input"), i("input"), i("input")],
|
||||
@@ -3215,12 +3269,15 @@ describe("handleSnapshot", () => {
|
||||
const send = vi.fn(async (_tabId: number, method: string) => {
|
||||
if (method === "Page.getLayoutMetrics") return VP_METRICS;
|
||||
if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
|
||||
if (method === "DOMSnapshot.captureSnapshot") return snapshot;
|
||||
if (method === "DOMSnapshot.captureSnapshot")
|
||||
return { ...snapshot, documents: [snapshot.documents[0]] };
|
||||
if (method === "Accessibility.getFullAXTree") return { nodes: mainAx };
|
||||
throw new Error(`unexpected root CDP method ${method}`);
|
||||
});
|
||||
const sendToTarget = vi.fn(async (_target, method: string) => {
|
||||
if (method === "Accessibility.enable") return {};
|
||||
if (method === "Accessibility.enable" || method === "DOMSnapshot.enable") return {};
|
||||
if (method === "DOMSnapshot.captureSnapshot")
|
||||
return { ...snapshot, documents: [snapshot.documents[1]] };
|
||||
if (method === "Accessibility.getFullAXTree") return { nodes: childAx };
|
||||
throw new Error(`unexpected child CDP method ${method}`);
|
||||
});
|
||||
@@ -3321,6 +3378,7 @@ describe("handleSnapshot", () => {
|
||||
strings,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1, 1, 3],
|
||||
nodeName: [index("html"), index("body"), index("button"), index("div"), index("#text")],
|
||||
@@ -3608,6 +3666,7 @@ describe("handleSnapshot", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
scrollOffsetX: 0,
|
||||
scrollOffsetY: 0,
|
||||
nodes: {
|
||||
@@ -3634,6 +3693,7 @@ describe("handleSnapshot", () => {
|
||||
},
|
||||
// documents[1]: cross-origin login form
|
||||
{
|
||||
frameId: "child",
|
||||
scrollOffsetX: 0,
|
||||
scrollOffsetY: 0,
|
||||
nodes: {
|
||||
@@ -3812,6 +3872,7 @@ describe("handleSnapshot", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1, 0, 3, 4, 5],
|
||||
nodeName: [
|
||||
|
||||
@@ -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));
|
||||
}
|
||||
|
||||
@@ -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,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
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;
|
||||
}
|
||||
|
||||
/** 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,
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,297 @@
|
||||
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, SnapshotProjection } from "./coordinate-types";
|
||||
|
||||
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 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<SnapshotProjection | null> {
|
||||
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);
|
||||
}
|
||||
const owner = await promise;
|
||||
return owner
|
||||
? {
|
||||
source,
|
||||
geometry: {
|
||||
sourceClips: [],
|
||||
edges: [
|
||||
{
|
||||
sourceViewport: owner.size,
|
||||
destinationQuad: owner.quad,
|
||||
destinationClips: ancestorClips,
|
||||
},
|
||||
],
|
||||
topViewport: viewport,
|
||||
},
|
||||
}
|
||||
: null;
|
||||
}
|
||||
|
||||
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 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;
|
||||
}
|
||||
}
|
||||
@@ -1,3 +1,4 @@
|
||||
import type { CapturedSceneInput } from "./vom/facts";
|
||||
// Observation handlers — `tool.snapshot`, `tool.get_html`, `tool.screenshot`,
|
||||
// and semantic `tool.observe` (design §7). Each handler resolves the target
|
||||
// tab (defaulting to the Agent Window's active tab when omitted) and
|
||||
@@ -34,6 +35,7 @@ import type {
|
||||
import { attachDialogs, markDialogCursor } from "./dialogs";
|
||||
import { rpcError } from "./errors";
|
||||
import { resolveNodeGeometry } from "./frame-geometry";
|
||||
import { screenshotPageRect } from "./geometry/coordinate-types";
|
||||
import {
|
||||
type ChromeTabsApi,
|
||||
enforceToolTargetScope,
|
||||
@@ -47,15 +49,9 @@ import {
|
||||
type ToolEffect,
|
||||
} from "./shared";
|
||||
import { resolveSnapshotRef } from "./snapshot-ref";
|
||||
import {
|
||||
type CapturedNode,
|
||||
type CapturedSurfaceProbe,
|
||||
type CapturedViewModel,
|
||||
captureViewModel,
|
||||
collectOverlayExcludedBackendIds,
|
||||
probeHoverSurfaces,
|
||||
} from "./vom/capture";
|
||||
import { type CapturedFrameDocument, captureFrameData } from "./vom/frame-capture";
|
||||
import { type CapturedNode, type CapturedSurfaceProbe, probeHoverSurfaces } from "./vom/capture";
|
||||
import { captureObservationFacts, semanticCapture } from "./vom/capture-coordinator";
|
||||
import type { FrameDocument as CapturedFrameDocument } from "./vom/frame-document";
|
||||
import { withOverlayBypass } from "./vom/hover-perception";
|
||||
import { probeTooltipNames } from "./vom/name-enrichment";
|
||||
import {
|
||||
@@ -197,15 +193,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,
|
||||
},
|
||||
});
|
||||
@@ -530,7 +525,7 @@ function buildActiveScopeBlocks(nodes: VomNode[], signals: VomNodeDomSignals): A
|
||||
|
||||
function buildConditionalSurfaces(
|
||||
nodes: VomNode[],
|
||||
captured: CapturedViewModel,
|
||||
captured: CapturedSceneInput,
|
||||
probes: CapturedSurfaceProbe[],
|
||||
): CondSurface[] {
|
||||
if (probes.length === 0) return [];
|
||||
@@ -660,161 +655,9 @@ export interface BuildVomSceneOptions {
|
||||
|
||||
export type VomFrameDocument = CapturedFrameDocument<CdpAxNode>;
|
||||
|
||||
function legacyFrameDocuments(
|
||||
axNodes: CdpAxNode[],
|
||||
captured: CapturedViewModel,
|
||||
pageUrl?: string,
|
||||
rootTarget: VomFrameDocument["target"] = { tabId: 0 },
|
||||
): VomFrameDocument[] {
|
||||
const rootFrameId = captured.rootFrameId ?? "root";
|
||||
const documents: VomFrameDocument[] = [
|
||||
{
|
||||
frameId: rootFrameId,
|
||||
contextScopeId: rootFrameId,
|
||||
target: rootTarget,
|
||||
...(pageUrl ? { url: pageUrl } : {}),
|
||||
axNodes: [],
|
||||
domNodes: captured.nodes.map((node) => ({ ...node, frameId: node.frameId ?? rootFrameId })),
|
||||
},
|
||||
];
|
||||
const pending = [...captured.iframeNodes.entries()];
|
||||
let progress = true;
|
||||
let nextSyntheticFrame = 1;
|
||||
while (pending.length > 0 && progress) {
|
||||
progress = false;
|
||||
for (let index = pending.length - 1; index >= 0; index -= 1) {
|
||||
const [ownerBackendNodeId, domNodes] = pending[index];
|
||||
const parent = documents.find((document) =>
|
||||
document.domNodes.some((node) => node.backendNodeId === ownerBackendNodeId),
|
||||
);
|
||||
if (!parent) continue;
|
||||
const frameId =
|
||||
domNodes.find((node) => node.frameId)?.frameId ?? `legacy-frame-${nextSyntheticFrame++}`;
|
||||
documents.push({
|
||||
frameId,
|
||||
parentFrameId: parent.frameId,
|
||||
ownerBackendNodeId,
|
||||
contextScopeId: frameId,
|
||||
target: parent.target,
|
||||
axNodes: [],
|
||||
domNodes: domNodes.map((node) => ({ ...node, frameId: node.frameId ?? frameId })),
|
||||
});
|
||||
pending.splice(index, 1);
|
||||
progress = true;
|
||||
}
|
||||
}
|
||||
|
||||
const documentByFrameId = new Map(documents.map((document) => [document.frameId, document]));
|
||||
const backendFrame = new Map<number, string>();
|
||||
const childFrameByOwner = new Map<number, string>();
|
||||
for (const document of documents) {
|
||||
if (document.ownerBackendNodeId !== undefined) {
|
||||
childFrameByOwner.set(document.ownerBackendNodeId, document.frameId);
|
||||
}
|
||||
for (const node of document.domNodes) backendFrame.set(node.backendNodeId, document.frameId);
|
||||
}
|
||||
const axById = new Map(axNodes.map((node) => [node.nodeId, node]));
|
||||
const ownership = new Map<string, string>();
|
||||
const resolving = new Set<string>();
|
||||
const frameForAx = (node: CdpAxNode): string => {
|
||||
const cached = ownership.get(node.nodeId);
|
||||
if (cached) return cached;
|
||||
let frameId: string | undefined;
|
||||
if (node.frameId && documentByFrameId.has(node.frameId)) frameId = node.frameId;
|
||||
if (!frameId && typeof node.backendDOMNodeId === "number") {
|
||||
frameId = backendFrame.get(node.backendDOMNodeId);
|
||||
}
|
||||
if (!frameId && node.parentId && !resolving.has(node.nodeId)) {
|
||||
const parent = axById.get(node.parentId);
|
||||
if (parent) {
|
||||
frameId =
|
||||
typeof parent.backendDOMNodeId === "number"
|
||||
? childFrameByOwner.get(parent.backendDOMNodeId)
|
||||
: undefined;
|
||||
if (!frameId) {
|
||||
resolving.add(node.nodeId);
|
||||
frameId = frameForAx(parent);
|
||||
resolving.delete(node.nodeId);
|
||||
}
|
||||
}
|
||||
}
|
||||
frameId ??= rootFrameId;
|
||||
ownership.set(node.nodeId, frameId);
|
||||
return frameId;
|
||||
};
|
||||
for (const node of axNodes) frameForAx(node);
|
||||
for (const node of axNodes) {
|
||||
const frameId = ownership.get(node.nodeId) ?? rootFrameId;
|
||||
const document = documentByFrameId.get(frameId) ?? documents[0];
|
||||
document.axNodes.push({
|
||||
...node,
|
||||
frameId,
|
||||
...(node.parentId && ownership.get(node.parentId) === frameId
|
||||
? { parentId: node.parentId }
|
||||
: { parentId: undefined }),
|
||||
...(node.childIds
|
||||
? { childIds: node.childIds.filter((childId) => ownership.get(childId) === frameId) }
|
||||
: {}),
|
||||
});
|
||||
}
|
||||
return documents;
|
||||
}
|
||||
|
||||
function withLegacyBackendIds(scene: VomScene): VomScene {
|
||||
const used = new Set<number>();
|
||||
const idMap = new Map<number, number>();
|
||||
let nextVirtualId = -1;
|
||||
for (const node of scene.nodes) {
|
||||
const preferred = node.backendNodeId;
|
||||
const id = preferred !== undefined && !used.has(preferred) ? preferred : nextVirtualId--;
|
||||
used.add(id);
|
||||
idMap.set(node.id, id);
|
||||
}
|
||||
return {
|
||||
...scene,
|
||||
nodes: scene.nodes.map((node) => ({
|
||||
...node,
|
||||
id: idMap.get(node.id) as number,
|
||||
parentId: node.parentId === null ? null : (idMap.get(node.parentId) ?? null),
|
||||
...(node.domParentId !== undefined
|
||||
? { domParentId: node.domParentId === null ? null : (idMap.get(node.domParentId) ?? null) }
|
||||
: {}),
|
||||
...(node.domAncestorIds
|
||||
? { domAncestorIds: node.domAncestorIds.flatMap((id) => idMap.get(id) ?? []) }
|
||||
: {}),
|
||||
})),
|
||||
...(scene.surfaces
|
||||
? {
|
||||
surfaces: scene.surfaces.map((surface) => ({
|
||||
...surface,
|
||||
triggerId: idMap.get(surface.triggerId) ?? surface.triggerId,
|
||||
})),
|
||||
}
|
||||
: {}),
|
||||
...(scene.activeScopeBlocks
|
||||
? {
|
||||
activeScopeBlocks: scene.activeScopeBlocks.map((block) => ({
|
||||
...block,
|
||||
triggerId: idMap.get(block.triggerId) ?? block.triggerId,
|
||||
})),
|
||||
}
|
||||
: {}),
|
||||
};
|
||||
}
|
||||
|
||||
export function buildVomScene(
|
||||
axNodes: CdpAxNode[],
|
||||
captured: CapturedViewModel,
|
||||
options: BuildVomSceneOptions = {},
|
||||
): VomScene {
|
||||
return withLegacyBackendIds(
|
||||
buildFrameVomScene(legacyFrameDocuments(axNodes, captured, options.pageUrl), captured, options),
|
||||
);
|
||||
}
|
||||
|
||||
export function buildFrameVomScene(
|
||||
documents: VomFrameDocument[],
|
||||
captured: CapturedViewModel,
|
||||
captured: CapturedSceneInput,
|
||||
options: BuildVomSceneOptions = {},
|
||||
): VomScene {
|
||||
const scene = buildSemanticVomScene({
|
||||
@@ -830,7 +673,7 @@ export function buildFrameVomScene(
|
||||
function attachCapturedSceneAnnotations(
|
||||
scene: VomScene,
|
||||
documents: VomFrameDocument[],
|
||||
captured: CapturedViewModel,
|
||||
captured: CapturedSceneInput,
|
||||
surfaceProbes: CapturedSurfaceProbe[],
|
||||
): VomScene {
|
||||
const rootDocument = documents.find((document) => document.frameId === scene.rootFrameId);
|
||||
@@ -980,51 +823,6 @@ export async function handleGetHtml(
|
||||
}
|
||||
}
|
||||
|
||||
function emptyCapturedViewModel(viewport = { width: 0, height: 0 }): CapturedViewModel {
|
||||
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,
|
||||
signal?: AbortSignal,
|
||||
): Promise<CapturedViewModel> {
|
||||
throwIfAborted(signal, "observation");
|
||||
let viewport = { width: 0, height: 0 };
|
||||
try {
|
||||
const metrics = await cdp.send<LayoutMetricsViewportReply>(tabId, "Page.getLayoutMetrics", {});
|
||||
throwIfAborted(signal, "observation");
|
||||
const source = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
|
||||
viewport = {
|
||||
width: source.clientWidth ?? 0,
|
||||
height: source.clientHeight ?? 0,
|
||||
};
|
||||
} catch (error) {
|
||||
if (isAbortError(error)) throw error;
|
||||
}
|
||||
const excludedBackendNodeIds = await collectOverlayExcludedBackendIds(cdp, tabId, signal);
|
||||
throwIfAborted(signal, "observation");
|
||||
return { ...emptyCapturedViewModel(viewport), excludedBackendNodeIds };
|
||||
}
|
||||
|
||||
async function captureForVom(
|
||||
cdp: CdpRunner,
|
||||
tabId: number,
|
||||
options: CaptureVomObservationOptions,
|
||||
): Promise<CapturedViewModel> {
|
||||
try {
|
||||
return await captureViewModel(cdp, tabId, { signal: options.signal });
|
||||
} catch (error) {
|
||||
if (isAbortError(error)) throw error;
|
||||
return fallbackCapturedViewModel(cdp, tabId, options.signal);
|
||||
}
|
||||
}
|
||||
|
||||
export interface HoverProbeOutcome {
|
||||
/** Whether any active hover was dispatched during this observation. */
|
||||
performed: boolean;
|
||||
@@ -1057,7 +855,7 @@ const NO_HOVER_PROBES: HoverProbeOutcome = {
|
||||
async function runHoverProbes(
|
||||
cdp: CdpRunner,
|
||||
tabId: number,
|
||||
captured: CapturedViewModel,
|
||||
captured: CapturedSceneInput,
|
||||
documents: VomFrameDocument[],
|
||||
staticSemantics: ReturnType<typeof resolveSemanticGraph>,
|
||||
options: CaptureVomObservationOptions,
|
||||
@@ -1096,14 +894,9 @@ 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 facts = await captureObservationFacts<CdpAxNode>(cdp, tabId, options.signal);
|
||||
const { captured, documents: normalizedDocuments } = semanticCapture(facts);
|
||||
throwIfAborted(options.signal, "observation");
|
||||
const documents = await captureFrameData<CdpAxNode>(cdp, tabId, captured, options.signal);
|
||||
throwIfAborted(options.signal, "observation");
|
||||
const normalizedDocuments =
|
||||
documents.length === 1 && captured.iframeNodes.size > 0
|
||||
? legacyFrameDocuments(documents[0].axNodes, captured, url, documents[0].target)
|
||||
: documents;
|
||||
const semanticGraph = buildSemanticGraph({
|
||||
documents: normalizedDocuments,
|
||||
viewport: captured.viewport,
|
||||
|
||||
@@ -55,6 +55,7 @@ export interface CdpRunner {
|
||||
sendToTarget?<T = unknown>(target: CdpTarget, method: string, params?: object): Promise<T>;
|
||||
detach?(tabId: number): Promise<void>;
|
||||
getFrameGraph?(tabId: number): Promise<CdpFrameGraph>;
|
||||
getAttachmentId?(tabId: number): string | undefined;
|
||||
ensureAttachedToUrl?(tabId: number, expectedUrl: string | undefined): Promise<void>;
|
||||
trackSessionTab?(sessionId: string, tabId: number): void;
|
||||
releaseSessionTab?(sessionId: string, tabId: number): Promise<void>;
|
||||
|
||||
@@ -0,0 +1,471 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import type { CdpFrame, CdpTarget } from "@/browser-driver/frame-graph";
|
||||
import { cdpTargetKey } from "@/browser-driver/frame-graph";
|
||||
import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
|
||||
import type { CdpRunner } from "../../shared";
|
||||
import { captureObservationFacts, semanticCapture } from "../capture-coordinator";
|
||||
import { buildSemanticGraph } from "../semantic-graph/build";
|
||||
import { REQUESTED_STYLES } from "../snapshot";
|
||||
|
||||
function fixture(
|
||||
options: {
|
||||
frames?: CdpFrame[];
|
||||
after?: Record<string, { loader?: string; element?: number; missing?: boolean }>;
|
||||
fail?: string;
|
||||
missingIdentity?: boolean;
|
||||
omitDocument?: string;
|
||||
attachmentChanged?: boolean;
|
||||
overlay?: string;
|
||||
} = {},
|
||||
) {
|
||||
const frames = options.frames ?? [
|
||||
{ frameId: "main", loaderId: "main-loader", target: { tabId: 4 } },
|
||||
{
|
||||
frameId: "same",
|
||||
parentFrameId: "main",
|
||||
ownerBackendNodeId: 3,
|
||||
loaderId: "same-loader",
|
||||
target: { tabId: 4 },
|
||||
},
|
||||
{
|
||||
frameId: "nested",
|
||||
parentFrameId: "same",
|
||||
ownerBackendNodeId: 13,
|
||||
loaderId: "nested-loader",
|
||||
target: { tabId: 4 },
|
||||
},
|
||||
{
|
||||
frameId: "remote",
|
||||
parentFrameId: "main",
|
||||
ownerBackendNodeId: 4,
|
||||
loaderId: "remote-loader",
|
||||
target: { tabId: 4, sessionId: "remote" },
|
||||
},
|
||||
];
|
||||
const elements = new Map(
|
||||
frames.map((frame, i) => [frame.frameId, frame.target.sessionId ? 1 : i * 10 + 1]),
|
||||
);
|
||||
const contexts = new Map(frames.map((frame, i) => [i + 1, frame.frameId]));
|
||||
const reads = new Map<string, number>();
|
||||
const logs: Array<{ target: CdpTarget; method: string; params: Record<string, unknown> }> = [];
|
||||
let snapshots = 0;
|
||||
const targetCount = new Set(frames.map((frame) => cdpTargetKey(frame.target))).size;
|
||||
const send = vi.fn(
|
||||
async <T>(target: CdpTarget, method: string, params: object = {}): Promise<T> => {
|
||||
logs.push({ target, method, params: params as Record<string, unknown> });
|
||||
const args = params as Record<string, string | number>;
|
||||
if (options.fail === `${target.sessionId ?? "main"}:${method}`)
|
||||
throw new Error("fixture failure");
|
||||
let result: unknown = {};
|
||||
if (method === "Page.createIsolatedWorld")
|
||||
result = {
|
||||
executionContextId: frames.findIndex((frame) => frame.frameId === args.frameId) + 1,
|
||||
};
|
||||
if (method === "Runtime.evaluate")
|
||||
result = { result: { objectId: contexts.get(Number(args.contextId)) } };
|
||||
if (method === "DOM.describeNode") {
|
||||
const id = String(args.objectId);
|
||||
const count = reads.get(id) ?? 0;
|
||||
reads.set(id, count + 1);
|
||||
result = options.missingIdentity
|
||||
? {}
|
||||
: {
|
||||
node: {
|
||||
backendNodeId:
|
||||
count > 0 ? (options.after?.[id]?.element ?? elements.get(id)) : elements.get(id),
|
||||
},
|
||||
};
|
||||
}
|
||||
if (method === "Page.getFrameTree") {
|
||||
const own = frames.filter(
|
||||
(frame) =>
|
||||
cdpTargetKey(frame.target) === cdpTargetKey(target) &&
|
||||
!options.after?.[frame.frameId]?.missing,
|
||||
);
|
||||
const trees = new Map(
|
||||
own.map((frame) => [
|
||||
frame.frameId,
|
||||
{
|
||||
frame: {
|
||||
id: frame.frameId,
|
||||
loaderId: options.after?.[frame.frameId]?.loader ?? frame.loaderId,
|
||||
},
|
||||
childFrames: [] as unknown[],
|
||||
},
|
||||
]),
|
||||
);
|
||||
for (const frame of own)
|
||||
if (frame.parentFrameId && trees.has(frame.parentFrameId))
|
||||
trees.get(frame.parentFrameId)!.childFrames.push(trees.get(frame.frameId));
|
||||
result = { frameTree: trees.get(own[0]?.frameId) };
|
||||
}
|
||||
if (method === "Page.getLayoutMetrics")
|
||||
result = { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
|
||||
if (method === "DOMSnapshot.captureSnapshot") {
|
||||
snapshots++;
|
||||
expect((params as { computedStyles: unknown }).computedStyles).toEqual(REQUESTED_STYLES);
|
||||
result = {
|
||||
strings: [
|
||||
"#document",
|
||||
"html",
|
||||
"button",
|
||||
OVERLAY_HOST_MARKER_ATTR,
|
||||
"",
|
||||
"visible",
|
||||
"1",
|
||||
"static",
|
||||
"auto",
|
||||
],
|
||||
documents: frames
|
||||
.filter(
|
||||
(frame) =>
|
||||
cdpTargetKey(frame.target) === cdpTargetKey(target) &&
|
||||
frame.frameId !== options.omitDocument,
|
||||
)
|
||||
.map((frame) => {
|
||||
const element = elements.get(frame.frameId)!;
|
||||
return {
|
||||
frameId: frame.frameId,
|
||||
nodes: {
|
||||
backendNodeId: [element - 1, element + 10000, element, element + 1],
|
||||
nodeName: [0, 1, 1, 2],
|
||||
nodeType: [9, 10, 1, 1],
|
||||
parentIndex: [-1, 0, 0, 2],
|
||||
attributes: [[], [], [], frame.frameId === options.overlay ? [3, 4] : []],
|
||||
},
|
||||
layout: {
|
||||
nodeIndex: [2, 3],
|
||||
bounds: [
|
||||
[0, 0, 1000, 800],
|
||||
[10, 20, 100, 40],
|
||||
],
|
||||
styles: [
|
||||
[7, 8, 8, 5, 6],
|
||||
[7, 8, 8, 5, 6],
|
||||
],
|
||||
},
|
||||
};
|
||||
}),
|
||||
};
|
||||
}
|
||||
if (method === "Accessibility.getFullAXTree") {
|
||||
const frameId = String(args.frameId);
|
||||
result = {
|
||||
nodes: [
|
||||
{
|
||||
nodeId: `${frameId}-button`,
|
||||
frameId,
|
||||
backendDOMNodeId: elements.get(frameId)! + 1,
|
||||
role: { value: "button" },
|
||||
name: { value: frameId },
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
return result as T;
|
||||
},
|
||||
);
|
||||
const cdp: CdpRunner = {
|
||||
getAttachmentId: () =>
|
||||
options.attachmentChanged && snapshots === targetCount ? "new-attachment" : "attachment",
|
||||
getFrameGraph: async () => ({ rootFrameId: frames[0].frameId, frames }),
|
||||
send: (tabId, method, params) =>
|
||||
(send as NonNullable<CdpRunner["sendToTarget"]>)({ tabId }, method, params),
|
||||
sendToTarget: send as NonNullable<CdpRunner["sendToTarget"]>,
|
||||
};
|
||||
return { cdp, logs, elements };
|
||||
}
|
||||
|
||||
describe("captureObservationFacts", () => {
|
||||
it("collects each target once, validates every document and scopes equal backend IDs", async () => {
|
||||
const { cdp, logs } = fixture();
|
||||
const facts = await captureObservationFacts(cdp, 4);
|
||||
expect(logs.filter((call) => call.method === "DOMSnapshot.captureSnapshot")).toHaveLength(2);
|
||||
expect(logs.filter((call) => call.method === "Accessibility.enable")).toHaveLength(2);
|
||||
expect(logs.filter((call) => call.method === "Accessibility.getFullAXTree")).toHaveLength(4);
|
||||
expect(logs.filter((call) => call.method === "DOM.describeNode")).toHaveLength(8);
|
||||
expect(logs.filter((call) => call.method === "Runtime.releaseObject")).toHaveLength(8);
|
||||
expect(facts.documents.every((doc) => doc.identity)).toBe(true);
|
||||
const main = facts.documents.find((doc) => doc.frame.frameId === "main")!;
|
||||
const remote = facts.documents.find((doc) => doc.frame.frameId === "remote")!;
|
||||
expect(main.index.nodes.get(2)).not.toBe(remote.index.nodes.get(2));
|
||||
expect(main.index.children.get(1)).toEqual([2]);
|
||||
expect(main.index.nodes.get(10001)?.nodeType).toBe(10);
|
||||
expect(main.identity?.documentElementBackendNodeId).toBe(1);
|
||||
expect(remote.axNodes[0].frameId).toBe("remote");
|
||||
expect(main.index.nodes.get(2)).toBe(main.domNodes.find((node) => node.backendNodeId === 2));
|
||||
expect(facts.finishedAt).toBeGreaterThanOrEqual(facts.startedAt);
|
||||
});
|
||||
|
||||
it.each([
|
||||
{ loader: "new-loader" },
|
||||
{ element: 99 },
|
||||
{ missing: true },
|
||||
])("isolates changed child identity %j and dependent descendants", async (change) => {
|
||||
const { cdp } = fixture({ after: { same: change } });
|
||||
const facts = await captureObservationFacts(cdp, 4);
|
||||
expect(facts.documents.map((doc) => doc.frame.frameId)).toEqual(["main", "remote"]);
|
||||
expect(facts.issues).toContainEqual(
|
||||
expect.objectContaining({ frameId: "same", reason: "document-changed" }),
|
||||
);
|
||||
});
|
||||
|
||||
it.each([
|
||||
{ after: { main: { element: 99 } } },
|
||||
{ attachmentChanged: true },
|
||||
])("rejects a root replacement or reattachment %j", async (options) => {
|
||||
await expect(captureObservationFacts(fixture(options).cdp, 4)).rejects.toThrow(
|
||||
"document identity",
|
||||
);
|
||||
});
|
||||
|
||||
it("does not retry failed or missing documents and retains valid AX-only semantics", async () => {
|
||||
const { cdp, logs } = fixture({
|
||||
fail: "remote:DOMSnapshot.captureSnapshot",
|
||||
omitDocument: "same",
|
||||
});
|
||||
const facts = await captureObservationFacts(cdp, 4);
|
||||
const remote = facts.documents.find((doc) => doc.frame.frameId === "remote")!;
|
||||
expect(remote.domNodes).toHaveLength(0);
|
||||
expect(remote.axNodes).toHaveLength(1);
|
||||
expect(logs.filter((call) => call.method === "DOMSnapshot.captureSnapshot")).toHaveLength(2);
|
||||
expect(facts.issues).toContainEqual(
|
||||
expect.objectContaining({ frameId: "same", stage: "dom", reason: "capture-unavailable" }),
|
||||
);
|
||||
expect(facts.issues).toContainEqual(
|
||||
expect.objectContaining({ target: { tabId: 4, sessionId: "remote" }, stage: "dom" }),
|
||||
);
|
||||
});
|
||||
|
||||
it("keeps missing identity explicit without manufacturing a verified document", async () => {
|
||||
const facts = await captureObservationFacts(fixture({ missingIdentity: true }).cdp, 4);
|
||||
expect(facts.documents.every((doc) => !doc.identity)).toBe(true);
|
||||
expect(facts.issues.filter((issue) => issue.reason === "identity-unverified")).toHaveLength(4);
|
||||
});
|
||||
|
||||
it("excludes overlay AX in its own document without excluding equal IDs elsewhere", async () => {
|
||||
const facts = await captureObservationFacts(fixture({ overlay: "remote" }).cdp, 4);
|
||||
const { documents } = semanticCapture(facts);
|
||||
const graph = buildSemanticGraph({
|
||||
documents,
|
||||
viewport: facts.viewport,
|
||||
rootFrameId: facts.rootFrameId,
|
||||
});
|
||||
expect(
|
||||
[...graph.nodes.values()].find(
|
||||
(node) => node.frameId === "remote" && node.backendNodeId === 2,
|
||||
)?.excluded,
|
||||
).toBe(true);
|
||||
expect(
|
||||
[...graph.nodes.values()].find((node) => node.frameId === "main" && node.backendNodeId === 2)
|
||||
?.excluded,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("bounds collection across many targets and stops scheduling after cancellation", async () => {
|
||||
const frames = Array.from({ length: 12 }, (_, i) => ({
|
||||
frameId: `f${i}`,
|
||||
target: { tabId: 4, ...(i ? { sessionId: `s${i}` } : {}) },
|
||||
}));
|
||||
const { cdp } = fixture({ frames });
|
||||
let active = 0,
|
||||
peak = 0;
|
||||
const original = cdp.sendToTarget!;
|
||||
const send: NonNullable<CdpRunner["sendToTarget"]> = async (target, method, params) => {
|
||||
active++;
|
||||
peak = Math.max(peak, active);
|
||||
try {
|
||||
await new Promise((resolve) => setTimeout(resolve, 1));
|
||||
return await original(target, method, params);
|
||||
} finally {
|
||||
active--;
|
||||
}
|
||||
};
|
||||
cdp.sendToTarget = send;
|
||||
cdp.send = (tabId, method, params) => send({ tabId }, method, params);
|
||||
await captureObservationFacts(cdp, 4);
|
||||
// This fixture has no frame edges, so no concurrent owner requests.
|
||||
expect(peak).toBeLessThanOrEqual(4);
|
||||
expect(peak).toBeGreaterThan(1);
|
||||
const controller = new AbortController();
|
||||
controller.abort();
|
||||
await expect(captureObservationFacts(cdp, 4, controller.signal)).rejects.toMatchObject({
|
||||
name: "AbortError",
|
||||
});
|
||||
expect(active).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
function childSnapshot(frameId: string, backendNodeId: number) {
|
||||
const strings = [frameId, "body", "button", "static", "auto", "pointer"];
|
||||
return {
|
||||
strings,
|
||||
documents: [
|
||||
{
|
||||
frameId,
|
||||
nodes: {
|
||||
parentIndex: [-1, 0],
|
||||
nodeName: [1, 2],
|
||||
backendNodeId: [backendNodeId - 1, backendNodeId],
|
||||
attributes: [[], []],
|
||||
},
|
||||
layout: {
|
||||
nodeIndex: [0, 1],
|
||||
styles: [
|
||||
[3, 4, 4],
|
||||
[3, 4, 5],
|
||||
],
|
||||
bounds: [
|
||||
[0, 0, 300, 200],
|
||||
[10, 20, 100, 40],
|
||||
],
|
||||
paintOrders: [0, 1],
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
describe("OOPIF capture", () => {
|
||||
it("captures and positions multiple OOPIF documents missing from the root snapshot", async () => {
|
||||
const sendToTarget = vi.fn(async (target, method) => {
|
||||
if (method === "Page.getLayoutMetrics") {
|
||||
return { cssLayoutViewport: { clientWidth: 300, clientHeight: 200, pageX: 0, pageY: 0 } };
|
||||
}
|
||||
if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
|
||||
if (method === "DOMSnapshot.captureSnapshot") {
|
||||
return target.sessionId === "left-session"
|
||||
? childSnapshot("left", 101)
|
||||
: childSnapshot("right", 201);
|
||||
}
|
||||
if (method === "Accessibility.getFullAXTree") return { nodes: [] };
|
||||
throw new Error(`unexpected ${method}`);
|
||||
});
|
||||
const cdp: CdpRunner = {
|
||||
send: vi.fn(async (_tabId, method, params) => {
|
||||
if (method === "Accessibility.enable" || method === "DOMSnapshot.enable") return {};
|
||||
if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("main", 1);
|
||||
if (method === "Accessibility.getFullAXTree") return { nodes: [] };
|
||||
if (method === "DOM.getBoxModel") {
|
||||
const backendNodeId = (params as { backendNodeId?: number })?.backendNodeId;
|
||||
const x = backendNodeId === 10 ? 50 : 500;
|
||||
return { model: { content: [x, 100, x + 300, 100, x + 300, 300, x, 300] } };
|
||||
}
|
||||
if (method === "Page.getLayoutMetrics") {
|
||||
return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
|
||||
}
|
||||
throw new Error(`unexpected root ${method}`);
|
||||
}) as CdpRunner["send"],
|
||||
sendToTarget: sendToTarget as unknown as NonNullable<CdpRunner["sendToTarget"]>,
|
||||
getFrameGraph: vi.fn(async () => ({
|
||||
rootFrameId: "main",
|
||||
frames: [
|
||||
{ frameId: "main", target: { tabId: 4 } },
|
||||
{
|
||||
frameId: "left",
|
||||
parentFrameId: "main",
|
||||
ownerBackendNodeId: 10,
|
||||
target: { tabId: 4, sessionId: "left-session" },
|
||||
},
|
||||
{
|
||||
frameId: "right",
|
||||
parentFrameId: "main",
|
||||
ownerBackendNodeId: 20,
|
||||
target: { tabId: 4, sessionId: "right-session" },
|
||||
},
|
||||
],
|
||||
})),
|
||||
};
|
||||
|
||||
const { documents: trees } = semanticCapture(await captureObservationFacts(cdp, 4));
|
||||
|
||||
expect(trees.map((tree) => tree.frameId)).toEqual(["main", "left", "right"]);
|
||||
expect(
|
||||
trees
|
||||
.find((doc) => doc.frameId === "left")
|
||||
?.domNodes?.find((node) => node.backendNodeId === 101)?.rect,
|
||||
).toEqual({ x: 60, y: 120, w: 100, h: 40 });
|
||||
expect(
|
||||
trees
|
||||
.find((doc) => doc.frameId === "right")
|
||||
?.domNodes?.find((node) => node.backendNodeId === 201)?.rect,
|
||||
).toEqual({ x: 510, y: 120, w: 100, h: 40 });
|
||||
expect(
|
||||
new Map(
|
||||
trees
|
||||
.filter((doc) => doc.ownerBackendNodeId !== undefined)
|
||||
.map((doc) => [doc.frameId, doc.ownerBackendNodeId]),
|
||||
),
|
||||
).toEqual(
|
||||
new Map([
|
||||
["left", 10],
|
||||
["right", 20],
|
||||
]),
|
||||
);
|
||||
expect(
|
||||
new Map(
|
||||
trees.filter((doc) => doc.parentFrameId).map((doc) => [doc.frameId, doc.parentFrameId]),
|
||||
),
|
||||
).toEqual(
|
||||
new Map([
|
||||
["left", "main"],
|
||||
["right", "main"],
|
||||
]),
|
||||
);
|
||||
});
|
||||
|
||||
it("keeps OOPIF semantics when viewport projection is unavailable", async () => {
|
||||
const cdp: CdpRunner = {
|
||||
send: vi.fn(async (_tabId, method) => {
|
||||
if (method === "Accessibility.enable" || method === "DOMSnapshot.enable") return {};
|
||||
if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("main", 1);
|
||||
if (method === "Accessibility.getFullAXTree") return { nodes: [] };
|
||||
if (method === "DOM.getBoxModel") throw new Error("owner geometry unavailable");
|
||||
if (method === "Page.getLayoutMetrics") {
|
||||
return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
|
||||
}
|
||||
throw new Error(`unexpected root ${method}`);
|
||||
}) as CdpRunner["send"],
|
||||
sendToTarget: vi.fn(async (_target, method) => {
|
||||
if (method === "Page.getLayoutMetrics") throw new Error("viewport unavailable");
|
||||
if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
|
||||
if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("child", 101);
|
||||
if (method === "Accessibility.getFullAXTree") {
|
||||
return {
|
||||
nodes: [
|
||||
{
|
||||
nodeId: "button",
|
||||
backendDOMNodeId: 101,
|
||||
role: { type: "role", value: "button" },
|
||||
name: { type: "computedString", value: "Continue" },
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
throw new Error(`unexpected ${method}`);
|
||||
}) as unknown 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" },
|
||||
},
|
||||
],
|
||||
})),
|
||||
};
|
||||
|
||||
const { documents } = semanticCapture(await captureObservationFacts(cdp, 4));
|
||||
const childDocument = documents.find((document) => document.frameId === "child");
|
||||
|
||||
expect(childDocument?.axNodes).toEqual([
|
||||
expect.objectContaining({ backendDOMNodeId: 101, frameId: "child" }),
|
||||
]);
|
||||
expect(childDocument?.domNodes.find((node) => node.backendNodeId === 101)).toEqual(
|
||||
expect.objectContaining({ rect: null, localRect: { x: 10, y: 20, w: 100, h: 40 } }),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -1,6 +1,7 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import { OVERLAY_HOST_MARKER_ATTR, OVERLAY_HOST_NAME } from "../../../lib/overlay-bridge";
|
||||
import { captureViewModel, collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";
|
||||
import { collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";
|
||||
import { captureObservationFacts, semanticCapture } from "../capture-coordinator";
|
||||
|
||||
// Minimal but format-accurate captureSnapshot reply: a body with one
|
||||
// fixed full-screen overlay div carrying a password input.
|
||||
@@ -26,6 +27,7 @@ function fakeSnapshotReply() {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1, 2],
|
||||
nodeType: [1, 1, 1, 1],
|
||||
@@ -73,6 +75,7 @@ function hoverTriggerSnapshotReply() {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1],
|
||||
nodeType: [1, 1, 1],
|
||||
@@ -117,6 +120,7 @@ function twoHoverTriggerSnapshotReply() {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1, 1],
|
||||
nodeType: [1, 1, 1, 1],
|
||||
@@ -170,6 +174,7 @@ function nestedHoverTriggerSnapshotReply() {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1, 2, 3],
|
||||
nodeType: [1, 1, 1, 1, 1],
|
||||
@@ -243,13 +248,11 @@ function makeCdp(snapshot: unknown) {
|
||||
};
|
||||
}
|
||||
|
||||
describe("captureViewModel", () => {
|
||||
describe("snapshot capture and hover", () => {
|
||||
it("parses nodes, attrs, rects, paint order and styles", async () => {
|
||||
const { nodes, viewport, iframeNodes } = await captureViewModel(
|
||||
makeCdp(fakeSnapshotReply()),
|
||||
4,
|
||||
);
|
||||
expect(iframeNodes.size).toBe(0);
|
||||
const { nodes, viewport } = semanticCapture(
|
||||
await captureObservationFacts(makeCdp(fakeSnapshotReply()), 4),
|
||||
).captured;
|
||||
expect(viewport).toEqual({ width: 1000, height: 800 });
|
||||
const div = nodes.find((n) => n.backendNodeId === 12);
|
||||
expect(div).toMatchObject({ tag: "div", position: "fixed", parentBackendNodeId: 11 });
|
||||
@@ -261,35 +264,11 @@ describe("captureViewModel", () => {
|
||||
|
||||
it("never hovers the page while capturing", async () => {
|
||||
const cdp = makeCdp(fakeSnapshotReply());
|
||||
await captureViewModel(cdp, 4);
|
||||
semanticCapture(await captureObservationFacts(cdp, 4)).captured;
|
||||
|
||||
expect(cdp.send).not.toHaveBeenCalledWith(4, "Input.dispatchMouseEvent", expect.anything());
|
||||
});
|
||||
|
||||
it("batch-enriches form controls without per-node object resolution", async () => {
|
||||
const cdp = makeCdp(fakeSnapshotReply());
|
||||
const result = await captureViewModel(cdp, 4);
|
||||
const input = result.nodes.find((node) => node.backendNodeId === 13);
|
||||
|
||||
expect(input).toMatchObject({
|
||||
formState: "filled",
|
||||
formPlaceholder: "secret",
|
||||
attrs: { type: "password" },
|
||||
});
|
||||
expect(input?.formValue).toBeUndefined();
|
||||
expect(input?.formDefaultValue).toBeUndefined();
|
||||
expect(cdp.send).toHaveBeenCalledWith(
|
||||
4,
|
||||
"Runtime.evaluate",
|
||||
expect.objectContaining({
|
||||
serializationOptions: expect.objectContaining({ serialization: "deep" }),
|
||||
}),
|
||||
);
|
||||
expect(cdp.send).toHaveBeenCalledWith(4, "Runtime.releaseObjectGroup", expect.anything());
|
||||
expect(cdp.send).not.toHaveBeenCalledWith(4, "DOM.resolveNode", expect.anything());
|
||||
expect(cdp.send).not.toHaveBeenCalledWith(4, "Runtime.callFunctionOn", expect.anything());
|
||||
});
|
||||
|
||||
it("runs hover surface probes when explicitly enabled", async () => {
|
||||
let hoverStateCalls = 0;
|
||||
const cdp = {
|
||||
@@ -329,7 +308,7 @@ describe("captureViewModel", () => {
|
||||
}) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
|
||||
};
|
||||
|
||||
const captured = await captureViewModel(cdp, 4);
|
||||
const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
|
||||
const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);
|
||||
|
||||
expect(surfaceProbes).toEqual([
|
||||
@@ -389,7 +368,7 @@ describe("captureViewModel", () => {
|
||||
}) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
|
||||
};
|
||||
|
||||
const captured = await captureViewModel(cdp, 4);
|
||||
const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
|
||||
const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);
|
||||
|
||||
expect(surfaceProbes).toEqual([
|
||||
@@ -434,7 +413,7 @@ describe("captureViewModel", () => {
|
||||
}) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
|
||||
};
|
||||
|
||||
const captured = await captureViewModel(cdp, 4);
|
||||
const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
|
||||
await probeHoverSurfaces(cdp, 4, captured.nodes);
|
||||
|
||||
expect(hoverMoves).toBe(1);
|
||||
@@ -466,6 +445,7 @@ describe("captureViewModel", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1, 0, 3, 4],
|
||||
nodeName: [i("html"), i("body"), i("div"), i(OVERLAY_HOST_NAME), i("div"), i("button")],
|
||||
@@ -496,7 +476,7 @@ describe("captureViewModel", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
|
||||
const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
|
||||
const ids = nodes.map((n) => n.backendNodeId);
|
||||
// Real page nodes survive.
|
||||
expect(ids).toContain(12);
|
||||
@@ -527,6 +507,7 @@ describe("captureViewModel", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1, 0, 3, 4],
|
||||
nodeName: [i("html"), i("body"), i("div"), i(OVERLAY_HOST_NAME), i("div"), i("button")],
|
||||
@@ -557,7 +538,9 @@ describe("captureViewModel", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const { excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
|
||||
const { excludedBackendNodeIds } = semanticCapture(
|
||||
await captureObservationFacts(makeCdp(snapshot), 4),
|
||||
).captured;
|
||||
expect(excludedBackendNodeIds).toEqual(new Set([13, 14, 15]));
|
||||
});
|
||||
|
||||
@@ -578,6 +561,7 @@ describe("captureViewModel", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1],
|
||||
nodeName: [i("html"), i("body"), i(OVERLAY_HOST_NAME)],
|
||||
@@ -600,7 +584,9 @@ describe("captureViewModel", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const { nodes, excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
|
||||
const { nodes, excludedBackendNodeIds } = semanticCapture(
|
||||
await captureObservationFacts(makeCdp(snapshot), 4),
|
||||
).captured;
|
||||
expect(nodes.map((n) => n.backendNodeId)).not.toContain(13);
|
||||
expect(excludedBackendNodeIds).toEqual(new Set([13]));
|
||||
});
|
||||
@@ -623,6 +609,7 @@ describe("captureViewModel", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1],
|
||||
nodeName: [i("html"), i("body"), i("div")],
|
||||
@@ -645,7 +632,9 @@ describe("captureViewModel", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const { nodes, excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
|
||||
const { nodes, excludedBackendNodeIds } = semanticCapture(
|
||||
await captureObservationFacts(makeCdp(snapshot), 4),
|
||||
).captured;
|
||||
expect(nodes.map((n) => n.backendNodeId)).not.toContain(13);
|
||||
expect(excludedBackendNodeIds).toEqual(new Set([13]));
|
||||
});
|
||||
@@ -668,6 +657,7 @@ describe("captureViewModel", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1],
|
||||
nodeName: [i("html"), i("body"), i("div")],
|
||||
@@ -690,7 +680,7 @@ describe("captureViewModel", () => {
|
||||
},
|
||||
],
|
||||
};
|
||||
const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
|
||||
const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
|
||||
expect(nodes.find((n) => n.backendNodeId === 12)?.cursor).toBe("pointer");
|
||||
expect(nodes.find((n) => n.backendNodeId === 11)?.cursor).toBe("auto");
|
||||
});
|
||||
@@ -702,6 +692,7 @@ describe("captureViewModel", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1, 1, 1],
|
||||
nodeName: [i("html"), i("body"), i("button"), i("button"), i("button")],
|
||||
@@ -728,7 +719,7 @@ describe("captureViewModel", () => {
|
||||
],
|
||||
};
|
||||
|
||||
const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
|
||||
const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
|
||||
|
||||
expect(nodes.find((node) => node.backendNodeId === 12)?.rendered).toBe(true);
|
||||
expect(nodes.find((node) => node.backendNodeId === 13)?.rendered).toBe(false);
|
||||
@@ -748,19 +739,20 @@ describe("captureViewModel", () => {
|
||||
throw new Error(method);
|
||||
}) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
|
||||
};
|
||||
const { nodes } = await captureViewModel(cdp, 4);
|
||||
const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
|
||||
const div = nodes.find((n) => n.backendNodeId === 12);
|
||||
expect(div?.localRect?.y).toBe(-200);
|
||||
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 = {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1],
|
||||
nodeName: [i("html"), i("body"), i("div")],
|
||||
@@ -795,13 +787,19 @@ describe("captureViewModel", () => {
|
||||
throw new Error(method);
|
||||
}) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
|
||||
};
|
||||
const { nodes } = await captureViewModel(cdp, 4);
|
||||
const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
|
||||
expect(nodes.find((n) => n.backendNodeId === 12)?.rect).toEqual({
|
||||
x: 0,
|
||||
y: 0,
|
||||
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 () => {
|
||||
@@ -825,6 +823,7 @@ describe("captureViewModel", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
scrollOffsetX: 0,
|
||||
scrollOffsetY: 0,
|
||||
nodes: {
|
||||
@@ -863,7 +862,7 @@ describe("captureViewModel", () => {
|
||||
throw new Error(method);
|
||||
}) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
|
||||
};
|
||||
const { nodes } = await captureViewModel(cdp, 4);
|
||||
const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
|
||||
const btn = nodes.find((n) => n.backendNodeId === 12);
|
||||
expect(btn?.textContent).toBe("登录");
|
||||
const link = nodes.find((n) => n.backendNodeId === 14);
|
||||
@@ -873,7 +872,7 @@ describe("captureViewModel", () => {
|
||||
expect(body?.textContent).toBeUndefined();
|
||||
});
|
||||
|
||||
it("parses iframe sub-documents and returns iframeNodes keyed by iframe backendNodeId", async () => {
|
||||
it("retains explicit iframe document ownership and projected nodes", async () => {
|
||||
const S = [
|
||||
"html",
|
||||
"body",
|
||||
@@ -950,36 +949,33 @@ 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>,
|
||||
};
|
||||
const {
|
||||
nodes,
|
||||
iframeNodes,
|
||||
frameNodes,
|
||||
frameOwnerBackendNodeIds,
|
||||
frameParentIds,
|
||||
rootFrameId,
|
||||
} = await captureViewModel(cdp, 4);
|
||||
// Main frame has 4 nodes; iframe is included
|
||||
expect(nodes.find((n) => n.backendNodeId === 13)?.tag).toBe("iframe");
|
||||
// iframeNodes keyed by the <iframe> element's backendNodeId=13
|
||||
expect(iframeNodes.size).toBe(1);
|
||||
expect(iframeNodes.has(13)).toBe(true);
|
||||
const subNodes = iframeNodes.get(13)!;
|
||||
const facts = await captureObservationFacts(cdp, 4);
|
||||
const root = facts.documents.find((doc) => doc.frame.frameId === "main-frame")!;
|
||||
const child = facts.documents.find((doc) => doc.frame.frameId === "child-frame")!;
|
||||
expect(facts.documents).toHaveLength(2);
|
||||
expect(root.domNodes.find((n) => n.backendNodeId === 13)?.tag).toBe("iframe");
|
||||
const subNodes = child.domNodes;
|
||||
const input = subNodes.find((n) => n.backendNodeId === 101);
|
||||
expect(input?.tag).toBe("input");
|
||||
expect(input?.attrs.type).toBe("text");
|
||||
expect(input?.ownerFrameBackendNodeId).toBe(13);
|
||||
expect(input?.localRect).toEqual({ x: 0, y: 0, w: 200, h: 40 });
|
||||
expect(input?.rect).toEqual({ x: 100, y: 300, w: 200, h: 40 });
|
||||
expect(rootFrameId).toBe("main-frame");
|
||||
expect(frameNodes?.get("child-frame")).toBe(subNodes);
|
||||
expect(frameOwnerBackendNodeIds?.get("child-frame")).toBe(13);
|
||||
expect(frameParentIds?.get("child-frame")).toBe("main-frame");
|
||||
expect(facts.rootFrameId).toBe("main-frame");
|
||||
expect(child.frame.ownerBackendNodeId).toBe(13);
|
||||
expect(child.frame.parentFrameId).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",
|
||||
@@ -997,6 +993,7 @@ describe("captureViewModel", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
scrollOffsetX: 0,
|
||||
scrollOffsetY: 0,
|
||||
nodes: {
|
||||
@@ -1014,6 +1011,7 @@ describe("captureViewModel", () => {
|
||||
},
|
||||
},
|
||||
{
|
||||
frameId: "child",
|
||||
scrollOffsetX: 0,
|
||||
scrollOffsetY: 0,
|
||||
nodes: {
|
||||
@@ -1040,15 +1038,23 @@ 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>,
|
||||
};
|
||||
|
||||
const { iframeNodes } = await captureViewModel(cdp, 4);
|
||||
const input = iframeNodes.get(13)?.find((n) => n.backendNodeId === 101);
|
||||
const { documents } = await captureObservationFacts(cdp, 4);
|
||||
const input = documents
|
||||
.find((doc) => doc.frame.frameId === "child")
|
||||
?.domNodes?.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 () => {
|
||||
@@ -1069,6 +1075,7 @@ describe("captureViewModel", () => {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1],
|
||||
nodeName: [i("html"), i("body"), i("iframe")],
|
||||
@@ -1090,6 +1097,7 @@ describe("captureViewModel", () => {
|
||||
},
|
||||
},
|
||||
{
|
||||
frameId: "child",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1],
|
||||
nodeName: [i("html"), i("body"), i("iframe")],
|
||||
@@ -1111,6 +1119,7 @@ describe("captureViewModel", () => {
|
||||
},
|
||||
},
|
||||
{
|
||||
frameId: "nested",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0],
|
||||
nodeName: [i("body"), i("input")],
|
||||
@@ -1127,21 +1136,52 @@ 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);
|
||||
const nestedIframe = iframeNodes.get(13)?.find((n) => n.backendNodeId === 23);
|
||||
const input = iframeNodes.get(23)?.find((n) => n.backendNodeId === 31);
|
||||
const { documents } = await captureObservationFacts(cdp, 4);
|
||||
const nestedIframe = documents
|
||||
.find((doc) => doc.frame.frameId === "child")
|
||||
?.domNodes?.find((n) => n.backendNodeId === 23);
|
||||
const input = documents
|
||||
.find((doc) => doc.frame.frameId === "nested")
|
||||
?.domNodes?.find((n) => n.backendNodeId === 31);
|
||||
|
||||
expect(nestedIframe?.localRect).toEqual({ x: 5, y: 6, w: 100, h: 80 });
|
||||
expect(nestedIframe?.rect).toEqual({ x: 15, y: 26, w: 100, h: 80 });
|
||||
@@ -1150,13 +1190,14 @@ 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 = {
|
||||
strings: S,
|
||||
documents: [
|
||||
{
|
||||
frameId: "root",
|
||||
nodes: {
|
||||
parentIndex: [-1, 0, 1],
|
||||
nodeName: [i("html"), i("body"), i("div")],
|
||||
@@ -1191,8 +1232,8 @@ describe("captureViewModel", () => {
|
||||
throw new Error(method);
|
||||
}) 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);
|
||||
const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
|
||||
expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 - 100);
|
||||
});
|
||||
|
||||
it("collectOverlayExcludedBackendIds walks the pierced overlay host subtree", async () => {
|
||||
|
||||
@@ -0,0 +1,156 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
|
||||
import { buildDocumentIndex, type DecodedNode } from "../facts";
|
||||
import { decodeDocument, REQUESTED_STYLES } from "../snapshot";
|
||||
|
||||
function node(id: number, parent: number | null): DecodedNode {
|
||||
return {
|
||||
backendNodeId: id,
|
||||
parentBackendNodeId: parent,
|
||||
tag: "div",
|
||||
attrs: {},
|
||||
paintOrder: 0,
|
||||
position: "static",
|
||||
pointerEvents: "auto",
|
||||
};
|
||||
}
|
||||
|
||||
describe("document facts", () => {
|
||||
it.each([
|
||||
1_000, 10_000, 100_000,
|
||||
])("indexes deep and wide inputs of %i without copying ancestors", async (count) => {
|
||||
for (const wide of [false, true]) {
|
||||
let reads = 0;
|
||||
const input = Array.from({ length: count }, (_, i) => {
|
||||
const item = node(i, i ? (wide ? 0 : i - 1) : null);
|
||||
Object.defineProperty(item, "parentBackendNodeId", {
|
||||
get: () => {
|
||||
reads++;
|
||||
return i ? (wide ? 0 : i - 1) : null;
|
||||
},
|
||||
});
|
||||
return item;
|
||||
}).reverse(); // parent need not precede child
|
||||
const index = await buildDocumentIndex(input);
|
||||
expect(index.nodes.size).toBe(count);
|
||||
expect(index.ancestry.get(count - 1)).toEqual({ complete: true, overlay: false });
|
||||
expect(index.children.get(0)?.length).toBe(wide ? count - 1 : 1);
|
||||
expect(reads).toBeLessThanOrEqual(count * 8);
|
||||
expect(index.nodes.get(count - 1)).toBe(input[0]);
|
||||
}
|
||||
});
|
||||
|
||||
it("marks cycles and orphans incomplete and propagates overlay through shadow roots", async () => {
|
||||
const host = { ...node(1, null), attrs: { [OVERLAY_HOST_MARKER_ATTR]: "" } };
|
||||
const input = [
|
||||
node(3, 2),
|
||||
{ ...node(2, 1), tag: "#document-fragment" },
|
||||
host,
|
||||
node(4, 99),
|
||||
node(5, 6),
|
||||
node(6, 5),
|
||||
node(7, 6),
|
||||
];
|
||||
const index = await buildDocumentIndex(input);
|
||||
expect([...index.excludedBackendNodeIds].sort()).toEqual([1, 2, 3]);
|
||||
for (const id of [4, 5, 6, 7]) expect(index.ancestry.get(id)?.complete).toBe(false);
|
||||
});
|
||||
|
||||
it("does not propagate a descendant overlay backwards into a cycle", async () => {
|
||||
const overlay = { ...node(3, 1), attrs: { [OVERLAY_HOST_MARKER_ATTR]: "" } };
|
||||
const index = await buildDocumentIndex([overlay, node(1, 2), node(2, 1)]);
|
||||
expect([...index.excludedBackendNodeIds]).toEqual([3]);
|
||||
});
|
||||
|
||||
it("does not treat a missing snapshot parent as a complete root", async () => {
|
||||
const { nodes } = await decodeDocument(
|
||||
{ nodes: { backendNodeId: [1], nodeName: [0], parentIndex: [99] } },
|
||||
["div"],
|
||||
);
|
||||
const index = await buildDocumentIndex(nodes);
|
||||
expect(index.ancestry.get(1)?.complete).toBe(false);
|
||||
});
|
||||
|
||||
it("retains raw box units and independent style/interaction evidence", async () => {
|
||||
const strings = [
|
||||
"html",
|
||||
"canvas",
|
||||
"aria-hidden",
|
||||
"true",
|
||||
"inert",
|
||||
"",
|
||||
"hidden",
|
||||
"visible",
|
||||
"0",
|
||||
"auto",
|
||||
"scroll",
|
||||
"matrix(2,0,0,2,0,0)",
|
||||
];
|
||||
const styles = REQUESTED_STYLES.map((style) =>
|
||||
style === "visibility"
|
||||
? 7
|
||||
: style === "opacity"
|
||||
? 8
|
||||
: style === "overflow-x"
|
||||
? 10
|
||||
: style === "transform"
|
||||
? 11
|
||||
: 9,
|
||||
);
|
||||
const { nodes } = await decodeDocument(
|
||||
{
|
||||
nodes: {
|
||||
backendNodeId: [1, 2],
|
||||
parentIndex: [-1, 0],
|
||||
nodeName: [0, 1],
|
||||
attributes: [[2, 3, 4, 5], []],
|
||||
},
|
||||
layout: {
|
||||
nodeIndex: [0, 1],
|
||||
bounds: [
|
||||
[0, 0, 200, 100],
|
||||
[10, 20, 120, 40],
|
||||
],
|
||||
clientRects: [
|
||||
[5, 5, 90, 40],
|
||||
[0, 0, 120, 40],
|
||||
],
|
||||
styles: [styles, styles],
|
||||
},
|
||||
},
|
||||
strings,
|
||||
);
|
||||
expect(nodes[0].attrs).toEqual({ "aria-hidden": "true", inert: "" });
|
||||
expect(nodes[0].layout).toMatchObject({
|
||||
boundsSpace: "snapshot-document-css",
|
||||
clientSpace: "unscaled-client-offset-css",
|
||||
clientRect: [5, 5, 90, 40],
|
||||
styles: {
|
||||
visibility: "visible",
|
||||
opacity: "0",
|
||||
"overflow-x": "scroll",
|
||||
transform: "matrix(2,0,0,2,0,0)",
|
||||
},
|
||||
});
|
||||
expect(nodes[0]).not.toHaveProperty("rect");
|
||||
expect(nodes[0]).not.toHaveProperty("excluded");
|
||||
});
|
||||
|
||||
it("yields during large inputs so cancellation interrupts indexing", async () => {
|
||||
const controller = new AbortController();
|
||||
const input = Array.from({ length: 100_000 }, (_, i) => node(i, i ? i - 1 : null));
|
||||
let reads = 0;
|
||||
for (const item of input)
|
||||
Object.defineProperty(item, "attrs", {
|
||||
get: () => {
|
||||
reads++;
|
||||
if (reads === 100) controller.abort();
|
||||
return {};
|
||||
},
|
||||
});
|
||||
await expect(buildDocumentIndex(input, controller.signal)).rejects.toMatchObject({
|
||||
name: "AbortError",
|
||||
});
|
||||
expect(reads).toBeLessThanOrEqual(356);
|
||||
});
|
||||
});
|
||||
@@ -1,6 +1,6 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import { type CdpRunner, cdpRunnerForTarget } from "../../shared";
|
||||
import { captureViewModel } from "../capture";
|
||||
import { captureObservationFacts } from "../capture-coordinator";
|
||||
|
||||
interface Control {
|
||||
id: number;
|
||||
@@ -106,17 +106,19 @@ describe("form state identity", () => {
|
||||
[11, state("alice@example.com")],
|
||||
]),
|
||||
);
|
||||
const captured = await captureViewModel(cdp, 7);
|
||||
expect(captured.nodes.find((n) => n.backendNodeId === 10)).toMatchObject({
|
||||
const captured = await captureObservationFacts(cdp, 7);
|
||||
expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 10)).toMatchObject({
|
||||
formValue: "",
|
||||
formState: "empty",
|
||||
formPlaceholder: "snapshot placeholder",
|
||||
});
|
||||
expect(captured.nodes.find((n) => n.backendNodeId === 11)).toMatchObject({
|
||||
expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)).toMatchObject({
|
||||
formValue: "alice@example.com",
|
||||
});
|
||||
expect(captured.nodes.find((n) => n.backendNodeId === 12)).toMatchObject({ formValue: "上海" });
|
||||
expect(captured.nodes.some((n) => n.backendNodeId === 99)).toBe(false);
|
||||
expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 12)).toMatchObject({
|
||||
formValue: "上海",
|
||||
});
|
||||
expect(captured.documents[0].domNodes.some((n) => n.backendNodeId === 99)).toBe(false);
|
||||
});
|
||||
|
||||
it("does not shift state between frames when one frame is absent from the runtime batch", async () => {
|
||||
@@ -133,8 +135,10 @@ describe("form state identity", () => {
|
||||
[21, state("second frame")],
|
||||
]),
|
||||
);
|
||||
const captured = await captureViewModel(cdp, 7);
|
||||
const controls = [...captured.iframeNodes.values()].flat();
|
||||
const captured = await captureObservationFacts(cdp, 7);
|
||||
const controls = captured.documents
|
||||
.filter((doc) => doc.frame.parentFrameId)
|
||||
.flatMap((doc) => doc.domNodes);
|
||||
expect(controls.find((n) => n.backendNodeId === 11)?.formValue).toBe("inaccessible frame");
|
||||
expect(controls.find((n) => n.backendNodeId === 21)?.formValue).toBe("second frame");
|
||||
expect(controls.find((n) => n.backendNodeId === 31)?.formValue).toBe("third frame");
|
||||
@@ -151,8 +155,13 @@ describe("form state identity", () => {
|
||||
});
|
||||
const cdp = { send, sendToTarget } as unknown as CdpRunner;
|
||||
for (const sessionId of ["left-frame", "right-frame"]) {
|
||||
const captured = await captureViewModel(cdpRunnerForTarget(cdp, { tabId: 7, sessionId }), 7);
|
||||
expect(captured.nodes.find((n) => n.backendNodeId === 11)?.formValue).toBe(sessionId);
|
||||
const captured = await captureObservationFacts(
|
||||
cdpRunnerForTarget(cdp, { tabId: 7, sessionId }),
|
||||
7,
|
||||
);
|
||||
expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)?.formValue).toBe(
|
||||
sessionId,
|
||||
);
|
||||
expect(sendToTarget).toHaveBeenCalledWith(
|
||||
{ tabId: 7, sessionId },
|
||||
"Runtime.releaseObjectGroup",
|
||||
@@ -178,8 +187,8 @@ describe("form state identity", () => {
|
||||
result.result.deepSerializedValue.value[0].value[1].value = "not json";
|
||||
return result;
|
||||
});
|
||||
const captured = await captureViewModel(cdp, 7);
|
||||
expect(captured.nodes.find((n) => n.backendNodeId === 11)).toMatchObject({
|
||||
const captured = await captureObservationFacts(cdp, 7);
|
||||
expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)).toMatchObject({
|
||||
formValue: "snapshot value",
|
||||
formPlaceholder: "snapshot placeholder",
|
||||
});
|
||||
@@ -192,7 +201,7 @@ describe("form state identity", () => {
|
||||
controller.abort();
|
||||
return reply([[11, state("new")]]);
|
||||
});
|
||||
await expect(captureViewModel(cdp, 7, { signal: controller.signal })).rejects.toMatchObject({
|
||||
await expect(captureObservationFacts(cdp, 7, controller.signal)).rejects.toMatchObject({
|
||||
name: "AbortError",
|
||||
});
|
||||
expect(send).toHaveBeenCalledWith(7, "Runtime.releaseObjectGroup", expect.anything());
|
||||
@@ -216,9 +225,13 @@ describe("form state identity", () => {
|
||||
return result;
|
||||
},
|
||||
);
|
||||
const captured = await captureViewModel(cdp, 7);
|
||||
expect(captured.nodes.find((n) => n.backendNodeId === 11)?.formValue).toBe("snapshot value");
|
||||
expect(captured.nodes.find((n) => n.backendNodeId === 12)?.formValue).toBe("live value");
|
||||
const captured = await captureObservationFacts(cdp, 7);
|
||||
expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)?.formValue).toBe(
|
||||
"snapshot value",
|
||||
);
|
||||
expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 12)?.formValue).toBe(
|
||||
"live value",
|
||||
);
|
||||
});
|
||||
|
||||
it.each([
|
||||
@@ -228,8 +241,8 @@ describe("form state identity", () => {
|
||||
const { cdp } = fakeCdp([[{ id: 11, value: "secret", type }]], () =>
|
||||
reply([[11, { ...state("secret"), sensitive: true }]]),
|
||||
);
|
||||
const captured = await captureViewModel(cdp, 7);
|
||||
const control = captured.nodes.find((n) => n.backendNodeId === 11);
|
||||
const captured = await captureObservationFacts(cdp, 7);
|
||||
const control = captured.documents[0].domNodes.find((n) => n.backendNodeId === 11);
|
||||
expect(control?.formState).toBe("filled");
|
||||
expect(control?.formValue).toBeUndefined();
|
||||
expect(control?.formDefaultValue).toBeUndefined();
|
||||
@@ -257,9 +270,13 @@ describe("form state identity", () => {
|
||||
expect(entries).toHaveLength(250);
|
||||
return reply(entries.map(([element, json]) => [element.backendNodeId, JSON.parse(json)]));
|
||||
});
|
||||
const captured = await captureViewModel(cdp, 7);
|
||||
expect(captured.nodes.find((n) => n.backendNodeId === 250)?.formValue).toBe("live 250");
|
||||
expect(captured.nodes.find((n) => n.backendNodeId === 251)?.formValue).toBe("old");
|
||||
const captured = await captureObservationFacts(cdp, 7);
|
||||
expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 250)?.formValue).toBe(
|
||||
"live 250",
|
||||
);
|
||||
expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 251)?.formValue).toBe(
|
||||
"old",
|
||||
);
|
||||
expect(send.mock.calls.filter(([, method]) => method === "Runtime.evaluate")).toHaveLength(1);
|
||||
expect(
|
||||
send.mock.calls.filter(([, method]) => method === "Runtime.releaseObjectGroup"),
|
||||
|
||||
@@ -1,198 +0,0 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import type { CdpRunner } from "../../shared";
|
||||
import type { CapturedNode, CapturedViewModel } from "../capture";
|
||||
import { captureFrameData } from "../frame-capture";
|
||||
|
||||
function ownerNode(backendNodeId: number, x: number): CapturedNode {
|
||||
return {
|
||||
backendNodeId,
|
||||
parentBackendNodeId: 1,
|
||||
frameId: "main",
|
||||
ownerFrameBackendNodeId: null,
|
||||
tag: "iframe",
|
||||
attrs: {},
|
||||
rect: { x, y: 100, w: 300, h: 200 },
|
||||
localRect: { x, y: 100, w: 300, h: 200 },
|
||||
paintOrder: 1,
|
||||
position: "static",
|
||||
pointerEvents: "auto",
|
||||
};
|
||||
}
|
||||
|
||||
function childSnapshot(frameId: string, backendNodeId: number) {
|
||||
const strings = [frameId, "body", "button", "static", "auto", "pointer"];
|
||||
return {
|
||||
strings,
|
||||
documents: [
|
||||
{
|
||||
frameId,
|
||||
nodes: {
|
||||
parentIndex: [-1, 0],
|
||||
nodeName: [1, 2],
|
||||
backendNodeId: [backendNodeId - 1, backendNodeId],
|
||||
attributes: [[], []],
|
||||
},
|
||||
layout: {
|
||||
nodeIndex: [0, 1],
|
||||
styles: [
|
||||
[3, 4, 4],
|
||||
[3, 4, 5],
|
||||
],
|
||||
bounds: [
|
||||
[0, 0, 300, 200],
|
||||
[10, 20, 100, 40],
|
||||
],
|
||||
paintOrders: [0, 1],
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
describe("captureFrameData", () => {
|
||||
it("captures and positions multiple OOPIF documents missing from the root snapshot", async () => {
|
||||
const leftOwner = ownerNode(10, 50);
|
||||
const rightOwner = ownerNode(20, 500);
|
||||
const captured: CapturedViewModel = {
|
||||
nodes: [leftOwner, rightOwner],
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
frameNodes: new Map([["main", [leftOwner, rightOwner]]]),
|
||||
frameOwnerBackendNodeIds: new Map(),
|
||||
rootFrameId: "main",
|
||||
excludedBackendNodeIds: new Set(),
|
||||
};
|
||||
const sendToTarget = vi.fn(async (target, method) => {
|
||||
if (method === "Page.getLayoutMetrics") {
|
||||
return { cssLayoutViewport: { clientWidth: 300, clientHeight: 200, pageX: 0, pageY: 0 } };
|
||||
}
|
||||
if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
|
||||
if (method === "DOMSnapshot.captureSnapshot") {
|
||||
return target.sessionId === "left-session"
|
||||
? childSnapshot("left", 101)
|
||||
: childSnapshot("right", 201);
|
||||
}
|
||||
if (method === "Accessibility.getFullAXTree") return { nodes: [] };
|
||||
throw new Error(`unexpected ${method}`);
|
||||
});
|
||||
const cdp: CdpRunner = {
|
||||
send: vi.fn(async (_tabId, method, params) => {
|
||||
if (method === "Accessibility.enable") return {};
|
||||
if (method === "Accessibility.getFullAXTree") return { nodes: [] };
|
||||
if (method === "DOM.getBoxModel") {
|
||||
const backendNodeId = (params as { backendNodeId?: number })?.backendNodeId;
|
||||
const x = backendNodeId === 10 ? 50 : 500;
|
||||
return { model: { content: [x, 100, x + 300, 100, x + 300, 300, x, 300] } };
|
||||
}
|
||||
if (method === "Page.getLayoutMetrics") {
|
||||
return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
|
||||
}
|
||||
throw new Error(`unexpected root ${method}`);
|
||||
}) as CdpRunner["send"],
|
||||
sendToTarget: sendToTarget as unknown as NonNullable<CdpRunner["sendToTarget"]>,
|
||||
getFrameGraph: vi.fn(async () => ({
|
||||
rootFrameId: "main",
|
||||
frames: [
|
||||
{ frameId: "main", target: { tabId: 4 } },
|
||||
{
|
||||
frameId: "left",
|
||||
parentFrameId: "main",
|
||||
ownerBackendNodeId: 10,
|
||||
target: { tabId: 4, sessionId: "left-session" },
|
||||
},
|
||||
{
|
||||
frameId: "right",
|
||||
parentFrameId: "main",
|
||||
ownerBackendNodeId: 20,
|
||||
target: { tabId: 4, sessionId: "right-session" },
|
||||
},
|
||||
],
|
||||
})),
|
||||
};
|
||||
|
||||
const trees = await captureFrameData(cdp, 4, captured);
|
||||
|
||||
expect(trees.map((tree) => tree.frameId)).toEqual(["main", "left", "right"]);
|
||||
expect(
|
||||
captured.frameNodes?.get("left")?.find((node) => node.backendNodeId === 101)?.rect,
|
||||
).toEqual({ x: 60, y: 120, w: 100, h: 40 });
|
||||
expect(
|
||||
captured.frameNodes?.get("right")?.find((node) => node.backendNodeId === 201)?.rect,
|
||||
).toEqual({ x: 510, y: 120, w: 100, h: 40 });
|
||||
expect(captured.frameOwnerBackendNodeIds).toEqual(
|
||||
new Map([
|
||||
["left", 10],
|
||||
["right", 20],
|
||||
]),
|
||||
);
|
||||
expect(captured.frameParentIds).toEqual(
|
||||
new Map([
|
||||
["left", "main"],
|
||||
["right", "main"],
|
||||
]),
|
||||
);
|
||||
});
|
||||
|
||||
it("keeps OOPIF semantics when viewport projection is unavailable", async () => {
|
||||
const owner = { ...ownerNode(10, 50), rect: null, localRect: null };
|
||||
const captured: CapturedViewModel = {
|
||||
nodes: [owner],
|
||||
viewport: { width: 1000, height: 800 },
|
||||
iframeNodes: new Map(),
|
||||
frameNodes: new Map([["main", [owner]]]),
|
||||
rootFrameId: "main",
|
||||
excludedBackendNodeIds: new Set(),
|
||||
};
|
||||
const cdp: CdpRunner = {
|
||||
send: vi.fn(async (_tabId, method) => {
|
||||
if (method === "Accessibility.enable") return {};
|
||||
if (method === "Accessibility.getFullAXTree") return { nodes: [] };
|
||||
if (method === "DOM.getBoxModel") throw new Error("owner geometry unavailable");
|
||||
if (method === "Page.getLayoutMetrics") {
|
||||
return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
|
||||
}
|
||||
throw new Error(`unexpected root ${method}`);
|
||||
}) as CdpRunner["send"],
|
||||
sendToTarget: vi.fn(async (_target, method) => {
|
||||
if (method === "Page.getLayoutMetrics") throw new Error("viewport unavailable");
|
||||
if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
|
||||
if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("child", 101);
|
||||
if (method === "Accessibility.getFullAXTree") {
|
||||
return {
|
||||
nodes: [
|
||||
{
|
||||
nodeId: "button",
|
||||
backendDOMNodeId: 101,
|
||||
role: { type: "role", value: "button" },
|
||||
name: { type: "computedString", value: "Continue" },
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
throw new Error(`unexpected ${method}`);
|
||||
}) as unknown 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" },
|
||||
},
|
||||
],
|
||||
})),
|
||||
};
|
||||
|
||||
const documents = await captureFrameData(cdp, 4, captured);
|
||||
const childDocument = documents.find((document) => document.frameId === "child");
|
||||
|
||||
expect(childDocument?.axNodes).toEqual([
|
||||
expect.objectContaining({ backendDOMNodeId: 101, frameId: "child" }),
|
||||
]);
|
||||
expect(childDocument?.domNodes.find((node) => node.backendNodeId === 101)).toEqual(
|
||||
expect.objectContaining({ rect: null, localRect: { x: 10, y: 20, w: 100, h: 40 } }),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -1,7 +1,12 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import type { CdpFrameGraph } from "@/browser-driver/frame-graph";
|
||||
import type { CapturedNode, CapturedViewModel } from "../capture";
|
||||
import { buildFrameDocuments, type FrameAxBatch, type FrameOwnedAxNode } from "../frame-document";
|
||||
import type { CapturedNode } from "../capture";
|
||||
import {
|
||||
buildFrameDocuments,
|
||||
type FrameAxBatch,
|
||||
type FrameDomInput,
|
||||
type FrameOwnedAxNode,
|
||||
} from "../frame-document";
|
||||
|
||||
function domNode(frameId: string, backendNodeId: number): CapturedNode {
|
||||
return {
|
||||
@@ -17,19 +22,16 @@ function domNode(frameId: string, backendNodeId: number): CapturedNode {
|
||||
};
|
||||
}
|
||||
|
||||
function captured(frameNodes: Map<string, CapturedNode[]>): CapturedViewModel {
|
||||
function captured(frameNodes: Map<string, CapturedNode[]>): FrameDomInput {
|
||||
return {
|
||||
nodes: frameNodes.get("main") ?? [],
|
||||
viewport: { width: 800, height: 600 },
|
||||
iframeNodes: new Map(),
|
||||
frameNodes,
|
||||
rootFrameId: "main",
|
||||
excludedBackendNodeIds: new Set(),
|
||||
};
|
||||
}
|
||||
|
||||
describe("buildFrameDocuments", () => {
|
||||
it("partitions mixed AX results by node ownership and cuts cross-frame parent edges", () => {
|
||||
it("partitions mixed AX results by node ownership and cuts cross-frame parent edges", async () => {
|
||||
const graph: CdpFrameGraph = {
|
||||
rootFrameId: "main",
|
||||
frames: [
|
||||
@@ -54,7 +56,7 @@ describe("buildFrameDocuments", () => {
|
||||
},
|
||||
];
|
||||
|
||||
const documents = buildFrameDocuments(
|
||||
const documents = await buildFrameDocuments(
|
||||
graph,
|
||||
batches,
|
||||
captured(
|
||||
@@ -72,7 +74,7 @@ describe("buildFrameDocuments", () => {
|
||||
expect(childNodes.find((node) => node.nodeId === "virtual")?.frameId).toBe("child");
|
||||
});
|
||||
|
||||
it("deduplicates overlapping same-target AX results using the strongest ownership", () => {
|
||||
it("deduplicates overlapping same-target AX results using the strongest ownership", async () => {
|
||||
const graph: CdpFrameGraph = {
|
||||
rootFrameId: "main",
|
||||
frames: [
|
||||
@@ -92,7 +94,7 @@ describe("buildFrameDocuments", () => {
|
||||
},
|
||||
];
|
||||
|
||||
const documents = buildFrameDocuments(
|
||||
const documents = await buildFrameDocuments(
|
||||
graph,
|
||||
batches,
|
||||
captured(
|
||||
@@ -107,7 +109,7 @@ describe("buildFrameDocuments", () => {
|
||||
expect(documents.find((document) => document.frameId === "child")?.axNodes).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("uses target-scoped backend ownership when OOPIF backend ids collide", () => {
|
||||
it("uses target-scoped backend ownership when OOPIF backend ids collide", async () => {
|
||||
const graph: CdpFrameGraph = {
|
||||
rootFrameId: "main",
|
||||
frames: [
|
||||
@@ -129,7 +131,7 @@ describe("buildFrameDocuments", () => {
|
||||
nodes: [{ nodeId: `${frame.frameId}-node`, backendDOMNodeId: 7 }],
|
||||
}));
|
||||
|
||||
const documents = buildFrameDocuments(
|
||||
const documents = await buildFrameDocuments(
|
||||
graph,
|
||||
batches,
|
||||
captured(
|
||||
@@ -149,7 +151,7 @@ describe("buildFrameDocuments", () => {
|
||||
);
|
||||
});
|
||||
|
||||
it("uses captured frame parent identity instead of guessing from backend ids", () => {
|
||||
it("uses captured frame parent identity instead of guessing from backend ids", async () => {
|
||||
const frameNodes = new Map([
|
||||
["main", [domNode("main", 1)]],
|
||||
["left", [domNode("left", 7)]],
|
||||
@@ -164,11 +166,42 @@ describe("buildFrameDocuments", () => {
|
||||
nodes: [],
|
||||
}));
|
||||
|
||||
const documents = buildFrameDocuments(null, frames, capture);
|
||||
const documents = await buildFrameDocuments(null, frames, capture);
|
||||
|
||||
expect(documents.find((document) => document.frameId === "child")).toMatchObject({
|
||||
parentFrameId: "left",
|
||||
ownerBackendNodeId: 7,
|
||||
});
|
||||
});
|
||||
it("rejects explicit AX frame ownership in a different target", async () => {
|
||||
const frames = [
|
||||
{ frameId: "main", target: { tabId: 4 } },
|
||||
{ frameId: "remote", target: { tabId: 4, sessionId: "remote" } },
|
||||
];
|
||||
const unresolved = vi.fn();
|
||||
const documents = await buildFrameDocuments(
|
||||
{ rootFrameId: "main", frames },
|
||||
[{ frame: frames[0], nodes: [{ nodeId: "wrong", frameId: "remote" }] }],
|
||||
captured(new Map()),
|
||||
undefined,
|
||||
unresolved,
|
||||
);
|
||||
expect(documents.every((doc) => doc.axNodes.length === 0)).toBe(true);
|
||||
expect(unresolved).toHaveBeenCalledOnce();
|
||||
});
|
||||
|
||||
it("resolves a reverse-ordered deep AX parent chain without recursion", async () => {
|
||||
const frame = { frameId: "main", target: { tabId: 4 } };
|
||||
const nodes: FrameOwnedAxNode[] = Array.from({ length: 10000 }, (_, i) => ({
|
||||
nodeId: String(i),
|
||||
...(i ? { parentId: String(i - 1) } : { frameId: "main" }),
|
||||
})).reverse();
|
||||
const documents = await buildFrameDocuments(
|
||||
{ rootFrameId: "main", frames: [frame] },
|
||||
[{ frame, nodes }],
|
||||
captured(new Map()),
|
||||
);
|
||||
expect(documents[0].axNodes).toHaveLength(10000);
|
||||
expect(documents[0].axNodes[0].frameId).toBe("main");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,382 @@
|
||||
import {
|
||||
buildFrameGraph,
|
||||
type CdpFrame,
|
||||
type CdpFrameGraph,
|
||||
type CdpFrameTreeNode,
|
||||
type CdpTarget,
|
||||
cdpTargetKey,
|
||||
} from "@/browser-driver/frame-graph";
|
||||
import { cssViewport, GeometryContext } from "../geometry/frame-context";
|
||||
import { type CdpRunner, cdpRunnerForTarget, sendToCdpTarget } from "../shared";
|
||||
import { collectOverlayExcludedBackendIds } from "./capture";
|
||||
import { readDocumentIdentity, sameDocument } from "./document-identity";
|
||||
import type { CapturedSceneInput } from "./facts";
|
||||
import {
|
||||
buildDocumentIndex,
|
||||
type CaptureIssue,
|
||||
type DocumentIdentity,
|
||||
isCaptureAbort,
|
||||
type ObservationFacts,
|
||||
throwCaptureAborted,
|
||||
} from "./facts";
|
||||
import { enrichFormControlStates } from "./form-capture";
|
||||
import {
|
||||
buildFrameDocuments,
|
||||
type FrameAxBatch,
|
||||
type FrameDocument,
|
||||
type FrameOwnedAxNode,
|
||||
} from "./frame-document";
|
||||
import { type NormalizedDocument, normalizeSnapshot } from "./normalize";
|
||||
import { REQUESTED_STYLES, type SnapshotReply, snapshotFrameId } from "./snapshot";
|
||||
|
||||
interface TargetBatch<T extends FrameOwnedAxNode> {
|
||||
target: CdpTarget;
|
||||
frames: CdpFrame[];
|
||||
before: Map<string, DocumentIdentity>;
|
||||
documents: NormalizedDocument[];
|
||||
ax: FrameAxBatch<T>[];
|
||||
fallbackExcluded: Set<number>;
|
||||
}
|
||||
|
||||
/** A fixed worker pool scoped to one capture; each worker issues at most one
|
||||
* collection request at a time. Geometry has its own measurement-phase bound. */
|
||||
async function collectTargets<T>(
|
||||
items: readonly T[],
|
||||
collect: (item: T) => Promise<void>,
|
||||
signal?: AbortSignal,
|
||||
): Promise<void> {
|
||||
let cursor = 0;
|
||||
await Promise.all(
|
||||
Array.from({ length: Math.min(4, items.length) }, async () => {
|
||||
while (cursor < items.length) {
|
||||
throwCaptureAborted(signal);
|
||||
const item = items[cursor++];
|
||||
await collect(item);
|
||||
}
|
||||
}),
|
||||
);
|
||||
}
|
||||
|
||||
/** When topology discovery is unavailable, snapshot documents still carry
|
||||
* explicit target/frame provenance. Only explicit contentDocumentIndex edges
|
||||
* establish ancestry; a foreign frame is never renamed to fit a request. */
|
||||
function snapshotFrames(snapshot: SnapshotReply, target: CdpTarget): CdpFrame[] {
|
||||
const raw = snapshot.documents ?? [];
|
||||
const strings = snapshot.strings ?? [];
|
||||
const frames = raw.map((doc) => {
|
||||
const frameId = snapshotFrameId(doc, strings);
|
||||
return frameId ? ({ frameId, target } as CdpFrame) : undefined;
|
||||
});
|
||||
for (let i = 0; i < raw.length; i++) {
|
||||
const edges = raw[i].nodes?.contentDocumentIndex;
|
||||
const parent = frames[i];
|
||||
if (!parent || !edges) continue;
|
||||
for (let e = 0; e < edges.index.length; e++) {
|
||||
const child = frames[edges.value[e]];
|
||||
const owner = raw[i].nodes?.backendNodeId?.[edges.index[e]];
|
||||
if (child && owner !== undefined && child !== parent) {
|
||||
child.parentFrameId = parent.frameId;
|
||||
child.ownerBackendNodeId = owner;
|
||||
}
|
||||
}
|
||||
}
|
||||
return frames.filter((frame): frame is CdpFrame => !!frame);
|
||||
}
|
||||
|
||||
export async function captureObservationFacts<T extends FrameOwnedAxNode>(
|
||||
cdp: CdpRunner,
|
||||
tabId: number,
|
||||
signal?: AbortSignal,
|
||||
): Promise<ObservationFacts<T>> {
|
||||
const startedAt = Date.now();
|
||||
throwCaptureAborted(signal);
|
||||
let graph: CdpFrameGraph | undefined;
|
||||
try {
|
||||
graph = await cdp.getFrameGraph?.(tabId);
|
||||
} catch (error) {
|
||||
if (isCaptureAbort(error)) throw error;
|
||||
}
|
||||
const geometry = new GeometryContext(cdp, tabId, graph, signal);
|
||||
const issues: CaptureIssue[] = [];
|
||||
const groups = new Map<string, TargetBatch<T>>();
|
||||
for (const frame of graph?.frames ?? []) {
|
||||
const key = cdpTargetKey(frame.target);
|
||||
let group = groups.get(key);
|
||||
if (!group) {
|
||||
group = {
|
||||
target: frame.target,
|
||||
frames: [],
|
||||
before: new Map(),
|
||||
documents: [],
|
||||
ax: [],
|
||||
fallbackExcluded: new Set(),
|
||||
};
|
||||
groups.set(key, group);
|
||||
}
|
||||
group.frames.push(frame);
|
||||
}
|
||||
if (!groups.size)
|
||||
groups.set(cdpTargetKey({ tabId }), {
|
||||
target: { tabId },
|
||||
frames: [],
|
||||
before: new Map(),
|
||||
documents: [],
|
||||
ax: [],
|
||||
fallbackExcluded: new Set(),
|
||||
});
|
||||
const batches = [...groups.values()];
|
||||
const unavailable = (batch: TargetBatch<T>, stage: CaptureIssue["stage"], frameId?: string) =>
|
||||
issues.push({ target: batch.target, frameId, stage, reason: "capture-unavailable" });
|
||||
let firstFailure: unknown;
|
||||
await collectTargets(
|
||||
batches,
|
||||
async (batch) => {
|
||||
const scoped = cdpRunnerForTarget(cdp, batch.target);
|
||||
for (const frame of batch.frames) {
|
||||
const identity = await readDocumentIdentity(cdp, frame, signal);
|
||||
if (identity) batch.before.set(frame.frameId, identity);
|
||||
}
|
||||
try {
|
||||
throwCaptureAborted(signal);
|
||||
await scoped.send(tabId, "DOMSnapshot.enable", {});
|
||||
throwCaptureAborted(signal);
|
||||
const snapshot = await scoped.send<SnapshotReply>(tabId, "DOMSnapshot.captureSnapshot", {
|
||||
computedStyles: REQUESTED_STYLES,
|
||||
includePaintOrder: true,
|
||||
includeDOMRects: true,
|
||||
});
|
||||
throwCaptureAborted(signal);
|
||||
if (!graph) batch.frames = snapshotFrames(snapshot, batch.target);
|
||||
batch.documents = await normalizeSnapshot(
|
||||
snapshot,
|
||||
batch.target,
|
||||
batch.frames,
|
||||
geometry,
|
||||
issues,
|
||||
signal,
|
||||
);
|
||||
if (
|
||||
!(await enrichFormControlStates(
|
||||
scoped,
|
||||
tabId,
|
||||
batch.documents.map((doc) => doc.domNodes),
|
||||
signal,
|
||||
))
|
||||
)
|
||||
unavailable(batch, "forms");
|
||||
const present = new Set(batch.documents.map((doc) => doc.frame.frameId));
|
||||
for (const frame of batch.frames)
|
||||
if (!present.has(frame.frameId)) unavailable(batch, "dom", frame.frameId);
|
||||
} catch (error) {
|
||||
if (isCaptureAbort(error)) throw error;
|
||||
firstFailure ??= error;
|
||||
unavailable(batch, "dom");
|
||||
batch.fallbackExcluded = await collectOverlayExcludedBackendIds(scoped, tabId, signal);
|
||||
}
|
||||
if (!batch.frames.length && !graph)
|
||||
batch.frames = [{ frameId: "root", target: batch.target }];
|
||||
try {
|
||||
throwCaptureAborted(signal);
|
||||
await scoped.send(tabId, "Accessibility.enable", {});
|
||||
} catch (error) {
|
||||
if (isCaptureAbort(error)) throw error;
|
||||
firstFailure ??= error;
|
||||
unavailable(batch, "ax");
|
||||
return;
|
||||
}
|
||||
for (const frame of batch.frames) {
|
||||
try {
|
||||
throwCaptureAborted(signal);
|
||||
const result = await scoped.send<{ nodes?: T[] }>(
|
||||
tabId,
|
||||
"Accessibility.getFullAXTree",
|
||||
frame.frameId === "root" ? {} : { frameId: frame.frameId },
|
||||
);
|
||||
batch.ax.push({ frame, nodes: result.nodes ?? [] });
|
||||
} catch (error) {
|
||||
if (isCaptureAbort(error)) throw error;
|
||||
firstFailure ??= error;
|
||||
unavailable(batch, "ax", frame.frameId);
|
||||
}
|
||||
}
|
||||
},
|
||||
signal,
|
||||
);
|
||||
|
||||
// Validate after every target's static data and geometry have been collected.
|
||||
const identities = new Map<string, DocumentIdentity>();
|
||||
const invalid = new Set<string>();
|
||||
await collectTargets(
|
||||
batches,
|
||||
async (batch) => {
|
||||
let fresh: Map<string, CdpFrame> | undefined;
|
||||
if (batch.before.size) {
|
||||
try {
|
||||
throwCaptureAborted(signal);
|
||||
const reply = await sendToCdpTarget<{ frameTree?: CdpFrameTreeNode }>(
|
||||
cdp,
|
||||
batch.target,
|
||||
"Page.getFrameTree",
|
||||
{},
|
||||
);
|
||||
const tree = reply.frameTree
|
||||
? buildFrameGraph([{ target: batch.target, tree: reply.frameTree }])
|
||||
: null;
|
||||
fresh = new Map(tree?.frames.map((frame) => [frame.frameId, frame]));
|
||||
} catch (error) {
|
||||
if (isCaptureAbort(error)) throw error;
|
||||
}
|
||||
}
|
||||
const docs = new Map(batch.documents.map((doc) => [doc.frame.frameId, doc]));
|
||||
for (const frame of batch.frames) {
|
||||
const before = batch.before.get(frame.frameId);
|
||||
const currentFrame = fresh?.get(frame.frameId);
|
||||
const after = currentFrame
|
||||
? await readDocumentIdentity(cdp, currentFrame, signal)
|
||||
: undefined;
|
||||
const doc = docs.get(frame.frameId);
|
||||
const snapshotMismatch =
|
||||
before &&
|
||||
doc?.documentElementBackendNodeId !== undefined &&
|
||||
before.documentElementBackendNodeId !== doc.documentElementBackendNodeId;
|
||||
if (
|
||||
before &&
|
||||
(snapshotMismatch ||
|
||||
(fresh && !currentFrame) ||
|
||||
(after && !sameDocument(before, after)) ||
|
||||
cdp.getAttachmentId?.(tabId) !== before.attachmentId)
|
||||
) {
|
||||
invalid.add(frame.frameId);
|
||||
issues.push({
|
||||
target: frame.target,
|
||||
frameId: frame.frameId,
|
||||
stage: "identity",
|
||||
reason: "document-changed",
|
||||
});
|
||||
} else if (before && !after) {
|
||||
invalid.add(frame.frameId);
|
||||
issues.push({
|
||||
target: frame.target,
|
||||
frameId: frame.frameId,
|
||||
stage: "identity",
|
||||
reason: "identity-unverified",
|
||||
});
|
||||
} else if (
|
||||
before &&
|
||||
after &&
|
||||
sameDocument(before, after) &&
|
||||
(!doc || doc.documentElementBackendNodeId === before.documentElementBackendNodeId)
|
||||
)
|
||||
identities.set(frame.frameId, after);
|
||||
else
|
||||
issues.push({
|
||||
target: frame.target,
|
||||
frameId: frame.frameId,
|
||||
stage: "identity",
|
||||
reason: "identity-unverified",
|
||||
});
|
||||
}
|
||||
},
|
||||
signal,
|
||||
);
|
||||
const allFrames = batches.flatMap((batch) => batch.frames);
|
||||
const rootFrameId = graph?.rootFrameId ?? allFrames[0]?.frameId ?? "root";
|
||||
if (invalid.has(rootFrameId))
|
||||
throw new Error(
|
||||
"observation document identity changed or could not be verified; observe again",
|
||||
);
|
||||
// A descendant cannot retain geometry measured through an invalid ancestor.
|
||||
const childFrames = new Map<string, string[]>();
|
||||
for (const frame of allFrames)
|
||||
if (frame.parentFrameId) {
|
||||
const children = childFrames.get(frame.parentFrameId);
|
||||
if (children) children.push(frame.frameId);
|
||||
else childFrames.set(frame.parentFrameId, [frame.frameId]);
|
||||
}
|
||||
const queue = [...invalid];
|
||||
for (let i = 0; i < queue.length; i++)
|
||||
for (const child of childFrames.get(queue[i]) ?? []) {
|
||||
if (!invalid.has(child)) {
|
||||
invalid.add(child);
|
||||
queue.push(child);
|
||||
}
|
||||
}
|
||||
const frames = allFrames.filter((frame) => !invalid.has(frame.frameId));
|
||||
const decoded = new Map(
|
||||
batches
|
||||
.flatMap((batch) => batch.documents)
|
||||
.filter((doc) => !invalid.has(doc.frame.frameId))
|
||||
.map((doc) => [doc.frame.frameId, doc]),
|
||||
);
|
||||
const ax = batches
|
||||
.flatMap((batch) => batch.ax)
|
||||
.filter((batch) => !invalid.has(batch.frame.frameId));
|
||||
const documents = await buildFrameDocuments(
|
||||
{ rootFrameId, frames },
|
||||
ax,
|
||||
{
|
||||
nodes: [],
|
||||
rootFrameId,
|
||||
frameNodes: new Map([...decoded].map(([id, doc]) => [id, doc.domNodes])),
|
||||
},
|
||||
signal,
|
||||
(frame) =>
|
||||
issues.push({
|
||||
target: frame.target,
|
||||
frameId: frame.frameId,
|
||||
stage: "ownership",
|
||||
reason: "frame-ownership-unresolved",
|
||||
}),
|
||||
);
|
||||
let viewport = { width: 0, height: 0 };
|
||||
try {
|
||||
const measured = cssViewport(await geometry.layoutMetrics({ tabId }));
|
||||
viewport = { width: measured.width, height: measured.height };
|
||||
} catch (error) {
|
||||
if (isCaptureAbort(error)) throw error;
|
||||
}
|
||||
const facts: ObservationFacts<T>["documents"][number][] = [];
|
||||
for (const document of documents) {
|
||||
const doc = decoded.get(document.frameId);
|
||||
const index = doc?.index ?? (await buildDocumentIndex([], signal));
|
||||
const fallback = groups.get(cdpTargetKey(document.target))?.fallbackExcluded;
|
||||
const { domNodes, axNodes, contextScopeId: _scope, ...frame } = document;
|
||||
facts.push({
|
||||
frame,
|
||||
identity: identities.get(document.frameId),
|
||||
index: fallback?.size ? { ...index, excludedBackendNodeIds: fallback } : index,
|
||||
domNodes,
|
||||
axNodes,
|
||||
});
|
||||
}
|
||||
throwCaptureAborted(signal);
|
||||
if (firstFailure && facts.every((doc) => !doc.domNodes.length && !doc.axNodes.length))
|
||||
throw firstFailure;
|
||||
return { rootFrameId, viewport, documents: facts, issues, startedAt, finishedAt: Date.now() };
|
||||
}
|
||||
|
||||
/** Existing semantic consumers get a narrow view; no raw snapshot or identity
|
||||
* metadata can leak through recording's allowlisted output DTO. */
|
||||
export function semanticCapture<T extends FrameOwnedAxNode>(
|
||||
facts: ObservationFacts<T>,
|
||||
): { captured: CapturedSceneInput; documents: FrameDocument<T>[] } {
|
||||
const documents = facts.documents.map((doc) => ({
|
||||
...doc.frame,
|
||||
contextScopeId: doc.frame.frameId,
|
||||
domNodes: doc.domNodes.filter(
|
||||
(node) => !doc.index.excludedBackendNodeIds.has(node.backendNodeId),
|
||||
),
|
||||
axNodes: doc.axNodes,
|
||||
excludedBackendNodeIds: doc.index.excludedBackendNodeIds,
|
||||
}));
|
||||
const root = documents.find((doc) => doc.frameId === facts.rootFrameId);
|
||||
return {
|
||||
documents,
|
||||
captured: {
|
||||
nodes: root?.domNodes ?? [],
|
||||
viewport: facts.viewport,
|
||||
rootFrameId: facts.rootFrameId,
|
||||
excludedBackendNodeIds: root?.excludedBackendNodeIds ?? new Set(),
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -1,332 +1,21 @@
|
||||
// CDP capture adapter: DOMSnapshot.captureSnapshot + Page.getLayoutMetrics
|
||||
// → CapturedNode[] + Viewport. This is the ONLY VOM module that touches
|
||||
// raw CDP. The captureSnapshot reply is columnar (parallel arrays + a
|
||||
// shared string table); requested computed styles are decoded through
|
||||
// STYLE_COL so capture and visibility policy share one explicit contract.
|
||||
|
||||
import type { Rect, Viewport } from "@browser-skill/vom";
|
||||
// Browser-side hover probes and overlay exclusion fallback. Static collection
|
||||
// lives in capture-coordinator; snapshot decoding has no browser dependency.
|
||||
import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
|
||||
import { isOverlayHostNode, OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
|
||||
import { childFrameProjection, type GeometryProjection, projectRectToViewport } from "../geometry";
|
||||
import { OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
|
||||
import type { CdpRunner } from "../shared";
|
||||
import type { CapturedNode, CapturedSurfaceProbe } from "./facts";
|
||||
|
||||
export type {
|
||||
CapturedNode,
|
||||
CapturedSurfaceProbe,
|
||||
} from "./facts";
|
||||
|
||||
import { isCaptureAbort as isAbortError, throwCaptureAborted as throwIfAborted } from "./facts";
|
||||
import { clearHover, ProbeBudget, waitForHover } from "./hover-perception";
|
||||
|
||||
const REQUESTED_STYLES = ["position", "pointer-events", "cursor", "visibility", "opacity"] as const;
|
||||
const STYLE_COL = Object.fromEntries(
|
||||
REQUESTED_STYLES.map((name, index) => [name, index]),
|
||||
) as Record<(typeof REQUESTED_STYLES)[number], number>;
|
||||
|
||||
export interface CapturedNode {
|
||||
backendNodeId: number;
|
||||
parentBackendNodeId: number | null;
|
||||
frameId?: string;
|
||||
/** Owning iframe backend node id; `null` for the top-level document. */
|
||||
ownerFrameBackendNodeId?: number | null;
|
||||
tag: string;
|
||||
attrs: Record<string, string>;
|
||||
/** Top-level viewport-relative CSS px, clipped to the owning frame viewport. */
|
||||
rect: Rect | null;
|
||||
/** Frame-local viewport-relative CSS px before top-level projection. */
|
||||
localRect?: Rect | null;
|
||||
paintOrder: number;
|
||||
position: string;
|
||||
pointerEvents: string;
|
||||
/**
|
||||
* computed `cursor`. `cursor: pointer` is the strongest CDP-free signal
|
||||
* that a non-semantic element (a `<div>`/`<span>` with a click handler)
|
||||
* is actually an interactive control — used by the adapter to surface
|
||||
* custom buttons/checkboxes the AX tree drops as `generic`. Optional like
|
||||
* `textContent`: the live parser always sets it, hand-built fixtures may not.
|
||||
*/
|
||||
cursor?: string;
|
||||
/**
|
||||
* Whether the live DOM snapshot provides a painted, non-hidden box for this
|
||||
* node. Semantic resolution uses this only for DOM fallback nodes; AX-backed
|
||||
* nodes remain authoritative even when they are outside the viewport.
|
||||
*/
|
||||
rendered?: boolean;
|
||||
textContent?: string;
|
||||
formState?: "empty" | "filled" | "default";
|
||||
formValue?: string;
|
||||
formDefaultValue?: string;
|
||||
formPlaceholder?: string;
|
||||
}
|
||||
|
||||
export type CapturedIframeNodes = Map<number, CapturedNode[]>;
|
||||
|
||||
export interface CapturedSurfaceProbe {
|
||||
triggerBackendNodeId: number;
|
||||
triggerPoint?: { x: number; y: number };
|
||||
triggerAction: "hover" | "focus" | string;
|
||||
subItems: string[];
|
||||
confidence?: "high" | "medium" | "low";
|
||||
}
|
||||
|
||||
export interface CapturedViewModel {
|
||||
nodes: CapturedNode[];
|
||||
viewport: Viewport;
|
||||
iframeNodes: CapturedIframeNodes;
|
||||
frameNodes?: Map<string, CapturedNode[]>;
|
||||
frameOwnerBackendNodeIds?: Map<string, number>;
|
||||
/** Explicit DOMSnapshot frame ancestry; never inferred from backend node ids. */
|
||||
frameParentIds?: Map<string, string>;
|
||||
rootFrameId?: string;
|
||||
/** Backend node ids belonging to the agent overlay host + its shadow subtree. */
|
||||
excludedBackendNodeIds: Set<number>;
|
||||
}
|
||||
|
||||
export interface CaptureViewModelOptions {
|
||||
signal?: AbortSignal;
|
||||
}
|
||||
|
||||
function captureAbortError(): Error {
|
||||
const error = new Error("observation aborted");
|
||||
error.name = "AbortError";
|
||||
return error;
|
||||
}
|
||||
|
||||
function isAbortError(error: unknown): boolean {
|
||||
return (
|
||||
typeof error === "object" &&
|
||||
error !== null &&
|
||||
(error as { name?: string }).name === "AbortError"
|
||||
);
|
||||
}
|
||||
|
||||
function throwIfAborted(signal: AbortSignal | undefined): void {
|
||||
if (signal?.aborted) throw captureAbortError();
|
||||
}
|
||||
|
||||
/** Sparse array format Chrome uses for infrequently-set per-node fields. */
|
||||
interface SparseArray {
|
||||
index: number[];
|
||||
value: number[];
|
||||
}
|
||||
|
||||
interface RareBooleanData {
|
||||
index: number[];
|
||||
}
|
||||
|
||||
interface SnapshotDocument {
|
||||
frameId?: string | number;
|
||||
scrollOffsetX?: number;
|
||||
scrollOffsetY?: number;
|
||||
nodes?: {
|
||||
parentIndex?: number[];
|
||||
nodeName?: number[];
|
||||
backendNodeId?: number[];
|
||||
attributes?: number[][];
|
||||
/**
|
||||
* Per-node text value (index into strings), set for `#text` / CDATA nodes.
|
||||
* Element nodes carry -1. Same length as `backendNodeId`.
|
||||
*/
|
||||
nodeValue?: number[];
|
||||
/** Maps node array index → index into `documents[]` for frame content. */
|
||||
contentDocumentIndex?: SparseArray;
|
||||
inputValue?: SparseArray;
|
||||
textValue?: SparseArray;
|
||||
inputChecked?: RareBooleanData;
|
||||
optionSelected?: RareBooleanData;
|
||||
};
|
||||
layout?: {
|
||||
nodeIndex?: number[];
|
||||
styles?: number[][];
|
||||
bounds?: number[][];
|
||||
paintOrders?: number[];
|
||||
};
|
||||
}
|
||||
|
||||
function snapshotFrameId(document: SnapshotDocument, strings: string[]): string | undefined {
|
||||
if (typeof document.frameId === "string") return document.frameId || undefined;
|
||||
if (typeof document.frameId === "number") return str(strings, document.frameId) || undefined;
|
||||
return undefined;
|
||||
}
|
||||
|
||||
interface SnapshotReply {
|
||||
strings?: string[];
|
||||
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";
|
||||
}
|
||||
|
||||
function isSensitiveFormControl(node: Pick<CapturedNode, "tag" | "attrs">): boolean {
|
||||
return node.tag === "input" && (node.attrs.type ?? "").toLowerCase() === "password";
|
||||
}
|
||||
|
||||
function snapshotFormState(
|
||||
value: string | undefined,
|
||||
defaultValue: string,
|
||||
hasDefaultValue: boolean,
|
||||
sensitive: boolean,
|
||||
): CapturedNode["formState"] {
|
||||
if (sensitive) {
|
||||
if (value === undefined && !hasDefaultValue) return undefined;
|
||||
return (value ?? defaultValue) === "" ? "empty" : "filled";
|
||||
}
|
||||
if (value === undefined) return undefined;
|
||||
if (value === "") return "empty";
|
||||
return value === defaultValue ? "default" : "filled";
|
||||
}
|
||||
|
||||
const MAX_FORM_ENRICH_CONTROLS = 250;
|
||||
|
||||
interface CapturedFormState {
|
||||
value?: string;
|
||||
defaultValue?: string;
|
||||
placeholder?: string;
|
||||
state?: "empty" | "filled" | "default";
|
||||
sensitive?: boolean;
|
||||
}
|
||||
|
||||
interface DeepSerializedValue {
|
||||
type: string;
|
||||
value?: unknown;
|
||||
}
|
||||
|
||||
function formStateBatchExpression(maxControls: number): string {
|
||||
return `(() => {
|
||||
const maxControls = ${JSON.stringify(maxControls)};
|
||||
let remaining = maxControls;
|
||||
const controlSelector = "input,textarea,select";
|
||||
const controlState = (el) => {
|
||||
const tag = el.tagName.toLowerCase();
|
||||
const type = tag === "input" ? String(el.type || "text").toLowerCase() : tag;
|
||||
const sensitive = type === "password" || type === "credit-card";
|
||||
const rawValue = typeof el.value === "string" ? el.value : "";
|
||||
const defaultValue = typeof el.defaultValue === "string" ? el.defaultValue : "";
|
||||
const placeholder = typeof el.placeholder === "string" ? el.placeholder : "";
|
||||
const state = rawValue === "" ? "empty" : rawValue === defaultValue ? "default" : "filled";
|
||||
return {
|
||||
state,
|
||||
sensitive,
|
||||
placeholder,
|
||||
...(sensitive ? {} : { value: rawValue, defaultValue }),
|
||||
};
|
||||
};
|
||||
const controls = [];
|
||||
const collect = (doc) => {
|
||||
for (const el of Array.from(doc.querySelectorAll(controlSelector))) {
|
||||
if (remaining <= 0) break;
|
||||
// Deep serialization supplies the node's backend id. Keep the
|
||||
// state as JSON so decoding needs no general-purpose V8 deserializer.
|
||||
controls.push([el, JSON.stringify(controlState(el))]);
|
||||
remaining -= 1;
|
||||
}
|
||||
for (const frame of Array.from(doc.querySelectorAll("iframe"))) {
|
||||
if (remaining <= 0) break;
|
||||
let childDoc = null;
|
||||
try { childDoc = frame.contentDocument; } catch { childDoc = null; }
|
||||
if (childDoc) collect(childDoc);
|
||||
}
|
||||
};
|
||||
collect(document);
|
||||
return controls;
|
||||
})()`;
|
||||
}
|
||||
|
||||
function formStatesByBackendId(result: RuntimeEvaluateReply): Map<number, CapturedFormState> {
|
||||
const states = new Map<number, CapturedFormState>();
|
||||
const serialized = result.result?.deepSerializedValue;
|
||||
if (serialized?.type !== "array" || !Array.isArray(serialized.value)) return states;
|
||||
for (const entry of serialized.value as DeepSerializedValue[]) {
|
||||
if (entry?.type !== "array" || !Array.isArray(entry.value)) continue;
|
||||
const [element, json] = entry.value as DeepSerializedValue[];
|
||||
if (element?.type !== "node" || json?.type !== "string" || typeof json.value !== "string") {
|
||||
continue;
|
||||
}
|
||||
const backendNodeId = (element.value as { backendNodeId?: number } | undefined)?.backendNodeId;
|
||||
if (typeof backendNodeId !== "number" || !Number.isSafeInteger(backendNodeId)) continue;
|
||||
try {
|
||||
const state = JSON.parse(json.value) as CapturedFormState | null;
|
||||
if (
|
||||
!state ||
|
||||
!["empty", "filled", "default"].includes(state.state ?? "") ||
|
||||
typeof state.sensitive !== "boolean" ||
|
||||
typeof state.placeholder !== "string" ||
|
||||
(!state.sensitive &&
|
||||
(typeof state.value !== "string" || typeof state.defaultValue !== "string"))
|
||||
) {
|
||||
continue;
|
||||
}
|
||||
states.set(backendNodeId, state);
|
||||
} catch {
|
||||
// A malformed entry must not overwrite the snapshot's own state.
|
||||
}
|
||||
}
|
||||
return states;
|
||||
}
|
||||
|
||||
function applyFormStates(nodes: CapturedNode[], states: Map<number, CapturedFormState>): void {
|
||||
for (const node of nodes) {
|
||||
if (!isFormControlTag(node.tag)) continue;
|
||||
const state = states.get(node.backendNodeId);
|
||||
if (!state) continue;
|
||||
node.formState = state.state;
|
||||
node.formPlaceholder = state.placeholder ?? "";
|
||||
if (state.sensitive || isSensitiveFormControl(node)) {
|
||||
delete node.formValue;
|
||||
delete node.formDefaultValue;
|
||||
delete node.attrs.value;
|
||||
} else {
|
||||
node.formDefaultValue = state.defaultValue ?? "";
|
||||
if (state.value !== undefined) node.formValue = state.value;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async function enrichFormControlStates(
|
||||
cdp: CdpRunner,
|
||||
tabId: number,
|
||||
frameNodeGroups: CapturedNode[][],
|
||||
signal?: AbortSignal,
|
||||
): Promise<void> {
|
||||
const hasControls = frameNodeGroups.some((nodes) =>
|
||||
nodes.some((node) => isFormControlTag(node.tag)),
|
||||
);
|
||||
if (!hasControls) return;
|
||||
const objectGroup = `bsk-vom-forms-${crypto.randomUUID()}`;
|
||||
try {
|
||||
throwIfAborted(signal);
|
||||
const result = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
|
||||
expression: formStateBatchExpression(MAX_FORM_ENRICH_CONTROLS),
|
||||
objectGroup,
|
||||
serializationOptions: {
|
||||
serialization: "deep",
|
||||
maxDepth: 3,
|
||||
additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
|
||||
},
|
||||
});
|
||||
throwIfAborted(signal);
|
||||
// Backend ids are scoped to this capture's CDP target. OOPIF targets
|
||||
// use their own captureViewModel call and never share this lookup.
|
||||
const states = formStatesByBackendId(result);
|
||||
for (const nodes of frameNodeGroups) {
|
||||
applyFormStates(nodes, states);
|
||||
}
|
||||
} catch (error) {
|
||||
if (isAbortError(error)) throw error;
|
||||
// Best-effort enrichment. DOMSnapshot/AX data still carries the nodes.
|
||||
} finally {
|
||||
await cdp.send(tabId, "Runtime.releaseObjectGroup", { objectGroup }).catch(() => undefined);
|
||||
}
|
||||
}
|
||||
|
||||
interface RuntimeEvaluateReply {
|
||||
result?: {
|
||||
value?: unknown;
|
||||
deepSerializedValue?: DeepSerializedValue;
|
||||
};
|
||||
}
|
||||
|
||||
@@ -345,44 +34,6 @@ interface CdpDomNode {
|
||||
shadowRoots?: CdpDomNode[];
|
||||
}
|
||||
|
||||
interface ParseDocumentResult {
|
||||
nodes: CapturedNode[];
|
||||
excludedBackendNodeIds: Set<number>;
|
||||
}
|
||||
|
||||
interface FrameContext {
|
||||
frameId?: string;
|
||||
ownerFrameBackendNodeId: number | null;
|
||||
projection: GeometryProjection | null;
|
||||
scrollX: number;
|
||||
scrollY: number;
|
||||
}
|
||||
|
||||
function str(strings: string[], idx: number | undefined): string {
|
||||
if (idx === undefined || idx < 0) return "";
|
||||
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;
|
||||
for (let i = 0; i < sparse.index.length; i++) {
|
||||
const nodeIndex = sparse.index[i];
|
||||
const docIndex = sparse.value[i];
|
||||
if (nodeIndex !== undefined && docIndex !== undefined) out.set(nodeIndex, docIndex);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function collectBackendIdsFromDomNode(node: CdpDomNode | undefined, out: Set<number>): void {
|
||||
if (!node) return;
|
||||
if (typeof node.backendNodeId === "number") {
|
||||
@@ -791,358 +442,3 @@ export async function collectOverlayExcludedBackendIds(
|
||||
}
|
||||
return excluded;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse one DOMSnapshot document into CapturedNode[].
|
||||
*
|
||||
* @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;
|
||||
const dl = doc.layout;
|
||||
if (!dn?.backendNodeId) {
|
||||
return { nodes: [], excludedBackendNodeIds: new Set() };
|
||||
}
|
||||
|
||||
const count = dn.backendNodeId.length;
|
||||
const layoutByNode = new Map<number, number>();
|
||||
(dl?.nodeIndex ?? []).forEach((nodeIdx, layoutIdx) => layoutByNode.set(nodeIdx, layoutIdx));
|
||||
|
||||
// The agent's own overlay (WXT shadow host, marked with OVERLAY_HOST_MARKER_ATTR)
|
||||
// is injected into the page and its open shadow root
|
||||
// is inlined by DOMSnapshot as descendants of the host. Its fixed
|
||||
// full-viewport click-blocker would otherwise dominate occlusion detection
|
||||
// and hide the real page, so mark the host + its whole subtree excluded.
|
||||
// parentIndex always references an earlier node, so one forward pass suffices.
|
||||
const excluded = new Array<boolean>(count).fill(false);
|
||||
const excludedBackendNodeIds = new Set<number>();
|
||||
for (let n = 0; n < count; n++) {
|
||||
const parentIdx = dn.parentIndex?.[n] ?? -1;
|
||||
const inherited = parentIdx >= 0 && excluded[parentIdx];
|
||||
let isOverlayHost = inherited;
|
||||
if (!isOverlayHost) {
|
||||
const pairs = dn.attributes?.[n] ?? [];
|
||||
const attrNames: string[] = [];
|
||||
for (let a = 0; a + 1 < pairs.length; a += 2) {
|
||||
attrNames.push(str(strings, pairs[a]));
|
||||
}
|
||||
isOverlayHost = isOverlayHostNode(str(strings, dn.nodeName?.[n]), attrNames);
|
||||
}
|
||||
if (!isOverlayHost) continue;
|
||||
excluded[n] = true;
|
||||
const backendNodeId = dn.backendNodeId[n];
|
||||
if (backendNodeId !== undefined) {
|
||||
excludedBackendNodeIds.add(backendNodeId);
|
||||
}
|
||||
}
|
||||
|
||||
const posCol = STYLE_COL.position;
|
||||
const peCol = STYLE_COL["pointer-events"];
|
||||
const cursorCol = STYLE_COL.cursor;
|
||||
const visibilityCol = STYLE_COL.visibility;
|
||||
const opacityCol = STYLE_COL.opacity;
|
||||
const inputValues = sparseIndexMap(dn.inputValue);
|
||||
const textValues = sparseIndexMap(dn.textValue);
|
||||
const checkedInputs = new Set(dn.inputChecked?.index ?? []);
|
||||
const selectedOptions = new Set(dn.optionSelected?.index ?? []);
|
||||
|
||||
// Collect visible text from #text child nodes so element CapturedNodes
|
||||
// carry a textContent value usable as a button/link label fallback.
|
||||
// nodeValue is a parallel array: string index for text nodes, -1 otherwise.
|
||||
const nodeTextContent = new Map<number, string>();
|
||||
if (dn.nodeValue) {
|
||||
for (let n = 0; n < count; n++) {
|
||||
const nvIdx = dn.nodeValue[n] ?? -1;
|
||||
if (nvIdx < 0) continue;
|
||||
const text = str(strings, nvIdx).trim();
|
||||
if (!text) continue;
|
||||
const parentIdx = dn.parentIndex?.[n] ?? -1;
|
||||
if (parentIdx >= 0) {
|
||||
const existing = nodeTextContent.get(parentIdx);
|
||||
nodeTextContent.set(parentIdx, existing ? `${existing} ${text}` : text);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Build CapturedNodes.
|
||||
const nodes: CapturedNode[] = [];
|
||||
for (let n = 0; n < count; n++) {
|
||||
if (excluded[n]) continue;
|
||||
const backendNodeId = dn.backendNodeId[n];
|
||||
const parentIdx = dn.parentIndex?.[n] ?? -1;
|
||||
const parentBackendNodeId = parentIdx >= 0 ? (dn.backendNodeId[parentIdx] ?? null) : null;
|
||||
const tag = str(strings, dn.nodeName?.[n]).toLowerCase();
|
||||
|
||||
const attrs: Record<string, string> = {};
|
||||
const pairs = dn.attributes?.[n] ?? [];
|
||||
for (let a = 0; a + 1 < pairs.length; a += 2) {
|
||||
attrs[str(strings, pairs[a]).toLowerCase()] = str(strings, pairs[a + 1]);
|
||||
}
|
||||
|
||||
let rect: Rect | null = null;
|
||||
let localRect: Rect | null = null;
|
||||
let paintOrder = 0;
|
||||
let position = "static";
|
||||
let pointerEvents = "auto";
|
||||
let cursor = "auto";
|
||||
let rendered = false;
|
||||
const li = layoutByNode.get(n);
|
||||
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;
|
||||
rect = bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
|
||||
}
|
||||
paintOrder = dl?.paintOrders?.[li] ?? 0;
|
||||
const styleRow = dl?.styles?.[li] ?? [];
|
||||
position = str(strings, styleRow[posCol]) || "static";
|
||||
pointerEvents = str(strings, styleRow[peCol]) || "auto";
|
||||
cursor = str(strings, styleRow[cursorCol]) || "auto";
|
||||
const visibility = str(strings, styleRow[visibilityCol]) || "visible";
|
||||
const opacity = str(strings, styleRow[opacityCol]) || "1";
|
||||
rendered =
|
||||
localRect !== null &&
|
||||
visibility !== "hidden" &&
|
||||
visibility !== "collapse" &&
|
||||
(Number.parseFloat(opacity) || 0) > 0;
|
||||
}
|
||||
|
||||
// Skip non-element nodes (#text, #cdata-section, etc.) — they carry no
|
||||
// geometry and are never queried by callers.
|
||||
if (tag.startsWith("#")) continue;
|
||||
|
||||
const textContent = nodeTextContent.get(n);
|
||||
|
||||
const rawFormValueIndex = tag === "textarea" ? textValues.get(n) : inputValues.get(n);
|
||||
const rawFormValue =
|
||||
rawFormValueIndex !== undefined ? str(strings, rawFormValueIndex) : undefined;
|
||||
const sensitive = isSensitiveFormControl({ tag, attrs });
|
||||
const formDefaultValue = attrs.value ?? "";
|
||||
const formValue = sensitive ? undefined : rawFormValue;
|
||||
const formState = snapshotFormState(
|
||||
rawFormValue,
|
||||
formDefaultValue,
|
||||
Object.prototype.hasOwnProperty.call(attrs, "value"),
|
||||
sensitive,
|
||||
);
|
||||
if (sensitive) delete attrs.value;
|
||||
|
||||
nodes.push({
|
||||
backendNodeId,
|
||||
parentBackendNodeId,
|
||||
...(context.frameId ? { frameId: context.frameId } : {}),
|
||||
ownerFrameBackendNodeId: context.ownerFrameBackendNodeId,
|
||||
tag,
|
||||
attrs,
|
||||
rect,
|
||||
localRect,
|
||||
paintOrder,
|
||||
position,
|
||||
pointerEvents,
|
||||
cursor,
|
||||
rendered,
|
||||
textContent,
|
||||
...(formValue !== undefined ? { formValue } : {}),
|
||||
...(tag === "input" || tag === "textarea"
|
||||
? {
|
||||
formPlaceholder: attrs.placeholder ?? "",
|
||||
...(!sensitive ? { formDefaultValue } : {}),
|
||||
...(formState ? { formState } : {}),
|
||||
}
|
||||
: {}),
|
||||
...(checkedInputs.has(n) ? { formValue: "true", formState: "filled" } : {}),
|
||||
...(selectedOptions.has(n) ? { formValue: attrs.value ?? textContent ?? "" } : {}),
|
||||
});
|
||||
}
|
||||
return { nodes, excludedBackendNodeIds };
|
||||
}
|
||||
|
||||
interface ParseFrameDocumentsResult {
|
||||
iframeNodes: CapturedIframeNodes;
|
||||
frameOwnerBackendNodeIds: Map<string, number>;
|
||||
frameParentIds: Map<string, string>;
|
||||
excludedBackendNodeIds: Set<number>;
|
||||
}
|
||||
|
||||
function parseChildFrameDocuments(
|
||||
documents: SnapshotDocument[],
|
||||
strings: string[],
|
||||
dpr: number,
|
||||
parentDocIndex: number,
|
||||
parentNodes: CapturedNode[],
|
||||
parentContext: FrameContext,
|
||||
visited = new Set<number>(),
|
||||
): ParseFrameDocumentsResult {
|
||||
const iframeNodes: CapturedIframeNodes = new Map();
|
||||
const frameOwnerBackendNodeIds = new Map<string, number>();
|
||||
const frameParentIds = new Map<string, string>();
|
||||
const excludedBackendNodeIds = new Set<number>();
|
||||
const parentDoc = documents[parentDocIndex];
|
||||
const cdi = sparseIndexMap(parentDoc?.nodes?.contentDocumentIndex);
|
||||
if (cdi.size === 0) {
|
||||
return { iframeNodes, frameOwnerBackendNodeIds, frameParentIds, excludedBackendNodeIds };
|
||||
}
|
||||
|
||||
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 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;
|
||||
|
||||
const childContext: FrameContext = {
|
||||
frameId: snapshotFrameId(childDoc, strings),
|
||||
ownerFrameBackendNodeId: iframeBackendId,
|
||||
projection,
|
||||
scrollX: childDoc.scrollOffsetX ?? 0,
|
||||
scrollY: childDoc.scrollOffsetY ?? 0,
|
||||
};
|
||||
const nextVisited = new Set(visited);
|
||||
nextVisited.add(childDocIndex);
|
||||
const parsed = parseDocumentNodes(childDoc, strings, dpr, childContext);
|
||||
iframeNodes.set(iframeBackendId, parsed.nodes);
|
||||
if (childContext.frameId) {
|
||||
frameOwnerBackendNodeIds.set(childContext.frameId, iframeBackendId);
|
||||
if (parentContext.frameId) frameParentIds.set(childContext.frameId, parentContext.frameId);
|
||||
}
|
||||
for (const id of parsed.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
|
||||
|
||||
const nested = parseChildFrameDocuments(
|
||||
documents,
|
||||
strings,
|
||||
dpr,
|
||||
childDocIndex,
|
||||
parsed.nodes,
|
||||
childContext,
|
||||
nextVisited,
|
||||
);
|
||||
for (const [nestedFrameId, nestedNodes] of nested.iframeNodes) {
|
||||
iframeNodes.set(nestedFrameId, nestedNodes);
|
||||
}
|
||||
for (const [frameId, ownerBackendNodeId] of nested.frameOwnerBackendNodeIds) {
|
||||
frameOwnerBackendNodeIds.set(frameId, ownerBackendNodeId);
|
||||
}
|
||||
for (const [frameId, parentFrameId] of nested.frameParentIds) {
|
||||
frameParentIds.set(frameId, parentFrameId);
|
||||
}
|
||||
for (const id of nested.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
|
||||
}
|
||||
|
||||
return { iframeNodes, frameOwnerBackendNodeIds, frameParentIds, excludedBackendNodeIds };
|
||||
}
|
||||
|
||||
export async function captureViewModel(
|
||||
cdp: CdpRunner,
|
||||
tabId: number,
|
||||
options: CaptureViewModelOptions = {},
|
||||
): Promise<CapturedViewModel> {
|
||||
throwIfAborted(options.signal);
|
||||
let metrics: LayoutMetricsReply = {};
|
||||
try {
|
||||
metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
|
||||
} 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;
|
||||
|
||||
await cdp.send(tabId, "DOMSnapshot.enable", {});
|
||||
throwIfAborted(options.signal);
|
||||
const snap = await cdp.send<SnapshotReply>(tabId, "DOMSnapshot.captureSnapshot", {
|
||||
computedStyles: REQUESTED_STYLES,
|
||||
includePaintOrder: true,
|
||||
includeDOMRects: true,
|
||||
});
|
||||
throwIfAborted(options.signal);
|
||||
|
||||
const strings = snap.strings ?? [];
|
||||
const documents = snap.documents ?? [];
|
||||
const doc0 = documents[0];
|
||||
if (!doc0?.nodes?.backendNodeId) {
|
||||
return {
|
||||
nodes: [],
|
||||
viewport,
|
||||
iframeNodes: new Map(),
|
||||
excludedBackendNodeIds: new Set(),
|
||||
};
|
||||
}
|
||||
|
||||
const topContext: FrameContext = {
|
||||
frameId: snapshotFrameId(doc0, strings),
|
||||
ownerFrameBackendNodeId: null,
|
||||
projection: {
|
||||
sourceClips: [],
|
||||
edges: [],
|
||||
topViewport: viewport,
|
||||
},
|
||||
scrollX,
|
||||
scrollY,
|
||||
};
|
||||
const mainParsed = parseDocumentNodes(doc0, strings, dpr, topContext);
|
||||
const nodes = mainParsed.nodes;
|
||||
const excludedBackendNodeIds = new Set(mainParsed.excludedBackendNodeIds);
|
||||
|
||||
const frameParsed = parseChildFrameDocuments(documents, strings, dpr, 0, nodes, topContext);
|
||||
const iframeNodes = frameParsed.iframeNodes;
|
||||
for (const id of frameParsed.excludedBackendNodeIds) {
|
||||
excludedBackendNodeIds.add(id);
|
||||
}
|
||||
|
||||
await enrichFormControlStates(cdp, tabId, [nodes, ...iframeNodes.values()], options.signal);
|
||||
throwIfAborted(options.signal);
|
||||
|
||||
const frameNodes = new Map<string, CapturedNode[]>();
|
||||
if (topContext.frameId) frameNodes.set(topContext.frameId, nodes);
|
||||
for (const iframeFrameNodes of iframeNodes.values()) {
|
||||
const frameId = iframeFrameNodes.find((node) => node.frameId)?.frameId;
|
||||
if (frameId) frameNodes.set(frameId, iframeFrameNodes);
|
||||
}
|
||||
for (const [frameId, ownerBackendNodeId] of frameParsed.frameOwnerBackendNodeIds) {
|
||||
if (!frameNodes.has(frameId)) {
|
||||
frameNodes.set(frameId, iframeNodes.get(ownerBackendNodeId) ?? []);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
nodes,
|
||||
viewport,
|
||||
iframeNodes,
|
||||
frameNodes,
|
||||
frameOwnerBackendNodeIds: frameParsed.frameOwnerBackendNodeIds,
|
||||
frameParentIds: frameParsed.frameParentIds,
|
||||
...(topContext.frameId ? { rootFrameId: topContext.frameId } : {}),
|
||||
excludedBackendNodeIds,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,65 @@
|
||||
import type { CdpFrame } from "@/browser-driver/frame-graph";
|
||||
import type { CdpRunner } from "../shared";
|
||||
import { sendToCdpTarget } from "../shared";
|
||||
import { type DocumentIdentity, isCaptureAbort, throwCaptureAborted } from "./facts";
|
||||
|
||||
/** Fresh, frame-scoped identity read. An isolated world supplies the owning
|
||||
* document without querying each node or installing a page observer. */
|
||||
export async function readDocumentIdentity(
|
||||
cdp: CdpRunner,
|
||||
frame: CdpFrame,
|
||||
signal?: AbortSignal,
|
||||
): Promise<DocumentIdentity | undefined> {
|
||||
const attachmentId = cdp.getAttachmentId?.(frame.target.tabId);
|
||||
if (!attachmentId || !frame.loaderId) return undefined;
|
||||
let objectId: string | undefined;
|
||||
const send = <T>(method: string, params: object) => {
|
||||
throwCaptureAborted(signal);
|
||||
return sendToCdpTarget<T>(cdp, frame.target, method, params);
|
||||
};
|
||||
try {
|
||||
const world = await send<{ executionContextId: number }>("Page.createIsolatedWorld", {
|
||||
frameId: frame.frameId,
|
||||
worldName: "bsk-document-identity",
|
||||
});
|
||||
const element = await send<{ result?: { objectId?: string } }>("Runtime.evaluate", {
|
||||
expression: "document.documentElement",
|
||||
contextId: world.executionContextId,
|
||||
});
|
||||
objectId = element.result?.objectId;
|
||||
if (!objectId) return undefined;
|
||||
const reply = await send<{ node?: { backendNodeId?: number } }>("DOM.describeNode", {
|
||||
objectId,
|
||||
depth: 0,
|
||||
});
|
||||
const backendNodeId = reply.node?.backendNodeId;
|
||||
if (!backendNodeId || cdp.getAttachmentId?.(frame.target.tabId) !== attachmentId)
|
||||
return undefined;
|
||||
return {
|
||||
attachmentId,
|
||||
target: frame.target,
|
||||
frameId: frame.frameId,
|
||||
loaderId: frame.loaderId,
|
||||
documentElementBackendNodeId: backendNodeId,
|
||||
};
|
||||
} catch (error) {
|
||||
if (isCaptureAbort(error)) throw error;
|
||||
return undefined;
|
||||
} finally {
|
||||
if (objectId)
|
||||
await sendToCdpTarget(cdp, frame.target, "Runtime.releaseObject", { objectId }).catch(
|
||||
() => {},
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
export function sameDocument(a: DocumentIdentity, b: DocumentIdentity): boolean {
|
||||
return (
|
||||
a.attachmentId === b.attachmentId &&
|
||||
a.target.tabId === b.target.tabId &&
|
||||
a.target.sessionId === b.target.sessionId &&
|
||||
a.frameId === b.frameId &&
|
||||
a.loaderId === b.loaderId &&
|
||||
a.documentElementBackendNodeId === b.documentElementBackendNodeId
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,221 @@
|
||||
import type { Rect, Viewport } from "@browser-skill/vom";
|
||||
import type { CdpFrame, CdpTarget } from "@/browser-driver/frame-graph";
|
||||
import { isOverlayHostNode } from "@/lib/overlay-bridge";
|
||||
import type { FrameOwnedAxNode } from "./frame-document";
|
||||
|
||||
export interface CapturedNode {
|
||||
backendNodeId: number;
|
||||
parentBackendNodeId: number | null;
|
||||
frameId?: string;
|
||||
/** Owning iframe backend node id; `null` for the top-level document. */
|
||||
ownerFrameBackendNodeId?: number | null;
|
||||
tag: string;
|
||||
attrs: Record<string, string>;
|
||||
/** Top-level viewport-relative CSS px, clipped to the owning frame viewport. */
|
||||
rect: Rect | null;
|
||||
/** Frame-local viewport-relative CSS px before top-level projection. */
|
||||
localRect?: Rect | null;
|
||||
paintOrder: number;
|
||||
position: string;
|
||||
pointerEvents: string;
|
||||
/**
|
||||
* computed `cursor`. `cursor: pointer` is the strongest CDP-free signal
|
||||
* that a non-semantic element (a `<div>`/`<span>` with a click handler)
|
||||
* is actually an interactive control — used by the adapter to surface
|
||||
* custom buttons/checkboxes the AX tree drops as `generic`. Optional like
|
||||
* `textContent`: the live parser always sets it, hand-built fixtures may not.
|
||||
*/
|
||||
cursor?: string;
|
||||
/**
|
||||
* Whether the live DOM snapshot provides a painted, non-hidden box for this
|
||||
* node. Semantic resolution uses this only for DOM fallback nodes; AX-backed
|
||||
* nodes remain authoritative even when they are outside the viewport.
|
||||
*/
|
||||
rendered?: boolean;
|
||||
textContent?: string;
|
||||
formState?: "empty" | "filled" | "default";
|
||||
formValue?: string;
|
||||
formDefaultValue?: string;
|
||||
formPlaceholder?: string;
|
||||
}
|
||||
|
||||
export interface CapturedSurfaceProbe {
|
||||
triggerBackendNodeId: number;
|
||||
triggerPoint?: { x: number; y: number };
|
||||
triggerAction: "hover" | "focus" | string;
|
||||
subItems: string[];
|
||||
confidence?: "high" | "medium" | "low";
|
||||
}
|
||||
|
||||
/** Narrow input shared by the existing semantic scene/hover consumers. */
|
||||
export interface CapturedSceneInput {
|
||||
nodes: CapturedNode[];
|
||||
viewport: Viewport;
|
||||
rootFrameId?: string;
|
||||
excludedBackendNodeIds: ReadonlySet<number>;
|
||||
}
|
||||
|
||||
export interface DocumentIdentity {
|
||||
attachmentId: string;
|
||||
target: CdpTarget;
|
||||
frameId: string;
|
||||
loaderId: string;
|
||||
documentElementBackendNodeId: number;
|
||||
}
|
||||
|
||||
/** Snapshot client/offset rectangles retain their protocol units. In particular,
|
||||
* transformed bounds cannot be combined with unscaled client offsets. */
|
||||
export interface SnapshotLayout {
|
||||
readonly boundsSpace: "snapshot-document-css";
|
||||
readonly clientSpace: "unscaled-client-offset-css";
|
||||
bounds?: number[];
|
||||
clientRect?: number[];
|
||||
offsetRect?: number[];
|
||||
scrollRect?: number[];
|
||||
styles: Readonly<Record<string, string>>;
|
||||
}
|
||||
|
||||
export interface DecodedNode extends Omit<CapturedNode, "rect" | "localRect" | "rendered"> {
|
||||
nodeType?: number;
|
||||
parentMissing?: boolean;
|
||||
layout?: SnapshotLayout;
|
||||
}
|
||||
|
||||
export interface AncestorState {
|
||||
complete: boolean;
|
||||
overlay: boolean;
|
||||
}
|
||||
|
||||
export interface NodeFacts extends CapturedNode {
|
||||
nodeType?: number;
|
||||
layout?: SnapshotLayout;
|
||||
}
|
||||
|
||||
export interface DocumentIndex<T extends DecodedNode = NodeFacts> {
|
||||
readonly nodes: ReadonlyMap<number, T>;
|
||||
readonly children: ReadonlyMap<number, readonly number[]>;
|
||||
readonly ancestry: ReadonlyMap<number, AncestorState>;
|
||||
readonly excludedBackendNodeIds: ReadonlySet<number>;
|
||||
}
|
||||
|
||||
export interface DecodedDocument {
|
||||
nodes: DecodedNode[];
|
||||
}
|
||||
|
||||
export interface CaptureIssue {
|
||||
target: CdpTarget;
|
||||
frameId?: string;
|
||||
stage: "dom" | "ax" | "identity" | "ownership" | "geometry" | "forms";
|
||||
reason:
|
||||
| "capture-unavailable"
|
||||
| "document-changed"
|
||||
| "identity-unverified"
|
||||
| "frame-ownership-unresolved"
|
||||
| "geometry-unavailable";
|
||||
}
|
||||
|
||||
export interface DocumentFacts<T extends FrameOwnedAxNode> {
|
||||
readonly frame: CdpFrame;
|
||||
readonly identity?: DocumentIdentity;
|
||||
readonly index: DocumentIndex;
|
||||
readonly domNodes: CapturedNode[];
|
||||
readonly axNodes: T[];
|
||||
}
|
||||
|
||||
export interface ObservationFacts<T extends FrameOwnedAxNode> {
|
||||
readonly rootFrameId: string;
|
||||
readonly viewport: Viewport;
|
||||
readonly documents: readonly DocumentFacts<T>[];
|
||||
readonly issues: readonly CaptureIssue[];
|
||||
readonly startedAt: number;
|
||||
readonly finishedAt: number;
|
||||
}
|
||||
|
||||
export function throwCaptureAborted(signal?: AbortSignal): void {
|
||||
if (signal?.aborted) throw new DOMException("observation aborted", "AbortError");
|
||||
}
|
||||
|
||||
export function isCaptureAbort(error: unknown): boolean {
|
||||
return error instanceof Error && error.name === "AbortError";
|
||||
}
|
||||
|
||||
/** Called only at bounded block boundaries, not once per node. */
|
||||
export async function captureCheckpoint(signal?: AbortSignal): Promise<void> {
|
||||
throwCaptureAborted(signal);
|
||||
await new Promise<void>((resolve) => {
|
||||
const channel = new MessageChannel();
|
||||
channel.port1.onmessage = () => {
|
||||
channel.port1.close();
|
||||
channel.port2.close();
|
||||
resolve();
|
||||
};
|
||||
channel.port2.postMessage(null);
|
||||
});
|
||||
throwCaptureAborted(signal);
|
||||
}
|
||||
|
||||
/** All snapshot nodes participate, including document and shadow roots. This
|
||||
* preserves ancestry evidence even when the semantic adapter omits those nodes. */
|
||||
export async function buildDocumentIndex<T extends DecodedNode>(
|
||||
input: readonly T[],
|
||||
signal?: AbortSignal,
|
||||
): Promise<DocumentIndex<T>> {
|
||||
const nodes = new Map<number, T>();
|
||||
const children = new Map<number, number[]>();
|
||||
const ancestry = new Map<number, AncestorState>();
|
||||
const excludedBackendNodeIds = new Set<number>();
|
||||
for (let i = 0; i < input.length; i++) {
|
||||
if (i % 256 === 0) await captureCheckpoint(signal);
|
||||
const node = input[i];
|
||||
nodes.set(node.backendNodeId, node);
|
||||
if (node.parentBackendNodeId !== null) {
|
||||
const siblings = children.get(node.parentBackendNodeId);
|
||||
if (siblings) siblings.push(node.backendNodeId);
|
||||
else children.set(node.parentBackendNodeId, [node.backendNodeId]);
|
||||
}
|
||||
}
|
||||
let work = 0;
|
||||
for (const node of input) {
|
||||
if (work++ % 256 === 0) await captureCheckpoint(signal);
|
||||
if (ancestry.has(node.backendNodeId)) continue;
|
||||
const path: DecodedNode[] = [];
|
||||
const visiting = new Set<number>();
|
||||
let current: DecodedNode | undefined = node;
|
||||
let state: AncestorState = { complete: true, overlay: false };
|
||||
while (current && !ancestry.has(current.backendNodeId)) {
|
||||
if (work++ % 256 === 0) await captureCheckpoint(signal);
|
||||
if (visiting.has(current.backendNodeId)) {
|
||||
// No member of a malformed cycle supplies complete ancestry evidence.
|
||||
state = {
|
||||
complete: false,
|
||||
overlay: path
|
||||
.slice(path.findIndex((item) => item.backendNodeId === current!.backendNodeId))
|
||||
.some((item) => isOverlayHostNode(item.tag, Object.keys(item.attrs))),
|
||||
};
|
||||
break;
|
||||
}
|
||||
visiting.add(current.backendNodeId);
|
||||
path.push(current);
|
||||
if (current.parentMissing) state = { complete: false, overlay: false };
|
||||
if (current.parentBackendNodeId === null) {
|
||||
current = undefined;
|
||||
break;
|
||||
}
|
||||
current = nodes.get(current.parentBackendNodeId);
|
||||
if (!current) state = { complete: false, overlay: false };
|
||||
}
|
||||
if (current && ancestry.has(current.backendNodeId))
|
||||
state = ancestry.get(current.backendNodeId)!;
|
||||
for (let i = path.length - 1; i >= 0; i--) {
|
||||
if (work++ % 256 === 0) await captureCheckpoint(signal);
|
||||
const item = path[i];
|
||||
state = {
|
||||
complete: state.complete,
|
||||
overlay: state.overlay || isOverlayHostNode(item.tag, Object.keys(item.attrs)),
|
||||
};
|
||||
ancestry.set(item.backendNodeId, state);
|
||||
if (state.overlay) excludedBackendNodeIds.add(item.backendNodeId);
|
||||
}
|
||||
}
|
||||
return { nodes, children, ancestry, excludedBackendNodeIds };
|
||||
}
|
||||
@@ -0,0 +1,154 @@
|
||||
import type { CdpRunner } from "../shared";
|
||||
import type { CapturedNode } from "./facts";
|
||||
import { isCaptureAbort as isAbortError, throwCaptureAborted as throwIfAborted } from "./facts";
|
||||
|
||||
interface RuntimeEvaluateReply {
|
||||
result?: { deepSerializedValue?: DeepSerializedValue };
|
||||
}
|
||||
const MAX_FORM_ENRICH_CONTROLS = 250;
|
||||
|
||||
interface CapturedFormState {
|
||||
value?: string;
|
||||
defaultValue?: string;
|
||||
placeholder?: string;
|
||||
state?: "empty" | "filled" | "default";
|
||||
sensitive?: boolean;
|
||||
}
|
||||
|
||||
interface DeepSerializedValue {
|
||||
type: string;
|
||||
value?: unknown;
|
||||
}
|
||||
|
||||
function formStateBatchExpression(maxControls: number): string {
|
||||
return `(() => {
|
||||
const maxControls = ${JSON.stringify(maxControls)};
|
||||
let remaining = maxControls;
|
||||
const controlSelector = "input,textarea,select";
|
||||
const controlState = (el) => {
|
||||
const tag = el.tagName.toLowerCase();
|
||||
const type = tag === "input" ? String(el.type || "text").toLowerCase() : tag;
|
||||
const sensitive = type === "password" || type === "credit-card";
|
||||
const rawValue = typeof el.value === "string" ? el.value : "";
|
||||
const defaultValue = typeof el.defaultValue === "string" ? el.defaultValue : "";
|
||||
const placeholder = typeof el.placeholder === "string" ? el.placeholder : "";
|
||||
const state = rawValue === "" ? "empty" : rawValue === defaultValue ? "default" : "filled";
|
||||
return {
|
||||
state,
|
||||
sensitive,
|
||||
placeholder,
|
||||
...(sensitive ? {} : { value: rawValue, defaultValue }),
|
||||
};
|
||||
};
|
||||
const controls = [];
|
||||
const collect = (doc) => {
|
||||
for (const el of Array.from(doc.querySelectorAll(controlSelector))) {
|
||||
if (remaining <= 0) break;
|
||||
// Deep serialization supplies the node's backend id. Keep the
|
||||
// state as JSON so decoding needs no general-purpose V8 deserializer.
|
||||
controls.push([el, JSON.stringify(controlState(el))]);
|
||||
remaining -= 1;
|
||||
}
|
||||
for (const frame of Array.from(doc.querySelectorAll("iframe"))) {
|
||||
if (remaining <= 0) break;
|
||||
let childDoc = null;
|
||||
try { childDoc = frame.contentDocument; } catch { childDoc = null; }
|
||||
if (childDoc) collect(childDoc);
|
||||
}
|
||||
};
|
||||
collect(document);
|
||||
return controls;
|
||||
})()`;
|
||||
}
|
||||
|
||||
function formStatesByBackendId(result: RuntimeEvaluateReply): Map<number, CapturedFormState> {
|
||||
const states = new Map<number, CapturedFormState>();
|
||||
const serialized = result.result?.deepSerializedValue;
|
||||
if (serialized?.type !== "array" || !Array.isArray(serialized.value)) return states;
|
||||
for (const entry of serialized.value as DeepSerializedValue[]) {
|
||||
if (entry?.type !== "array" || !Array.isArray(entry.value)) continue;
|
||||
const [element, json] = entry.value as DeepSerializedValue[];
|
||||
if (element?.type !== "node" || json?.type !== "string" || typeof json.value !== "string") {
|
||||
continue;
|
||||
}
|
||||
const backendNodeId = (element.value as { backendNodeId?: number } | undefined)?.backendNodeId;
|
||||
if (typeof backendNodeId !== "number" || !Number.isSafeInteger(backendNodeId)) continue;
|
||||
try {
|
||||
const state = JSON.parse(json.value) as CapturedFormState | null;
|
||||
if (
|
||||
!state ||
|
||||
!["empty", "filled", "default"].includes(state.state ?? "") ||
|
||||
typeof state.sensitive !== "boolean" ||
|
||||
typeof state.placeholder !== "string" ||
|
||||
(!state.sensitive &&
|
||||
(typeof state.value !== "string" || typeof state.defaultValue !== "string"))
|
||||
) {
|
||||
continue;
|
||||
}
|
||||
states.set(backendNodeId, state);
|
||||
} catch {
|
||||
// A malformed entry must not overwrite the snapshot's own state.
|
||||
}
|
||||
}
|
||||
return states;
|
||||
}
|
||||
|
||||
function applyFormStates(nodes: CapturedNode[], states: Map<number, CapturedFormState>): void {
|
||||
for (const node of nodes) {
|
||||
if (!["input", "textarea", "select"].includes(node.tag)) continue;
|
||||
const state = states.get(node.backendNodeId);
|
||||
if (!state) continue;
|
||||
node.formState = state.state;
|
||||
node.formPlaceholder = state.placeholder ?? "";
|
||||
if (
|
||||
state.sensitive ||
|
||||
(node.tag === "input" && (node.attrs.type ?? "").toLowerCase() === "password")
|
||||
) {
|
||||
delete node.formValue;
|
||||
delete node.formDefaultValue;
|
||||
delete node.attrs.value;
|
||||
} else {
|
||||
node.formDefaultValue = state.defaultValue ?? "";
|
||||
if (state.value !== undefined) node.formValue = state.value;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export async function enrichFormControlStates(
|
||||
cdp: CdpRunner,
|
||||
tabId: number,
|
||||
frameNodeGroups: CapturedNode[][],
|
||||
signal?: AbortSignal,
|
||||
): Promise<boolean> {
|
||||
const hasControls = frameNodeGroups.some((nodes) =>
|
||||
nodes.some((node) => ["input", "textarea", "select"].includes(node.tag)),
|
||||
);
|
||||
if (!hasControls) return true;
|
||||
const objectGroup = `bsk-vom-forms-${crypto.randomUUID()}`;
|
||||
try {
|
||||
throwIfAborted(signal);
|
||||
const result = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
|
||||
expression: formStateBatchExpression(MAX_FORM_ENRICH_CONTROLS),
|
||||
objectGroup,
|
||||
serializationOptions: {
|
||||
serialization: "deep",
|
||||
maxDepth: 3,
|
||||
additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
|
||||
},
|
||||
});
|
||||
throwIfAborted(signal);
|
||||
// Backend ids are scoped to this capture's CDP target. OOPIF targets
|
||||
// have separate enrichment calls and never share this lookup.
|
||||
const states = formStatesByBackendId(result);
|
||||
for (const nodes of frameNodeGroups) {
|
||||
applyFormStates(nodes, states);
|
||||
}
|
||||
return true;
|
||||
} catch (error) {
|
||||
if (isAbortError(error)) throw error;
|
||||
// Best-effort enrichment. DOMSnapshot/AX data still carries the nodes.
|
||||
return false;
|
||||
} finally {
|
||||
await cdp.send(tabId, "Runtime.releaseObjectGroup", { objectGroup }).catch(() => undefined);
|
||||
}
|
||||
}
|
||||
@@ -1,181 +0,0 @@
|
||||
import type { CdpFrame, CdpFrameGraph } from "@/browser-driver/frame-graph";
|
||||
import { resolveFrameProjection } from "../frame-geometry";
|
||||
import { type GeometryProjection, projectRectToViewport } from "../geometry";
|
||||
import { type CdpRunner, cdpRunnerForTarget, sendToCdpTarget } from "../shared";
|
||||
import { type CapturedNode, type CapturedViewModel, captureViewModel } from "./capture";
|
||||
import {
|
||||
buildFrameDocuments,
|
||||
type FrameAxBatch,
|
||||
type FrameDocument,
|
||||
type FrameOwnedAxNode,
|
||||
} from "./frame-document";
|
||||
|
||||
export type FrameAxNode = FrameOwnedAxNode;
|
||||
export type CapturedFrameDocument<T extends FrameAxNode> = FrameDocument<T>;
|
||||
|
||||
function throwIfAborted(signal?: AbortSignal): void {
|
||||
if (signal?.aborted) throw new DOMException("observation aborted", "AbortError");
|
||||
}
|
||||
|
||||
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,
|
||||
): CapturedNode[] {
|
||||
return nodes.map((node) => ({
|
||||
...node,
|
||||
rect: projection
|
||||
? (() => {
|
||||
const bounds = projectRectToViewport(node.rect, projection);
|
||||
return bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
|
||||
})()
|
||||
: null,
|
||||
}));
|
||||
}
|
||||
|
||||
async function captureMissingFrameDocuments(
|
||||
cdp: CdpRunner,
|
||||
tabId: number,
|
||||
graph: CdpFrameGraph,
|
||||
captured: CapturedViewModel,
|
||||
signal?: AbortSignal,
|
||||
): Promise<void> {
|
||||
if (!captured.frameNodes) captured.frameNodes = new Map();
|
||||
if (!captured.frameOwnerBackendNodeIds) captured.frameOwnerBackendNodeIds = new Map();
|
||||
if (!captured.frameParentIds) captured.frameParentIds = new Map();
|
||||
|
||||
for (const frame of graph.frames) {
|
||||
if (!frame.target.sessionId || captured.frameNodes.has(frame.frameId)) continue;
|
||||
try {
|
||||
const child = await captureViewModel(cdpRunnerForTarget(cdp, frame.target), tabId, {
|
||||
signal,
|
||||
});
|
||||
let projection: GeometryProjection | null = null;
|
||||
try {
|
||||
projection = await resolveFrameProjection(cdp, graph, frame.frameId);
|
||||
} catch (err) {
|
||||
if (isAbortError(err)) throw err;
|
||||
console.debug("[bsk observation] child frame geometry projection failed", {
|
||||
frameId: frame.frameId,
|
||||
err,
|
||||
});
|
||||
}
|
||||
const rootFrameId = child.rootFrameId ?? frame.frameId;
|
||||
const childFrames = child.frameNodes ?? new Map<string, CapturedNode[]>();
|
||||
if (!childFrames.has(rootFrameId)) childFrames.set(rootFrameId, child.nodes);
|
||||
if (rootFrameId !== frame.frameId && !childFrames.has(frame.frameId)) {
|
||||
childFrames.set(
|
||||
frame.frameId,
|
||||
child.nodes.map((node) => ({ ...node, frameId: frame.frameId })),
|
||||
);
|
||||
}
|
||||
for (const [childFrameId, nodes] of childFrames) {
|
||||
captured.frameNodes.set(childFrameId, transformFrameNodes(nodes, projection));
|
||||
}
|
||||
if (frame.ownerBackendNodeId !== undefined) {
|
||||
captured.iframeNodes.set(
|
||||
frame.ownerBackendNodeId,
|
||||
captured.frameNodes.get(frame.frameId) ?? [],
|
||||
);
|
||||
captured.frameOwnerBackendNodeIds.set(frame.frameId, frame.ownerBackendNodeId);
|
||||
}
|
||||
if (frame.parentFrameId) captured.frameParentIds.set(frame.frameId, frame.parentFrameId);
|
||||
for (const [childFrameId, ownerBackendNodeId] of child.frameOwnerBackendNodeIds ?? []) {
|
||||
captured.frameOwnerBackendNodeIds.set(childFrameId, ownerBackendNodeId);
|
||||
}
|
||||
for (const [childFrameId, parentFrameId] of child.frameParentIds ?? []) {
|
||||
captured.frameParentIds.set(childFrameId, parentFrameId);
|
||||
}
|
||||
} catch (err) {
|
||||
if (isAbortError(err)) throw err;
|
||||
console.debug("[bsk observation] child frame DOM capture failed", {
|
||||
frameId: frame.frameId,
|
||||
err,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async function captureAxTrees<T extends FrameAxNode>(
|
||||
cdp: CdpRunner,
|
||||
tabId: number,
|
||||
discoveredFrames: CdpFrame[],
|
||||
captured: CapturedViewModel,
|
||||
signal?: AbortSignal,
|
||||
): Promise<FrameAxBatch<T>[]> {
|
||||
let frames = [...discoveredFrames];
|
||||
const capturedFrameIds = [...(captured.frameNodes?.keys() ?? [])];
|
||||
if (frames.length === 0) {
|
||||
const rootFrameId = captured.rootFrameId ?? capturedFrameIds[0] ?? "root";
|
||||
frames = [{ frameId: rootFrameId, target: { tabId } }];
|
||||
}
|
||||
for (const frameId of capturedFrameIds) {
|
||||
if (!frames.some((frame) => frame.frameId === frameId)) {
|
||||
frames.push({ frameId, target: { tabId } });
|
||||
}
|
||||
}
|
||||
|
||||
let firstFailure: unknown;
|
||||
const trees = await Promise.all(
|
||||
frames.map(async (frame): Promise<FrameAxBatch<T>> => {
|
||||
try {
|
||||
throwIfAborted(signal);
|
||||
await sendToCdpTarget(cdp, frame.target, "Accessibility.enable", {});
|
||||
const result = await sendToCdpTarget<{ nodes?: T[] }>(
|
||||
cdp,
|
||||
frame.target,
|
||||
"Accessibility.getFullAXTree",
|
||||
frame.frameId === "root" ? {} : { frameId: frame.frameId },
|
||||
);
|
||||
throwIfAborted(signal);
|
||||
return {
|
||||
frame,
|
||||
nodes: result.nodes ?? [],
|
||||
};
|
||||
} catch (err) {
|
||||
if (isAbortError(err)) throw err;
|
||||
firstFailure ??= err;
|
||||
console.debug("[bsk observation] frame AX capture failed", {
|
||||
frameId: frame.frameId,
|
||||
err,
|
||||
});
|
||||
return { frame, nodes: [] };
|
||||
}
|
||||
}),
|
||||
);
|
||||
const capturedNodeCount = [...captured.iframeNodes.values()].reduce(
|
||||
(count, nodes) => count + nodes.length,
|
||||
captured.nodes.length,
|
||||
);
|
||||
if (firstFailure && capturedNodeCount === 0 && trees.every((tree) => tree.nodes.length === 0)) {
|
||||
throw firstFailure;
|
||||
}
|
||||
return trees;
|
||||
}
|
||||
|
||||
export async function captureFrameData<T extends FrameAxNode>(
|
||||
cdp: CdpRunner,
|
||||
tabId: number,
|
||||
captured: CapturedViewModel,
|
||||
signal?: AbortSignal,
|
||||
): Promise<CapturedFrameDocument<T>[]> {
|
||||
const graph = await discoverFrameGraph(cdp, tabId);
|
||||
const frames = graph?.frames ?? [];
|
||||
if (graph) await captureMissingFrameDocuments(cdp, tabId, graph, captured, signal);
|
||||
throwIfAborted(signal);
|
||||
const batches = await captureAxTrees<T>(cdp, tabId, frames, captured, signal);
|
||||
return buildFrameDocuments(graph, batches, captured);
|
||||
}
|
||||
@@ -4,7 +4,8 @@ import {
|
||||
type CdpTarget,
|
||||
cdpTargetKey,
|
||||
} from "@/browser-driver/frame-graph";
|
||||
import type { CapturedNode, CapturedViewModel } from "./capture";
|
||||
import type { CapturedNode } from "./facts";
|
||||
import { captureCheckpoint } from "./facts";
|
||||
|
||||
export interface FrameOwnedAxNode {
|
||||
nodeId: string;
|
||||
@@ -23,6 +24,16 @@ export interface FrameDocument<T extends FrameOwnedAxNode> extends CdpFrame {
|
||||
contextScopeId: string;
|
||||
axNodes: T[];
|
||||
domNodes: CapturedNode[];
|
||||
excludedBackendNodeIds?: ReadonlySet<number>;
|
||||
}
|
||||
|
||||
/** Explicit snapshot document data used to join DOM and AX ownership. */
|
||||
export interface FrameDomInput {
|
||||
nodes: CapturedNode[];
|
||||
rootFrameId?: string;
|
||||
frameNodes?: ReadonlyMap<string, CapturedNode[]>;
|
||||
frameOwnerBackendNodeIds?: ReadonlyMap<string, number>;
|
||||
frameParentIds?: ReadonlyMap<string, string>;
|
||||
}
|
||||
|
||||
interface Ownership {
|
||||
@@ -47,17 +58,13 @@ function targetBackendKey(target: CdpTarget, backendNodeId: number): string {
|
||||
function frameList<T extends FrameOwnedAxNode>(
|
||||
graph: CdpFrameGraph | null,
|
||||
batches: FrameAxBatch<T>[],
|
||||
captured: CapturedViewModel,
|
||||
captured: FrameDomInput,
|
||||
): CdpFrame[] {
|
||||
const frames = new Map<string, CdpFrame>();
|
||||
for (const frame of graph?.frames ?? []) frames.set(frame.frameId, frame);
|
||||
for (const batch of batches) {
|
||||
if (!frames.has(batch.frame.frameId)) frames.set(batch.frame.frameId, batch.frame);
|
||||
}
|
||||
for (const frameId of captured.frameNodes?.keys() ?? []) {
|
||||
if (!frames.has(frameId))
|
||||
frames.set(frameId, { frameId, target: { tabId: batches[0]?.frame.target.tabId ?? 0 } });
|
||||
}
|
||||
return [...frames.values()].map((frame) => {
|
||||
const ownerBackendNodeId =
|
||||
frame.ownerBackendNodeId ?? captured.frameOwnerBackendNodeIds?.get(frame.frameId);
|
||||
@@ -70,11 +77,14 @@ function frameList<T extends FrameOwnedAxNode>(
|
||||
});
|
||||
}
|
||||
|
||||
export function buildFrameDocuments<T extends FrameOwnedAxNode>(
|
||||
export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
|
||||
graph: CdpFrameGraph | null,
|
||||
batches: FrameAxBatch<T>[],
|
||||
captured: CapturedViewModel,
|
||||
): FrameDocument<T>[] {
|
||||
captured: FrameDomInput,
|
||||
signal?: AbortSignal,
|
||||
unresolved?: (frame: CdpFrame) => void,
|
||||
): Promise<FrameDocument<T>[]> {
|
||||
let work = 0;
|
||||
const frames = frameList(graph, batches, captured);
|
||||
const frameById = new Map(frames.map((frame) => [frame.frameId, frame]));
|
||||
const rootFrameId = graph?.rootFrameId ?? captured.rootFrameId ?? frames[0]?.frameId;
|
||||
@@ -83,54 +93,74 @@ export function buildFrameDocuments<T extends FrameOwnedAxNode>(
|
||||
const backendOwner = new Map<string, string>();
|
||||
for (const frame of frames) {
|
||||
for (const node of domNodesForFrame(frame.frameId)) {
|
||||
if (work++ % 256 === 0) await captureCheckpoint(signal);
|
||||
backendOwner.set(targetBackendKey(frame.target, node.backendNodeId), frame.frameId);
|
||||
}
|
||||
}
|
||||
|
||||
const candidates = new Map<string, OwnedCandidate<T>>();
|
||||
for (const batch of batches) {
|
||||
const nodeById = new Map(batch.nodes.map((node) => [node.nodeId, node]));
|
||||
const nodeById = new Map<string, T>();
|
||||
for (const node of batch.nodes) {
|
||||
if (work++ % 256 === 0) await captureCheckpoint(signal);
|
||||
nodeById.set(node.nodeId, node);
|
||||
}
|
||||
let reported = false;
|
||||
const ownershipByNodeId = new Map<string, Ownership>();
|
||||
const resolving = new Set<string>();
|
||||
const resolveOwnership = (node: T): Ownership => {
|
||||
const cached = ownershipByNodeId.get(node.nodeId);
|
||||
if (cached) return cached;
|
||||
if (node.frameId && frameById.has(node.frameId)) {
|
||||
const ownership = { frameId: node.frameId, strength: 4 };
|
||||
ownershipByNodeId.set(node.nodeId, ownership);
|
||||
return ownership;
|
||||
}
|
||||
if (typeof node.backendDOMNodeId === "number") {
|
||||
const frameId = backendOwner.get(
|
||||
targetBackendKey(batch.frame.target, node.backendDOMNodeId),
|
||||
);
|
||||
const resolveOwnership = async (node: T): Promise<Ownership> => {
|
||||
const path: T[] = [];
|
||||
const visiting = new Set<string>();
|
||||
let current: T | undefined = node;
|
||||
let ownership: Ownership = { frameId: batch.frame.frameId, strength: 1 };
|
||||
while (current) {
|
||||
if (work++ % 256 === 0) await captureCheckpoint(signal);
|
||||
const cached = ownershipByNodeId.get(current.nodeId);
|
||||
if (cached) {
|
||||
ownership = cached;
|
||||
break;
|
||||
}
|
||||
if (visiting.has(current.nodeId)) break;
|
||||
visiting.add(current.nodeId);
|
||||
if (current.frameId) {
|
||||
const frame = frameById.get(current.frameId);
|
||||
// An explicit contradiction must not fall through to a guessed owner.
|
||||
if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(batch.frame.target)) {
|
||||
if (!reported) {
|
||||
unresolved?.(batch.frame);
|
||||
reported = true;
|
||||
}
|
||||
ownership = { frameId: "", strength: 0 };
|
||||
break;
|
||||
}
|
||||
ownership = { frameId: frame.frameId, strength: 4 };
|
||||
ownershipByNodeId.set(current.nodeId, ownership);
|
||||
break;
|
||||
}
|
||||
const frameId =
|
||||
typeof current.backendDOMNodeId === "number"
|
||||
? backendOwner.get(targetBackendKey(batch.frame.target, current.backendDOMNodeId))
|
||||
: undefined;
|
||||
if (frameId) {
|
||||
const ownership = { frameId, strength: 3 };
|
||||
ownershipByNodeId.set(node.nodeId, ownership);
|
||||
return ownership;
|
||||
ownership = { frameId, strength: 3 };
|
||||
ownershipByNodeId.set(current.nodeId, ownership);
|
||||
break;
|
||||
}
|
||||
path.push(current);
|
||||
current = current.parentId ? nodeById.get(current.parentId) : undefined;
|
||||
}
|
||||
if (node.parentId && !resolving.has(node.nodeId)) {
|
||||
const parent = nodeById.get(node.parentId);
|
||||
if (parent) {
|
||||
resolving.add(node.nodeId);
|
||||
const inherited = resolveOwnership(parent);
|
||||
resolving.delete(node.nodeId);
|
||||
const ownership = {
|
||||
frameId: inherited.frameId,
|
||||
strength: Math.min(2, inherited.strength),
|
||||
};
|
||||
ownershipByNodeId.set(node.nodeId, ownership);
|
||||
return ownership;
|
||||
}
|
||||
for (let i = path.length - 1; i >= 0; i--) {
|
||||
if (work++ % 256 === 0) await captureCheckpoint(signal);
|
||||
ownership = { frameId: ownership.frameId, strength: Math.min(2, ownership.strength) };
|
||||
ownershipByNodeId.set(path[i].nodeId, ownership);
|
||||
}
|
||||
const ownership = { frameId: batch.frame.frameId, strength: 1 };
|
||||
ownershipByNodeId.set(node.nodeId, ownership);
|
||||
if (!ownershipByNodeId.has(node.nodeId)) ownershipByNodeId.set(node.nodeId, ownership);
|
||||
return ownership;
|
||||
};
|
||||
|
||||
for (const node of batch.nodes) {
|
||||
const ownership = resolveOwnership(node);
|
||||
if (work++ % 256 === 0) await captureCheckpoint(signal);
|
||||
const ownership = await resolveOwnership(node);
|
||||
if (!ownership.frameId) continue;
|
||||
const key = targetNodeKey(batch.frame.target, node.nodeId);
|
||||
const existing = candidates.get(key);
|
||||
if (!existing || ownership.strength > existing.ownership.strength) {
|
||||
@@ -144,6 +174,7 @@ export function buildFrameDocuments<T extends FrameOwnedAxNode>(
|
||||
);
|
||||
const axNodesByFrame = new Map<string, T[]>();
|
||||
for (const candidate of candidates.values()) {
|
||||
if (work++ % 256 === 0) await captureCheckpoint(signal);
|
||||
const { node, target, ownership } = candidate;
|
||||
const parentFrameId = node.parentId
|
||||
? ownershipByTargetNode.get(targetNodeKey(target, node.parentId))
|
||||
|
||||
@@ -0,0 +1,184 @@
|
||||
import type { Viewport } from "@browser-skill/vom";
|
||||
import type { CdpFrame, CdpTarget } from "@/browser-driver/frame-graph";
|
||||
import { type GeometryProjection, projectRectToViewport } from "../geometry";
|
||||
import {
|
||||
projectSnapshotRect,
|
||||
type SnapshotProjection,
|
||||
snapshotViewportRect,
|
||||
} from "../geometry/coordinate-types";
|
||||
import { cssViewport, GeometryContext } from "../geometry/frame-context";
|
||||
import type { CapturedNode } from "./facts";
|
||||
import {
|
||||
buildDocumentIndex,
|
||||
type CaptureIssue,
|
||||
captureCheckpoint,
|
||||
type DocumentIndex,
|
||||
isCaptureAbort,
|
||||
type NodeFacts,
|
||||
} from "./facts";
|
||||
import {
|
||||
decodeDocument,
|
||||
type SnapshotDocument,
|
||||
type SnapshotReply,
|
||||
snapshotFrameId,
|
||||
} from "./snapshot";
|
||||
|
||||
export interface NormalizedDocument {
|
||||
index: DocumentIndex;
|
||||
frame: CdpFrame;
|
||||
domNodes: CapturedNode[];
|
||||
documentElementBackendNodeId?: number;
|
||||
}
|
||||
|
||||
/** One target's snapshot. Source ownership is checked before interpreting any
|
||||
* coordinates. Snapshot and live quad coordinates are deliberately not conflated. */
|
||||
export async function normalizeSnapshot(
|
||||
snapshot: SnapshotReply,
|
||||
target: CdpTarget,
|
||||
frames: readonly CdpFrame[],
|
||||
geometry: GeometryContext,
|
||||
issues: CaptureIssue[],
|
||||
signal?: AbortSignal,
|
||||
): Promise<NormalizedDocument[]> {
|
||||
const strings = snapshot.strings ?? [];
|
||||
const raw = snapshot.documents ?? [];
|
||||
const frameById = new Map(frames.map((frame) => [frame.frameId, frame]));
|
||||
const sources = new Map<string, SnapshotDocument>();
|
||||
for (const doc of raw) {
|
||||
const id = snapshotFrameId(doc, strings);
|
||||
if (!id || !frameById.has(id) || sources.has(id)) {
|
||||
issues.push({
|
||||
target,
|
||||
frameId: id,
|
||||
stage: "ownership",
|
||||
reason: "frame-ownership-unresolved",
|
||||
});
|
||||
continue;
|
||||
}
|
||||
sources.set(id, doc);
|
||||
}
|
||||
let viewport: Viewport = { width: 0, height: 0 };
|
||||
let scrollX = 0,
|
||||
scrollY = 0;
|
||||
try {
|
||||
const measured = cssViewport(await geometry.layoutMetrics(target));
|
||||
viewport = { width: measured.width, height: measured.height };
|
||||
scrollX = measured.scrollX;
|
||||
scrollY = measured.scrollY;
|
||||
} catch (error) {
|
||||
if (isCaptureAbort(error)) throw error;
|
||||
}
|
||||
|
||||
const children = new Map<string, CdpFrame[]>();
|
||||
const pending: CdpFrame[] = [];
|
||||
for (const frame of frames) {
|
||||
if (!frame.parentFrameId || !frameById.has(frame.parentFrameId)) pending.push(frame);
|
||||
else {
|
||||
const siblings = children.get(frame.parentFrameId);
|
||||
if (siblings) siblings.push(frame);
|
||||
else children.set(frame.parentFrameId, [frame]);
|
||||
}
|
||||
}
|
||||
const projections = new Map<string, SnapshotProjection | null>();
|
||||
const result: NormalizedDocument[] = [];
|
||||
let targetProjection: GeometryProjection | null = null;
|
||||
const targetRoot = pending[0];
|
||||
if (target.sessionId && targetRoot) {
|
||||
try {
|
||||
targetProjection = await geometry.targetProjection(targetRoot.frameId);
|
||||
} catch (error) {
|
||||
if (isCaptureAbort(error)) throw error;
|
||||
}
|
||||
}
|
||||
for (let cursor = 0; cursor < pending.length; cursor++) {
|
||||
if (cursor % 256 === 0) await captureCheckpoint(signal);
|
||||
const frame = pending[cursor];
|
||||
for (const child of children.get(frame.frameId) ?? []) pending.push(child);
|
||||
const doc = sources.get(frame.frameId);
|
||||
if (!doc) continue;
|
||||
const source = { target, frameId: frame.frameId };
|
||||
const parent = frame.parentFrameId ? frameById.get(frame.parentFrameId) : undefined;
|
||||
let projection: SnapshotProjection | null = null;
|
||||
if (!parent)
|
||||
projection = { source, geometry: { sourceClips: [], edges: [], topViewport: viewport } };
|
||||
else {
|
||||
const parentProjection = projections.get(parent.frameId)?.geometry;
|
||||
if (parentProjection && frame.ownerBackendNodeId !== undefined) {
|
||||
const edge = parentProjection.edges[0];
|
||||
const clips = edge
|
||||
? [edge.destinationQuad, ...(edge.destinationClips ?? [])]
|
||||
: parentProjection.sourceClips;
|
||||
try {
|
||||
projection = await geometry.snapshotProjection(
|
||||
source,
|
||||
frame.ownerBackendNodeId,
|
||||
clips,
|
||||
viewport,
|
||||
);
|
||||
} catch (error) {
|
||||
if (isCaptureAbort(error)) throw error;
|
||||
}
|
||||
}
|
||||
}
|
||||
projections.set(frame.frameId, projection);
|
||||
if (!projection || (target.sessionId && !targetProjection))
|
||||
issues.push({
|
||||
target,
|
||||
frameId: frame.frameId,
|
||||
stage: "geometry",
|
||||
reason: "geometry-unavailable",
|
||||
});
|
||||
const decoded = await decodeDocument(doc, strings, signal);
|
||||
const nodes: NodeFacts[] = [];
|
||||
for (let i = 0; i < decoded.nodes.length; i++) {
|
||||
if (i % 256 === 0) await captureCheckpoint(signal);
|
||||
const node = decoded.nodes[i];
|
||||
const input = snapshotViewportRect(node.layout?.bounds ?? [], source, {
|
||||
x: doc.scrollOffsetX ?? (parent ? 0 : scrollX),
|
||||
y: doc.scrollOffsetY ?? (parent ? 0 : scrollY),
|
||||
});
|
||||
const local = input?.rect;
|
||||
let rect = input && projection ? projectSnapshotRect(input, projection) : null;
|
||||
if (rect && target.sessionId)
|
||||
rect = targetProjection
|
||||
? projectRectToViewport(
|
||||
{ x: rect.x, y: rect.y, w: rect.width, h: rect.height },
|
||||
targetProjection,
|
||||
)
|
||||
: null;
|
||||
const styles = node.layout?.styles;
|
||||
const visibility = styles?.visibility || "visible";
|
||||
const opacity = styles?.opacity || "1";
|
||||
nodes.push({
|
||||
...node,
|
||||
frameId: frame.frameId,
|
||||
ownerFrameBackendNodeId: frame.ownerBackendNodeId ?? null,
|
||||
localRect: local ? { x: local.x, y: local.y, w: local.width, h: local.height } : null,
|
||||
rect: rect ? { x: rect.x, y: rect.y, w: rect.width, h: rect.height } : null,
|
||||
rendered:
|
||||
!!local &&
|
||||
visibility !== "hidden" &&
|
||||
visibility !== "collapse" &&
|
||||
(Number.parseFloat(opacity) || 0) > 0,
|
||||
});
|
||||
}
|
||||
const index = await buildDocumentIndex(nodes, signal);
|
||||
const domNodes = nodes.filter((node) => !node.tag.startsWith("#"));
|
||||
result.push({
|
||||
index,
|
||||
frame,
|
||||
domNodes,
|
||||
documentElementBackendNodeId: nodes.find(
|
||||
(node) =>
|
||||
node.nodeType === 1 &&
|
||||
node.parentBackendNodeId !== null &&
|
||||
index.nodes.get(node.parentBackendNodeId)?.nodeType === 9,
|
||||
)?.backendNodeId,
|
||||
});
|
||||
}
|
||||
for (const frameId of sources.keys()) {
|
||||
if (!projections.has(frameId))
|
||||
issues.push({ target, frameId, stage: "ownership", reason: "frame-ownership-unresolved" });
|
||||
}
|
||||
return result;
|
||||
}
|
||||
@@ -2,7 +2,10 @@ import type { Rect, RenderedRef, VomResult } from "@browser-skill/vom";
|
||||
import type { CdpTarget } from "@/browser-driver/frame-graph";
|
||||
import { readRecordingDocumentIdentity } from "@/shared/recording-document-identity";
|
||||
import type { CapturedSurfaceProbe } from "./capture";
|
||||
import type { CapturedFrameDocument, FrameAxNode } from "./frame-capture";
|
||||
import type {
|
||||
FrameDocument as CapturedFrameDocument,
|
||||
FrameOwnedAxNode as FrameAxNode,
|
||||
} from "./frame-document";
|
||||
|
||||
/** Frame identity needed to resolve an `@eN` that lives in an iframe. */
|
||||
export interface CaptureVomFrame {
|
||||
|
||||
@@ -61,8 +61,9 @@ export function buildSemanticGraph(input: BuildSemanticGraphInput): SemanticGrap
|
||||
dom,
|
||||
sourceOrder: index,
|
||||
excluded:
|
||||
document.frameId === rootFrameId &&
|
||||
input.excludedBackendNodeIds?.has(dom.backendNodeId) === true,
|
||||
document.excludedBackendNodeIds?.has(dom.backendNodeId) === true ||
|
||||
(document.frameId === rootFrameId &&
|
||||
input.excludedBackendNodeIds?.has(dom.backendNodeId) === true),
|
||||
};
|
||||
nodes.set(id, node);
|
||||
frameNodeIds.push(id);
|
||||
@@ -90,9 +91,10 @@ export function buildSemanticGraph(input: BuildSemanticGraphInput): SemanticGrap
|
||||
ax,
|
||||
sourceOrder: document.domNodes.length + index,
|
||||
excluded:
|
||||
document.frameId === rootFrameId &&
|
||||
typeof ax.backendDOMNodeId === "number" &&
|
||||
input.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true,
|
||||
(document.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true ||
|
||||
(document.frameId === rootFrameId &&
|
||||
input.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true)),
|
||||
});
|
||||
frameNodeIds.push(id);
|
||||
}
|
||||
|
||||
@@ -0,0 +1,230 @@
|
||||
import type { CapturedNode } from "./facts";
|
||||
import { captureCheckpoint, type DecodedDocument, type DecodedNode } from "./facts";
|
||||
export const REQUESTED_STYLES = [
|
||||
"position",
|
||||
"pointer-events",
|
||||
"cursor",
|
||||
"visibility",
|
||||
"opacity",
|
||||
"display",
|
||||
"overflow-x",
|
||||
"overflow-y",
|
||||
"transform",
|
||||
"zoom",
|
||||
"clip-path",
|
||||
"mask-image",
|
||||
] as const;
|
||||
const STYLE_COL = Object.fromEntries(
|
||||
REQUESTED_STYLES.map((name, index) => [name, index]),
|
||||
) as Record<(typeof REQUESTED_STYLES)[number], number>;
|
||||
/** Sparse array format Chrome uses for infrequently-set per-node fields. */
|
||||
interface SparseArray {
|
||||
index: number[];
|
||||
value: number[];
|
||||
}
|
||||
|
||||
interface RareBooleanData {
|
||||
index: number[];
|
||||
}
|
||||
|
||||
export interface SnapshotDocument {
|
||||
frameId?: string | number;
|
||||
scrollOffsetX?: number;
|
||||
scrollOffsetY?: number;
|
||||
nodes?: {
|
||||
parentIndex?: number[];
|
||||
nodeName?: number[];
|
||||
nodeType?: number[];
|
||||
backendNodeId?: number[];
|
||||
attributes?: number[][];
|
||||
/**
|
||||
* Per-node text value (index into strings), set for `#text` / CDATA nodes.
|
||||
* Element nodes carry -1. Same length as `backendNodeId`.
|
||||
*/
|
||||
nodeValue?: number[];
|
||||
/** Maps node array index → index into `documents[]` for frame content. */
|
||||
contentDocumentIndex?: SparseArray;
|
||||
inputValue?: SparseArray;
|
||||
textValue?: SparseArray;
|
||||
inputChecked?: RareBooleanData;
|
||||
optionSelected?: RareBooleanData;
|
||||
};
|
||||
layout?: {
|
||||
nodeIndex?: number[];
|
||||
styles?: number[][];
|
||||
bounds?: number[][];
|
||||
paintOrders?: number[];
|
||||
clientRects?: number[][];
|
||||
offsetRects?: number[][];
|
||||
scrollRects?: number[][];
|
||||
};
|
||||
}
|
||||
|
||||
export function snapshotFrameId(document: SnapshotDocument, strings: string[]): string | undefined {
|
||||
if (typeof document.frameId === "string") return document.frameId || undefined;
|
||||
if (typeof document.frameId === "number") return str(strings, document.frameId) || undefined;
|
||||
return undefined;
|
||||
}
|
||||
|
||||
export interface SnapshotReply {
|
||||
strings?: string[];
|
||||
documents?: SnapshotDocument[];
|
||||
}
|
||||
|
||||
function isSensitiveFormControl(node: Pick<CapturedNode, "tag" | "attrs">): boolean {
|
||||
return node.tag === "input" && (node.attrs.type ?? "").toLowerCase() === "password";
|
||||
}
|
||||
|
||||
function snapshotFormState(
|
||||
value: string | undefined,
|
||||
defaultValue: string,
|
||||
hasDefaultValue: boolean,
|
||||
sensitive: boolean,
|
||||
): CapturedNode["formState"] {
|
||||
if (sensitive) {
|
||||
if (value === undefined && !hasDefaultValue) return undefined;
|
||||
return (value ?? defaultValue) === "" ? "empty" : "filled";
|
||||
}
|
||||
if (value === undefined) return undefined;
|
||||
if (value === "") return "empty";
|
||||
return value === defaultValue ? "default" : "filled";
|
||||
}
|
||||
|
||||
function str(strings: string[], idx: number | undefined): string {
|
||||
if (idx === undefined || idx < 0) return "";
|
||||
return strings[idx] ?? "";
|
||||
}
|
||||
|
||||
function sparseIndexMap(sparse: SparseArray | undefined): Map<number, number> {
|
||||
const out = new Map<number, number>();
|
||||
if (!sparse?.index || !sparse.value) return out;
|
||||
for (let i = 0; i < sparse.index.length; i++) {
|
||||
const nodeIndex = sparse.index[i];
|
||||
const docIndex = sparse.value[i];
|
||||
if (nodeIndex !== undefined && docIndex !== undefined) out.set(nodeIndex, docIndex);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
export async function decodeDocument(
|
||||
doc: SnapshotDocument,
|
||||
strings: string[],
|
||||
signal?: AbortSignal,
|
||||
): Promise<DecodedDocument> {
|
||||
const dn = doc.nodes;
|
||||
const dl = doc.layout;
|
||||
if (!dn?.backendNodeId) {
|
||||
return { nodes: [] };
|
||||
}
|
||||
|
||||
const count = dn.backendNodeId.length;
|
||||
const layoutByNode = new Map<number, number>();
|
||||
for (let i = 0; i < (dl?.nodeIndex?.length ?? 0); i++) {
|
||||
if (i % 256 === 0) await captureCheckpoint(signal);
|
||||
layoutByNode.set(dl!.nodeIndex![i], i);
|
||||
}
|
||||
|
||||
const inputValues = sparseIndexMap(dn.inputValue);
|
||||
const textValues = sparseIndexMap(dn.textValue);
|
||||
const checkedInputs = new Set(dn.inputChecked?.index ?? []);
|
||||
const selectedOptions = new Set(dn.optionSelected?.index ?? []);
|
||||
|
||||
// Collect visible text from #text child nodes so element CapturedNodes
|
||||
// carry a textContent value usable as a button/link label fallback.
|
||||
// nodeValue is a parallel array: string index for text nodes, -1 otherwise.
|
||||
const nodeTextContent = new Map<number, string[]>();
|
||||
if (dn.nodeValue) {
|
||||
for (let n = 0; n < count; n++) {
|
||||
if (n % 256 === 0) await captureCheckpoint(signal);
|
||||
const nvIdx = dn.nodeValue[n] ?? -1;
|
||||
if (nvIdx < 0) continue;
|
||||
const text = str(strings, nvIdx).trim();
|
||||
if (!text) continue;
|
||||
const parentIdx = dn.parentIndex?.[n] ?? -1;
|
||||
if (parentIdx >= 0) {
|
||||
const existing = nodeTextContent.get(parentIdx);
|
||||
if (existing) existing.push(text);
|
||||
else nodeTextContent.set(parentIdx, [text]);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Decode fields without assigning a coordinate projection or semantic policy.
|
||||
const nodes: DecodedNode[] = [];
|
||||
for (let n = 0; n < count; n++) {
|
||||
if (n % 256 === 0) await captureCheckpoint(signal);
|
||||
const backendNodeId = dn.backendNodeId[n];
|
||||
const parentIdx = dn.parentIndex?.[n] ?? -1;
|
||||
const parentBackendNodeId = parentIdx >= 0 ? (dn.backendNodeId[parentIdx] ?? null) : null;
|
||||
const tag = str(strings, dn.nodeName?.[n]).toLowerCase();
|
||||
|
||||
const attrs: Record<string, string> = {};
|
||||
const pairs = dn.attributes?.[n] ?? [];
|
||||
for (let a = 0; a + 1 < pairs.length; a += 2) {
|
||||
attrs[str(strings, pairs[a]).toLowerCase()] = str(strings, pairs[a + 1]);
|
||||
}
|
||||
|
||||
const li = layoutByNode.get(n);
|
||||
const styleRow = li === undefined ? [] : (dl?.styles?.[li] ?? []);
|
||||
const styles: Record<string, string> = {};
|
||||
for (const name of REQUESTED_STYLES) styles[name] = str(strings, styleRow[STYLE_COL[name]]);
|
||||
const layout =
|
||||
li === undefined
|
||||
? undefined
|
||||
: {
|
||||
boundsSpace: "snapshot-document-css" as const,
|
||||
clientSpace: "unscaled-client-offset-css" as const,
|
||||
bounds: dl?.bounds?.[li],
|
||||
clientRect: dl?.clientRects?.[li],
|
||||
offsetRect: dl?.offsetRects?.[li],
|
||||
scrollRect: dl?.scrollRects?.[li],
|
||||
styles,
|
||||
};
|
||||
|
||||
const textContent = nodeTextContent.get(n)?.join(" ");
|
||||
|
||||
const rawFormValueIndex = tag === "textarea" ? textValues.get(n) : inputValues.get(n);
|
||||
const rawFormValue =
|
||||
rawFormValueIndex !== undefined ? str(strings, rawFormValueIndex) : undefined;
|
||||
const sensitive = isSensitiveFormControl({ tag, attrs });
|
||||
const formDefaultValue = attrs.value ?? "";
|
||||
const formValue = sensitive ? undefined : rawFormValue;
|
||||
const formState = snapshotFormState(
|
||||
rawFormValue,
|
||||
formDefaultValue,
|
||||
Object.prototype.hasOwnProperty.call(attrs, "value"),
|
||||
sensitive,
|
||||
);
|
||||
if (sensitive) delete attrs.value;
|
||||
|
||||
nodes.push({
|
||||
backendNodeId,
|
||||
nodeType: dn.nodeType?.[n],
|
||||
parentBackendNodeId,
|
||||
...(parentIdx >= 0 && dn.backendNodeId[parentIdx] === undefined
|
||||
? { parentMissing: true }
|
||||
: {}),
|
||||
|
||||
tag,
|
||||
attrs,
|
||||
layout,
|
||||
paintOrder: li === undefined ? 0 : (dl?.paintOrders?.[li] ?? 0),
|
||||
position: styles.position || "static",
|
||||
pointerEvents: styles["pointer-events"] || "auto",
|
||||
cursor: styles.cursor || "auto",
|
||||
|
||||
textContent,
|
||||
...(formValue !== undefined ? { formValue } : {}),
|
||||
...(tag === "input" || tag === "textarea"
|
||||
? {
|
||||
formPlaceholder: attrs.placeholder ?? "",
|
||||
...(!sensitive ? { formDefaultValue } : {}),
|
||||
...(formState ? { formState } : {}),
|
||||
}
|
||||
: {}),
|
||||
...(checkedInputs.has(n) ? { formValue: "true", formState: "filled" } : {}),
|
||||
...(selectedOptions.has(n) ? { formValue: attrs.value ?? textContent ?? "" } : {}),
|
||||
});
|
||||
}
|
||||
return { nodes };
|
||||
}
|
||||
@@ -73,14 +73,6 @@ where
|
||||
P: Serialize + Send + 'static,
|
||||
R: DeserializeOwned + Send + 'static,
|
||||
{
|
||||
let parent_cancel = stdin_cancellation();
|
||||
if parent_cancel.as_ref().is_some_and(|rx| *rx.borrow()) {
|
||||
return Err(CliError::from_rpc(RpcError {
|
||||
code: ErrorCode::Cancelled,
|
||||
message: "parent closed the cancellation pipe".into(),
|
||||
data: Some(serde_json::json!({"reason": "cancelled_before_dispatch"})),
|
||||
}));
|
||||
}
|
||||
let rpc_id: RpcId = format!("{}-{}", rpc_id_prefix, random_short_id());
|
||||
let mut client = IpcClient::connect(sock.clone()).await?;
|
||||
let rpc_id_for_call = rpc_id.clone();
|
||||
@@ -96,16 +88,16 @@ where
|
||||
let outcome = tokio::select! {
|
||||
biased;
|
||||
res = &mut main_fut => res?,
|
||||
sig = wait_for_cancel(parent_cancel) => {
|
||||
sig.context("wait for cancellation").map_err(CliError::Local)?;
|
||||
debug!(rpc_id = %rpc_id_for_cancel, "forwarding cancel to daemon");
|
||||
sig = wait_for_sigint() => {
|
||||
sig.context("install SIGINT handler").map_err(CliError::Local)?;
|
||||
debug!(rpc_id = %rpc_id_for_cancel, "SIGINT: forwarding cancel to daemon");
|
||||
let _ = send_cancel(&sock, &rpc_id_for_cancel).await;
|
||||
match tokio::time::timeout(CANCEL_RESPONSE_GRACE, &mut main_fut).await {
|
||||
Ok(res) => res?,
|
||||
Err(_) => {
|
||||
debug!(
|
||||
rpc_id = %rpc_id_for_cancel,
|
||||
"cancel grace elapsed; synthesising cancelled error"
|
||||
"SIGINT: cancel grace elapsed; synthesising cancelled error"
|
||||
);
|
||||
return Err(CliError::from_rpc(RpcError {
|
||||
code: ErrorCode::Cancelled,
|
||||
@@ -120,46 +112,6 @@ where
|
||||
outcome.map_err(CliError::from_rpc)
|
||||
}
|
||||
|
||||
/// Release caller-owned staging even after cancellation. This deliberately
|
||||
/// exposes only transfer.release, not a general bypass for business RPCs.
|
||||
/// The entire batch, including connection setup, shares one bounded budget.
|
||||
pub fn release_transfers<'a>(
|
||||
sock: &Path,
|
||||
transfer_ids: impl IntoIterator<Item = &'a str>,
|
||||
) -> Result<(), CliError> {
|
||||
use bsk_protocol::tools::{TransferIdParams, TransferReleaseResult};
|
||||
const CLEANUP_TIMEOUT: Duration = Duration::from_secs(5);
|
||||
let ids: Vec<_> = transfer_ids.into_iter().collect();
|
||||
if ids.is_empty() {
|
||||
return Ok(());
|
||||
}
|
||||
let rt = tokio::runtime::Builder::new_current_thread()
|
||||
.enable_all()
|
||||
.build()
|
||||
.context("build runtime for transfer cleanup")?;
|
||||
rt.block_on(async {
|
||||
tokio::time::timeout(CLEANUP_TIMEOUT, async {
|
||||
let mut client = IpcClient::connect(sock).await?;
|
||||
for id in ids {
|
||||
client
|
||||
.call::<_, TransferReleaseResult>(
|
||||
"transfer-release",
|
||||
Method::TransferRelease,
|
||||
Some(TransferIdParams {
|
||||
transfer_id: id.to_string(),
|
||||
}),
|
||||
CLEANUP_TIMEOUT,
|
||||
)
|
||||
.await?
|
||||
.map_err(CliError::from_rpc)?;
|
||||
}
|
||||
Ok::<_, CliError>(())
|
||||
})
|
||||
.await
|
||||
.context("transfer cleanup exceeded its total time budget")?
|
||||
})
|
||||
}
|
||||
|
||||
/// Send a `cancel { rpc_id }` frame over a fresh connection so it
|
||||
/// lands on the daemon while the original call is still parked.
|
||||
///
|
||||
@@ -194,57 +146,8 @@ fn random_short_id() -> String {
|
||||
bytes.iter().map(|b| format!("{b:02x}")).collect()
|
||||
}
|
||||
|
||||
/// Opt-in control pipe for parent processes that cannot send Ctrl-C (Node on
|
||||
/// Windows). One reader survives the short-lived runtimes used by multi-RPC
|
||||
/// commands such as upload. Ordinary CLI stdin and terminal Ctrl-C are unchanged.
|
||||
fn stdin_cancellation() -> Option<tokio::sync::watch::Receiver<bool>> {
|
||||
if std::env::var("BSK_CANCEL_ON_STDIN_CLOSE").as_deref() != Ok("1") {
|
||||
return None;
|
||||
}
|
||||
static CANCEL: std::sync::OnceLock<tokio::sync::watch::Receiver<bool>> =
|
||||
std::sync::OnceLock::new();
|
||||
Some(
|
||||
CANCEL
|
||||
.get_or_init(|| {
|
||||
let (tx, rx) = tokio::sync::watch::channel(false);
|
||||
std::thread::spawn(move || {
|
||||
use std::io::Read;
|
||||
let mut stdin = std::io::stdin().lock();
|
||||
let mut buf = [0; 64];
|
||||
loop {
|
||||
match stdin.read(&mut buf) {
|
||||
Ok(0) => break,
|
||||
Ok(_) => {}
|
||||
Err(err) if err.kind() == std::io::ErrorKind::Interrupted => continue,
|
||||
Err(_) => break,
|
||||
}
|
||||
}
|
||||
let _ = tx.send(true);
|
||||
});
|
||||
rx
|
||||
})
|
||||
.clone(),
|
||||
)
|
||||
}
|
||||
|
||||
async fn wait_for_cancel(
|
||||
parent_cancel: Option<tokio::sync::watch::Receiver<bool>>,
|
||||
) -> anyhow::Result<()> {
|
||||
let parent_closed = async move {
|
||||
match parent_cancel {
|
||||
Some(mut rx) => {
|
||||
let _ = rx.wait_for(|closed| *closed).await;
|
||||
}
|
||||
None => std::future::pending::<()>().await,
|
||||
}
|
||||
};
|
||||
tokio::select! {
|
||||
result = wait_for_sigint() => result,
|
||||
_ = parent_closed => Ok(()),
|
||||
}
|
||||
}
|
||||
|
||||
/// Wait for terminal Ctrl-C.
|
||||
/// Wait for either Ctrl-C or process SIGTERM. Returning here means
|
||||
/// the user has asked us to stop.
|
||||
async fn wait_for_sigint() -> anyhow::Result<()> {
|
||||
tokio::signal::ctrl_c().await.context("listen for SIGINT")?;
|
||||
Ok(())
|
||||
|
||||
@@ -9,7 +9,8 @@ use anyhow::Context;
|
||||
use base64::Engine;
|
||||
use bsk_protocol::Method;
|
||||
use bsk_protocol::tools::{
|
||||
DownloadParams, DownloadResult, TransferChunkParams, TransferChunkResult,
|
||||
DownloadParams, DownloadResult, TransferChunkParams, TransferChunkResult, TransferIdParams,
|
||||
TransferReleaseResult,
|
||||
};
|
||||
use clap::Args;
|
||||
use uuid::Uuid;
|
||||
@@ -69,7 +70,13 @@ pub fn dispatch(args: DownloadArgs, format: Format) -> Result<(), CliError> {
|
||||
CliError::Local(anyhow::anyhow!("daemon returned no download transfer id"))
|
||||
})?;
|
||||
let write_result = write_transfer(&info.sock_path, &transfer_id, &args.out, args.overwrite);
|
||||
let _ = crate::cli::business_rpc::release_transfers(&info.sock_path, [transfer_id.as_str()]);
|
||||
let _: Result<TransferReleaseResult, CliError> = crate::cli::business_rpc::call(
|
||||
info.sock_path,
|
||||
"transfer-release",
|
||||
Method::TransferRelease,
|
||||
Some(TransferIdParams { transfer_id }),
|
||||
Duration::from_secs(5),
|
||||
);
|
||||
write_result?;
|
||||
match format {
|
||||
Format::Json => {
|
||||
|
||||
@@ -10,7 +10,8 @@ use base64::Engine;
|
||||
use bsk_protocol::Method;
|
||||
use bsk_protocol::tools::{
|
||||
TransferBeginParams, TransferBeginResult, TransferChunkParams, TransferChunkResult,
|
||||
TransferIdParams, TransferReadyResult, UploadFile, UploadMode, UploadParams, UploadResult,
|
||||
TransferIdParams, TransferReadyResult, TransferReleaseResult, UploadFile, UploadMode,
|
||||
UploadParams, UploadResult,
|
||||
};
|
||||
use clap::{Args, ValueEnum};
|
||||
|
||||
@@ -68,12 +69,14 @@ pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
|
||||
let (ref_, selector) = split_target(args.target, args.ref_, args.selector)?;
|
||||
let mut staged = Vec::new();
|
||||
for path in &args.files {
|
||||
if let Err(err) = stage_file(&info.sock_path, &args.session, path, &mut staged) {
|
||||
let _ = crate::cli::business_rpc::release_transfers(
|
||||
&info.sock_path,
|
||||
staged.iter().map(|(id, _)| id.as_str()),
|
||||
);
|
||||
return Err(err);
|
||||
match stage_file(&info.sock_path, &args.session, path) {
|
||||
Ok(file) => staged.push(file),
|
||||
Err(err) => {
|
||||
for (id, _) in &staged {
|
||||
let _ = release(&info.sock_path, id);
|
||||
}
|
||||
return Err(err);
|
||||
}
|
||||
}
|
||||
}
|
||||
let params = UploadParams {
|
||||
@@ -99,17 +102,6 @@ pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
|
||||
Some(params),
|
||||
ipc_timeout(args.timeout),
|
||||
);
|
||||
// The helper can reject cancellation before handing any request to the
|
||||
// daemon. In that case staging still belongs to this CLI.
|
||||
if result.as_ref().is_err_and(|err| {
|
||||
err.data()
|
||||
.is_some_and(|data| data["reason"] == "cancelled_before_dispatch")
|
||||
}) {
|
||||
let _ = crate::cli::business_rpc::release_transfers(
|
||||
&info.sock_path,
|
||||
staged.iter().map(|(id, _)| id.as_str()),
|
||||
);
|
||||
}
|
||||
// Once tool.upload is dispatched, staging ownership belongs to the
|
||||
// session. A transport timeout cannot prove that Chrome did not attach
|
||||
// the file, so releasing here could invalidate a late successful attach.
|
||||
@@ -126,12 +118,7 @@ pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn stage_file(
|
||||
sock: &Path,
|
||||
session: &str,
|
||||
path: &PathBuf,
|
||||
staged: &mut Vec<(String, String)>,
|
||||
) -> Result<(), CliError> {
|
||||
fn stage_file(sock: &Path, session: &str, path: &PathBuf) -> Result<(String, String), CliError> {
|
||||
let mut file = File::open(path)
|
||||
.with_context(|| format!("open upload file {}", path.display()))
|
||||
.map_err(CliError::Local)?;
|
||||
@@ -162,39 +149,55 @@ fn stage_file(
|
||||
}),
|
||||
Duration::from_secs(10),
|
||||
)?;
|
||||
// Record ownership immediately so one error path releases both completed
|
||||
// files and the current partially staged file.
|
||||
staged.push((begin.transfer_id.clone(), name));
|
||||
let mut offset = 0u64;
|
||||
let mut buf = vec![0u8; begin.chunk_size as usize];
|
||||
loop {
|
||||
let n = file.read(&mut buf).map_err(|e| CliError::Local(e.into()))?;
|
||||
if n == 0 {
|
||||
break;
|
||||
let staged = (|| {
|
||||
let mut offset = 0u64;
|
||||
let mut buf = vec![0u8; begin.chunk_size as usize];
|
||||
loop {
|
||||
let n = file.read(&mut buf).map_err(|e| CliError::Local(e.into()))?;
|
||||
if n == 0 {
|
||||
break;
|
||||
}
|
||||
let reply: TransferChunkResult = crate::cli::business_rpc::call(
|
||||
sock.to_path_buf(),
|
||||
"transfer-chunk",
|
||||
Method::TransferChunk,
|
||||
Some(TransferChunkParams {
|
||||
transfer_id: begin.transfer_id.clone(),
|
||||
offset,
|
||||
data_base64: base64::engine::general_purpose::STANDARD.encode(&buf[..n]),
|
||||
}),
|
||||
Duration::from_secs(30),
|
||||
)?;
|
||||
offset = reply.next_offset;
|
||||
}
|
||||
let reply: TransferChunkResult = crate::cli::business_rpc::call(
|
||||
let _: TransferReadyResult = crate::cli::business_rpc::call(
|
||||
sock.to_path_buf(),
|
||||
"transfer-chunk",
|
||||
Method::TransferChunk,
|
||||
Some(TransferChunkParams {
|
||||
"transfer-finish",
|
||||
Method::TransferFinish,
|
||||
Some(TransferIdParams {
|
||||
transfer_id: begin.transfer_id.clone(),
|
||||
offset,
|
||||
data_base64: base64::engine::general_purpose::STANDARD.encode(&buf[..n]),
|
||||
}),
|
||||
Duration::from_secs(30),
|
||||
Duration::from_secs(10),
|
||||
)?;
|
||||
offset = reply.next_offset;
|
||||
Ok::<_, CliError>(())
|
||||
})();
|
||||
if let Err(err) = staged {
|
||||
let _ = release(sock, &begin.transfer_id);
|
||||
return Err(err);
|
||||
}
|
||||
let _: TransferReadyResult = crate::cli::business_rpc::call(
|
||||
Ok((begin.transfer_id, name))
|
||||
}
|
||||
|
||||
fn release(sock: &Path, id: &str) -> Result<TransferReleaseResult, CliError> {
|
||||
crate::cli::business_rpc::call(
|
||||
sock.to_path_buf(),
|
||||
"transfer-finish",
|
||||
Method::TransferFinish,
|
||||
"transfer-release",
|
||||
Method::TransferRelease,
|
||||
Some(TransferIdParams {
|
||||
transfer_id: begin.transfer_id.clone(),
|
||||
transfer_id: id.to_string(),
|
||||
}),
|
||||
Duration::from_secs(10),
|
||||
)?;
|
||||
Ok(())
|
||||
Duration::from_secs(5),
|
||||
)
|
||||
}
|
||||
|
||||
fn ipc_timeout(timeout_ms: u32) -> Duration {
|
||||
|
||||
@@ -1,342 +0,0 @@
|
||||
//! Real Windows CLI cancellation, including caller-owned transfer cleanup.
|
||||
#![cfg(windows)]
|
||||
|
||||
use std::path::Path;
|
||||
use std::sync::{Arc, Mutex};
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use bsk::daemon::{file_transfer::TransferRegistry, info::DaemonInfo};
|
||||
use bsk_protocol::tools::{TransferBeginParams, TransferIdParams};
|
||||
use bsk_protocol::{ErrorCode, Frame, Method, ResponseBody, ResponseFrame, RpcError};
|
||||
use serde_json::json;
|
||||
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
|
||||
use tokio::net::windows::named_pipe::ServerOptions;
|
||||
use tokio::process::Command;
|
||||
use tokio::sync::{Notify, watch};
|
||||
|
||||
fn response<T: serde::Serialize>(result: Result<T, RpcError>) -> ResponseBody {
|
||||
match result {
|
||||
Ok(value) => ResponseBody::Ok(serde_json::to_value(value).unwrap()),
|
||||
Err(err) => ResponseBody::Err(err),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn stdin_close_cancels_business_but_releases_resources_with_a_bounded_budget() {
|
||||
// Resolve the production registry's root before starting any runtime threads.
|
||||
let registry_home = tempfile::tempdir().unwrap();
|
||||
let original_home = std::env::var_os("BSK_HOME");
|
||||
unsafe {
|
||||
std::env::set_var("BSK_HOME", registry_home.path());
|
||||
}
|
||||
let transfers = Arc::new(TransferRegistry::new().unwrap());
|
||||
unsafe {
|
||||
match original_home {
|
||||
Some(value) => std::env::set_var("BSK_HOME", value),
|
||||
None => std::env::remove_var("BSK_HOME"),
|
||||
}
|
||||
}
|
||||
transfers.initialize().unwrap();
|
||||
tokio::runtime::Builder::new_current_thread()
|
||||
.enable_all()
|
||||
.build()
|
||||
.unwrap()
|
||||
.block_on(exercise(
|
||||
transfers,
|
||||
®istry_home.path().join("run/transfers"),
|
||||
));
|
||||
}
|
||||
|
||||
async fn exercise(transfers: Arc<TransferRegistry>, staging_root: &Path) {
|
||||
for mode in [
|
||||
"wait",
|
||||
"upload",
|
||||
"upload-multi",
|
||||
"upload-before-dispatch",
|
||||
"download",
|
||||
"upload-multi-stall",
|
||||
"ordinary",
|
||||
] {
|
||||
let home = tempfile::tempdir().unwrap();
|
||||
let pipe_name = format!(r"\\.\pipe\bsk-parent-cancel-{}", uuid::Uuid::new_v4());
|
||||
let info = DaemonInfo::now(std::process::id(), (&pipe_name).into(), 0, "0.2.0");
|
||||
std::fs::write(
|
||||
home.path().join("daemon.json"),
|
||||
serde_json::to_vec(&info).unwrap(),
|
||||
)
|
||||
.unwrap();
|
||||
let mut pipe = ServerOptions::new()
|
||||
.first_pipe_instance(true)
|
||||
.create(&pipe_name)
|
||||
.unwrap();
|
||||
let registered = Arc::new(Notify::new());
|
||||
let pending = Arc::new(Mutex::new(None::<String>));
|
||||
let ids = Arc::new(Mutex::new(Vec::<String>::new()));
|
||||
let released = Arc::new(Mutex::new(Vec::<String>::new()));
|
||||
let received = Arc::new(Mutex::new(Vec::<Method>::new()));
|
||||
let download_id = if mode == "download" {
|
||||
let staging = transfers.begin_download("fixture").unwrap();
|
||||
let browser_dir = home.path().join("BrowserSkill").join(&staging.transfer_id);
|
||||
std::fs::create_dir_all(&browser_dir).unwrap();
|
||||
let file = browser_dir.join("download.txt");
|
||||
std::fs::write(&file, b"download fixture").unwrap();
|
||||
transfers
|
||||
.import_download(&staging.transfer_id, &file)
|
||||
.unwrap();
|
||||
ids.lock().unwrap().push(staging.transfer_id.clone());
|
||||
Some(staging.transfer_id)
|
||||
} else {
|
||||
None
|
||||
};
|
||||
let (cancel, cancelled) = watch::channel(false);
|
||||
let ready = Arc::clone(®istered);
|
||||
let name = pipe_name.clone();
|
||||
let registry = Arc::clone(&transfers);
|
||||
let server_ids = Arc::clone(&ids);
|
||||
let server_released = Arc::clone(&released);
|
||||
let server_received = Arc::clone(&received);
|
||||
let server = tokio::spawn(async move {
|
||||
let mut connections = tokio::task::JoinSet::new();
|
||||
loop {
|
||||
pipe.connect().await.unwrap();
|
||||
let next = ServerOptions::new().create(&name).unwrap();
|
||||
let connection = std::mem::replace(&mut pipe, next);
|
||||
let ready = Arc::clone(&ready);
|
||||
let pending = Arc::clone(&pending);
|
||||
let cancel = cancel.clone();
|
||||
let mut cancelled = cancelled.clone();
|
||||
let name = name.clone();
|
||||
let registry = Arc::clone(®istry);
|
||||
let ids = Arc::clone(&server_ids);
|
||||
let released = Arc::clone(&server_released);
|
||||
let received = Arc::clone(&server_received);
|
||||
let download_id = download_id.clone();
|
||||
connections.spawn(async move {
|
||||
let (read, mut write) = tokio::io::split(connection);
|
||||
let mut reader = BufReader::new(read);
|
||||
let mut line = String::new();
|
||||
while reader.read_line(&mut line).await.unwrap_or(0) > 0 {
|
||||
let Frame::Request(req) = serde_json::from_str::<Frame>(&line).unwrap()
|
||||
else {
|
||||
panic!("expected request");
|
||||
};
|
||||
line.clear();
|
||||
received.lock().unwrap().push(req.method.clone());
|
||||
let params = req.params.clone().unwrap_or_default();
|
||||
let body = match req.method {
|
||||
Method::SystemStatus => ResponseBody::Ok(json!({
|
||||
"daemon_version": "0.2.0", "protocol_version": "1.1",
|
||||
"pid": std::process::id(), "uptime_secs": 0,
|
||||
"ws_port": 0, "sock_path": name,
|
||||
"browsers": [], "sessions": [], "version_skew_browsers": []
|
||||
})),
|
||||
Method::TransferBegin => {
|
||||
let begin = registry
|
||||
.begin_upload(serde_json::from_value(params).unwrap())
|
||||
.unwrap();
|
||||
ids.lock().unwrap().push(begin.transfer_id.clone());
|
||||
response(Ok(begin))
|
||||
}
|
||||
Method::ToolDownload => ResponseBody::Ok(json!({
|
||||
"tab_id": 1, "suggested_filename": "download.txt",
|
||||
"byte_size": 16, "transfer_id": download_id,
|
||||
})),
|
||||
Method::ToolWaitMs if mode == "ordinary" => {
|
||||
ResponseBody::Ok(json!({"waited_ms": 1}))
|
||||
}
|
||||
Method::TransferChunk
|
||||
if mode == "upload-before-dispatch"
|
||||
|| (mode.contains("multi")
|
||||
&& ids.lock().unwrap().len() == 1) =>
|
||||
{
|
||||
response(
|
||||
registry.write_chunk(serde_json::from_value(params).unwrap()),
|
||||
)
|
||||
}
|
||||
Method::TransferFinish if mode != "upload-before-dispatch" => response(
|
||||
registry.finish_upload(serde_json::from_value(params).unwrap()),
|
||||
),
|
||||
Method::ToolWaitMs
|
||||
| Method::TransferChunk
|
||||
| Method::TransferRead
|
||||
| Method::TransferFinish => {
|
||||
*pending.lock().unwrap() = Some(req.id.clone());
|
||||
ready.notify_one();
|
||||
cancelled.wait_for(|value| *value).await.unwrap();
|
||||
if mode == "upload-before-dispatch" {
|
||||
// Finish won the race with cancellation, but tool.upload must
|
||||
// not be dispatched and the CLI still owns the staging.
|
||||
response(
|
||||
registry
|
||||
.finish_upload(serde_json::from_value(params).unwrap()),
|
||||
)
|
||||
} else {
|
||||
ResponseBody::Err(RpcError {
|
||||
code: ErrorCode::Cancelled,
|
||||
message: "parent cancellation reached daemon".into(),
|
||||
data: None,
|
||||
})
|
||||
}
|
||||
}
|
||||
Method::Cancel => {
|
||||
let target = params["rpc_id"].as_str().unwrap();
|
||||
assert_eq!(pending.lock().unwrap().as_deref(), Some(target));
|
||||
cancel.send(true).unwrap();
|
||||
ResponseBody::Ok(json!({"cancelled": true}))
|
||||
}
|
||||
Method::TransferRelease => {
|
||||
let params: TransferIdParams =
|
||||
serde_json::from_value(params).unwrap();
|
||||
released.lock().unwrap().push(params.transfer_id.clone());
|
||||
if mode.contains("stall") {
|
||||
std::future::pending::<()>().await;
|
||||
}
|
||||
response(Ok(registry.release(params)))
|
||||
}
|
||||
other => panic!("unexpected request after cancellation: {other:?}"),
|
||||
};
|
||||
let response = Frame::Response(ResponseFrame { id: req.id, body });
|
||||
let mut bytes = serde_json::to_vec(&response).unwrap();
|
||||
bytes.push(b'\n');
|
||||
if write.write_all(&bytes).await.is_err() {
|
||||
break;
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
let mut cmd = Command::new(env!("CARGO_BIN_EXE_bsk"));
|
||||
cmd.env("BSK_HOME", home.path())
|
||||
.env("BSK_AUTO_UPDATE", "off")
|
||||
.env_remove("BSK_CANCEL_ON_STDIN_CLOSE")
|
||||
.stdout(std::process::Stdio::piped())
|
||||
.stderr(std::process::Stdio::piped())
|
||||
.creation_flags(0x0800_0000)
|
||||
.kill_on_drop(true);
|
||||
if mode.starts_with("upload") {
|
||||
let source = home.path().join("upload.txt");
|
||||
// Declare 300 MiB without allocating or transferring that much data.
|
||||
std::fs::File::create(&source)
|
||||
.unwrap()
|
||||
.set_len(if mode == "upload-before-dispatch" {
|
||||
16
|
||||
} else {
|
||||
300 * 1024 * 1024
|
||||
})
|
||||
.unwrap();
|
||||
cmd.args(["upload", "--session", "fixture", "--selector", "input"]);
|
||||
if mode.contains("multi") {
|
||||
let first = home.path().join("first.txt");
|
||||
std::fs::write(&first, b"first file").unwrap();
|
||||
cmd.arg("--file").arg(first);
|
||||
}
|
||||
cmd.arg("--file").arg(source);
|
||||
} else if mode == "download" {
|
||||
let out = home.path().join("out.txt");
|
||||
std::fs::write(&out, b"existing output").unwrap();
|
||||
cmd.args([
|
||||
"download",
|
||||
"--session",
|
||||
"fixture",
|
||||
"--selector",
|
||||
"a",
|
||||
"--overwrite",
|
||||
"--out",
|
||||
])
|
||||
.arg(out);
|
||||
} else {
|
||||
cmd.args(["wait-ms", if mode == "ordinary" { "1ms" } else { "60s" }]);
|
||||
}
|
||||
cmd.arg("--json");
|
||||
if mode == "ordinary" {
|
||||
cmd.stdin(std::process::Stdio::null());
|
||||
} else {
|
||||
cmd.env("BSK_CANCEL_ON_STDIN_CLOSE", "1")
|
||||
.stdin(std::process::Stdio::piped());
|
||||
}
|
||||
let mut child = cmd.spawn().unwrap();
|
||||
if mode != "ordinary" {
|
||||
tokio::time::timeout(Duration::from_secs(10), registered.notified())
|
||||
.await
|
||||
.expect("CLI registered business RPC");
|
||||
child
|
||||
.stdin
|
||||
.as_mut()
|
||||
.unwrap()
|
||||
.write_all(b"still connected")
|
||||
.await
|
||||
.unwrap();
|
||||
drop(child.stdin.take());
|
||||
}
|
||||
let start = Instant::now();
|
||||
let output = tokio::time::timeout(Duration::from_secs(8), child.wait_with_output())
|
||||
.await
|
||||
.expect("CLI must settle promptly, including cleanup")
|
||||
.unwrap();
|
||||
server.abort();
|
||||
let _ = server.await;
|
||||
assert_eq!(
|
||||
output.status.code(),
|
||||
Some(if mode == "ordinary" { 0 } else { 2 }),
|
||||
"{mode}: stdout={} stderr={}",
|
||||
String::from_utf8_lossy(&output.stdout),
|
||||
String::from_utf8_lossy(&output.stderr)
|
||||
);
|
||||
if mode != "ordinary" {
|
||||
let body: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
|
||||
assert_eq!(body["code"], "cancelled");
|
||||
if mode != "upload-before-dispatch" {
|
||||
assert_eq!(body["message"], "parent cancellation reached daemon");
|
||||
}
|
||||
let received = received.lock().unwrap();
|
||||
let cancel = received.iter().position(|m| *m == Method::Cancel).unwrap();
|
||||
assert!(
|
||||
received[cancel + 1..]
|
||||
.iter()
|
||||
.all(|m| *m == Method::TransferRelease),
|
||||
"only cleanup may follow cancellation: {received:?}"
|
||||
);
|
||||
}
|
||||
let ids = ids.lock().unwrap();
|
||||
if mode.contains("stall") {
|
||||
assert_eq!(released.lock().unwrap().len(), 1);
|
||||
assert!(start.elapsed() >= Duration::from_secs(4));
|
||||
// The CLI cannot force an unresponsive daemon to clean up.
|
||||
transfers.release_session("fixture");
|
||||
} else {
|
||||
assert_eq!(
|
||||
*released.lock().unwrap(),
|
||||
*ids,
|
||||
"{mode}: every allocation must be released"
|
||||
);
|
||||
for id in ids.iter() {
|
||||
assert!(!staging_root.join(id).exists(), "staging leaked: {id}");
|
||||
}
|
||||
if mode.starts_with("upload") {
|
||||
let retry = transfers
|
||||
.begin_upload(TransferBeginParams {
|
||||
session_id: "fixture".into(),
|
||||
name: "retry.txt".into(),
|
||||
byte_size: 300 * 1024 * 1024,
|
||||
})
|
||||
.expect("same session must have room for another 300 MiB upload");
|
||||
transfers.release(TransferIdParams {
|
||||
transfer_id: retry.transfer_id,
|
||||
});
|
||||
}
|
||||
}
|
||||
if mode == "download" {
|
||||
assert_eq!(
|
||||
std::fs::read(home.path().join("out.txt")).unwrap(),
|
||||
b"existing output"
|
||||
);
|
||||
assert!(
|
||||
!std::fs::read_dir(home.path())
|
||||
.unwrap()
|
||||
.flatten()
|
||||
.any(|entry| entry.file_name().to_string_lossy().ends_with(".part"))
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
+15
-41
@@ -21,7 +21,6 @@ $ErrorActionPreference = "Stop"
|
||||
|
||||
$Repo = if ($env:BSK_REPO) { $env:BSK_REPO } else { "Tencent/BrowserSkill" }
|
||||
$InstallDir = if ($env:BSK_INSTALL_DIR) { $env:BSK_INSTALL_DIR } else { Join-Path $HOME ".local\bin" }
|
||||
$InstallDir = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($InstallDir)
|
||||
$GitHub = "https://github.com/${Repo}"
|
||||
|
||||
function Write-Log {
|
||||
@@ -65,7 +64,7 @@ function Get-PlatformTriple {
|
||||
function Add-ToUserPath {
|
||||
param([string]$Dir)
|
||||
|
||||
$currentUserPath = @([Environment]::GetEnvironmentVariable("PATH", "User") -split ";" | Where-Object { $_ })
|
||||
$currentUserPath = [Environment]::GetEnvironmentVariable("PATH", "User") -split ";" | Where-Object { $_ }
|
||||
|
||||
if ($currentUserPath -contains $Dir) {
|
||||
Write-Log "$Dir is already in your user PATH"
|
||||
@@ -91,59 +90,30 @@ function Add-ToSessionPath {
|
||||
# ── Git Bash (bash environment) PATH helper ──────────────────────────────────
|
||||
|
||||
function Add-ToBashProfile {
|
||||
param([string]$Dir, [string]$BashRc = (Join-Path $HOME ".bashrc"))
|
||||
param([string]$Dir)
|
||||
|
||||
# Convert Windows path (e.g. C:\Users\foo\.local\bin) to Git-Bash Unix-style (/c/Users/foo/.local/bin)
|
||||
$unixPath = $Dir -replace '\\', '/'
|
||||
if ($unixPath -match '^([A-Z]):(.*)$') {
|
||||
$unixPath = '/' + $matches[1].ToLower() + $matches[2]
|
||||
}
|
||||
# Single-quote the literal directory; only the existing PATH is expanded.
|
||||
$shellQuote = "'" + [char]34 + "'" + [char]34 + "'"
|
||||
$quotedPath = "'" + $unixPath.Replace("'", $shellQuote) + "'"
|
||||
$exportLine = "export PATH=${quotedPath}:`"`$PATH`" # bsk CLI"
|
||||
$bashRc = Join-Path $HOME ".bashrc"
|
||||
$exportLine = "export PATH=""${unixPath}:`$PATH"" # bsk CLI"
|
||||
|
||||
if (Test-Path -LiteralPath $BashRc) {
|
||||
$content = [System.IO.File]::ReadAllText($BashRc)
|
||||
if ($content.Contains($exportLine)) {
|
||||
if (Test-Path $bashRc) {
|
||||
$content = Get-Content $bashRc -Raw -ErrorAction SilentlyContinue
|
||||
if ($content -match [regex]::Escape($unixPath)) {
|
||||
Write-Log "$unixPath is already in ~/.bashrc"
|
||||
return
|
||||
}
|
||||
}
|
||||
|
||||
# Explicit BOM-less UTF-8 also works in Windows PowerShell 5.1.
|
||||
[System.IO.File]::AppendAllText($BashRc, "`n$exportLine`n", (New-Object System.Text.UTF8Encoding($false)))
|
||||
Add-Content $bashRc "`n$exportLine" -Encoding ASCII
|
||||
Write-Log "added ${unixPath} to ~/.bashrc"
|
||||
}
|
||||
|
||||
# ── Main ──────────────────────────────────────────────────────────────────────
|
||||
|
||||
# Stage on the destination volume before stopping the daemon. Never truncate
|
||||
# the installed executable: failed replacement must leave it usable.
|
||||
function Install-Binary {
|
||||
param([string]$Source, [string]$Target)
|
||||
|
||||
$staged = "$Target.install-$([Guid]::NewGuid().ToString('N'))"
|
||||
try {
|
||||
[System.IO.File]::Copy($Source, $staged)
|
||||
if ([System.IO.File]::Exists($Target)) {
|
||||
# Use the downloaded CLI: older versions have broken Windows
|
||||
# liveness checks. Stop verifies daemon identity before terminating it.
|
||||
& $Source daemon stop
|
||||
if ($LASTEXITCODE -ne 0) { throw "could not stop bsk daemon; existing installation was not replaced" }
|
||||
# PowerShell 5.1 converts $null to an empty path for string parameters.
|
||||
[System.IO.File]::Replace($staged, $Target, [NullString]::Value)
|
||||
Write-Log "daemon will restart automatically on the next browser command"
|
||||
}
|
||||
else {
|
||||
[System.IO.File]::Move($staged, $Target)
|
||||
}
|
||||
}
|
||||
finally {
|
||||
if ([System.IO.File]::Exists($staged)) { [System.IO.File]::Delete($staged) }
|
||||
}
|
||||
}
|
||||
|
||||
function Main {
|
||||
$platform = Get-PlatformTriple
|
||||
|
||||
@@ -214,7 +184,7 @@ function Main {
|
||||
New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
|
||||
}
|
||||
|
||||
Install-Binary -Source (Join-Path $tempDir "bsk.exe") -Target (Join-Path $InstallDir "bsk.exe")
|
||||
Copy-Item -Path (Join-Path $tempDir "bsk.exe") -Destination (Join-Path $InstallDir "bsk.exe") -Force
|
||||
|
||||
Write-Log "installed bsk to $InstallDir\bsk.exe"
|
||||
|
||||
@@ -229,8 +199,12 @@ function Main {
|
||||
|
||||
# Verify
|
||||
$bskPath = Join-Path $InstallDir "bsk.exe"
|
||||
& $bskPath --version
|
||||
if ($LASTEXITCODE -ne 0) { throw "installed bsk failed verification" }
|
||||
if (Get-Command bsk -ErrorAction SilentlyContinue) {
|
||||
& bsk --version
|
||||
}
|
||||
else {
|
||||
Write-Log "verify install: & ""$bskPath"" --version"
|
||||
}
|
||||
|
||||
Write-Log "done"
|
||||
Write-Host ""
|
||||
|
||||
@@ -1,51 +1,13 @@
|
||||
# BrowserSkill for DeepSeek Harness
|
||||
# dsh-plugin-browserskill
|
||||
|
||||
[](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)
|
||||
npm: [`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)
|
||||
|
||||
Use [BrowserSkill](https://github.com/Tencent/BrowserSkill) in
|
||||
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) to browse
|
||||
websites, fill forms, and capture screenshots through native `browser_*` tools.
|
||||
Browser tasks run in Agent Windows, with a live view in the dsh Web UI.
|
||||
A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) tool plugin that exposes
|
||||
[BrowserSkill](https://github.com/Tencent/BrowserSkill) (`bsk`) browser automation to the model.
|
||||
|
||||
## Installation
|
||||
|
||||
Before installing the plugin:
|
||||
|
||||
- Install [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) and
|
||||
[pnpm](https://pnpm.io/installation), which dsh uses to manage plugins.
|
||||
- Install the `bsk` CLI and connect the BrowserSkill extension in Chrome or Edge.
|
||||
Follow the [BrowserSkill setup guide](https://github.com/Tencent/BrowserSkill#quick-start).
|
||||
- Make sure `bsk` is on the `PATH` used to start dsh, or set `bskPath` in the plugin configuration.
|
||||
|
||||
Install the plugin into the `web` profile, then start it:
|
||||
|
||||
```sh
|
||||
dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
|
||||
dsh --profile web
|
||||
```
|
||||
|
||||
Replace `web` with your profile name if you use a different profile. The plugin
|
||||
includes the `browser-skill` skill; no separate `bsk install-skill` step is needed.
|
||||
|
||||
In a conversation, try:
|
||||
|
||||
```text
|
||||
/browser-skill open example.com and summarize the page.
|
||||
```
|
||||
|
||||
By default, the browser tools become available when the skill is invoked.
|
||||
|
||||
## Updating
|
||||
|
||||
Installed plugins do not update automatically. To upgrade this plugin to npm's
|
||||
`latest` version, including versions outside the profile's saved dependency range:
|
||||
|
||||
```sh
|
||||
dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest
|
||||
```
|
||||
|
||||
Restart that dsh profile after upgrading. This command updates the plugin; update
|
||||
the `bsk` CLI and browser extension separately when a release requires it.
|
||||
Each action maps to one `bsk <cmd> --json` invocation: the plugin spawns the bsk CLI, parses its
|
||||
structured JSON output, and returns a canonical typed value. The bsk daemon, browser, and browser
|
||||
extension keep owning the actual browser control — this package is a thin, well-typed bridge.
|
||||
|
||||
## Tools
|
||||
|
||||
@@ -58,7 +20,23 @@ the `bsk` CLI and browser extension separately when a release requires it.
|
||||
| `browser_tabs` | `list`, `create`, `select`, `close`, `borrow`, `return` | Manage Agent Window tabs and temporarily borrow user tabs. |
|
||||
| `browser_assist` | `resize`, `emulate`, `request-help` | Resize or emulate the browser and pause for human-only steps. |
|
||||
|
||||
Arbitrary page-script evaluation and interaction recording are not supported.
|
||||
`bsk evaluate` and `bsk record` are intentionally not exposed by this plugin: arbitrary page
|
||||
evaluation is a higher-risk capability, while recording is long-running and needs a dedicated
|
||||
DeepSeek Harness lifecycle before it can be added safely.
|
||||
|
||||
## Agent skill (progressive disclosure)
|
||||
|
||||
Beyond the tools, the plugin publishes the **`browser-skill` agent skill** through the harness's
|
||||
official skill seam (`ctx.skills.register`): the catalog entry (name + routing description) is
|
||||
resident in `<available_skills>`, and the body is loaded only when the model invokes the `skill`
|
||||
tool. Its single source is the DSH-specific `skill/SKILL.md`, which documents only structured
|
||||
`browser_*` calls and their plugin semantics. The repository-root CLI skill is intentionally not
|
||||
concatenated: its command examples belong to a different execution interface and would bypass
|
||||
the plugin's ownership, live observation UI, cancellation, and cleanup path if followed directly.
|
||||
The build rejects internal CLI-name leakage, command-line code blocks, unknown browser tools, and
|
||||
missing supported browser tools before embedding the Markdown. Registration and every pre-step
|
||||
catalog snapshot are pure in-memory reads (no disk/process/daemon); compositions without the skill
|
||||
seam degrade silently.
|
||||
|
||||
## Multi-session model
|
||||
|
||||
@@ -77,73 +55,136 @@ an explicit `session` argument naming a foreign or unknown id is rejected, the `
|
||||
`browser_session` shows plugin-created sessions only (no daemon-wide view), and stop/unload cleanup
|
||||
can never touch a session owned by another program.
|
||||
|
||||
## Configuration
|
||||
## Installation
|
||||
|
||||
After installing the plugin, edit your profile's `cordis.patch.yml`. For the `web`
|
||||
profile, the default location is `~/.dsh/profiles/web/cordis.patch.yml`. If you set
|
||||
`DSH_HOME`, use `$DSH_HOME/profiles/web/cordis.patch.yml` instead. Replace `web` with
|
||||
your profile name as needed.
|
||||
The plugin follows the standard dsh bundle layout (`dsh.bundle` manifest + `cordis.patch.yml`):
|
||||
|
||||
If the file contains only comments and `[]`, keep the comments and replace `[]`
|
||||
with the YAML below. If it already contains patch entries, add this entry to the
|
||||
existing list or edit its existing `id: browserskill` entry. Keep a single
|
||||
top-level YAML list. This overrides the plugin registered by the installed bundle:
|
||||
|
||||
```yaml
|
||||
- id: browserskill
|
||||
config:
|
||||
bskPath: bsk
|
||||
defaultTimeoutMs: 120000
|
||||
maxSessions: 5
|
||||
observationEnabled: true
|
||||
thumbnailIntervalMs: 1500
|
||||
idleIntervalMs: 8000
|
||||
lazyTools: true
|
||||
```sh
|
||||
dsh plugin --profile <name> add @wxg-prc-cpg/browser-skill-dsh-plugin
|
||||
dsh --profile <name>
|
||||
```
|
||||
|
||||
Change `bskPath` to the full path of your CLI binary if it is not on dsh's `PATH`.
|
||||
A patch replaces the entry's entire `config` object, so keep all overrides you need
|
||||
together in that object.
|
||||
Prerequisite: the `bsk` CLI must be installed and on `PATH`, and the BrowserSkill browser extension
|
||||
(Chrome or Edge) must be connected — see the
|
||||
[BrowserSkill README](https://github.com/Tencent/BrowserSkill). When bsk is missing, tool calls fail
|
||||
with install guidance instead of a bare spawn error.
|
||||
|
||||
Configuration changes follow `dsh.profile.patchReload` in the profile's
|
||||
`package.json`: `live` (the default for `web`) applies changes when you save the
|
||||
patch file; `startup` requires restarting the profile. Restart after upgrading
|
||||
the plugin in either case.
|
||||
## Configuration
|
||||
|
||||
All fields are optional; omitted fields use the defaults below:
|
||||
All fields are optional and validated through the plugin's Schemastery `Config`:
|
||||
|
||||
| Option | Default | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `bskPath` | `bsk` | Path to the CLI binary. |
|
||||
| `defaultTimeoutMs` | `120000` | Default command timeout in milliseconds. |
|
||||
| `maxSessions` | `5` | Maximum concurrent sessions started by this plugin. |
|
||||
| `observationEnabled` | `true` | Enable live browser observation. |
|
||||
| `thumbnailIntervalMs` | `1500` | Screenshot interval for active sessions, in milliseconds. |
|
||||
| `idleIntervalMs` | `8000` | Screenshot interval for idle sessions and the recent-activity window, in milliseconds. |
|
||||
| `lazyTools` | `true` | Reveal the browser tools when the skill is invoked. Set `false` to register them at startup. |
|
||||
```yaml
|
||||
# cordis.patch.yml override example
|
||||
- insert:
|
||||
- id: browserskill
|
||||
name: "@wxg-prc-cpg/browser-skill-dsh-plugin"
|
||||
config:
|
||||
bskPath: bsk # path to the bsk binary (default: resolve from PATH)
|
||||
defaultTimeoutMs: 120000
|
||||
maxSessions: 5
|
||||
# observationEnabled: true # live PiP/overlay observation (below)
|
||||
# thumbnailIntervalMs: 1500 # frame cadence while a session is active
|
||||
# idleIntervalMs: 8000 # idle cadence / recent-activity window
|
||||
# lazyTools: true # reveal browser_* tools only after the skill is invoked
|
||||
```
|
||||
|
||||
With `lazyTools: true`, only the skill's catalog entry is initially advertised to
|
||||
the model. The six `browser_*` tool schemas are added to the system prompt after
|
||||
the `browser-skill` skill is successfully invoked, either by the model or through
|
||||
`/browser-skill`. Set `lazyTools: false` to make the tools available immediately.
|
||||
- **`lazyTools` (default `true`)** — the final progressive-disclosure stage: the six
|
||||
`browser_*` tool schemas stay OUT of the system prompt (zero schema tokens) until the
|
||||
`browser-skill` skill is actually invoked — the skill catalog entry is the only
|
||||
advertisement. One successful invocation (model tool call, or a `/browser-skill` user
|
||||
gesture) registers the whole suite for the rest of the process; repeated invocations are
|
||||
no-ops, and sessions resumed with a past invocation in their durable log reveal the suite
|
||||
on entry. Set `false` for the legacy always-on registration.
|
||||
|
||||
## Live browser view
|
||||
## Observation overlay (PiP mini-window)
|
||||
|
||||
The dsh Web UI shows the plugin's browser sessions in a floating panel. If your
|
||||
profile provides the `dsh-better-sidebar` integration, the view appears in a
|
||||
**Browser Skill** sidebar tab instead.
|
||||
When the plugin runs inside the dsh Web UI, an **observation overlay** floats over the app
|
||||
(registered into the `shell.overlay` seat): a breathing thumbnail per owned session plus its
|
||||
current action and elapsed time. The card docks at the top-right of the content area (clear of
|
||||
the composer and the shell's header controls) and wears the **BrowserSkill product family's own
|
||||
look**: the overlay reuses `@browser-skill/ui` components (`Button`, `cn`) and its oklch design
|
||||
tokens (`--card`, `--primary`, `--destructive`, `--ring`, …), status dots spec'd after the
|
||||
extension popup's connection indicator, and Remix icons. The BSK utility sheet is compiled
|
||||
scoped under the `.bsk-obs` root class (`scripts/build-client-css.mjs`), so the overlay looks
|
||||
like the BrowserSkill extension without leaking a single selector into the host shell — and the
|
||||
shell's theme cannot bleed back in.
|
||||
|
||||
- See the current action, elapsed time, and recent screenshot for each session.
|
||||
- Select a session to focus on it. The sidebar view follows the current conversation.
|
||||
- Use **Interrupt** to cancel the current browser command. The agent may continue
|
||||
with another action afterward.
|
||||
- Drag or resize the floating panel, or use **Pop out** to open a Picture-in-Picture
|
||||
window in browsers that support it.
|
||||
- Periodic screenshots are requested while a browser observation view is visible.
|
||||
Configure the active and idle intervals with the options above.
|
||||
- **Lifecycle**: hidden while the plugin owns no sessions; appears on the first
|
||||
`browser_session` start action; disappears when all sessions stop (or the plugin unloads).
|
||||
- **Focus view**: status row (green/idle/red dot + session + action + mm:ss), the latest page
|
||||
frame (while viewed, refreshes every ~1.5s while active, ~8s when idle; the last good frame stays on
|
||||
stage while the next one loads, and is kept on errors so the card does not flash),
|
||||
and a compact icon toolbar (Interrupt + Pop out, hover for the label).
|
||||
- **Interrupt**: one click kills the in-flight bsk command of the focus session (same semantics
|
||||
as the chat Stop button — the current action fails, the agent run may continue). Strip items
|
||||
carry their own hover interrupt button.
|
||||
- **Multi-session strip**: every session gets a tile (mini frame + id + status dot); focus
|
||||
auto-follows the most recently active session; clicking a tile pins focus (pin badge, click
|
||||
again to release); errored sessions get a red edge without stealing focus; sessions the daemon
|
||||
lost are greyed out; prolonged daemon/browser outage shows "browser unavailable" and greys
|
||||
the interrupt button until captures recover.
|
||||
- **Drag & resize**: drag the header to move the card; drag any of the four
|
||||
corners to resize (min 240×180, max 80% of the viewport; no visible grip).
|
||||
Both are remembered for the page lifetime.
|
||||
- **Pop out (PiP)**: upgrades the card into a native Document PiP window (requires a user
|
||||
gesture, per browser rules), sized from the current card; closing the PiP falls back to the
|
||||
in-page card with state intact. Browsers without Document PiP simply hide the button.
|
||||
- **Screenshot demand**: the client requests periodic screenshots while an observation view is
|
||||
visible, using the PiP document's visibility when popped out. Hidden or collapsed views can
|
||||
keep subscribing to state without requesting screenshots. The first screenshot subscriber
|
||||
starts capture scheduling; the last one's departure cancels timers and skips queued captures.
|
||||
An already running capture may finish. Demand applies to the service's owned sessions, not just
|
||||
the selected session.
|
||||
- **Wire**: `GET /bsk-observation/events` is the live synchronization channel (SSE). Every connection,
|
||||
including reconnects, starts with `{ type: "snapshot", sessions, available }`, followed by
|
||||
`upsert`, `remove`, `reset`, and `availability` events on the same stream. Replace local state
|
||||
with each snapshot before applying subsequent events. Use `?thumbnails=0` for state-only
|
||||
subscriptions or `?thumbnails=1` to request screenshots; omitting the parameter defaults to
|
||||
requesting screenshots for compatibility. Closing the stream releases its screenshot demand.
|
||||
`GET /bsk-observation/state` remains a one-time `{ sessions, available }` read and does not
|
||||
request screenshots. It has no ordering guarantee relative to a separate SSE connection;
|
||||
live clients should initialize and resynchronize from the stream's snapshot instead.
|
||||
The host also serves `POST /bsk-observation/interrupt`, `POST /bsk-observation/stop`, and
|
||||
`GET /bsk-observation/thumbnail/<attachmentId>` through the dsh `webServer` route seam
|
||||
(dsh 0.1's Typert Remote pipeline is closed to out-of-tree packages). All commands for one
|
||||
session — tool calls and frame captures alike — run through a per-session FIFO, because the
|
||||
daemon accepts only one unfinished command per session.
|
||||
- **Programmatic subscription**: `ObservationService.subscribe(listener, { thumbnails: false })`
|
||||
subscribes to state without requesting screenshots. On an active service, the listener receives
|
||||
the initial `snapshot` synchronously, before `subscribe` returns, then receives subsequent
|
||||
changes. `thumbnails` defaults to `true`, so callers should choose it explicitly. The returned
|
||||
unsubscribe function is safe to call repeatedly and releases this subscription's screenshot
|
||||
demand. Subscribing after service disposal is a no-op.
|
||||
- **Trust model**: these routes expose live screenshots (and an interrupt write), so they
|
||||
replicate the browser-trust fence dsh applies to its own `/api` routes: the request Host
|
||||
must be a loopback authority (`localhost`, `127.0.0.0/8`, `[::1]`), a present Origin must
|
||||
match the Host, `sec-fetch-site: cross-site` is refused, and POST requires an
|
||||
`application/json` body (cross-site simple requests can never satisfy that). The channel is
|
||||
therefore built for **loopback-only serving** — binding the dsh web server to `0.0.0.0` and
|
||||
reaching it through a LAN address will (deliberately) fail the fence; do not put these
|
||||
routes behind a non-loopback reverse proxy without adding your own authentication.
|
||||
- Configure with `observationEnabled` / `thumbnailIntervalMs` / `idleIntervalMs`.
|
||||
|
||||
The observation endpoints require a loopback address such as `localhost` or
|
||||
`127.0.0.1`. Access through a LAN hostname or non-loopback reverse proxy is not supported.
|
||||
## Behavior notes
|
||||
|
||||
- **Cancellation**: aborting a tool call (`exec.signal`) kills the underlying bsk child process,
|
||||
matching BrowserSkill's cooperative tool-cancellation model.
|
||||
- **UI cards**: calls render as terminal cards (command line as title, output as the completed
|
||||
card). Screenshots additionally attach the image itself when the host mounts an attachment store
|
||||
and the active model route declares image input; otherwise the PNG path is returned.
|
||||
- **Web UI toolview (browser half)**: the package is dual-face. `dsh.client` (platform `web`) ships
|
||||
`lib/client.cjs`, which registers a keyed `tool.call.toolview` view for `browser_inspect`. The
|
||||
custom view keeps a terminal block for every inspect action and, when a screenshot result carries
|
||||
an image block, resolves the durable attachment through the client session's authorized
|
||||
`readAttachment` RPC and renders it with the shared `MessageImage` thumbnail/lightbox atoms.
|
||||
The other five tools keep the stock terminal card. The bundle follows the dsh client
|
||||
contract: a CJS closure factory handed to `window.__ModuleLoader__.load`, platform modules
|
||||
(`react`, `dsh-client-ui-*`) external, everything else inlined, CSS Modules compiled by
|
||||
lightningcss.
|
||||
- **Errors**: non-zero bsk exits surface the CLI's JSON error envelope (`code`, `message`, `hint`)
|
||||
so the model gets the daemon's actionable guidance.
|
||||
- **Long-running work** (e.g. `bsk record`) is not backgrounded via `ctx.jobs` yet — tracked as a
|
||||
follow-up.
|
||||
|
||||
## Development
|
||||
|
||||
@@ -154,47 +195,22 @@ pnpm --filter @wxg-prc-cpg/browser-skill-dsh-plugin test # unit tests mock b
|
||||
pnpm --filter @wxg-prc-cpg/browser-skill-dsh-plugin build # tsdown -> lib/
|
||||
```
|
||||
|
||||
See the [development notes](https://github.com/Tencent/BrowserSkill/blob/main/packages/dsh-plugin-browserskill/docs/development.md)
|
||||
for skill registration, tool results, and observation APIs in the current source.
|
||||
|
||||
## Publishing
|
||||
|
||||
The [Release dsh plugin workflow](https://github.com/Tencent/BrowserSkill/blob/main/.github/workflows/release-dsh-plugin.yml)
|
||||
publishes the package and this README to npm. Pushing a `dsh-plugin-vX.Y.Z` tag
|
||||
triggers it; ordinary commits to `main` do not.
|
||||
The GitHub Actions workflow **Release dsh plugin** publishes this package to npm
|
||||
as `@wxg-prc-cpg/browser-skill-dsh-plugin`. The Cordis plugin id, client
|
||||
bundle registration, and `cordis.patch.yml` name are the same specifier so
|
||||
dsh can import and materialize the plugin without a ModuleLoader id mismatch.
|
||||
|
||||
1. Commit this README and any other changes intended for the release.
|
||||
2. From the repository root, run the
|
||||
[release script](https://github.com/Tencent/BrowserSkill/blob/main/scripts/release.mjs)
|
||||
with a new stable version, replacing `<version>` below. The script updates the
|
||||
CLI, extension, and DSH plugin versions, commits the version changes, and creates
|
||||
their release tags:
|
||||
Trigger it by pushing a tag that matches `package.json`'s `version`:
|
||||
|
||||
```sh
|
||||
node scripts/release.mjs <version>
|
||||
```
|
||||
```sh
|
||||
git tag dsh-plugin-v0.1.2
|
||||
git push origin dsh-plugin-v0.1.2
|
||||
```
|
||||
|
||||
3. Push the version commit to the release branch, then push the DSH plugin tag
|
||||
created by the script, using the same `<version>`:
|
||||
|
||||
```sh
|
||||
git push origin HEAD
|
||||
git push origin dsh-plugin-v<version>
|
||||
```
|
||||
|
||||
This publishes the DSH plugin. Push the CLI and extension tags separately when
|
||||
those components are ready for release.
|
||||
|
||||
The workflow checks the version, runs typechecks and tests, builds the package,
|
||||
and publishes it to npm.
|
||||
|
||||
You can also run the workflow manually from GitHub Actions on the intended release
|
||||
ref. Both triggers require an unpublished version and the `NPM_TOKEN` secret in the
|
||||
`npm-publish` GitHub Environment.
|
||||
|
||||
npm updates the package README only when a new version is published, including
|
||||
for documentation-only changes. Published versions cannot be overwritten. See
|
||||
[npm's README update rules](https://docs.npmjs.com/about-package-readme-files/).
|
||||
Or run the workflow from the Actions tab (`workflow_dispatch`). The job reads the
|
||||
`NPM_TOKEN` secret from the `npm-publish` GitHub Environment.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@@ -1,90 +0,0 @@
|
||||
# DSH plugin development notes
|
||||
|
||||
For installation, usage, and configuration, see the [plugin README](../README.md).
|
||||
These notes describe the current source on this branch; a published npm version may
|
||||
not include later changes.
|
||||
|
||||
## Tool execution
|
||||
|
||||
The plugin runs the `bsk` CLI and parses its JSON output. The daemon and browser
|
||||
extension perform the browser operations. The published package name is also the
|
||||
Cordis plugin id, client bundle registration id, and `cordis.patch.yml` plugin name.
|
||||
Keep these identifiers aligned so dsh can load both halves of the plugin.
|
||||
|
||||
## Agent skill
|
||||
|
||||
Beyond the tools, the plugin publishes the **`browser-skill` agent skill** through the harness's
|
||||
official skill seam (`ctx.skills.register`): the catalog entry (name + routing description) is
|
||||
resident in `<available_skills>`, and the body is loaded only when the model invokes the `skill`
|
||||
tool. Its single source is the DSH-specific `skill/SKILL.md`, which documents only structured
|
||||
`browser_*` calls and their plugin semantics. The repository-root CLI skill is intentionally not
|
||||
concatenated: its command examples belong to a different execution interface and would bypass
|
||||
the plugin's ownership, live observation UI, cancellation, and cleanup path if followed directly.
|
||||
The build rejects internal CLI-name leakage, command-line code blocks, unknown browser tools, and
|
||||
missing supported browser tools before embedding the Markdown. Registration and every pre-step
|
||||
catalog snapshot are pure in-memory reads (no disk/process/daemon); compositions without the skill
|
||||
seam degrade silently.
|
||||
|
||||
With `lazyTools: true`, the six tool schemas stay out of the system prompt until
|
||||
the skill is successfully invoked. Registration happens once and lasts until the
|
||||
plugin is unloaded. Repeated invocations do not register duplicate tools. Entering
|
||||
a resumed conversation whose history contains a successful skill invocation also
|
||||
registers the tools. Setting `lazyTools: false` registers them at plugin startup.
|
||||
|
||||
## Observation subscriptions and routes
|
||||
|
||||
- **Screenshot demand**: the client requests periodic screenshots while an observation view is
|
||||
visible, using the PiP document's visibility when popped out. Hidden or collapsed views can
|
||||
keep subscribing to state without requesting screenshots. The first screenshot subscriber
|
||||
starts capture scheduling; the last one's departure cancels timers and skips queued captures.
|
||||
An already running capture may finish. Demand applies to the service's owned sessions, not just
|
||||
the selected session.
|
||||
- **Wire**: `GET /bsk-observation/events` is the live synchronization channel (SSE). Every connection,
|
||||
including reconnects, starts with `{ type: "snapshot", sessions, available }`, followed by
|
||||
`upsert`, `remove`, `reset`, and `availability` events on the same stream. Replace local state
|
||||
with each snapshot before applying subsequent events. Use `?thumbnails=0` for state-only
|
||||
subscriptions or `?thumbnails=1` to request screenshots; omitting the parameter defaults to
|
||||
requesting screenshots for compatibility. Closing the stream releases its screenshot demand.
|
||||
`GET /bsk-observation/state` remains a one-time `{ sessions, available }` read and does not
|
||||
request screenshots. It has no ordering guarantee relative to a separate SSE connection;
|
||||
live clients should initialize and resynchronize from the stream's snapshot instead.
|
||||
The host also serves `POST /bsk-observation/interrupt`, `POST /bsk-observation/stop`, and
|
||||
`GET /bsk-observation/thumbnail/<attachmentId>` through the dsh `webServer` route seam
|
||||
(dsh 0.1's Typert Remote pipeline is closed to out-of-tree packages). All commands for one
|
||||
session — tool calls and frame captures alike — run through a per-session FIFO, because the
|
||||
daemon accepts only one unfinished command per session.
|
||||
- **Programmatic subscription**: `ObservationService.subscribe(listener, { thumbnails: false })`
|
||||
subscribes to state without requesting screenshots. On an active service, the listener receives
|
||||
the initial `snapshot` synchronously, before `subscribe` returns, then receives subsequent
|
||||
changes. `thumbnails` defaults to `true`, so callers should choose it explicitly. The returned
|
||||
unsubscribe function is safe to call repeatedly and releases this subscription's screenshot
|
||||
demand. Subscribing after service disposal is a no-op.
|
||||
- **Trust model**: these routes expose live screenshots (and an interrupt write), so they
|
||||
replicate the browser-trust fence dsh applies to its own `/api` routes: the request Host
|
||||
must be a loopback authority (`localhost`, `127.0.0.0/8`, `[::1]`), a present Origin must
|
||||
match the Host, `sec-fetch-site: cross-site` is refused, and POST requires an
|
||||
`application/json` body (cross-site simple requests can never satisfy that). The channel is
|
||||
therefore built for **loopback-only serving** — binding the dsh web server to `0.0.0.0` and
|
||||
reaching it through a LAN address will (deliberately) fail the fence; do not put these
|
||||
routes behind a non-loopback reverse proxy without adding your own authentication.
|
||||
|
||||
## Tool results and cancellation
|
||||
|
||||
- **Cancellation**: aborting a tool call (`exec.signal`) kills the underlying bsk child process,
|
||||
matching BrowserSkill's cooperative tool-cancellation model.
|
||||
- **UI cards**: calls render as terminal cards (command line as title, output as the completed
|
||||
card). Screenshots additionally attach the image itself when the host mounts an attachment store
|
||||
and the active model route declares image input; otherwise the PNG path is returned.
|
||||
- **Web UI toolview (browser half)**: the package is dual-face. `dsh.client` (platform `web`) ships
|
||||
`lib/client.cjs`, which registers a keyed `tool.call.toolview` view for `browser_inspect`. The
|
||||
custom view keeps a terminal block for every inspect action and, when a screenshot result carries
|
||||
an image block, resolves the durable attachment through the client session's authorized
|
||||
`readAttachment` RPC and renders it with the shared `MessageImage` thumbnail/lightbox atoms.
|
||||
The other five tools keep the stock terminal card. The bundle follows the dsh client
|
||||
contract: a CJS closure factory handed to `window.__ModuleLoader__.load`, platform modules
|
||||
(`react`, `dsh-client-ui-*`) external, everything else inlined, CSS Modules compiled by
|
||||
lightningcss.
|
||||
- **Errors**: non-zero bsk exits surface the CLI's JSON error envelope (`code`, `message`, `hint`)
|
||||
so the model gets the daemon's actionable guidance.
|
||||
- **Long-running work** (e.g. `bsk record`) is not backgrounded via `ctx.jobs` yet — tracked as a
|
||||
follow-up.
|
||||
@@ -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",
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
* map the CLI's JSON error envelope onto a thrown `BskError`.
|
||||
*/
|
||||
|
||||
import { type ChildProcess, type SpawnOptionsWithoutStdio, spawn } from "node:child_process";
|
||||
import { type ChildProcess, spawn } from "node:child_process";
|
||||
|
||||
/** Shape of the JSON error envelope `bsk --json` prints on failure. */
|
||||
export interface BskErrorBody {
|
||||
@@ -53,11 +53,7 @@ export interface BskRunOptions {
|
||||
}
|
||||
|
||||
/** Minimal spawn signature so tests can substitute a fake child process. */
|
||||
export type SpawnImpl = (
|
||||
command: string,
|
||||
args: string[],
|
||||
options?: SpawnOptionsWithoutStdio,
|
||||
) => ChildProcess;
|
||||
export type SpawnImpl = (command: string, args: string[]) => ChildProcess;
|
||||
|
||||
export interface BskRunner {
|
||||
/** Run `bsk <args...> --json` and collect its output. */
|
||||
@@ -68,66 +64,29 @@ export interface BskRunner {
|
||||
killFor(tag: string): number;
|
||||
}
|
||||
|
||||
// Business RPCs translate Ctrl-C / opt-in stdin EOF into cancel(rpc_id).
|
||||
// Allow reconciliation before hard-killing an old or unresponsive CLI.
|
||||
// Business RPCs translate SIGINT into the daemon's cancel(rpc_id) protocol.
|
||||
// Give that bounded reconciliation path time to settle before the hard kill.
|
||||
const KILL_GRACE_MS = 3000;
|
||||
// Windows IPC may spend 5s connecting, 2s cancelling, 2s settling,
|
||||
// and up to 5s releasing the entire batch of caller-owned transfers.
|
||||
const WINDOWS_KILL_GRACE_MS = 15_000;
|
||||
const SESSION_BUSY_RETRY_DELAY_MS = 100;
|
||||
|
||||
export function createBskRunner(bskPath: string, spawnImpl: SpawnImpl = spawn): BskRunner {
|
||||
const live = new Map<ChildProcess, string | undefined>();
|
||||
const windows = process.platform === "win32";
|
||||
const cancelling = new Set<ChildProcess>();
|
||||
|
||||
function killChild(child: ChildProcess): void {
|
||||
if (child.exitCode !== null || child.signalCode !== null || cancelling.has(child)) return;
|
||||
cancelling.add(child);
|
||||
// Node kills Windows children outright for SIGINT. EOF asks the CLI to
|
||||
// send its existing cancel RPC and wait for browser reconciliation.
|
||||
if (windows && child.stdin) child.stdin.end();
|
||||
else child.kill("SIGINT");
|
||||
const force = setTimeout(
|
||||
() => {
|
||||
if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
|
||||
},
|
||||
windows ? WINDOWS_KILL_GRACE_MS : KILL_GRACE_MS,
|
||||
);
|
||||
if (child.exitCode !== null || child.signalCode !== null) return;
|
||||
child.kill("SIGINT");
|
||||
const force = setTimeout(() => {
|
||||
if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
|
||||
}, KILL_GRACE_MS);
|
||||
force.unref();
|
||||
child.once("close", () => {
|
||||
clearTimeout(force);
|
||||
cancelling.delete(child);
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
run(args, options = {}) {
|
||||
if (options.signal?.aborted) {
|
||||
return Promise.resolve({
|
||||
code: null,
|
||||
stdout: "",
|
||||
stderr: "",
|
||||
timedOut: false,
|
||||
aborted: true,
|
||||
});
|
||||
}
|
||||
return new Promise<BskRunResult>((resolve, reject) => {
|
||||
let child: ChildProcess;
|
||||
try {
|
||||
child = spawnImpl(
|
||||
bskPath,
|
||||
[...args, "--json"],
|
||||
windows
|
||||
? {
|
||||
windowsHide: true,
|
||||
env: { ...process.env, BSK_CANCEL_ON_STDIN_CLOSE: "1" },
|
||||
}
|
||||
: undefined,
|
||||
);
|
||||
// A child exiting while cancellation closes stdin may report EPIPE.
|
||||
// Its close/error event remains the authority for the run result.
|
||||
child.stdin?.on("error", () => {});
|
||||
child = spawnImpl(bskPath, [...args, "--json"]);
|
||||
} catch (error) {
|
||||
reject(error);
|
||||
return;
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
import type { ChildProcess } from "node:child_process";
|
||||
import { EventEmitter } from "node:events";
|
||||
import { PassThrough } from "node:stream";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
type BskRunResult,
|
||||
createBskRunner,
|
||||
@@ -93,77 +92,6 @@ describe("createBskRunner", () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe("Windows parent cancellation", () => {
|
||||
const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform")!;
|
||||
beforeEach(() => Object.defineProperty(process, "platform", { value: "win32" }));
|
||||
afterEach(() => {
|
||||
Object.defineProperty(process, "platform", originalPlatform);
|
||||
vi.useRealTimers();
|
||||
});
|
||||
|
||||
it("opts in to stdin cancellation and waits for CLI reconciliation", async () => {
|
||||
const child = Object.assign(new FakeChild(), { stdin: new PassThrough() });
|
||||
const spawn = vi.fn(() => child as unknown as ChildProcess);
|
||||
const runner = createBskRunner("bsk", spawn);
|
||||
const abort = new AbortController();
|
||||
const result = runner.run(["snapshot"], { signal: abort.signal });
|
||||
expect(spawn.mock.calls[0]).toEqual([
|
||||
"bsk",
|
||||
["snapshot", "--json"],
|
||||
{
|
||||
windowsHide: true,
|
||||
env: { ...process.env, BSK_CANCEL_ON_STDIN_CLOSE: "1" },
|
||||
},
|
||||
]);
|
||||
abort.abort();
|
||||
expect(child.stdin.writableEnded).toBe(true);
|
||||
expect(child.killedWith).toEqual([]);
|
||||
// Closing an already-exited child's pipe must not crash the host.
|
||||
child.stdin.emit("error", Object.assign(new Error("closed"), { code: "EPIPE" }));
|
||||
child.finish(2, '{"code":"cancelled"}');
|
||||
expect(await result).toMatchObject({ code: 2, aborted: true });
|
||||
});
|
||||
|
||||
it("bounds cancellation of an old or unresponsive CLI", async () => {
|
||||
vi.useFakeTimers();
|
||||
const child = Object.assign(new FakeChild(), { stdin: new PassThrough() });
|
||||
const runner = createBskRunner("bsk", fakeSpawn([child]));
|
||||
const result = runner.run(["snapshot"], { timeoutMs: 5 });
|
||||
await vi.advanceTimersByTimeAsync(5);
|
||||
expect(child.stdin.writableEnded).toBe(true);
|
||||
expect(child.killedWith).toEqual([]);
|
||||
await vi.advanceTimersByTimeAsync(10_000);
|
||||
expect(child.killedWith).toEqual([]);
|
||||
await vi.advanceTimersByTimeAsync(5_000);
|
||||
expect(child.killedWith).toEqual(["SIGKILL"]);
|
||||
expect(await result).toMatchObject({ timedOut: true });
|
||||
});
|
||||
|
||||
it("cancels only the requested tag and clears the fallback after exit", async () => {
|
||||
vi.useFakeTimers();
|
||||
const a = Object.assign(new FakeChild(), { stdin: new PassThrough() });
|
||||
const b = Object.assign(new FakeChild(), { stdin: new PassThrough() });
|
||||
const runner = createBskRunner("bsk", fakeSpawn([a, b]));
|
||||
const first = runner.run(["snapshot"], { tag: "a" });
|
||||
const second = runner.run(["snapshot"], { tag: "b" });
|
||||
expect(runner.killFor("a")).toBe(1);
|
||||
expect(a.stdin.writableEnded).toBe(true);
|
||||
expect(b.stdin.writableEnded).toBe(false);
|
||||
a.finish(2);
|
||||
b.finish(0);
|
||||
await Promise.all([first, second]);
|
||||
expect(vi.getTimerCount()).toBe(0);
|
||||
});
|
||||
|
||||
it("does not start work for an already-aborted call", async () => {
|
||||
const spawn = vi.fn();
|
||||
const runner = createBskRunner("bsk", spawn);
|
||||
const signal = AbortSignal.abort();
|
||||
expect(await runner.run(["snapshot"], { signal })).toMatchObject({ aborted: true });
|
||||
expect(spawn).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe("parseBskJson", () => {
|
||||
const base: BskRunResult = { code: 0, stdout: "", stderr: "", timedOut: false, aborted: false };
|
||||
|
||||
|
||||
@@ -1,135 +0,0 @@
|
||||
#Requires -Version 5.1
|
||||
param([string]$BskPath = (Join-Path $PSScriptRoot "../target/debug/bsk.exe"))
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
# Load definitions, never Main: no downloads or changes to the real user PATH.
|
||||
$installer = Join-Path $PSScriptRoot "../install.ps1"
|
||||
$tokens = $null
|
||||
$errors = $null
|
||||
$ast = [System.Management.Automation.Language.Parser]::ParseFile($installer, [ref]$tokens, [ref]$errors)
|
||||
if ($errors.Count) { throw ($errors | Out-String) }
|
||||
foreach ($statement in $ast.EndBlock.Statements) {
|
||||
if ($statement -is [System.Management.Automation.Language.FunctionDefinitionAst]) {
|
||||
$definition = $statement.Extent.Text
|
||||
if ($statement.Name -eq "Add-ToUserPath") {
|
||||
$definition = $definition.Replace('[Environment]::GetEnvironmentVariable("PATH", "User")', '$script:UserPath')
|
||||
$definition = $definition.Replace('[Environment]::SetEnvironmentVariable("PATH", $newUserPath, "User")', '$script:UserPath = $newUserPath')
|
||||
}
|
||||
Invoke-Expression $definition
|
||||
}
|
||||
}
|
||||
function Assert-Equal($Actual, $Expected) {
|
||||
if ($Actual -cne $Expected) { throw "expected [$Expected], got [$Actual]" }
|
||||
}
|
||||
function Assert-Fails([scriptblock]$Action) {
|
||||
$failed = $false
|
||||
try { & $Action } catch { $failed = $true }
|
||||
if (-not $failed) { throw "expected failure" }
|
||||
}
|
||||
|
||||
$dir = 'C:\Users\Alice\.local\bin'
|
||||
foreach ($existing in @('', 'C:\WindowsApps', 'C:\A;C:\B')) {
|
||||
$script:UserPath = $existing
|
||||
Add-ToUserPath $dir
|
||||
$expected = if ($existing) { "$existing;$dir" } else { $dir }
|
||||
Assert-Equal $script:UserPath $expected
|
||||
Add-ToUserPath $dir
|
||||
Assert-Equal $script:UserPath $expected
|
||||
}
|
||||
|
||||
$root = Join-Path ([IO.Path]::GetTempPath()) ("bsk-install-test-" + [Guid]::NewGuid().ToString('N'))
|
||||
[IO.Directory]::CreateDirectory($root) | Out-Null
|
||||
$oldBskHome = $env:BSK_HOME
|
||||
$oldAutoUpdate = $env:BSK_AUTO_UPDATE
|
||||
$daemon = $null
|
||||
try {
|
||||
$utf8 = New-Object System.Text.UTF8Encoding($false)
|
||||
$bashRc = Join-Path $root ".bashrc"
|
||||
$existing = "# existing 中文 configuration" + [char]10
|
||||
[IO.File]::WriteAllText($bashRc, $existing, $utf8)
|
||||
$special = 'C:\Users\张三 space $HOME $(echo unsafe) ! & [x] O''Brien\.local\bin'
|
||||
Add-ToBashProfile $special $bashRc
|
||||
$first = [IO.File]::ReadAllText($bashRc)
|
||||
if (-not $first.StartsWith($existing)) { throw "existing bashrc content changed" }
|
||||
if (-not $first.Contains('张三')) { throw "Unicode path was lost" }
|
||||
Add-ToBashProfile $special $bashRc
|
||||
Assert-Equal ([IO.File]::ReadAllText($bashRc)) $first
|
||||
$bytes = [IO.File]::ReadAllBytes($bashRc)
|
||||
if ($bytes[0] -eq 0xEF) { throw "unexpected UTF-8 BOM" }
|
||||
|
||||
$bash = [IO.Path]::GetFullPath((Join-Path (Split-Path (Get-Command git).Source -Parent) "../bin/bash.exe"))
|
||||
if (-not (Test-Path -LiteralPath $bash)) { throw "Git Bash is required for quoting regression" }
|
||||
$env:BSK_TEST_RC = $bashRc
|
||||
$probe = Join-Path $root 'probe.sh'
|
||||
[IO.File]::WriteAllText($probe, 'source "$BSK_TEST_RC"; printf "%s\n" "${PATH%%:*}"', $utf8)
|
||||
$actual = & $bash --noprofile --norc $probe
|
||||
if ($LASTEXITCODE -ne 0) { throw "Git Bash failed" }
|
||||
Assert-Equal $actual ('/c' + $special.Substring(2).Replace('\', '/'))
|
||||
|
||||
$env:BSK_HOME = Join-Path $root "home"
|
||||
$env:BSK_AUTO_UPDATE = "off"
|
||||
[IO.Directory]::CreateDirectory($env:BSK_HOME) | Out-Null
|
||||
$sourceDir = Join-Path $root "download"
|
||||
[IO.Directory]::CreateDirectory($sourceDir) | Out-Null
|
||||
$source = Join-Path $sourceDir "bsk.exe"
|
||||
[IO.File]::Copy((Resolve-Path -LiteralPath $BskPath).Path, $source)
|
||||
$targetDir = Join-Path $root "中文 space [x] & install"
|
||||
[IO.Directory]::CreateDirectory($targetDir) | Out-Null
|
||||
$target = Join-Path $targetDir "bsk.exe"
|
||||
Install-Binary $source $target
|
||||
Assert-Equal (Get-FileHash -LiteralPath $target).Hash (Get-FileHash -LiteralPath $source).Hash
|
||||
|
||||
$daemon = Start-Process -FilePath $target -ArgumentList @('daemon', 'start', '--foreground', '--port', '0') -WindowStyle Hidden -PassThru
|
||||
$infoPath = Join-Path $env:BSK_HOME "daemon.json"
|
||||
$deadline = [DateTime]::UtcNow.AddSeconds(15)
|
||||
while (-not [IO.File]::Exists($infoPath)) {
|
||||
if ($daemon.HasExited -or [DateTime]::UtcNow -gt $deadline) { throw "daemon failed to start" }
|
||||
Start-Sleep -Milliseconds 50
|
||||
}
|
||||
# PE overlays distinguish old/new executables without another build.
|
||||
$stream = [IO.File]::OpenWrite($source)
|
||||
try {
|
||||
$stream.Seek(0, [IO.SeekOrigin]::End) | Out-Null
|
||||
$marker = $utf8.GetBytes("installer replacement regression")
|
||||
$stream.Write($marker, 0, $marker.Length)
|
||||
} finally { $stream.Dispose() }
|
||||
Install-Binary $source $target
|
||||
if (-not $daemon.WaitForExit(5000)) { throw "old daemon still running" }
|
||||
Assert-Equal (Get-FileHash -LiteralPath $target).Hash (Get-FileHash -LiteralPath $source).Hash
|
||||
& $target --version
|
||||
if ($LASTEXITCODE -ne 0) { throw "replacement is not executable" }
|
||||
|
||||
# Refuse replacement when daemon identity cannot be verified.
|
||||
[IO.File]::WriteAllText($infoPath, 'invalid daemon metadata')
|
||||
$before = (Get-FileHash -LiteralPath $target).Hash
|
||||
Assert-Fails { Install-Binary $source $target }
|
||||
Assert-Equal (Get-FileHash -LiteralPath $target).Hash $before
|
||||
[IO.File]::Delete($infoPath)
|
||||
|
||||
# A remaining lock must fail without truncation or staging debris.
|
||||
$lock = [IO.File]::Open($target, [IO.FileMode]::Open, [IO.FileAccess]::Read, [IO.FileShare]::None)
|
||||
try { Assert-Fails { Install-Binary $source $target } } finally { $lock.Dispose() }
|
||||
Assert-Equal (Get-FileHash -LiteralPath $target).Hash $before
|
||||
if (@(Get-ChildItem -LiteralPath $targetDir -Filter "*.install-*").Count) { throw "staging files leaked" }
|
||||
Write-Host "Windows installer regressions passed ($($PSVersionTable.PSVersion))"
|
||||
}
|
||||
catch {
|
||||
Write-Host ($_ | Out-String)
|
||||
Write-Host $_.ScriptStackTrace
|
||||
throw
|
||||
}
|
||||
finally {
|
||||
if ($daemon -and -not $daemon.HasExited) {
|
||||
Stop-Process -Id $daemon.Id -Force
|
||||
$daemon.WaitForExit(5000) | Out-Null
|
||||
}
|
||||
$env:BSK_HOME = $oldBskHome
|
||||
$env:BSK_AUTO_UPDATE = $oldAutoUpdate
|
||||
Remove-Item Env:BSK_TEST_RC -ErrorAction SilentlyContinue
|
||||
# Resolve and verify before recursive cleanup; only this fixture is removed.
|
||||
$resolvedRoot = [IO.Path]::GetFullPath($root)
|
||||
$tempRoot = [IO.Path]::GetFullPath([IO.Path]::GetTempPath()).TrimEnd('\') + '\'
|
||||
if (-not $resolvedRoot.StartsWith($tempRoot, [StringComparison]::OrdinalIgnoreCase) -or
|
||||
-not ([IO.Path]::GetFileName($resolvedRoot)).StartsWith('bsk-install-test-')) { throw "invalid cleanup path" }
|
||||
Remove-Item -LiteralPath $resolvedRoot -Recurse -Force
|
||||
}
|
||||
+3
-9
@@ -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}`);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in new issue
Block a user