@deepseek-ai/dsh-experimental-inspector 0.2.0-rc.1 → 0.2.1-alpha.1

package/README.i18n.yaml

@@ -3,35 +3,38 @@
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/experimental/inspector/README.md
 /:
-  en: ff4e1ec5ccd5d0b3
-  zh: d29383843e3decc8
+  en: b5b7ccdfa1cc2907
+  zh: d575593a7efa37fd
 /deepseek-ai-dsh-experimental-inspector:
   en: 1060bee3ef37134d
   zh: 7a7b0096714f4279
 /deepseek-ai-dsh-experimental-inspector/summary:
-  en: 65ed8a4c21915cc0
-  zh: dcb1ae527e6bfc8c
+  en: e2a633d32f00aa99
+  zh: 1d48f445800e3a35
 /deepseek-ai-dsh-experimental-inspector/table-of-contents:
-  en: 2650c2b268bf6dff
-  zh: 43a08863d2c75ad1
+  en: 331f844c32631a82
+  zh: a9bc365f7d61d9ed
+/deepseek-ai-dsh-experimental-inspector/use-this-package:
+  en: 426fcb436dd12d08
+  zh: 1eb502409031216e
 /deepseek-ai-dsh-experimental-inspector/runtime-layout:
-  en: a713d2910acf48c9
-  zh: 152dcdba78e73115
+  en: 30dad7b7fe3b3465
+  zh: 2bda395981802f59
 /deepseek-ai-dsh-experimental-inspector/configuration:
-  en: 95f1c9c4ea6ba8b8
-  zh: 16b56e2dd8c7408a
+  en: d094842893700446
+  zh: 7a7f880ba795948f
 /deepseek-ai-dsh-experimental-inspector/observation-api:
   en: d32f994e6c9d0c4a
   zh: ac2f35f5799aeae0
 /deepseek-ai-dsh-experimental-inspector/cordis-tree-inspection:
-  en: 9abe1a8cd52386fb
-  zh: a5e96ec22a503153
+  en: d2a470558b97acbd
+  zh: 2a7d0ce6951b7b52
 /deepseek-ai-dsh-experimental-inspector/host-fetch-capture:
   en: 187859f65acc45d7
   zh: 606e93905c8275e6
 /deepseek-ai-dsh-experimental-inspector/security:
-  en: 2372c96aba1ce7e6
-  zh: 823ceaa99cfb1f6a
+  en: dc390db1bce00de1
+  zh: c4257690ffcabebc
 /deepseek-ai-dsh-experimental-inspector/model-experience:
   en: 6ac8fb2f45b3a97c
   zh: 9162ffb1a133e11b
@@ -39,8 +42,8 @@
   en: ca75c51c89c2c9b0
   zh: 64715dc7e6d02f71
 /deepseek-ai-dsh-experimental-inspector/known-limitations-and-deferred-work:
-  en: a35e1559aff5e7aa
-  zh: fbe20422dbe4a0f6
+  en: 74e9eb329f240bb7
+  zh: 25612a9b993582c0
 /deepseek-ai-dsh-experimental-inspector/known-limitations-and-deferred-work/dev-note:
-  en: 59a59a4788c80163
-  zh: db23a6b9dc0880ba
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,6 +1,6 @@
 ---
 description: "Experimental Chrome DevTools inspection for Host and browser Client Cordis runtimes, including Console evaluation, Sources, Network capture, Elements trees, and a CDP-independent query API."
-kind: "package-bundle"
+kind: "package-reference"
 ---
 
 # @deepseek-ai/dsh-experimental-inspector
@@ -11,10 +11,11 @@ English | [中文](README.zh.md)
 
 Inspect one running dsh Host and its browser Clients in Chrome DevTools: Host and Client Console contexts, Host Sources and debugging, captured Host fetches, and a shared Cordis tree, with all CDP state in a Worker.
 
-The Inspector stays off the default plugin list. Install its bundle explicitly with `dsh plugin --profile web add @deepseek-ai/dsh-experimental-inspector`. Its [`cordis.patch.yml`](cordis.patch.yml) mounts the installed package; `pnpm run demo:inspector` mounts the source tree. The Host row needs a Web server. The Worker never accesses live Cordis objects: the shared collector projects them into validated snapshots before transport.
+The optional [Developer Tools bundle](../inspector-profile/README.md) enables both NodeJS Inspector and Session Log, including Host fetch capture. Web startup does not require or accept `--inspect`.
 
 ## Table of Contents
 
