dsh-builtin-browser 0.1.17 → 0.1.19

package/README.en.md

@@ -217,7 +217,7 @@ agent (browser_* tools)
 
 **The self-hosted browser IS a real browser**: every task (DSH session) gets its **own browser window** with a full toolbar — address bar, back/forward/reload buttons, and a tab strip (new/switch/close tabs). A human can use it exactly like Chrome: type a URL in the address bar (https:// is added automatically), click tabs, open new ones. Keyboard focus follows your clicks — **click the address bar to type, click the page to interact** (Windows focus routing; fixes the case where clicks did not move focus and the address bar could not receive typed URLs). Human and agent actions feed the **same session model** (same tabs, history, and navigation); the window title always shows the task label plus the page title/URL, and views follow the window size on resize. A window closes automatically with its session when the task ends.
 
-**Electron lookup order**: ① the current process IS Electron (DSH Desktop main process) → reuse the host binary directly; ② walk the process ancestry for the host's Electron binary (covers hosts that run the plugin in a child Node process, e.g. DSH Desktop; PowerShell CIM on Windows, last resort only); ③ `require('electron')` (peer dependency); ④ `ELECTRON_PATH` (explicit override); ⑤ the newest among DSH install anchors and pnpm virtual stores. **Zero extra install on DSH Desktop**; when nothing is found a clear error tells you what to do (including the per-profile install command).
+**Electron lookup order**: ① the current process IS Electron (DSH Desktop main process) → reuse the host binary directly; ② walk the process ancestry for the host's Electron binary (covers hosts that run the plugin in a child Node process, e.g. DSH Desktop; PowerShell CIM on Windows, last resort only); ③ `require('electron')` (the electron package bundled with the plugin); ④ `ELECTRON_PATH` (explicit override); ⑤ the newest among DSH install anchors and pnpm virtual stores. **Zero extra install on DSH Desktop**; when nothing is found a clear error tells you what to do.
 
 ## Division of labor with the desktop shell
 
@@ -226,9 +226,9 @@ The browser's **visible view**, the **browser column layout**, and the **column-
 ## Requirements
 
 - DeepSeek Harness (dsh) with the matching profile (`web` / `desktop`, etc.)
-- **Electron runtime** (optional peer dependency):
-  - **DSH Desktop**: the host itself runs on Electron — the plugin reuses the host binary automatically, **zero extra install**;
-  - **plain `dsh web` self-hosted**: an Electron binary is required and located automatically (see above; ≥ 40 recommended; 44+ downloads its binary on first use, needs network)
+- **Electron runtime** (required dependency, installed automatically with the plugin):
+  - **DSH Desktop**: the host itself runs on Electron — the plugin reuses the host binary automatically (the bundled electron is just a fallback);
+  - **plain `dsh web` self-hosted**: uses the bundled electron package directly (≥ 40 recommended; 44+ downloads its binary on first use, needs network)
 
 ### Verified versions
 
@@ -237,7 +237,7 @@ The browser's **visible view**, the **browser column layout**, and the **column-
 | DeepSeek Harness (dsh) | `0.1.1-rc.2` (peer range `^0.1.1-rc.2`) |
 | Electron | `44.0.0` (≥ 40 recommended; 33.x has a compositor defect) |
 | Node.js | `22.20.0` |
-| dsh-builtin-browser | `0.1.17` |
+| dsh-builtin-browser | `0.1.19` |
 | OS | Windows 10 (10.0.26200) |
 
 > The plugin declares `electron >= 30`; it has **only been verified on Windows** (macOS/Linux untested, not yet promised).
@@ -292,6 +292,10 @@ Code layout:
 | **0.1.16** | 2026-08-26 | **Release**: all seven rounds ship as **0.1.16** (build clean, 21/21 tests pass, `v0.1.16`) |
 | 8 | 2026-08-27 | **DSH Desktop host-Electron reuse**: running inside an Electron process reuses the host binary directly; when the host runs the plugin in a child Node process, walk the process ancestry to find the host's Electron (PowerShell CIM on Windows, last resort only) — **DSH Desktop works with zero install**; error now hints per active profile; electron shim completed to fix the CI typecheck; docs updated |
 | **0.1.17** | 2026-08-27 | **Release**: round 8 ships as **0.1.17** (build clean, 21/21 tests pass) |
+| 9 | 2026-08-27 | **electron becomes a required dependency**: moved from optional peer into `dependencies`, so installing the plugin brings the electron package automatically (44+ downloads its binary lazily on first use); DSH Desktop still reuses the host binary; docs and error message updated |
+| **0.1.18** | 2026-08-27 | **Release**: round 9 (electron as a required dependency) ships as **0.1.18** (build clean, 21/21 tests pass) |
+| 10 | 2026-08-27 | **DSH-Store compatibility declaration**: added `dsh.compatibility.dshReleases` (rc.2/rc.1=compatible, rc.8=unknown) plus profiles/dsh range, clearing the store's auto-unlisting (HOLD) |
+| **0.1.19** | 2026-08-27 | **Release**: round 10 (DSH-Store compatibility declaration) ships as **0.1.19** (build clean, 21/21 tests pass) |
 
 ## Acknowledgements
 

package/README.md

@@ -217,7 +217,7 @@ agent (browser_* 工具)
 
 **自托管浏览器就是一台真正的浏览器**:每个任务(DSH 会话)拥有**独立的浏览器窗口**,窗口自带完整工具栏——地址栏、后退/前进/刷新按钮、标签条(新建/切换/关闭标签)。人可以直接像用 Chrome 一样使用它:在地址栏输入网址(自动补 `https://`)、点标签切换页面、开新标签;键盘焦点跟随点击——**点地址栏即可输入、点页面即可操作**(Windows 焦点路由,修复了点击不转移焦点导致地址栏无法输入的问题)。agent 与人的操作都汇入**同一个会话模型**(同一套标签、历史与导航),窗口标题实时显示当前任务标识与页面标题/URL,窗口缩放时视图自动跟随。任务结束后窗口随会话自动关闭。
 
-**Electron 定位顺序**:① 插件运行在 Electron 进程内(DSH Desktop 主进程)时直接复用宿主二进制 → ② 进程祖先树中的宿主 Electron 二进制(DSH Desktop 把插件跑在子 Node 进程时的兜底)→ ③ `require('electron')`(peer 依赖)→ ④ `ELECTRON_PATH`(显式覆盖)→ ⑤ DSH 安装锚点与 pnpm 虚拟仓库中**版本最新**者。**DSH Desktop 上零额外安装**;找不到时工具会报清晰的错误提示(含按当前 profile 的安装命令)。
+**Electron 定位顺序**:① 插件运行在 Electron 进程内(DSH Desktop 主进程)时直接复用宿主二进制 → ② 进程祖先树中的宿主 Electron 二进制(DSH Desktop 把插件跑在子 Node 进程时的兜底)→ ③ `require('electron')`(随插件安装的 electron 包)→ ④ `ELECTRON_PATH`(显式覆盖)→ ⑤ DSH 安装锚点与 pnpm 虚拟仓库中**版本最新**者。**DSH Desktop 上零额外安装**;找不到时工具会报清晰的错误提示。
 
 ## 与桌面外壳的分工
 
@@ -226,9 +226,9 @@ agent (browser_* 工具)
 ## 环境要求
 
 - DeepSeek Harness(dsh),已安装对应 profile(`web` / `desktop` 等)
-- **Electron 运行时**(可选 peer 依赖):
-  - **DSH Desktop**:宿主本身基于 Electron,**插件自动复用宿主二进制,零额外安装**;
-  - **纯 `dsh web` 自托管**:需要 Electron 二进制,插件自动定位(见上,建议 ≥ 40;44+ 首次使用自动下载,需网络)
+- **Electron 运行时**(必装依赖,随插件自动安装):
+  - **DSH Desktop**:宿主本身基于 Electron,**插件自动复用宿主二进制**(随包安装的 electron 仅作后备);
+  - **纯 `dsh web` 自托管**:直接使用随插件安装的 electron 包(建议 ≥ 40;44+ 首次使用自动下载二进制,需网络)
 
 ### 验证过的版本
 
@@ -237,7 +237,7 @@ agent (browser_* 工具)
 | DeepSeek Harness(dsh) | `0.1.1-rc.2`(peer 声明 `^0.1.1-rc.2`) |
 | Electron | `44.0.0`(推荐 ≥ 40;33.x 存在合成器缺陷) |
 | Node.js | `22.20.0` |
-| dsh-builtin-browser | `0.1.17` |
+| dsh-builtin-browser | `0.1.19` |
 | 操作系统 | Windows 10 (10.0.26200) |
 
 > 插件声明 `electron >= 30`;**当前仅在 Windows 环境实测**(macOS/Linux 未验证,暂不承诺)。
@@ -255,7 +255,7 @@ agent (browser_* 工具)
 - 页面弹窗(`window.open` / `target=_blank`)会被重定向到当前标签页内打开,不创建独立窗口,以免破坏标签/会话模型。
 - `browser_auth` 的 cookie 往返不保留 `hostOnly`/`sameSite` 字段(host-only cookie 恢复后变成 domain cookie);仅自托管浏览器可用。
 - 自托管浏览器子进程崩溃后会自动重启,但崩溃前已打开的会话视图已失效,调用 `browser_reset_session` 重建即可。
-- Electron 44+ 首次打开浏览器窗口时会自动下载二进制(约 100MB,需网络);之后不再需要。若探测时网络不可用,可预装 `ELECTRON_PATH` 指定的二进制。
+- electron 随插件安装;Electron 44+ 首次打开浏览器窗口时自动下载二进制(约 100MB,需网络),之后不再需要。若探测时网络不可用,可预装 `ELECTRON_PATH` 指定的二进制。
 - 本插件不含浏览器列 UI——那是宿主外壳的配套,别把"浏览器列"当成插件能力。
 
 ## 开发
@@ -292,6 +292,10 @@ npm run build
 | **0.1.16** | 2026-08-26 | **发布**:以上七轮全部随 **0.1.16** 发布(构建零错误、21 项测试全绿,`v0.1.16`) |
 | 第八轮 | 2026-08-27 | **DSH Desktop 宿主 Electron 复用**:插件运行在 Electron 进程内直接复用宿主二进制;插件跑在宿主子 Node 进程时沿进程祖先树找到宿主 Electron 兜底(Windows 用 PowerShell CIM,仅最后手段)——DSH Desktop **零安装开箱可用**;报错按当前 profile 动态提示;补齐 electron shim 修复 CI 类型检查;文档同步 |
 | **0.1.17** | 2026-08-27 | **发布**:第八轮修复随 **0.1.17** 发布(构建零错误、21 项测试全绿) |
+| 第九轮 | 2026-08-27 | **electron 改为必装依赖**:从 optional peer 移入 `dependencies`,安装插件即自动带上 electron 包(44+ 二进制首次使用懒下载);DSH Desktop 依旧复用宿主二进制;文档与报错同步 |
+| **0.1.18** | 2026-08-27 | **发布**:第九轮「electron 改为必装依赖」随 **0.1.18** 发布(构建零错误、21 项测试全绿) |
+| 第十轮 | 2026-08-27 | **DSH-Store 兼容性声明**:新增 `dsh.compatibility.dshReleases`(rc.2/rc.1=compatible、rc.8=unknown)与 profiles/dsh 范围,解除商店自动下架(HOLD) |
+| **0.1.19** | 2026-08-27 | **发布**:第十轮「DSH-Store 兼容性声明」随 **0.1.19** 发布(构建零错误、21 项测试全绿) |
 
 ## 特别感谢
 

package/docs/architecture.md

@@ -60,7 +60,7 @@ RemoteElectronViewHost  ──TCP JSON-RPC──▶  host-main.js
 
 - **协议**:本机 loopback TCP,每行一个 JSON(`{ id, op, ... }` ↔ `{ id, ok, result|err }`);
 - **认证**:每次 spawn 生成随机 token(经 `--rpc-token` 传入),子进程首条消息必须回传该 token(`hello`);服务端只接受**一个**连接,其余连接直接断开——本机其他进程无法伪冒子进程或注入回复;
-- **Electron 定位**:① 插件运行在 Electron 进程内(DSH Desktop 主进程)时直接复用宿主二进制(`process.execPath`);② 进程祖先树中的宿主 Electron 二进制(DSH Desktop 把插件跑在子 Node 进程时的兜底,Windows 用 PowerShell CIM 查询,仅在其它路径全部落空时才执行)→ ③ peer 依赖 → ④ `ELECTRON_PATH` → ⑤ 锚点与 pnpm store 中**版本最新**者(33.x 有合成器缺陷,建议 ≥ 40);
+- **Electron 定位**:① 插件运行在 Electron 进程内(DSH Desktop 主进程)时直接复用宿主二进制(`process.execPath`);② 进程祖先树中的宿主 Electron 二进制(DSH Desktop 把插件跑在子 Node 进程时的兜底,Windows 用 PowerShell CIM 查询,仅在其它路径全部落空时才执行)→ ③ 随插件安装的 electron 包 → ④ `ELECTRON_PATH` → ⑤ 锚点与 pnpm store 中**版本最新**者(33.x 有合成器缺陷,建议 ≥ 40);
 - **稳健性**:子进程/套接字都有 `error` 监听(否则未捕获事件会炸掉整个 DSH 进程);子进程退出自动重启;物化失败可重试;下载仅限 HTTP(S)、`savePath` 必须绝对路径(默认限定 `~/Downloads`,可配置 `downloadDir` 覆盖)、流式限流 + Content-Length 提前拒绝、256MB 上限与 60s 超时,文件由**子进程直接落盘**(临时文件 + rename,不再经 RPC 传 base64);cookie 导出/恢复有 30s 超时;
 - **视图可见性**:多标签/多会话时,`showView` 隐藏其他视图并把目标视图置顶(remove+re-add),确保用户看到的是活动标签;目标是当前可见视图时**跳过** remove/re-add(否则每次操作都闪烁);窗口标题实时显示当前可见会话的任务标识 + 页面标题/URL(`showView` 携带会话 label,子进程读 `getTitle`/`getURL`);窗口 resize 时视图 bounds 自动跟随;
 - **孤儿防护**:父进程断开时子进程自动退出,不留僵尸窗口;

package/docs/user-guide.md

@@ -3,9 +3,9 @@
 ## 环境要求
 
 - DeepSeek Harness(dsh),已安装对应 profile(`web` / `desktop` 等)
-- **Electron 运行时**(可选 peer 依赖):
-  - **DSH Desktop**:宿主本身基于 Electron,**插件自动复用宿主二进制,零额外安装**;
-  - **纯 `dsh web` 自托管**:需要 Electron 二进制,插件自动定位(建议 ≥ 40,33.x 存在截图合成器缺陷;44+ 首次使用自动下载,需网络),找不到时按下文 FAQ 安装即可。
+- **Electron 运行时**(必装依赖,随插件自动安装):
+  - **DSH Desktop**:宿主本身基于 Electron,**插件自动复用宿主二进制**(随包安装的 electron 仅作后备);
+  - **纯 `dsh web` 自托管**:直接使用随插件安装的 electron 包(建议 ≥ 40,33.x 存在截图合成器缺陷;44+ 首次使用自动下载,需网络)。
 
 ## 安装
 
@@ -74,9 +74,9 @@ dsh plugin --profile web add <本仓库路径>
 能。插件自托管:自己拉起 Electron 窗口,无需桌面外壳。
 
 **Q:找不到 Electron?**
-插件按顺序自动定位:① 插件运行在 Electron 进程内(DSH Desktop 主进程)时直接复用宿主二进制 → ② 进程祖先树中的宿主 Electron 二进制(DSH Desktop 把插件跑在子 Node 进程时的兜底)→ ③ peer 依赖 `require('electron')`(仅二进制已就绪时)→ ④ `ELECTRON_PATH` 环境变量 → ⑤ DSH 锚点与 pnpm 虚拟仓库中版本最新者。
+插件按顺序自动定位:① 插件运行在 Electron 进程内(DSH Desktop 主进程)时直接复用宿主二进制 → ② 进程祖先树中的宿主 Electron 二进制(DSH Desktop 把插件跑在子 Node 进程时的兜底)→ ③ 随插件安装的 electron 包 `require('electron')`(仅二进制已就绪时)→ ④ `ELECTRON_PATH` 环境变量 → ⑤ DSH 锚点与 pnpm 虚拟仓库中版本最新者。
 
-DSH Desktop 上①②任一命中即开箱可用,无需任何安装。纯 `dsh web` 下全部落空时,报错会给出指引:可 `dsh plugin --profile <你的-profile> add electron`(DSH Desktop 的 profile 是 `desktop`)或设置 `ELECTRON_PATH`。
+DSH Desktop 上①②任一命中即开箱可用,无需任何安装。纯 `dsh web` 下全部落空时,报错会给出指引:electron 已随插件安装,44+ 二进制首次使用自动下载(需网络);必要时可 `npx install-electron` 或设置 `ELECTRON_PATH`。
 
 **Q:截图失败或挂起?**
 确保 Electron ≥ 40(33.x 有合成器缺陷)。自托管截图优先走原生 `capturePage`,多视图/窗口未激活时自动兜底到 CDP。

package/lib/browser-electron/remote-host.js

@@ -40,7 +40,8 @@ const MAX_RPC_BUFFER_BYTES = 512 * 1024 * 1024;
  *   0. the current process IS Electron (DSH Desktop hosts load this plugin
  *      inside their own Electron main process) — reuse the host binary, so
  *      the plugin works out of the box without `add electron`;
- *   1. require('electron') from this module (optional peer dependency),
+ *   1. require('electron') from this module (bundled dependency — the
+ *      electron package ships with the plugin),
  *   2. ELECTRON_PATH (explicit override),
  *   3. every DSH install anchor + pnpm virtual store candidate, choosing the
  *      NEWEST version found. Older Electron releases (e.g. 33.x) have a
@@ -59,8 +60,8 @@ function resolveElectronPath() {
         if (typeof exe === 'string' && exe.length > 0 && existsSync(exe))
             return exe;
     }
-    // 1. Optional peer dependency — but ONLY when its binary is already on
-    //    disk. Electron 44+ downloads the binary lazily on the first require()
+    // 1. Bundled dependency — but ONLY when its binary is already on disk.
+    //    Electron 44+ downloads the binary lazily on the first require()
     //    (it has no postinstall anymore), so probing here must never trigger a
     //    synchronous network download: available() would block DSH startup for
     //    the download (or fail outright offline), surfacing as a broken plugin.
@@ -151,11 +152,12 @@ function resolveElectronPath() {
     if (hostExe !== undefined)
         return hostExe;
     throw new Error('dsh-builtin-browser: cannot locate the Electron binary. Options: (1) if you are on DSH Desktop, ' +
-        'this should never appear — the plugin reuses the host Electron automatically; (2) install electron ' +
-        'into the active profile (`dsh plugin --profile <your-profile> add electron`; on DSH Desktop the ' +
-        'profile is `desktop`); (3) set ELECTRON_PATH to the electron executable. Note: Electron 44+ downloads ' +
-        'its binary on first use, so if the package is installed but the binary is missing, run ' +
-        '`npx install-electron` once (needs network) and retry.');
+        'this should never appear — the plugin reuses the host Electron automatically; (2) the electron ' +
+        'package ships with the plugin, so on newer installs nothing is needed here — on installs from ' +
+        'before that change, add it to the active profile (`dsh plugin --profile <your-profile> add electron`; ' +
+        'on DSH Desktop the profile is `desktop`); (3) set ELECTRON_PATH to the electron executable. Note: ' +
+        'Electron 44+ downloads its binary on first use, so if the package is installed but the binary is ' +
+        'missing, run `npx install-electron` once (needs network) and retry.');
 }
 /**
  * Last-resort Electron discovery: walk this process's ancestry looking for a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Shared real browser plugin for DeepSeek Harness: install-and-use — a visible native browser the human can take over, driven by the agent over CDP. DOM-level interaction (React/Vue safe), per-task session isolation, cookie persistence (browser_auth), CAPTCHA detection, batch form fill (browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",
@@ -60,19 +60,15 @@
   "engines": {
     "node": ">=22.19"
   },
-  "dependencies": {},
+  "dependencies": {
+    "electron": ">= 30.0.0"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "electron": ">= 30.0.0"
-  },
-  "peerDependenciesMeta": {
-    "electron": {
-      "optional": true
-    }
+    "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -81,6 +77,18 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dsh": ">=0.1.1-rc.1 <0.2.0",
+      "profiles": [
+        "web",
+        "desktop"
+      ],
+      "dshReleases": {
+        "0.1.0-rc.8": "unknown",
+        "0.1.1-rc.1": "compatible",
+        "0.1.1-rc.2": "compatible"
+      }
     }
   }
 }

package/src/browser-electron/remote-host.ts

@@ -46,7 +46,8 @@ const MAX_RPC_BUFFER_BYTES = 512 * 1024 * 1024
  *   0. the current process IS Electron (DSH Desktop hosts load this plugin
  *      inside their own Electron main process) — reuse the host binary, so
  *      the plugin works out of the box without `add electron`;
- *   1. require('electron') from this module (optional peer dependency),
+ *   1. require('electron') from this module (bundled dependency — the
+ *      electron package ships with the plugin),
  *   2. ELECTRON_PATH (explicit override),
  *   3. every DSH install anchor + pnpm virtual store candidate, choosing the
  *      NEWEST version found. Older Electron releases (e.g. 33.x) have a
@@ -64,8 +65,8 @@ function resolveElectronPath(): string {
     const exe = process.execPath
     if (typeof exe === 'string' && exe.length > 0 && existsSync(exe)) return exe
   }
-  // 1. Optional peer dependency — but ONLY when its binary is already on
-  //    disk. Electron 44+ downloads the binary lazily on the first require()
+  // 1. Bundled dependency — but ONLY when its binary is already on disk.
+  //    Electron 44+ downloads the binary lazily on the first require()
   //    (it has no postinstall anymore), so probing here must never trigger a
   //    synchronous network download: available() would block DSH startup for
   //    the download (or fail outright offline), surfacing as a broken plugin.
@@ -150,11 +151,12 @@ function resolveElectronPath(): string {
   if (hostExe !== undefined) return hostExe
   throw new Error(
     'dsh-builtin-browser: cannot locate the Electron binary. Options: (1) if you are on DSH Desktop, ' +
-    'this should never appear — the plugin reuses the host Electron automatically; (2) install electron ' +
-    'into the active profile (`dsh plugin --profile <your-profile> add electron`; on DSH Desktop the ' +
-    'profile is `desktop`); (3) set ELECTRON_PATH to the electron executable. Note: Electron 44+ downloads ' +
-    'its binary on first use, so if the package is installed but the binary is missing, run ' +
-    '`npx install-electron` once (needs network) and retry.',
+    'this should never appear — the plugin reuses the host Electron automatically; (2) the electron ' +
+    'package ships with the plugin, so on newer installs nothing is needed here — on installs from ' +
+    'before that change, add it to the active profile (`dsh plugin --profile <your-profile> add electron`; ' +
+    'on DSH Desktop the profile is `desktop`); (3) set ELECTRON_PATH to the electron executable. Note: ' +
+    'Electron 44+ downloads its binary on first use, so if the package is installed but the binary is ' +
+    'missing, run `npx install-electron` once (needs network) and retry.',
   )
 }
 

package/src/types/electron-shim.d.ts

@@ -1,8 +1,9 @@
 /**
  * Ambient declaration for the `electron` module used by the self-hosted
- * browser host (`host-main.ts`). The electron package is an optional peer
- * dependency (present in desktop-shell environments), so it is not in
- * devDependencies; this shim keeps typechecking self-contained.
+ * browser host (`host-main.ts`). The electron package is a bundled runtime
+ * dependency, but its type definitions can be absent when the published
+ * `src/` is typechecked standalone; this shim keeps typechecking
+ * self-contained.
  * @module dsh-browser/types/electron-shim
  */