build: release 0.3.0

.github/workflows/chrome-update.yml

@@ -0,0 +1,84 @@
+# Checks every day whether stable Chrome ships another devtools-frontend commit than the one pinned
+# in packages/devtools-frontend/REVISION, minor versions included (DEV.md, "Working on the
+# frontend"), and opens an issue for it. It builds nothing: the update itself is done by hand.
+#
+# Chromium Dash's JSON endpoint (the one build.ts --latest reads) has no documentation nor promise:
+# its answer is checked, and a run fails, rather than passes, when it is not what is expected.
+name: Chrome update
+
+on:
+  schedule:
+    - cron: '17 3 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: chrome-update
+  cancel-in-progress: false
+
+jobs:
+  check:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            packages/devtools-frontend/REVISION
+            packages/devtools-frontend/package.json
+          sparse-checkout-cone-mode: false
+
+      - name: Stable Chrome
+        id: stable
+        run: |
+          curl -fsS --retry 3 --max-time 30 \
+            'https://chromiumdash.appspot.com/fetch_releases?channel=Stable&platform=Mac&num=1' > release.json
+          node -e '
+            const [release] = JSON.parse(require("fs").readFileSync("release.json", "utf8"));
+            const version = release?.version, devtools = release?.hashes?.devtools;
+            if (!/^\d+(\.\d+){3}$/.test(version ?? "") || !/^[0-9a-f]{40}$/.test(devtools ?? ""))
+              throw new Error("Chromium Dash answered without a version or a devtools commit");
+            console.log(`version=${version}\ndevtools=${devtools}`);
+          ' >> "$GITHUB_OUTPUT"
+
+      - name: Open an issue if it ships another frontend
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.stable.outputs.version }}
+          DEVTOOLS: ${{ steps.stable.outputs.devtools }}
+        run: |
+          pinned=$(tr -d '[:space:]' < packages/devtools-frontend/REVISION)
+          chrome=$(node -p "require('./packages/devtools-frontend/package.json').chrome")
+          echo "Pinned: Chrome $chrome, devtools $pinned. Stable: Chrome $VERSION, devtools $DEVTOOLS."
+          [ "$pinned" = "$DEVTOOLS" ] && exit 0
+
+          title="Update the DevTools frontend to Chrome $VERSION"
+          open=$(gh issue list --repo "$GITHUB_REPOSITORY" --state open --search "in:title \"Update the DevTools frontend to Chrome\"" \
+            --json number,title --jq '.[] | "\(.number)\t\(.title)"')
+          if printf '%s\n' "$open" | cut -f2 | grep -qxF "$title"; then
+            echo "Already open: $title"
+            exit 0
+          fi
+
+          new=$(gh issue create --repo "$GITHUB_REPOSITORY" --title "$title" --body "$(cat <<EOF
+          Stable Chrome is now $VERSION, which ships devtools-frontend [\`$DEVTOOLS\`](https://chromium.googlesource.com/devtools/devtools-frontend/+/$DEVTOOLS); \`REVISION\` pins \`$pinned\` (Chrome $chrome).
+
+          \`\`\`bash
+          pnpm --filter @devtools-anywhere/devtools-frontend update
+          \`\`\`
+
+          Then as in DEV.md, "Working on the frontend": the patches, \`pnpm test\`, \`pnpm licenses:update\`, and the changelogs.
+
+          Opened by \`.github/workflows/chrome-update.yml\`.
+          EOF
+          )")
+          echo "Opened $new"
+
+          # An older update not done yet is replaced by this one.
+          printf '%s\n' "$open" | while IFS=$'\t' read -r number old; do
+            [ -n "$number" ] || continue
+            gh issue close "$number" --repo "$GITHUB_REPOSITORY" --reason "not planned" --comment "Superseded by $new."
+          done

.github/workflows/ci.yml

@@ -1,6 +1,7 @@
 # Checks every push to main and every pull request: lint, types, the DevTools frontend built from
 # source at the pinned REVISION, and all tests against Chrome for Testing at the version the
-# frontend comes from (the packages' "chrome" field).
+# frontend comes from (the packages' "chrome" field). Not the pushes to the development branches
+# (dev/x.y.0): they are checked by the release pull request, or by hand (workflow_dispatch).
 #
 # Caches (actions/cache: a key that misses is saved at the end of the job; a hit is not saved
 # again):

.gitignore

@@ -15,3 +15,4 @@ Thumbs.db
 
 node_modules/
 dist/
+dist-test/

CHANGELOG.md

@@ -4,6 +4,33 @@ All packages share one version and are released together (see DEV.md, "Releasing
 
 ## Unreleased
 
+## 0.3.0
+
+Based on Chrome 156 (156.0.8078.80).
+
+- Same-origin iframes, as in Chrome: Elements expands them; each has its frame in the Page tree and its execution context in the Console's context menu, with its console messages and errors; Styles shows its own sheets and media; Network tags its requests with its frame; highlighting, inspect mode and Input reach into it. Iframes in shadow trees and same-origin `<object>` and `<embed>` documents are frames too; `Page.getResourceTree` lists each frame's own resources. Logs and requests an iframe makes before its load event are missing (except for srcdoc and blank iframes), and its navigations are reported once loaded.
+- Cross-origin iframes whose page loads the probe too, when each side trusts the other (`data-frame-origins` in the parent, `data-parent-origins` in the iframe; the Vite options `frameOrigins` and `parentOrigins`): they are child targets, as Chrome's out-of-process iframes, through `Target.setAutoAttach` and messages routed by `sessionId`, in every setup (embedded, shell mode, remote). Elements shows their document under the `<iframe>` (`DOM.getFrameOwner`), the Console their contexts; input over them reaches them, and wheels chain back to the parent. Each client attaching them gets a session of its own, as in Chrome (the page's DevTools and a remote agent at once). Their targets survive navigations, and iframes in them link level by level.
+- Sandboxed iframes without `allow-same-origin` (with a `src` of the page's origin, `about:blank` or `srcdoc`) whose document loads the probe, when the parent lists `sandboxed` in `data-frame-origins` and the document the parent's origin in `data-parent-origins`: they are merged into the parent's target, as Chrome keeps them there, with no child target. Elements shows their document under the `<iframe>`, the Console their context and messages, Network their requests, Sources their scripts, Styles their sheets; highlighting, inspect mode and Input reach into them. Off by default; those with a `src` of another origin, same-site too, are still refused. The remaining gaps are in the usage guide's limitations.
+- `DOM.getNodeForLocation` takes document coordinates, not viewport ones, and `DOM.scrollIntoViewIfNeeded` centers an element that is out of view, as in Chrome. Hovering with `Input.dispatchMouseEvent` sends `pointerout`, `pointerover`, `mouseout`, `mouseover` in Chrome's order.
+- `Page.navigatedWithinDocument` for `history.pushState`, `replaceState`, fragment changes and navigations the Navigation API intercepts, in the top page and in frames.
+- Requests the page made before the probe ran are reported from Resource Timing (without stack, headers or body), as Chrome reports them too.
+- `DOM.requestChildNodes` no longer sends children the client already has, as in Chrome: the frontend asking twice emptied an expanded iframe.
+- In shell mode, a reloaded frontend starts a new session, as in Chrome.
+- In shell mode, `Emulation.setDeviceMetricsOverride` and `clearDeviceMetricsOverride` work from any client of the page (a remote agent, a `createCdpSession`), not only the shell's frontend: the last override set applies, and a client's clear or end only lifts its own; a remote client's override survives page reloads, re-applied in the order the clients attached, as in Chrome. Their parameters are checked with Chrome's errors; outside shell mode the two commands fail, saying so.
+- Commands the page cannot carry out (auto dark mode, turning focus emulation on, the pinch zoom, background services, bypassing the Service Worker, autofill addresses, the security isolation status, browser feature flags, network throttling, enabling domains whose events only the browser has such as the profilers, …) fail with "Not supported in the page: <why>" instead of succeeding without effect or answering with made-up data; `CSS.getEnvironmentVariables` returns the env() values the page resolves; those that could be done in the page still succeed, and are listed in the roadmap.
+- An embedded frontend that reloads is told by its command ids starting again, not by its frame's load event, which comes after its first commands: what it enabled at once is no longer ended by the load.
+- `CSS.createStyleSheet` fails with "Frame not found" for an unknown `frameId`, as in Chrome.
+- Merged sandboxed iframes, as in Chrome: each new document gets new ids, and a reloaded one's execution contexts are destroyed and not reused, while a document linking again keeps its own; DOM undo and redo cover the page and its merged frames in one history, in the order of the edits, CSS edits in the frames included; a frame not answering within 1 s for its document, a node or a point is taken as not answering; `Page.navigate` takes a sandboxed iframe's `frameId`, merged or not; after `Page.disable`, the frames' queued events are no longer sent.
+
+### API changes
+
+Public API, as in `packages/*/etc/*.public.api.md`: additions only, nothing removed, renamed or changed.
+
+- Probe script attributes (`devtools-anywhere`): `data-frame-origins` (origins of cross-origin iframes this page's DevTools debugs, space-separated; `sandboxed` for its sandboxed iframes) and `data-parent-origins` (origins of the pages that may debug this one in their iframe).
+- Vite plugin options (`@devtools-anywhere/vite-plugin`): `frameOrigins` and `parentOrigins` (arrays), written into those two attributes.
+- CDP: commands the page cannot carry out now fail with -32000 "Not supported in the page: <reason>" instead of succeeding without effect (listed above); `CSS.createStyleSheet` with an unknown `frameId` fails. Other changes to CDP answers and events are behavior fixes towards Chrome, listed above.
+- The messages between the probe, the shell and the remote server gained the internal methods `DevtoolsAnywhere.attach` and `DevtoolsAnywhere.metrics`: use the probe and `@devtools-anywhere/remote-server` of the same version.
+
 ## 0.2.0
 
 Based on Chrome 156 (156.0.8078.80).

CHANGELOG.zh-CN.md

@@ -4,6 +4,33 @@
 
 ## Unreleased
 
+## 0.3.0
+
+基于 Chrome 156（156.0.8078.80）。
+
+- 支持同源 iframe，与 Chrome 一致：Elements 能展开；每个 iframe 在 Page 的 frame 树里有自己的 frame，在 Console 的上下文菜单里有自己的执行上下文，带着它的 console 消息和错误；Styles 显示它自己的样式表和媒体条件；Network 的请求标出所属 frame；高亮、检查模式和 Input 都能进入 iframe。shadow tree 里的 iframe 以及同源 `<object>`、`<embed>` 的文档同样是 frame；`Page.getResourceTree` 列出每个 frame 自己的资源。iframe 在 load 事件之前的日志和请求拿不到（srcdoc 和空 iframe 除外），导航要加载完成后才报出。
+- 支持跨域 iframe：iframe 页面也加载探针，并且双方互相信任时（父页面配 `data-frame-origins`，iframe 页面配 `data-parent-origins`；Vite 选项为 `frameOrigins`、`parentOrigins`），它们作为子 target 接入，和 Chrome 的进程外 iframe 一样，通过 `Target.setAutoAttach` 和按 `sessionId` 转发的消息工作，直接嵌入、外壳模式、远程调试都支持。Elements 把它们的文档显示在 `<iframe>` 下（`DOM.getFrameOwner`），Console 里有它们的执行上下文；落在它们上面的输入会转进去，滚轮滚到底会传回父页面。每个接入它们的客户端各有自己的会话，与 Chrome 一致（比如页面上的 DevTools 和远程连入的 agent 同时调试）。导航后 target 保留，iframe 里再嵌的跨域 iframe 逐级接入。
+- 支持没有 `allow-same-origin` 的沙箱 iframe（`src` 与页面同源、`about:blank` 或 `srcdoc`）：沙箱文档加载探针，父页面的 `data-frame-origins` 写 `sandboxed`、沙箱文档的 `data-parent-origins` 写父页面的源时，它并入父页面的 target，和 Chrome 一样留在那里，不开子 target。Elements 把它的文档显示在 `<iframe>` 下，Console 里有它的执行上下文和消息，Network 有它的请求，Sources 有它的脚本，Styles 有它的样式表；高亮、检查模式和 Input 都能进入它。默认关闭；`src` 跨源的仍然拒绝，同站的也一样。其余差异见使用说明的限制。
+- `DOM.getNodeForLocation` 按文档坐标而不是视口坐标计算；`DOM.scrollIntoViewIfNeeded` 对不在视口内的元素滚到居中，与 Chrome 一致。`Input.dispatchMouseEvent` 悬停时按 Chrome 的顺序发出 `pointerout`、`pointerover`、`mouseout`、`mouseover`。
+- `history.pushState`、`replaceState`、hash 变化以及 Navigation API 拦截的导航会发出 `Page.navigatedWithinDocument`，顶层页面和 frame 都是。
+- 探针运行之前页面发出的请求，改为从 Resource Timing 补报（没有调用栈、请求头和请求体），Chrome 同样会报这些请求。
+- `DOM.requestChildNodes` 不再重复发送客户端已有的子节点，与 Chrome 一致：前端请求两次时，展开的 iframe 会变成空白。
+- 外壳模式下重新加载的前端开始一个新会话，与 Chrome 一致。
+- 外壳模式下，页面的任何客户端（远程连入的 agent、`createCdpSession`）都能用 `Emulation.setDeviceMetricsOverride` 和 `clearDeviceMetricsOverride`，不再只限外壳自带的前端：以最后一次设置为准，客户端清除或断开时只撤销自己的设置；远程客户端的设置在页面重新加载后仍然有效，按客户端连上的先后重新应用，与 Chrome 一致。参数按 Chrome 的规则校验，报错相同；非外壳模式下这两条命令返回错误并说明原因。
+- 页面做不到的命令（自动深色模式、开启焦点模拟、双指缩放、后台服务记录、绕过 Service Worker、自动填充地址、安全隔离状态、浏览器功能开关、网络限速、启用性能分析器等只有浏览器才有事件的域等）改为返回错误「Not supported in the page: <原因>」，不再假装成功或编造数据；`CSS.getEnvironmentVariables` 返回页面解析出的 env() 值；能在页面里实现、只是还没做的仍返回成功，并记进路线图。
+- 直接嵌入的前端重新加载后，改为按命令 id 重新从 1 开始来判断，不再看 iframe 的 load 事件：load 晚于新前端的第一批命令，会把它刚启用的东西又关掉。
+- `CSS.createStyleSheet` 遇到不存在的 `frameId` 时报错「Frame not found」，与 Chrome 一致。
+- 并入的沙箱 iframe 与 Chrome 对齐：每个新文档分配新的 id，重新加载时销毁旧的执行上下文且 id 不复用，同一文档重新链接时沿用原来的；DOM 的撤销和重做把页面和并入的 frame 放在同一个历史里，按编辑先后，frame 里的 CSS 编辑也在内；向 frame 取文档、节点或坐标 1 秒内没有应答，按未应答处理；`Page.navigate` 接受沙箱 iframe 的 `frameId`，并入与否都行；`Page.disable` 之后不再发出 frame 排队的事件。
+
+### 接口变化
+
+公开 API（以 `packages/*/etc/*.public.api.md` 为准）只有新增，没有删除、改名或改动。
+
+- 探针脚本属性（`devtools-anywhere`）：新增 `data-frame-origins`（本页 DevTools 可以调试的跨域 iframe 的源，空格分隔；写 `sandboxed` 调试它的沙箱 iframe）和 `data-parent-origins`（可以在 iframe 里调试本页的父页面的源）。
+- Vite 插件选项（`@devtools-anywhere/vite-plugin`）：新增 `frameOrigins` 和 `parentOrigins`（数组），写进上面两个属性。
+- CDP：页面做不到的命令改为报错 -32000「Not supported in the page: <原因>」，不再返回成功却没有效果（见上文）；`CSS.createStyleSheet` 遇到不存在的 `frameId` 时报错。CDP 应答和事件的其他变化都是向 Chrome 对齐的行为修正，见上文。
+- 探针、外壳和远程服务之间的消息新增内部方法 `DevtoolsAnywhere.attach` 和 `DevtoolsAnywhere.metrics`：探针和 `@devtools-anywhere/remote-server` 请使用同一版本。
+
 ## 0.2.0
 
 基于 Chrome 156（156.0.8078.80）。