+- [Use this package](#use-this-package)
 - [Runtime layout](#runtime-layout)
 - [Configuration](#configuration)
 - [Observation API](#observation-api)
@@ -27,23 +28,44 @@ The Inspector stays off the default plugin list. Install its bundle explicitly w
 
 -----
 
+<a id="use-this-package"></a>
+## Use this package
+
+For trusted local development, `pnpm run demo:inspector` explicitly mounts the source overlay through the normal Web profile. The Host prints a debugging URL; Chrome is required to inspect that target. Fetch capture includes secrets, and the local debugging endpoint permits arbitrary code execution.
+
+The bundle sets `experimental-inspector` to `disabled: false` with `captureFetch: true`. The Host's optional `--inspect` argument hook only opens an external Chrome window; it does not control whether the Inspector runs.
+
+When this component is enabled, **Ctrl/Cmd+Shift+.** toggles **NodeJS Inspector** in the full-width bottom panel without requiring a selected Session. Drag its top edge to resize it, taking space from the content above; the selected height is retained across collapse and navigation. The focused divider also accepts Up/Down, Home and End. Its iframe loads on the first open and remains mounted while collapsed and across Session or main-panel navigation; unloading the component resets it. The X button and shortcut restore the opening control's focus when that control remains connected. The iframe automatically connects to this Host and opens Console; the manual Connection panel is omitted. Each embedded frontend shows Host and only its embedding page's Client in Console, Sources and the Cordis tree. The printed `devtools://` URL shows all Clients.
+
+The Host serves the mirrored DevTools frontend at the application-relative `inspector/devtools/devtools_app.html` path, using the existing Web login. The `inspector/devtools` prefix redirects to that entry; GET and HEAD serve files, missing resources return 404, and other methods return 405. Its `cdp` WebSocket route authenticates the same browser session and forwards only to this Inspector's Worker page target. The bottom panel supplies its claimed `clientSourceId` to the entry and automatic WebSocket endpoint; the selection follows that logical Client across reconnects. An absent selector includes all Clients, an unavailable selected Client leaves Host visible, and empty or repeated selectors reject the upgrade with 400. Explicit `ws` or `wss` query parameters override the automatic endpoint, including its selection.
+
+The build compiles the official `chrome-devtools-frontend@1.0.1638082` TypeScript sources with the root workspace's Vite `8.0.16`. This npm snapshot is an ancestor of the Chromium 150 release branch, not an exact copy of its later stable release. The [source configuration](scripts/devtools/source.ts) and package manifest fix the version. Normal npm installation supplies the source and toolchain; building needs no appspot access, browser download, browser launch, or PAK extraction. Neither workspace installation nor published-package installation runs a DevTools download hook.
+
+The [distribution build](scripts/build-devtools.ts) emits ESM entries, shared chunks, explicit Workers, injected scripts, and runtime assets into `lib/devtools`. It preserves original module-relative resource URLs, including deployment prefixes. CSS text modules, image variables, and minimal English locale constants replace GN-generated inputs without modifying npm sources. The frontend uses English UIStrings directly from upstream modules, with no translation files or dictionary generator. Other language preferences resolve to English. All upstream panels, including Lighthouse, remain included. Memory retains its parser Worker; Performance records Host CPU. Published packages contain the built assets, integrity manifest, and Chromium license, not the build-time npm source or Vite dependencies.
+
+The frontend uses browser runtime adapters and excludes Node-only transports at build time, without an import map. Its same-origin connection bootstrap precedes the application entry. The bottom panel adds `disableLocaleInfoBar=true`; the bootstrap sets DevTools' own `disable-locale-info-bar` preference without changing its language. Updating the frontend requires changing the npm pin and source configuration together, then rerunning the panel and Worker checks; incompatible source edits fail the build.
+
 <a id="runtime-layout"></a>
 ## Runtime layout
 
-The Host plugin starts the Worker and connects a dedicated `MessagePort`. The Client plugin reads the injected `globalThis.__DSH_INSPECTOR__` bootstrap and opens a separate authenticated WebSocket directly to the Worker; a page opened before the Host row was enabled has no bootstrap, fails its Client plugin with a reload instruction, and inspects only after a reload. Chrome DevTools connects to the Worker's CDP WebSocket. A private `node:inspector.Session` per DevTools connection attaches from the Worker to the Host main thread, so Host Console evaluation, Sources, breakpoints, and resume remain available while Host JavaScript is paused.
+The Worker never accesses live Cordis objects: the shared Host/Client collector projects them into validated snapshots before transport. Cordis owns plugin composition, `ctx.inspector` registration, bootstrap injection, and disposal. A late-loading Client fetches its bootstrap through an authenticated Host route. Bootstrap transport and source-setup failures warn and retain connection-reset recovery for both injected and fetched startup; invalid bootstrap data or service-registration failures reject startup. Source replacement joins old service-consumer cleanup before claiming another source, and unloading an active plugin cancels its pending bootstrap refresh.
+
+The Host plugin starts the Worker and connects a dedicated `MessagePort`. The Client uses injected or fetched browser-source parameters to open an authenticated WebSocket directly to the Worker; it receives no DevTools URL. Chrome DevTools connects to the Worker's CDP WebSocket. A private `node:inspector.Session` per DevTools connection attaches from the Worker to the Host main thread, so Host debugging remains available while Host JavaScript is paused.
 
 The source tree follows those execution environments: `client/` and `host/` provide mirrored adapter entry paths, `worker/` contains only Worker-thread orchestration and Chrome protocol state, and `shared/` contains environment-independent Cordis and network models, normalized realm backend interfaces, and the internal bridge protocol. Worker-side Client and Host adapters are mirrored under `worker/realms/`; a Client adapter in that directory still executes in the Worker.
 
 Host and Client producers send internal observation records rather than CDP messages. Records contain a source generation, sequence, source-clock timestamp, topic, and JSON payload. The Worker validates every process or network frame, owns source state and retention, and translates recognized topics to standard CDP domains.
 
-Client sources declare typed Runtime, Console, and read-only Sources capabilities. `Runtime.enable` publishes the real Host execution context and one synthetic context for every connected Client source. Selecting a Client context routes evaluation, property access, function calls, promise awaiting, and object release to that browser realm. Client Console arguments use the same session-local object table, while `Debugger.enable` publishes the built `lib/client.js` catalog and `Debugger.getScriptSource` reads bounded content chunks. Client-script breakpoints, step, and call frames remain unsupported; target-wide pause and resume control the Host debugger only.
+Client sources declare typed Runtime, Console, and read-only Sources capabilities. `Runtime.enable` publishes only the default Host execution context and one synthetic context for every connected Client included in that DevTools connection; Node's internal and additional VM contexts are not listed. Selecting a Client context routes evaluation, property access, function calls, promise awaiting, and object release to that browser realm. Client Console arguments use the same session-local object table, while `Debugger.enable` publishes the built `lib/client.js` catalog and `Debugger.getScriptSource` reads bounded content chunks. Source-map URLs come from the loaded script's `sourceMappingURL` trailer, including combo URLs and deployment prefixes. Client-script breakpoints, step, and call frames remain unsupported; target-wide pause and resume control the Host debugger only.
+
+A Client synchronously closes its source on `pagehide` and reconnects with the same logical identity on `pageshow` after a cached-page restore. Switching a live page to the background does not disconnect it. Closed generations cannot publish delayed execution contexts or script catalogs.
 
 Both plugin faces run the same browser-safe Cordis collector. It converts reachable Context and Fiber objects into a versioned `CordisTreeSnapshot`; the Worker stores that CDP-independent representation and projects each Host or Client source into the Elements panel.
 
 <a id="configuration"></a>
 ## Configuration
 
-The Host plugin injects `webServer` and accepts these fields:
+The Host plugin injects `webServer` and `connection` and accepts these fields:
 
 | Field | Default | Meaning |
 |---|---:|---|
@@ -98,15 +120,15 @@ Publishing validates lossless JSON and schedules delivery without waiting for th
 <a id="cordis-tree-inspection"></a>
 ## Cordis tree inspection
 
-The Elements document has fixed `<host>` and `<clients>` containers. `<host>` contains the Host root Context; `<clients>` contains one `<client>` per Client source, and each `<client>` contains that realm's root Context. The Cordis root Fiber is omitted. Every other Fiber is a child of `fiber.parent`, owns exactly one Context child for `fiber.ctx`, and carries only `uid="<Cordis Fiber.uid>"`; Context elements have no attributes. Context-only `extend()`, `isolate()`, and `intercept()` layers remain direct Context descendants.
+The Elements document has fixed `<host>` and `<clients>` containers. `<host>` contains the Host root Context; `<clients>` contains one `<client>` per Client source, and each `<client>` contains that realm's root Context. The Cordis root Fiber is omitted. After removing Cordis service-call `shadow` wrappers, every other Fiber is a child of `fiber.parent`, owns exactly one Context child for `fiber.ctx`, and carries only `uid="<Cordis Fiber.uid>"`; Context elements have no attributes. Context-only `extend()`, `isolate()`, and `intercept()` layers remain direct Context descendants.
 
 Host and Client publish the same nested `CordisTreeSnapshot` type. Context and Fiber nodes carry opaque object handles for realm-local object lookup; Fiber nodes additionally carry Cordis `uid`. The Worker composes those realm snapshots into one `{ host, clients }` inspection tree. It assigns `BackendNodeId` values per source generation; each DevTools connection assigns its own `NodeId` values; `DOM.resolveNode` asks the owning Host or Client Runtime for a connection-local `RemoteObjectId`. `DOM.requestNode` maps that object id back to the same Elements node. `ctx.inspector.cordis.getTree()` and `DSHInspector.getCordisTree` read the detached consumer-neutral tree without routing handles or CDP ids.
 
-Node delivery is depth-limited per DevTools connection: `DOM.getDocument` serves three document levels when the caller omits `depth`, withheld levels advertise `childNodeCount`, and expansion fetches them through `DOM.requestChildNodes` (`depth: -1` for a whole subtree). NodeIds leaving through `DOM.performSearch`, `DOM.requestNode`, or `DOM.pushNodesByBackendIdsToFrontend` first push the not-yet-sent ancestor levels as `DOM.setChildNodes` events.
+Node delivery is depth-limited per DevTools connection: `DOM.getDocument` serves three document levels when the caller omits `depth`, withheld levels advertise `childNodeCount`, and expansion fetches them through `DOM.requestChildNodes` (`depth: -1` for a whole subtree). Repeated expansion requests deliver only missing child lists, preserving existing frontend node objects and deeper loaded descendants. NodeIds leaving through `DOM.performSearch`, `DOM.requestNode`, or `DOM.pushNodesByBackendIdsToFrontend` first push the not-yet-sent ancestor levels as `DOM.setChildNodes` events.
 
-Sources publish complete snapshots, while the Worker compares stable backend node identities before notifying DevTools. Unchanged snapshots emit no DOM event; additions, removals, and attribute changes use node-level CDP events, inserted-node payloads withhold their subtree, and sibling reordering replaces only that parent's children. Existing `NodeId` values and unaffected Elements expansion remain stable.
+Sources publish complete snapshots, while the Worker compares stable backend node identities before notifying DevTools. Unchanged snapshots emit no DOM event. Changes to a known node's undelivered child list send only `DOM.childNodeCountUpdated`; expanding it fetches the complete current child list. Delivered child lists receive node-level insertion and removal events, inserted-node payloads withhold their subtree, and sibling reordering replaces only that parent's children. Attribute changes target delivered nodes only. Re-fetching a document replaces its delivered depth; `DOM.describeNode` does not attach nodes to the frontend tree. Existing `NodeId` values and unaffected Elements expansion remain stable.
 
-When a Client disconnects, its Console execution context and live object ids are destroyed immediately. With disconnected-tree retention enabled, Elements keeps the last tree unchanged while connection state remains in the inspection model rather than becoming an unreviewed DOM attribute. Reconnection keeps the logical source id, creates a new synthetic CDP context id for the new transport generation, and replaces the stale tree after its complete snapshot arrives. The Client retains its logical id in `sessionStorage` and claims it through Web Locks for the page lifetime, so refresh reuses the id while a duplicated live tab receives a new one. The Worker retains at most `maxDisconnectedCordisTrees` such snapshots; zero removes them immediately.
+When a Client disconnects, its Console execution context and live object ids are destroyed immediately, removing it from Console's context selector. With disconnected-tree retention enabled, Elements keeps the last tree and adds the boolean `disconnected` attribute to its `<client>` element. Reconnection keeps the logical source id, creates a new synthetic CDP context id for the new transport generation, and removes the attribute when its complete snapshot replaces the stale tree. Attribute changes arrive incrementally without refreshing DevTools. The Client retains its logical id in `sessionStorage` and claims it through Web Locks for the page lifetime, so refresh reuses the id while a duplicated live tab receives a new one. The Worker retains at most `maxDisconnectedCordisTrees` such snapshots; zero removes them immediately.
 
 <a id="host-fetch-capture"></a>
 ## Host fetch capture
@@ -120,6 +142,8 @@ After response headers arrive, a caller-side abort can stop the observer's clone
 <a id="security"></a>
 ## Security
 
+Client selection limits one DevTools connection's realm sessions, DOM projection and diagnostic queries; it does not stop collection or change the shared observation API. It is a display filter, not authorization: a trusted debugging user can open an unfiltered connection, and Host evaluation retains its existing authority.
+
 The CDP target grants arbitrary code execution in both Host and connected Client realms through `Runtime.evaluate`; Host Debugger operations provide additional control. Full fetch capture includes secrets. The Worker therefore accepts only a `127.0.0.1` bind address. Client ingest additionally requires a random WebSocket subprotocol token injected by the Host and rejects non-loopback origins unless explicitly configured. The CDP socket itself has no token; loopback binding is its only access control.
 
 <a id="model-experience"></a>
@@ -135,6 +159,8 @@ None; this package neither assembles nor sends a provider request.
 
 <a id="known-limitations-and-deferred-work"></a>
 
+- **Memory and Performance inspect the Host** — Memory captures the Host heap; Performance records Host CPU samples. Client Runtime contexts do not expose browser heap snapshots or rendering traces.
+- **The same-origin relay runs on the Host main thread** — pausing Host JavaScript also pauses this relay. Use the printed direct Worker DevTools endpoint for breakpoint debugging and resume control.
 - **Client active debugging is unsupported** — Console events, Runtime evaluation, RemoteObject access, and read-only `lib/client.js` Sources work. Client-script debugger requests return explicit unsupported errors; target-wide pause and resume control the Host only.
 - **Client Sources expose the Inspector bundle only** — other page scripts are not cataloged by this package.
 - **Client evaluation uses page JavaScript** — page Content Security Policy can block dynamic evaluation, and the synthetic context does not provide DevTools command-line helpers or native REPL declaration semantics.
@@ -152,5 +178,3 @@ None; this package neither assembles nor sends a provider request.
 None.
 
 </details>
-
-**Runtime invariant:** No companion is published. Wire parsing, generations, Worker lifecycle, and CDP sessions reject invalid relationships in their owning operations.

package/README.zh.md

@@ -1,6 +1,6 @@
 ---
 description: "面向 Host 与浏览器 Client Cordis 运行时的实验性 Chrome DevTools 检查，包括 Console 求值、Sources、Network 采集、Elements 树和独立于 CDP 的查询 API。"
-kind: "package-bundle"
+kind: "package-reference"
 ---
 
 # @deepseek-ai/dsh-experimental-inspector
@@ -11,10 +11,11 @@ kind: "package-bundle"
 
 在 Chrome DevTools 中检查一个运行中的 dsh Host 及其浏览器 Client：Host 与 Client Console context、Host Sources 与调试、Host fetch 采集和共享 Cordis 树，全部 CDP 状态都在 Worker 中。
 
-Inspector 不在默认插件列表中显示。使用 `dsh plugin --profile web add @deepseek-ai/dsh-experimental-inspector` 显式安装其 bundle。其 [`cordis.patch.yml`](cordis.patch.yml) 挂载已安装的包；`pnpm run demo:inspector` 则挂载源码树。Host 行需要 Web 服务器。Worker 不访问实时 Cordis 对象；共享 collector 会在传输前把它们投影成已验证快照。
+可选的[开发者工具组合包](../inspector-profile/README.zh.md) 同时启用 NodeJS 诊断和会话数据诊断，并开启 Host fetch 采集。Web startup 不需要也不接受 `--inspect`。
 
 ## 目录
 
+- [使用本包](#use-this-package)
 - [运行时布局](#runtime-layout)
 - [配置](#configuration)
 - [观测 API](#observation-api)
@@ -27,23 +28,44 @@ Inspector 不在默认插件列表中显示。使用 `dsh plugin --profile web a
 
 -----
 
+<a id="use-this-package"></a>
+## 使用本包
+
+可信本地开发可通过 `pnpm run demo:inspector`，经普通 Web profile 显式挂载源码 overlay。Host 会打印调试链接，检查该目标需要 Chrome。fetch 采集包含密钥等敏感信息，本地调试端口允许执行任意代码。
+
+组合包将 `experimental-inspector` 设置为 `disabled: false`，并设置 `captureFetch: true`。Host 可选的 `--inspect` 参数处理仅负责打开外部 Chrome 窗口，不控制 Inspector 是否运行。
+
+启用此组件后，按 **Ctrl/Cmd+Shift+.** 可展开或收起整宽底部面板中的 **NodeJS 诊断**，无需选中 Session。拖动上边缘可调整面板高度，占用上方内容的可用空间；收起和切换页面时保留所选高度。聚焦分隔条后也可使用上/下方向键、Home 和 End。iframe 首次展开时加载，收起、切换 Session 或主面板时保持挂载；卸载此组件会重置前端。X 按钮和快捷键会在原打开控件仍连接时恢复其焦点。iframe 自动连接当前 Host 并打开 Console；不包含手动 Connection 面板。每个内嵌前端的 Console、Sources 和 Cordis 树只显示 Host 与嵌入它的页面所对应的 Client；打印的 `devtools://` 链接仍显示全部 Client。
+
+Host 在相对于应用根目录的 `inspector/devtools/devtools_app.html` 路径提供镜像后的 DevTools 前端，沿用现有 Web 登录鉴权。`inspector/devtools` 前缀重定向到该入口；GET 和 HEAD 提供文件，缺失资源返回 404，其他方法返回 405。其 `cdp` WebSocket 路由鉴权同一浏览器会话，只转发到当前 Inspector 的 Worker page target。底部面板将已声明的页面 `clientSourceId` 传给入口及自动 WebSocket 端点，重连时继续选择同一逻辑 Client。没有选择参数时包含全部 Client；指定 Client 不在线时保留 Host；空值或重复参数以 400 拒绝升级。显式 `ws` 或 `wss` query 参数覆盖自动端点及其选择范围。
+
+构建使用官方 `chrome-devtools-frontend@1.0.1638082` TypeScript 源码及根 workspace 的 Vite `8.0.16`。该 npm 快照是 Chromium 150 发布分支的祖先，不是其后续稳定版的逐字节副本。[源码配置](scripts/devtools/source.ts)与包清单共同固定版本。普通 npm 安装提供源码和工具链；构建不需要 appspot、下载或启动浏览器，也不需要提取 PAK。workspace 安装和发布包安装都不运行 DevTools 下载 hook。
+
+[分发构建](scripts/build-devtools.ts)将 ESM 入口、共享 chunk、显式 Worker、注入脚本与运行时资源输出到 `lib/devtools`，保留原始模块相对资源 URL，包括部署子路径。CSS 文本模块、图片变量和最小英文 locale 常量替代 GN 生成输入，不修改 npm 源码。前端直接使用上游模块内的英文 UIStrings，不包含翻译文件或词条生成器，其他语言偏好回退英文。所有上游面板均保留，包括 Lighthouse。Memory 带有解析 Worker，Performance 记录 Host CPU。发布包包含构建资源、完整性清单和 Chromium license，不包含构建用 npm 源码或 Vite 依赖。
+
+前端在构建时选择浏览器运行时适配器、排除 Node 专用传输，不使用 import map。同源连接 bootstrap 先于应用入口执行。底部面板添加 `disableLocaleInfoBar=true`，bootstrap 设置 DevTools 自己的 `disable-locale-info-bar` 偏好，不改变语言。升级前端时，需要一起调整 npm 版本和源码配置，然后重跑面板和 Worker 检查；不兼容的源码变动会使构建失败。
+
 <a id="runtime-layout"></a>
 ## 运行时布局
 
-Host 插件启动 Worker 并连接专用 `MessagePort`。Client 插件读取注入的 `globalThis.__DSH_INSPECTOR__` bootstrap，直接向 Worker 打开一条独立、带鉴权的 WebSocket；在 Host 行启用前打开的页面没有 bootstrap，其 Client 插件会以刷新提示失败，刷新后才能被检查。Chrome DevTools 连接 Worker 的 CDP WebSocket。每条 DevTools 连接在 Worker 中独占一个连接 Host 主线程的 `node:inspector.Session`，因此 Host JavaScript 暂停时，Host Console 求值、Sources、断点和 resume 仍然可用。
+Worker 不访问实时 Cordis 对象；共享 Host/Client collector 会在传输前把它们投影成已验证快照。Cordis 负责插件组合、注册 `ctx.inspector`、注入 bootstrap 和 dispose（资源释放）。后加载的 Client 通过已鉴权的 Host 路由获取 bootstrap。初始注入与主动获取两条路径中，bootstrap 传输或 source 建立失败均记录警告并保留连接重置后的重试；bootstrap 数据非法或服务注册失败则使启动失败。替换 source 会等待旧服务消费者清理完成，再申请新 source；卸载已激活插件会取消其未完成的 bootstrap 刷新。
+
+Host 插件启动 Worker 并连接专用 `MessagePort`。Client 使用注入或主动获取的浏览器 source 参数，直接向 Worker 打开带鉴权的 WebSocket，不接收 DevTools URL。Chrome DevTools 连接 Worker 的 CDP WebSocket。每条 DevTools 连接在 Worker 中独占一个连接 Host 主线程的 `node:inspector.Session`，因此 Host JavaScript 暂停时仍可调试 Host。
 
 源码树遵循这些执行环境：`client/` 与 `host/` 提供镜像的适配器 entry path，`worker/` 只包含 Worker thread orchestration 与 Chrome protocol 状态，`shared/` 包含与环境无关的 Cordis 和 network model、规范化 realm 后端接口及内部 bridge protocol。Worker 侧 Client 与 Host 适配器镜像放在 `worker/realms/` 下；其中的 Client 适配器仍然在 Worker 中执行。
 
 Host 与 Client producer 发送内部观测记录，不发送 CDP 消息。记录包含 source generation、sequence、source 时钟时间、topic 和 JSON payload。Worker 验证每个进程或网络帧，独占 source 状态与保留历史，并把已识别 topic 转换成标准 CDP domain。
 
-Client source 声明类型化 Runtime、Console 和只读 Sources 能力。`Runtime.enable` 发布真实 Host execution context，并为每个已连接的 Client source 发布一个 synthetic context。选择 Client context 后，求值、属性读取、函数调用、Promise await 和对象释放都会路由到该浏览器 realm。Client Console argument 使用同一份会话本地 object table；`Debugger.enable` 发布构建后的 `lib/client.js` catalog，`Debugger.getScriptSource` 读取有界 content chunk。Client script 断点、step 和 call frame 仍不支持；target-wide pause 与 resume 只控制 Host debugger。
+Client source 声明类型化 Runtime、Console 和只读 Sources 能力。`Runtime.enable` 只发布默认 Host execution context，并为此 DevTools 连接范围内的每个已连接 Client 发布一个 synthetic context；不列出 Node internal 和额外 VM context。选择 Client context 后，求值、属性读取、函数调用、Promise await 和对象释放都会路由到该浏览器 realm。Client Console argument 使用同一份会话本地 object table；`Debugger.enable` 发布构建后的 `lib/client.js` catalog，`Debugger.getScriptSource` 读取有界 content chunk。Source map 地址来自已加载脚本末尾的 `sourceMappingURL`，保留 combo URL 和部署前缀。Client script 断点、step 和 call frame 仍不支持；target-wide pause 与 resume 只控制 Host debugger。
+
+Client 在 `pagehide` 时同步关闭 source，缓存页面恢复并收到 `pageshow` 后，使用同一逻辑身份重新连接。仍然存活的页面切到后台不会断开。已关闭的 generation 不会在异步操作完成后发布执行上下文或 script catalog。
 
 两个插件端运行同一份可在浏览器中安全运行的 Cordis collector。它把可达 Context 与 Fiber 对象转换成有版本的 `CordisTreeSnapshot`；Worker 存储这份与 CDP 无关的表示，并把每个 Host 或 Client source 投影到 Elements 面板。
 
 <a id="configuration"></a>
 ## 配置
 
-Host 插件注入 `webServer`，接受以下字段：
+Host 插件注入 `webServer` 和 `connection`，接受以下字段：
 
 | 字段 | 默认值 | 含义 |
 |---|---:|---|
@@ -98,15 +120,15 @@ await ctx.inspector.cordis.getTree()
 <a id="cordis-tree-inspection"></a>
 ## Cordis 树检查
 
-Elements document 包含固定的 `<host>` 与 `<clients>` 容器。`<host>` 包含 Host root Context；`<clients>` 为每个 Client source 包含一个 `<client>`，每个 `<client>` 再包含该 realm 的根 Context。Cordis root Fiber 不显示。其他 Fiber 都是 `fiber.parent` 的子节点，并包含唯一一个表示 `fiber.ctx` 的 Context 子节点；Fiber 只携带 `uid="<Cordis Fiber.uid>"`，Context element 不携带 attribute。只有 Context 的 `extend()`、`isolate()` 与 `intercept()` 层仍然是直接 Context 后代。
+Elements document 包含固定的 `<host>` 与 `<clients>` 容器。`<host>` 包含 Host root Context；`<clients>` 为每个 Client source 包含一个 `<client>`，每个 `<client>` 再包含该 realm 的根 Context。Cordis root Fiber 不显示。移除 Cordis 服务调用的 `shadow` 包装层后，其他 Fiber 都是 `fiber.parent` 的子节点，并包含唯一一个表示 `fiber.ctx` 的 Context 子节点；Fiber 只携带 `uid="<Cordis Fiber.uid>"`，Context element 不携带 attribute。只有 Context 的 `extend()`、`isolate()` 与 `intercept()` 层仍然是直接 Context 后代。
 
 Host 与 Client 发布同一种嵌套 `CordisTreeSnapshot` 类型。Context 与 Fiber 节点携带用于 realm-local 对象查询的不透明 object 句柄；Fiber 还携带 Cordis `uid`。Worker 把这些 realm 快照组合成一棵 `{ host, clients }` inspection tree。Worker 按 source generation 分配 `BackendNodeId`；每条 DevTools 连接分配自己的 `NodeId`；`DOM.resolveNode` 请求所属 Host 或 Client Runtime 生成连接本地 `RemoteObjectId`。`DOM.requestNode` 把该 object id 映射回同一个 Elements 节点。`ctx.inspector.cordis.getTree()` 与 `DSHInspector.getCordisTree` 读取不含 routing 句柄或 CDP id 的 detached 消费方无关 tree。
 
-节点按 DevTools 连接做深度受限下发：调用方省略 `depth` 时 `DOM.getDocument` 提供三层 document，被扣留的层级通过 `childNodeCount` 声明数量，展开时经 `DOM.requestChildNodes` 获取（`depth: -1` 取整棵子树）。经 `DOM.performSearch`、`DOM.requestNode` 或 `DOM.pushNodesByBackendIdsToFrontend` 流出的 NodeId 会先把尚未下发的祖先层级以 `DOM.setChildNodes` 事件推送出去。
+节点按 DevTools 连接做深度受限下发：调用方省略 `depth` 时 `DOM.getDocument` 提供三层 document，被扣留的层级通过 `childNodeCount` 声明数量，展开时经 `DOM.requestChildNodes` 获取（`depth: -1` 取整棵子树）。重复展开只补发缺失的子节点列表，保留已有前端节点对象和已加载的深层后代。经 `DOM.performSearch`、`DOM.requestNode` 或 `DOM.pushNodesByBackendIdsToFrontend` 流出的 NodeId 会先把尚未下发的祖先层级以 `DOM.setChildNodes` 事件推送出去。
 
-source 仍发布完整 snapshot，Worker 在通知 DevTools 前按稳定的 backend node identity 比较差异。无变化的 snapshot 不发送 DOM 事件；新增、移除和 attribute 变化使用节点级 CDP 事件，插入节点的载荷扣留其子树，兄弟节点重排只替换对应 parent 的 children。现有 `NodeId` 与未受影响的 Elements 展开状态保持稳定。
+source 仍发布完整 snapshot，Worker 在通知 DevTools 前按稳定的 backend node identity 比较差异。无变化的 snapshot 不发送 DOM 事件。已知节点尚未下发的子节点列表有变化时，只发送 `DOM.childNodeCountUpdated`；展开时再获取完整的当前子节点列表。已下发的子节点列表接收节点级插入和移除事件，插入节点的载荷扣留其子树，兄弟节点重排只替换对应 parent 的 children。attribute 变化只发给已下发的节点。重新获取 document 会替换其已下发深度；`DOM.describeNode` 不会将节点挂入前端树。现有 `NodeId` 与未受影响的 Elements 展开状态保持稳定。
 
-Client 断联时，其 Console execution context 与 live object id 会立即销毁。启用断联树保留后，Elements 会原样保留最后一棵树；连接状态留在 inspection model 中，不会未经审查就成为 DOM attribute。重连会沿用逻辑 source id，为新的 transport generation 创建新的 synthetic CDP context id，并在完整 snapshot 到达后替换旧树。Client 把逻辑 id 保存在 `sessionStorage` 中，并通过 Web Locks 在页面存活期间独占该 id，因此刷新会复用 id，而复制出的另一个 live tab 会取得新 id。Worker 最多保留 `maxDisconnectedCordisTrees` 棵此类 snapshot；设为零会立即移除。
+Client 断联时，其 Console execution context 与 live object id 会立即销毁，该项随即从 Console 上下文选择器中移除。启用断联树保留后，Elements 保留最后一棵树，并在其 `<client>` 元素上添加布尔属性 `disconnected`。重连会沿用逻辑 source id，为新的 transport generation 创建新的 synthetic CDP context id，并在完整 snapshot 替换旧树时移除该属性。属性变化通过增量事件到达，不需要刷新 DevTools。Client 把逻辑 id 保存在 `sessionStorage` 中，并通过 Web Locks 在页面存活期间独占该 id，因此刷新会复用 id，而复制出的另一个 live tab 会取得新 id。Worker 最多保留 `maxDisconnectedCordisTrees` 棵此类 snapshot；设为零会立即移除。
 
 <a id="host-fetch-capture"></a>
 ## Host fetch 采集
@@ -120,6 +142,8 @@ response headers 到达后，调用方 abort 可能会终止 observer clone；
 <a id="security"></a>
 ## 安全
 
+Client 选择只限制一条 DevTools 连接的 realm session、DOM 投影和诊断查询，不停止采集，也不改变共享观测 API。它是显示筛选，不是授权机制：可信调试用户可以打开不带筛选的连接，Host 求值仍拥有原有权限。
+
 CDP target 通过 `Runtime.evaluate` 提供 Host 和已连接 Client realm 中的任意代码执行能力，Host Debugger 操作还会提供额外控制，完整 fetch 采集也包含敏感信息。因此 Worker 只接受 `127.0.0.1` 监听地址。Client ingest 还要求 Host 注入的随机 WebSocket subprotocol token；除非配置明确允许，否则拒绝非 loopback origin。CDP socket 本身不携带 token，loopback 监听是它唯一的访问控制。
 
 <a id="model-experience"></a>
@@ -135,6 +159,8 @@ CDP target 通过 `Runtime.evaluate` 提供 Host 和已连接 Client realm 中
 
 <a id="known-limitations-and-deferred-work"></a>
 
+- **Memory 和 Performance 检查 Host** — Memory 抓取 Host 堆快照，Performance 记录 Host CPU 采样。Client Runtime context 不提供浏览器堆快照或渲染轨迹。
+- **同源转发运行在 Host 主线程** — 暂停 Host JavaScript 也会暂停转发。断点调试和恢复执行应使用启动时打印的 Worker 直连 DevTools 端点。
 - **Client active debugging 不受支持**——Console event、Runtime 求值、RemoteObject 访问和只读 `lib/client.js` Sources 可用。Client script debugger request 返回明确的 unsupported error；target-wide pause 与 resume 只控制 Host。
 - **Client Sources 只暴露 Inspector bundle**——本包不收录页面中的其他 script。
 - **Client 求值使用页面 JavaScript**——页面 Content Security Policy 可能阻止动态求值；synthetic context 不提供 DevTools command-line helper 或原生 REPL 声明语义。
@@ -152,5 +178,3 @@ CDP target 通过 `Runtime.evaluate` 提供 Host 和已连接 Client realm 中
 无。
 
 </details>
-
-**运行时不变式：** 不发布伴生入口。wire 解析、generation、Worker 生命周期与 CDP 会话会在所属操作中拒绝无效关系。