@deepseek-ai/dsh-experimental-webworker-runtime 0.1.7-rc.1 → 0.2.0-rc.1

package/README.i18n.yaml

@@ -1,6 +1,31 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/experimental/webworker-runtime/README.md
-README.md: 3a5d702c2163c19daa3230ffd14270b4f236f2d9
-README.zh.md: a987fed1db5f607aee4e95e2faf96575c1d0c904
+/:
+  en: 9a7ee334bf98bb3d
+  zh: 0a78ada4049c27fe
+/deepseek-ai-dsh-experimental-webworker-runtime:
+  en: ca354d8ca21609bb
+  zh: 2eff66603192a3ff
+/deepseek-ai-dsh-experimental-webworker-runtime/summary:
+  en: cfff0da51e5e9bde
+  zh: 38e7960b16c77c2c
+/deepseek-ai-dsh-experimental-webworker-runtime/table-of-contents:
+  en: 4e53164159b5ce41
+  zh: 89582dc0294d0776
+/deepseek-ai-dsh-experimental-webworker-runtime/use-this-package:
+  en: 7c80a0d046f93fb1
+  zh: a9fdcc7a9f9a8828
+/deepseek-ai-dsh-experimental-webworker-runtime/model-experience:
+  en: 61fce9b4c7dc96e6
+  zh: dc2d931063a38327
+/deepseek-ai-dsh-experimental-webworker-runtime/model-experience/kv-cache-effect:
+  en: ca75c51c89c2c9b0
+  zh: 64715dc7e6d02f71
+/deepseek-ai-dsh-experimental-webworker-runtime/known-limitations-and-deferred-work:
+  en: 6fe586817a42fdad
+  zh: c19ab678d61e82d3
+/deepseek-ai-dsh-experimental-webworker-runtime/known-limitations-and-deferred-work/dev-note:
+  en: f14ab6f2449c3c53
+  zh: e3f7d3a3d772c0b7

package/README.md

@@ -27,10 +27,10 @@ The public npm package exposes the runtime library at its root, the self-contain
 
 Three build artifacts and one source-owned process layer:
 
-- **`lib/index.js` (assembly library)** — `createWorkerHost`/`startWorkerHost` mount the base image and any ordered data overlays (`storage/`), install the module loader (`module-system/`) and the `process` shim, boot the tree through the image's own `dsh-app-boot`, and hand the tunnel its serving seams. Overlays may replace files only under `home/` and `workspace/`; they cannot replace the base manifest, configuration, or modules. The image layout contract (`image-layout.ts`: virtual root, config/manifest paths, empty directories, the `lowered` wrapper-contract gate) is shared with the packer. The Worker supplies `profileContext` for an editable profile at `home/profiles/preview/`: the packed rows seed its insertion patch, and ConfigEditor persists overrides in that VFS patch. ConfigEditor reconciles each write and Loader commits live values; package management and Node module HMR stay disabled. Deployment overlays keep JSONL session logs plaintext and preset roots at the image's `config/agent-presets`. Configuration edits last for the current Worker lifetime.
+- **`lib/index.js` (assembly library)** — `createWorkerHost`/`startWorkerHost` mount the base image and any ordered data overlays (`storage/`), install the module loader (`module-system/`) and the `process` shim, boot the tree through the image's own `dsh-app-boot`, and hand the tunnel its serving seams. Overlays may replace files only under `home/` and `workspace/`; they cannot replace the base manifest, configuration, or modules. The image layout contract (`image-layout.ts`: virtual root, config/manifest paths, empty directories, the `lowered` wrapper-contract gate) is shared with the packer. The Worker supplies `profileContext` for an editable profile at `home/profiles/preview/`: the packed rows seed its insertion patch, and ConfigEditor persists overrides in that VFS patch. ConfigEditor reconciles each write and Loader commits live values. The Worker commits `appReady` once the tunnel serves, so HMR loads and queues profile configuration changes; the `process` shim reports no entry script, so HMR performs no Node module-cache classification. Plugin management loads and edits the profile, and its package operations fail with the `execa` refusal. Deployment overlays keep JSONL session logs plaintext and preset roots at the image's `config/agent-presets`. Configuration edits last for the current Worker lifetime.
 - **`lib/worker.js` (worker bundle)** — the assembly plus this package's Node-compatibility layer as one self-contained ES module. The module proxy table (`module-proxies.ts`) is the only platform fork: `node:*` builtins over VFS/tunnel/browser primitives, structural stubs that fail loud on the console for what a browser cannot do, and native/binary package replacements. `node:module` supplies `createRequire().resolve` and `.resolve.paths()` over the image package root, so unchanged packages can discover manifests without evaluating their modules. The `node:util` JSON-data comparator compares own enumerable properties, preserving Node admission decisions for recorded fields such as `__proto__`. The global `process` shim carries Node detection fields including `title`, preventing Worker execution from entering DOM-only branches. The pack-time parser reports statically named module requests, including module-scope direct calls of the form `createRequire(import.meta.url)('pkg')` through a named `node:module` or `module` import, to the packer's reachability walk. Stored, CommonJS-obtained, and rebased `createRequire` calls require image entry seeds. VFS mutations drive `node:fs` callback, polling, and promise watchers; open descriptors retain file identity and access mode across rename, replacement, and unlink, `FileHandle.stat({ bigint: true })` reports the same device and inode identity as a path stat while the name still refers to that file, and `FileHandle.chmod()` updates the opened file identity; `readable-stream` supplies `node:stream/promises` completion and pipeline helpers and the stream state machine used by file streams and unchanged image packages such as Chokidar and readdirp. AsyncLocalStorage carries sync-stack causality across `await` through the snapshot/restore faces the pack-time lowering injects. The worker holds no compiler: an image the packer did not lower is refused at mount. The callback `fs.realpath.native` alias resolves within the mounted VFS and supports `util.promisify`.
-- **`src/shell/` (the worker's own process layer)** — a browser worker cannot fork, so `node:child_process` is not a stub but an implementation: `spawn` starts the command in its own Web Worker — this same bundle, told by its first frame to be a shell process — and reports it through the `ChildProcess` surface the subprocess service consumes. The command runs off the host's thread, `SIGKILL` terminates it whatever it is doing, and it reaches the VFS only by message (the host serves those frames). Worker platform executables preserve native-package protocols such as Landlock without replacing their JavaScript packages or coupling their implementations to `node:child_process`; ordinary commands use the package's evaluator and coreutils command table. The grammar is `@yarnpkg/parsers`' `parseShell`, while `execSync`/`fork` still refuse because they need a real process.
-- **`lib/client.js` (page half)** — startup has two independent stages. `chooseWorkerHostSource({ image?, fixtureManifest? })` optionally owns the boot barrier and fixture manifest: without `preview-fixture` it waits at the source chooser, while a valid query selects directly; either path returns ordered overlays. `connectWorkerHost(worker, { image?, overlays? })` remains the public base-runtime connector; callers that skip the chooser get an empty overlay list. `apps/web` invokes both and supplies its statically bundled Worker. The opening `init` frame carries the base and ordered overlay URLs, the boot payload delivers the structured index-injection table, and `applyIndexInjections` executes it before the shell entry runs. Script preload rows are advisory and skipped because `/plugins` resources resolve only through the tunnel; `loadBundle` fetches each combo on first demand, embeds its tunnel-only source map as a Base64 data URL, and executes the script as a Blob. The tunnel also exposes fetch-shaped transport, the independent file-upload carrier, and the API client. Request frames preserve Blob bodies through structured clone and transfer `ReadableStream<Uint8Array>` ownership. The Host Worker streams both forms into the route, so neither browser thread creates a complete byte array for a generic-file upload. A Remote stream's uplink crosses as `stream-uplink-item` / `stream-uplink-end` frames into an unbounded `TunnelUplink` that drops items arriving after `end`: the page and its worker are one trusted same-origin boundary, so the Host inbox cap does not apply.
+- **`src/shell/` (the worker's own process layer)** — a browser worker cannot fork, so `node:child_process` is not a stub but an implementation: `spawn` starts the command in its own Web Worker — this same bundle, told by its first frame to be a shell process — and reports it through the `ChildProcess` surface the subprocess service consumes. The command runs off the host's thread, `SIGKILL` terminates it whatever it is doing, and it reaches the VFS only by message (the host serves those frames). Worker platform executables preserve native-package protocols such as Landlock without replacing their JavaScript packages or coupling their implementations to `node:child_process`; `xdg-open` sends one VFS text file to the page's read-only viewer, so desktop-opener actions such as **Open configuration file** show the file in the page; ordinary commands use the package's evaluator and coreutils command table. The grammar is `@yarnpkg/parsers`' `parseShell`, while `execSync`/`fork` still refuse because they need a real process.
+- **`lib/client.js` (page half)** — startup has two independent stages. `chooseWorkerHostSource({ image?, fixtureManifest? })` optionally owns the boot barrier and fixture manifest: without `preview-fixture` it waits at the source chooser, while a valid query selects directly; either path returns ordered overlays. `connectWorkerHost(worker, { image?, overlays? })` remains the public base-runtime connector; callers that skip the chooser get an empty overlay list. `apps/web` invokes both and supplies its statically bundled Worker. The opening `init` frame carries the base and ordered overlay URLs, the boot payload delivers the structured index-injection table, and `applyIndexInjections` executes it before the shell entry runs. Script preload rows are advisory and skipped because `/plugins` resources resolve only through the tunnel; `loadBundle` fetches each combo on first demand, embeds its tunnel-only source map as a Base64 data URL, and executes the script as a Blob. The worker's unsolicited `view-text` frame opens the page's modal text viewer. The tunnel also exposes fetch-shaped transport, the independent file-upload carrier, and the API client. Request frames preserve Blob bodies through structured clone and transfer `ReadableStream<Uint8Array>` ownership. The Host Worker streams both forms into the route, so neither browser thread creates a complete byte array for a generic-file upload. A Remote stream's uplink crosses as `stream-uplink-item` / `stream-uplink-end` frames into an unbounded `TunnelUplink` that drops items arriving after `end`: the page and its worker are one trusted same-origin boundary, so the Host inbox cap does not apply.
 
 Acceptance lives in `apps/web/tests/preview-boot.e2e.ts`, which serves the real built pages and drives the pre-boot chooser plus Worker activation in headless Chromium. The empty selection exercises first-run startup. The `vfs-example` overlay supplies ordinary workspace files and plaintext persistence artifacts for cold Workspace/Session discovery, tool presentation, subagent navigation, and history paging without a model request. The [packer](../webworker-packer/README.md) prepares current-generation successors from committed historical logs in Node; those source logs remain byte-identical in the overlay. The fixture generator owns the acceptance test's current projection cache. The chooser reserves WebFS as a separate user-authorized source; that provider does not read the built-in fixture.
 
@@ -53,7 +53,8 @@ None; this package neither assembles nor sends a provider request.
 
 - **The worker composition writes plaintext session logs** (`compression: 'none'` boot patch): it carries no Zstandard codec, so exported logs are `.jsonl`, never `.jsonl.zstd`.
 - **`node:dns/promises`, `node:vm`, `node:net`, `node:sqlite`, `node:worker_threads` are structural stubs**: every call reports its refusal on the console and throws. Rows needing native DNS, a real process, or realm isolation cannot run here.
-- **Host package commands are unavailable**: `execa` reports an explicit worker-host refusal; the preview cannot run pnpm or install native dependencies.
+- **Desktop product telemetry is unavailable**: `got.post` reports an explicit worker-host refusal. Got and its Node HTTP dependencies are excluded from the browser image; Desktop reporting remains disabled in the preview composition.
+- **Host package commands are unavailable**: `execa` reports an explicit worker-host refusal; the preview cannot run pnpm, install plugins, or install native dependencies.
 - **PTC Node programs are unavailable**: the process shim exposes `/dsh/bin/node` as its executable identity so the provider can activate, but the Worker has neither a Node executable nor `stripTypeScriptTypes`. Program execution fails before launching a child.
 - **Office conversion requires a Node Host**: the LibreOffice kit replacement rejects converter creation with `unavailable`. The browser image excludes the kit and its engine dependencies; the Office preview reports that conversion is unavailable.
 - **Filesystem watchers observe only the mounted VFS**: image seeding is silent and the VFS has no symlinks or external writers. `persistent`, `ref()`, and `unref()` preserve the Node API but cannot control a dedicated Worker's lifetime because browsers expose no ref-counted event loop.

package/README.zh.md

@@ -27,10 +27,10 @@ kind: "package-library"
 
 一条 tsdown 管线产出三个构建产物；另有一层由源码维护的进程实现：
 
-- **`lib/index.js`（装配库）**——`createWorkerHost`/`startWorkerHost` 挂载基础镜像和按序排列的数据 overlays（`storage/`）、安装模块加载器（`module-system/`）与 `process` shim、经镜像自带的 `dsh-app-boot` 启动插件树，并把服务 seam 交给隧道。Overlay 只能替换 `home/` 与 `workspace/` 下的文件，不能替换基础 manifest、配置或模块。镜像布局契约（`image-layout.ts`：虚拟根、config/manifest 路径、空目录、`lowered` 包装契约门）与 packer 共享。Worker 为 `home/profiles/preview/` 下可编辑的 profile 提供 `profileContext`：打包行初始化其插入 patch，ConfigEditor 将覆盖值持久化到该 VFS patch。ConfigEditor 协调每次写入，Loader 提交实时值；包管理和 Node 模块 HMR 保持禁用。部署 overlay 保持 JSONL 会话日志为明文，preset 根指向镜像内 `config/agent-presets`。配置修改在当前 Worker 生命周期内有效。预设声明包含在组合后的配置中。
+- **`lib/index.js`（装配库）**——`createWorkerHost`/`startWorkerHost` 挂载基础镜像和按序排列的数据 overlays（`storage/`）、安装模块加载器（`module-system/`）与 `process` shim、经镜像自带的 `dsh-app-boot` 启动插件树，并把服务 seam 交给隧道。Overlay 只能替换 `home/` 与 `workspace/` 下的文件，不能替换基础 manifest、配置或模块。镜像布局契约（`image-layout.ts`：虚拟根、config/manifest 路径、空目录、`lowered` 包装契约门）与 packer 共享。Worker 为 `home/profiles/preview/` 下可编辑的 profile 提供 `profileContext`：打包行初始化其插入 patch，ConfigEditor 将覆盖值持久化到该 VFS patch。ConfigEditor 协调每次写入，Loader 提交实时值。Worker 在隧道开始服务后提交 `appReady`，因此 HMR 可以加载并排队处理 profile 配置变更；`process` shim 不报告入口脚本，因此 HMR 不做 Node 模块缓存分类。插件管理可以加载并编辑 profile，其包操作会因 `execa` 拒绝而失败。部署 overlay 保持 JSONL 会话日志为明文，preset 根指向镜像内 `config/agent-presets`。配置修改在当前 Worker 生命周期内有效。预设声明包含在组合后的配置中。
 - **`lib/worker.js`（worker 束）**——装配库加本包的 Node 兼容层，合成一个自含 ES module。模块代理表（`module-proxies.ts`）是唯一平台叉口：`node:*` 内建走 VFS、隧道和浏览器原语，浏览器做不到的走结构化 stub（调用即在 console 报错并抛出），native/binary 包则替换执行后端。`node:module` 在镜像 package 根之上提供 `createRequire().resolve` 与 `.resolve.paths()`，使未修改的包无需执行目标模块即可发现 manifest。`node:util` 的 JSON 数据比较器检查可枚举的自有属性，使 `__proto__` 等记录字段的准入判定与 Node 一致。全局 `process` shim 带有包括 `title` 在内的 Node 环境识别字段，避免 Worker 执行误入仅适用于 DOM 的分支。pack 期解析器会把名称静态可知的模块请求报告给 packer 的可达性遍历，其中包括通过 `node:module` 或 `module` 具名导入在模块作用域直接发起的 `createRequire(import.meta.url)('pkg')` 调用。保存、经 CommonJS 获取或另设基准的 `createRequire` 调用需要镜像入口种子。VFS mutation 驱动 `node:fs` 的 callback、polling 和 promise watcher；打开的 descriptor 在 rename、replacement 和 unlink 后仍保留文件身份与访问模式，只要文件名仍指向该文件，`FileHandle.stat({ bigint: true })` 报告的 device 与 inode 身份就与路径 stat 相同，`FileHandle.chmod()` 则更新打开文件身份的权限；`readable-stream` 提供 `node:stream/promises` 的完成等待与管道方法，以及文件流以及 Chokidar、readdirp 等未修改镜像包所用的流状态机。AsyncLocalStorage 经 pack 时降低注入的 snapshot/restore 面在 `await` 间携带同步栈因果。worker 不带编译器：packer 未降低的镜像在挂载时被拒。回调式 `fs.realpath.native` 别名在已挂载的 VFS 内解析路径，并支持 `util.promisify`。
-- **`src/shell/`（worker 自己的进程层）**——浏览器 worker 无法 fork，所以 `node:child_process` 不是 stub 而是实现：`spawn` 把命令放进它自己的 Web Worker——就是这同一个束，由首帧告诉它「你是 shell 进程」——并以 subprocess 服务消费的 `ChildProcess` 面报告结果。命令不占宿主线程，`SIGKILL` 不管它在干什么都能终止它，而它只能靠消息触达 VFS（由宿主应答这些帧）。Worker 平台 executable 在不替换 JavaScript 包、也不把具体实现耦合进 `node:child_process` 的情况下保持 Landlock 等 native 包协议；普通命令使用本包的求值器与 coreutils 命令表。语法来自 `@yarnpkg/parsers` 的 `parseShell`，而 `execSync`/`fork` 依然拒绝，因为它们需要真进程。
-- **`lib/client.js`（页面半）**——启动分为相互独立的两段。`chooseWorkerHostSource({ image?, fixtureManifest? })` 可选地拥有 boot barrier 与 fixture manifest：没有 `preview-fixture` 时停在来源选择面板，合法 query 则直接选择；两条路径都返回按序排列的 overlays。`connectWorkerHost(worker, { image?, overlays? })` 仍是公开的基础运行态连接器；调用方跳过选择器时 overlay 列表为空。`apps/web` 调用这两段并提供静态打包的 Worker。开局 `init` 帧携带基础镜像与按序排列的 overlay URL，boot 载荷送达结构化 index 注入表，`applyIndexInjections` 在壳入口运行前逐行执行。脚本 preload 行只是提示，因此会被跳过：`/plugins` 资源只能经 tunnel 解析，`loadBundle` 会在首次需要时获取 combo、把仅 tunnel 可达的 sourcemap 内嵌为 Base64 data URL，再以 Blob 执行脚本。Tunnel 还暴露 fetch 形式的传输、独立文件上传载体和 API 客户端。请求帧通过结构化克隆保留 Blob 请求体，并转移 `ReadableStream<Uint8Array>` 的所有权。Host Worker 将两种请求体都逐块送入路由，因此通用文件上传不会在任何浏览器线程创建完整字节数组。Remote 流的上行以 `stream-uplink-item` / `stream-uplink-end` 帧进入没有上限的 `TunnelUplink`，`end` 之后到达的项被丢弃：页面与其 worker 是同一个可信的同源边界，Host 的 inbox 上限在此不适用。
+- **`src/shell/`（worker 自己的进程层）**——浏览器 worker 无法 fork，所以 `node:child_process` 不是 stub 而是实现：`spawn` 把命令放进它自己的 Web Worker——就是这同一个束，由首帧告诉它「你是 shell 进程」——并以 subprocess 服务消费的 `ChildProcess` 面报告结果。命令不占宿主线程，`SIGKILL` 不管它在干什么都能终止它，而它只能靠消息触达 VFS（由宿主应答这些帧）。Worker 平台 executable 在不替换 JavaScript 包、也不把具体实现耦合进 `node:child_process` 的情况下保持 Landlock 等 native 包协议；`xdg-open` 把一个 VFS 文本文件交给页面的只读查看器，因此 **打开配置文件** 等桌面打开操作会在页面内显示该文件；普通命令使用本包的求值器与 coreutils 命令表。语法来自 `@yarnpkg/parsers` 的 `parseShell`，而 `execSync`/`fork` 依然拒绝，因为它们需要真进程。
+- **`lib/client.js`（页面半）**——启动分为相互独立的两段。`chooseWorkerHostSource({ image?, fixtureManifest? })` 可选地拥有 boot barrier 与 fixture manifest：没有 `preview-fixture` 时停在来源选择面板，合法 query 则直接选择；两条路径都返回按序排列的 overlays。`connectWorkerHost(worker, { image?, overlays? })` 仍是公开的基础运行态连接器；调用方跳过选择器时 overlay 列表为空。`apps/web` 调用这两段并提供静态打包的 Worker。开局 `init` 帧携带基础镜像与按序排列的 overlay URL，boot 载荷送达结构化 index 注入表，`applyIndexInjections` 在壳入口运行前逐行执行。脚本 preload 行只是提示，因此会被跳过：`/plugins` 资源只能经 tunnel 解析，`loadBundle` 会在首次需要时获取 combo、把仅 tunnel 可达的 sourcemap 内嵌为 Base64 data URL，再以 Blob 执行脚本。worker 主动发出的 `view-text` 帧会打开页面的模态文本查看器。Tunnel 还暴露 fetch 形式的传输、独立文件上传载体和 API 客户端。请求帧通过结构化克隆保留 Blob 请求体，并转移 `ReadableStream<Uint8Array>` 的所有权。Host Worker 将两种请求体都逐块送入路由，因此通用文件上传不会在任何浏览器线程创建完整字节数组。Remote 流的上行以 `stream-uplink-item` / `stream-uplink-end` 帧进入没有上限的 `TunnelUplink`，`end` 之后到达的项被丢弃：页面与其 worker 是同一个可信的同源边界，Host 的 inbox 上限在此不适用。
 
 验收在 `apps/web/tests/preview-boot.e2e.ts`：静态服务真实构建页面，在 headless Chromium 里驱动 pre-boot 选择面板与 Worker 激活。空白选择验证首次启动；`vfs-example` overlay 提供普通 workspace 文件与明文 persistence 产物，无需模型请求即可验证 Workspace/Session 冷发现、工具呈现、subagent 导航和历史分页。[打包器](../webworker-packer/README.zh.md)在 Node 中根据已提交的历史日志准备当前代后继文件；这些源日志在 overlay 中逐字节保持不变。fixture 生成器负责验收测试的当前投影缓存。选择面板为 WebFS 保留独立的用户授权来源；该 provider 不读取内置 fixture。
 
@@ -53,7 +53,8 @@ kind: "package-library"
 
 - **worker 组合写明文会话日志**（`compression: 'none'` boot patch）：不带 Zstandard 编解码器，导出日志是 `.jsonl`，不会是 `.jsonl.zstd`。
 - **`node:dns/promises`、`node:vm`、`node:net`、`node:sqlite`、`node:worker_threads` 是结构化 stub**：每次调用在 console 报告拒绝并抛出。需要原生 DNS、真进程或真 realm 隔离的行在此无法运行。
-- **宿主包管理命令不可用**：`execa` 明确报告 worker host 不支持该调用；预览无法运行 pnpm 或安装原生依赖。
+- **桌面产品埋点不可用**：`got.post` 明确报告 worker host 不支持该调用。浏览器镜像不包含 Got 及其 Node HTTP 依赖；预览组合不启用桌面上报。
+- **宿主包管理命令不可用**：`execa` 明确报告 worker host 不支持该调用；预览无法运行 pnpm、安装插件或安装原生依赖。
 - **PTC Node 程序不可用**：process shim 用 `/dsh/bin/node` 表示可执行文件身份，使 provider 能够激活，但 Worker 既没有 Node 可执行文件，也没有 `stripTypeScriptTypes`。程序执行会在启动子进程前失败。
 - **Office 转换需要 Node Host**：LibreOffice kit 的替代模块以 `unavailable` 拒绝创建转换器。浏览器镜像排除 kit 及其引擎依赖；Office 预览提示转换不可用。
 - **文件 watcher 只能观察已挂载的 VFS**：镜像 seed 不产生事件，VFS 也没有符号链接或外部写入方。`persistent`、`ref()` 和 `unref()` 保留 Node API，但浏览器没有引用计数事件循环，因此这些接口不能控制 dedicated Worker 的生存期。

package/lib/client.js

@@ -52,6 +52,96 @@ function parsePreviewFixtureManifest(value) {
 	};
 }
 //#endregion
+//#region src/client/text-viewer.ts
+/** Read-only text viewer the page shows when the worker's `xdg-open` names a VFS file. */
+const VIEWER_STYLE = `
+  [data-preview-text-viewer] {
+    width: min(960px, calc(100vw - 32px));
+    height: min(720px, calc(100dvh - 32px));
+    padding: 0;
+    box-sizing: border-box;
+    border: 1px solid var(--dsw-alias-border-l2, rgb(0 0 0 / 10%));
+    border-radius: var(--dsw-radius-lg, 16px);
+    color: var(--dsw-alias-label-primary, #0f1115);
+    background: var(--dsw-alias-bg-base, #fff);
+    font-family: var(--dsw-font-family, inherit);
+  }
+  [data-preview-text-viewer][open] { display: flex; flex-direction: column; }
+  [data-preview-text-viewer]::backdrop { background: rgb(0 0 0 / 32%); }
+  [data-preview-text-viewer] header {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 12px 16px;
+    border-bottom: 1px solid var(--dsw-alias-border-l1, rgb(0 0 0 / 6%));
+  }
+  [data-preview-text-viewer] h2 {
+    flex: 1;
+    min-width: 0;
+    margin: 0;
+    overflow: hidden;
+    font-size: 14px;
+    line-height: 22px;
+    font-weight: 500;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  [data-preview-text-viewer] button {
+    height: 28px;
+    padding: 0 12px;
+    border: 1px solid var(--dsw-alias-border-l2, rgb(0 0 0 / 10%));
+    border-radius: var(--dsw-radius-sm, 8px);
+    color: inherit;
+    background: transparent;
+    font: inherit;
+    cursor: pointer;
+  }
+  [data-preview-text-viewer] pre {
+    flex: 1;
+    margin: 0;
+    padding: 16px;
+    overflow: auto;
+    background: var(--dsw-alias-markdown-code-block, transparent);
+    font: 13px/20px ui-monospace, SFMono-Regular, Menlo, monospace;
+    white-space: pre;
+  }
+`;
+/**
+* Show one file in the page's modal viewer, replacing any file it already shows.
+* @param path - Absolute VFS path used as the title.
+* @param text - File contents, rendered as plain text.
+*/
+function showTextViewer(path, text) {
+	let dialog = document.querySelector("dialog[data-preview-text-viewer]");
+	if (dialog === null) {
+		const style = document.createElement("style");
+		style.textContent = VIEWER_STYLE;
+		document.head.append(style);
+		dialog = document.createElement("dialog");
+		dialog.dataset.previewTextViewer = "";
+		const header = document.createElement("header");
+		const title = document.createElement("h2");
+		const close = document.createElement("button");
+		close.type = "button";
+		close.textContent = "Close";
+		const shown = dialog;
+		close.addEventListener("click", () => {
+			shown.close();
+		});
+		dialog.addEventListener("keydown", (event) => {
+			event.stopPropagation();
+		});
+		header.append(title, close);
+		dialog.append(header, document.createElement("pre"));
+		document.body.append(dialog);
+	}
+	const title = dialog.querySelector("h2");
+	title.textContent = path;
+	title.title = path;
+	dialog.querySelector("pre").textContent = text;
+	if (!dialog.open) dialog.showModal();
+}
+//#endregion
 //#region src/client/client.ts
 /** Error carrying stream semantics across independently bundled Client code. */
 var TunnelLogicalStreamError = class extends Error {
@@ -538,6 +628,9 @@ var WorkerTunnel = class {
 				controller.error(reason);
 				return;
 			}
+			case "view-text":
+				showTextViewer(frame.path, frame.text);
+				return;
 			case "stream-item":
 			case "stream-end":
 			case "stream-error": {

package/lib/index.js

@@ -745,6 +745,7 @@ const MODULE_PROXIES = {
 	"sharp": "./node/external_packages/sharp.ts",
 	"node-pty": "./node/external_packages/node-pty.ts",
 	"execa": "./node/external_packages/execa.ts",
+	"got": "./node/external_packages/got.ts",
 	"@vscode/ripgrep": "./node/external_packages/ripgrep.ts",
 	"@earendil-works/pi-ai": "./node/external_packages/pi-ai.ts",
 	"ws": "./node/external_packages/ws.ts"
@@ -768,6 +769,7 @@ const REPLACED_EXTERNAL_PACKAGES = [
 	"koffi",
 	"node-pty",
 	"execa",
+	"got",
 	"sharp",
 	"ws"
 ];
@@ -1657,6 +1659,18 @@ var TunnelServer = class {
 		this.failure = message;
 		for (const frame of this.queue.splice(0)) this.refuse(frame, message);
 	}
+	/**
+	* Ask the page to show one text file in its read-only viewer.
+	* @param path - Absolute VFS path the viewer names.
+	* @param text - File contents.
+	*/
+	viewText(path, text) {
+		this.send({
+			t: "view-text",
+			path,
+			text
+		});
+	}
 	send(frame, transfer) {
 		this.port.postMessage(frame, transfer);
 	}
@@ -1979,6 +1993,8 @@ function signalProcess(pid, signal) {
 * packages use the presence of `process.title` to avoid browser-only globals.
 * @module @deepseek-ai/dsh-experimental-webworker-runtime/src/node/globals/process
 */
+/** Virtual executable identity; the worker has no Node binary behind it. */
+const EXEC_PATH = "/dsh/bin/node";
 /**
 * Publish `globalThis.process`.
 *
@@ -1996,9 +2012,9 @@ function installProcessGlobal(options) {
 	};
 	const shim = {
 		env: { ...options.env },
-		argv: [...options.argv ?? ["node", "dsh-webworker"]],
+		argv: [...options.argv ?? [EXEC_PATH]],
 		execArgv: [],
-		execPath: "/dsh/bin/node",
+		execPath: EXEC_PATH,
 		title: "dsh-webworker",
 		platform: "linux",
 		arch: "x64",
@@ -3373,6 +3389,7 @@ function createWorkerHost(options) {
 			const require = loader.requireFrom(dirname(configPath));
 			const appBoot = require("@deepseek-ai/dsh-app-boot");
 			const cmdline = require("@deepseek-ai/dsh-cmdline");
+			const started = Promise.withResolvers();
 			const { patches, profile } = bootPatches(loader, mounted, configPath, root);
 			const profileConfig = join(profile.dir, "cordis.yml");
 			const ctx = await appBoot.boot("dsh-webworker", profileConfig, patches, (hostCtx) => {
@@ -3389,7 +3406,16 @@ function createWorkerHost(options) {
 					]],
 					exit: (code) => {
 						console.warn(`webworker host: tree requested exit(${String(code)})`);
-					}
+					},
+					ready: { onReady: (listener) => {
+						let pending = true;
+						started.promise.then(() => {
+							if (pending) listener();
+						});
+						return () => {
+							pending = false;
+						};
+					} }
 				});
 			});
 			context = ctx;
@@ -3406,6 +3432,7 @@ function createWorkerHost(options) {
 				openStream: (endpoint, payload, uplink, signal) => typertGateway.wireStream.open(endpoint, payload, uplink, void 0, signal),
 				streamFailure: typertGateway.wireStream.failure
 			});
+			started.resolve();
 		} catch (reason) {
 			tunnel.fail(reason);
 			throw reason;
@@ -3501,10 +3528,6 @@ function bootPatches(loader, vfs, configPath, root) {
 	};
 	const configOf = (row) => typeof row.config === "object" && row.config !== null && !Array.isArray(row.config) ? row.config : {};
 	const patches = [];
-	for (const id of ["hmr", "plugin-manager"]) if (find(rows, id) !== void 0) patches.push({
-		id,
-		disabled: true
-	});
 	const jsonl = find(rows, "session-persistence-jsonl");
 	if (jsonl !== void 0) patches.push({
 		id: "session-persistence-jsonl",

package/lib/types/client/client.d.ts

@@ -3,6 +3,7 @@
  * turns fetch-shaped calls into `req` frames and rebuilds Responses from the
  * worker's `res` / `res-head`+`res-chunk`+`res-end` frames, so every consumer
  * (boot payload, bundle transport, ApiClient, Typert RPC) speaks plain HTTP.
+ * The worker's unsolicited `view-text` frame opens the page's text viewer.
  */
 import type { IndexInjection } from '@deepseek-ai/dsh-host-webserver';
 /** Boot payload of the tunnel bootstrap route. */

package/lib/types/client/text-viewer.d.ts

@@ -0,0 +1,8 @@
+/** Read-only text viewer the page shows when the worker's `xdg-open` names a VFS file. */
+/**
+ * Show one file in the page's modal viewer, replacing any file it already shows.
+ * @param path - Absolute VFS path used as the title.
+ * @param text - File contents, rendered as plain text.
+ */
+export declare function showTextViewer(path: string, text: string): void;
+//# sourceMappingURL=text-viewer.d.ts.map

package/lib/types/node/external_packages/got.d.ts

@@ -0,0 +1,8 @@
+/** CommonJS interop marker for the worker loader's default import. */
+export declare const __esModule = true;
+/** Reject product telemetry HTTP requests without opening a connection. */
+declare const got: {
+    post: (...args: never[]) => never;
+};
+export default got;
+//# sourceMappingURL=got.d.ts.map

package/lib/types/node/globals/process.d.ts

@@ -4,7 +4,7 @@ export interface ProcessShimOptions {
     readonly cwd: string;
     /** Environment the tree reads; `DSH_HOME` belongs here. */
     readonly env: Readonly<Record<string, string>>;
-    /** Argument vector reported to the tree. */
+    /** Argument vector reported to the tree; defaults to the executable alone, since no entry script exists. */
     readonly argv?: readonly string[];
 }
 /** The members this shim publishes. */

package/lib/types/shell/process/xdg-open.d.ts

@@ -0,0 +1,11 @@
+import type { VirtualExecutable } from './virtual-executables.ts';
+/** Page-side display of one text file. */
+export type TextViewer = (path: string, text: string) => void;
+/**
+ * Install the page viewer `xdg-open` reports to; the worker host calls this once its tunnel exists.
+ * @param next - Viewer that forwards to the page.
+ */
+export declare function setTextViewer(next: TextViewer): void;
+/** Virtual executable replacing the desktop opener with the page's text viewer. */
+export declare const XDG_OPEN_EXECUTABLE: VirtualExecutable;
+//# sourceMappingURL=xdg-open.d.ts.map

package/lib/types/transport/frames.d.ts

@@ -108,8 +108,15 @@ export interface TunnelStreamErrorFrame {
         readonly message: string;
     };
 }
+/** Worker request to show one VFS text file in the page's read-only viewer; no reply follows. */
+export interface TunnelViewTextFrame {
+    readonly t: 'view-text';
+    /** Absolute VFS path, shown as the viewer title. */
+    readonly path: string;
+    readonly text: string;
+}
 /** Frames the worker emits. */
-export type TunnelOutboundFrame = TunnelResponseFrame | TunnelResponseHeadFrame | TunnelResponseChunkFrame | TunnelResponseEndFrame | TunnelResponseErrorFrame | TunnelStreamItemFrame | TunnelStreamEndFrame | TunnelStreamErrorFrame;
+export type TunnelOutboundFrame = TunnelViewTextFrame | TunnelResponseFrame | TunnelResponseHeadFrame | TunnelResponseChunkFrame | TunnelResponseEndFrame | TunnelResponseErrorFrame | TunnelStreamItemFrame | TunnelStreamEndFrame | TunnelStreamErrorFrame;
 /**
  * Validate a `postMessage` payload as a tunnel frame.
  * @param data - Message data received by the worker.

package/lib/types/transport/tunnel.d.ts

@@ -107,6 +107,12 @@ export declare class TunnelServer {
      * @param reason - Boot failure to report.
      */
     fail(reason: unknown): void;
+    /**
+     * Ask the page to show one text file in its read-only viewer.
+     * @param path - Absolute VFS path the viewer names.
+     * @param text - File contents.
+     */
+    viewText(path: string, text: string): void;
     private send;
     private refuse;
     private dispatchFrame;

package/lib/worker.js

@@ -619,6 +619,8 @@ function signalProcess(pid, signal) {
 * packages use the presence of `process.title` to avoid browser-only globals.
 * @module @deepseek-ai/dsh-experimental-webworker-runtime/src/node/globals/process
 */
+/** Virtual executable identity; the worker has no Node binary behind it. */
+const EXEC_PATH = "/dsh/bin/node";
 /**
 * Publish `globalThis.process`.
 *
@@ -636,9 +638,9 @@ function installProcessGlobal(options) {
 	};
 	const shim = {
 		env: { ...options.env },
-		argv: [...options.argv ?? ["node", "dsh-webworker"]],
+		argv: [...options.argv ?? [EXEC_PATH]],
 		execArgv: [],
-		execPath: "/dsh/bin/node",
+		execPath: EXEC_PATH,
 		title: "dsh-webworker",
 		platform: "linux",
 		arch: "x64",
@@ -1098,6 +1100,18 @@ var TunnelServer = class {
 		this.failure = message;
 		for (const frame of this.queue.splice(0)) this.refuse(frame, message);
 	}
+	/**
+	* Ask the page to show one text file in its read-only viewer.
+	* @param path - Absolute VFS path the viewer names.
+	* @param text - File contents.
+	*/
+	viewText(path, text) {
+		this.send({
+			t: "view-text",
+			path,
+			text
+		});
+	}
 	send(frame, transfer) {
 		this.port.postMessage(frame, transfer);
 	}
@@ -2546,6 +2560,50 @@ function requireActiveVfs() {
 	if (active === void 0) throw new Error("webworker vfs: no filesystem is mounted; the worker entry must call setActiveVfs before any node:fs access");
 	return active;
 }
+//#endregion
+//#region src/shell/process/xdg-open.ts
+/**
+* The Worker's `xdg-open`: hands one VFS text file to the page's read-only
+* viewer, the only desktop a preview has. Exit statuses follow xdg-open(1):
+* 1 usage, 2 missing file, 3 no viewer for the target, 4 action failed.
+*/
+let viewer;
+/**
+* Install the page viewer `xdg-open` reports to; the worker host calls this once its tunnel exists.
+* @param next - Viewer that forwards to the page.
+*/
+function setTextViewer(next) {
+	viewer = next;
+}
+function exit(exitCode, stderr = "") {
+	return {
+		kind: "exit",
+		exitCode,
+		stdout: "",
+		stderr
+	};
+}
+/** Virtual executable replacing the desktop opener with the page's text viewer. */
+const XDG_OPEN_EXECUTABLE = {
+	name: "xdg-open",
+	async prepare(args, context) {
+		if (args.length !== 1) return exit(1, "xdg-open: usage: xdg-open { file | URL }\n");
+		const path = resolve$2(context.cwd, args[0]);
+		const stats = await context.filesystem.stat(path);
+		if (stats === void 0) return exit(2, `xdg-open: file '${path}' does not exist\n`);
+		if (stats.directory) return exit(3, `xdg-open: no viewer for directory '${path}'\n`);
+		if (viewer === void 0) return exit(3, "xdg-open: no page viewer is attached\n");
+		try {
+			viewer(path, await context.filesystem.readText(path));
+		} catch (error) {
+			return exit(4, `xdg-open: ${error instanceof Error ? error.message : String(error)}\n`);
+		}
+		return exit(0);
+	},
+	runSync() {
+		return { kind: "asynchronous" };
+	}
+};
 function requireGlobalPort(channel) {
 	if (channel !== void 0) return channel;
 	const post = globalThis.postMessage;
@@ -2576,6 +2634,9 @@ function createWorkerHost(options) {
 		...options.privilegedMethods === void 0 ? {} : { privilegedMethods: options.privilegedMethods },
 		...options.unaryApiLane === void 0 ? {} : { unaryApiLane: options.unaryApiLane }
 	});
+	setTextViewer((path, text) => {
+		tunnel.viewText(path, text);
+	});
 	let vfs;
 	let modules;
 	let context;
@@ -2611,6 +2672,7 @@ function createWorkerHost(options) {
 			const require = loader.requireFrom(dirname$1(configPath));
 			const appBoot = require("@deepseek-ai/dsh-app-boot");
 			const cmdline = require("@deepseek-ai/dsh-cmdline");
+			const started = Promise.withResolvers();
 			const { patches, profile } = bootPatches(loader, mounted, configPath, root);
 			const profileConfig = join$1(profile.dir, "cordis.yml");
 			const ctx = await appBoot.boot("dsh-webworker", profileConfig, patches, (hostCtx) => {
@@ -2627,7 +2689,16 @@ function createWorkerHost(options) {
 					]],
 					exit: (code) => {
 						console.warn(`webworker host: tree requested exit(${String(code)})`);
-					}
+					},
+					ready: { onReady: (listener) => {
+						let pending = true;
+						started.promise.then(() => {
+							if (pending) listener();
+						});
+						return () => {
+							pending = false;
+						};
+					} }
 				});
 			});
 			context = ctx;
@@ -2644,6 +2715,7 @@ function createWorkerHost(options) {
 				openStream: (endpoint, payload, uplink, signal) => typertGateway.wireStream.open(endpoint, payload, uplink, void 0, signal),
 				streamFailure: typertGateway.wireStream.failure
 			});
+			started.resolve();
 		} catch (reason) {
 			tunnel.fail(reason);
 			throw reason;
@@ -2739,10 +2811,6 @@ function bootPatches(loader, vfs, configPath, root) {
 	};
 	const configOf = (row) => typeof row.config === "object" && row.config !== null && !Array.isArray(row.config) ? row.config : {};
 	const patches = [];
-	for (const id of ["hmr", "plugin-manager"]) if (find(rows, id) !== void 0) patches.push({
-		id,
-		disabled: true
-	});
 	const jsonl = find(rows, "session-persistence-jsonl");
 	if (jsonl !== void 0) patches.push({
 		id: "session-persistence-jsonl",
@@ -20711,7 +20779,7 @@ const LANDLOCK_EXECUTABLE = {
 //#endregion
 //#region src/shell/process/virtual-executables.ts
 /** Virtual executable registry used by the Worker process launcher. */
-const EXECUTABLES = new Map([[LANDLOCK_EXECUTABLE.name, LANDLOCK_EXECUTABLE]]);
+const EXECUTABLES = new Map([[LANDLOCK_EXECUTABLE.name, LANDLOCK_EXECUTABLE], [XDG_OPEN_EXECUTABLE.name, XDG_OPEN_EXECUTABLE]]);
 /**
 * Resolve a Worker platform executable by logical name.
 * @param path - Bare name or executable path passed to `spawn`.
@@ -21539,6 +21607,15 @@ var execa_exports = /* @__PURE__ */ __exportAll({ execa: () => execa });
 /** Refuse external package commands in the worker host. */
 const execa = notImplementedFail("execa", "execa");
 //#endregion
+//#region src/node/external_packages/got.ts
+/** Node HTTP product telemetry is unavailable in the browser preview. */
+var got_exports = /* @__PURE__ */ __exportAll({
+	__esModule: () => true,
+	default: () => got
+});
+/** Reject product telemetry HTTP requests without opening a connection. */
+const got = { post: notImplementedFail("got", "post") };
+//#endregion
 //#region src/node/external_packages/pi-ai.ts
 /**
 * `@earendil-works/pi-ai` stub, including its `/providers/all` and `/api/*.lazy`
@@ -21768,6 +21845,7 @@ const REPLACED_EXTERNAL_PACKAGES = [
 	"koffi",
 	"node-pty",
 	"execa",
+	"got",
 	"sharp",
 	"ws"
 ];
@@ -21833,6 +21911,7 @@ const EXTERNALS = {
 	"sharp": () => sharp_exports,
 	"node-pty": () => node_pty_exports,
 	"execa": () => execa_exports,
+	"got": () => got_exports,
 	"ws": () => ws_exports,
 	"@vscode/ripgrep": () => ripgrep_exports,
 	"@earendil-works/pi-ai": () => pi_ai_exports

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-experimental-webworker-runtime",
   "description": "Browser-only harness runtime: in-memory VFS, module transform and loader, postMessage tunnel, and the dedicated Web Worker assembly, with the Node-compatibility layer that lets the host tree run unchanged",
-  "version": "0.1.7-rc.1",
+  "version": "0.2.0-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -34,15 +34,15 @@
     "buffer": "^6.0.3",
     "picomatch": "^4.0.4",
     "readable-stream": "^4.7.0",
-    "@deepseek-ai/dsh-util-crypto": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-web": "0.1.7-rc.1"
+    "@deepseek-ai/dsh-util-crypto": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-web": "0.2.0-rc.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-client-modules": "0.2.0-rc.1",
     "@deepseek-ai/cordis-plugin-loader": "~1.0.5",
-    "@deepseek-ai/dsh-client-connection": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-modules": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "0.1.7-rc.1"
+    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.1"
   },
   "devDependencies": {
     "@types/picomatch": "^3.0.2",
@@ -50,21 +50,21 @@
     "chokidar": "^5.0.0",
     "@deepseek-ai/cordis": "~4.0.4",
     "@deepseek-ai/cordis-plugin-loader": "~1.0.5",
-    "@deepseek-ai/dsh-api-gateway": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-app-boot": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-bash-sandbox": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-connection": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-file-upload": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-modules": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-sandbox-local": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-projection": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-subagent": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-subprocess-local": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-api-gateway": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-app-boot": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-bash-sandbox": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-file-upload": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-sandbox-local": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-subagent": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-subprocess-local": "0.2.0-rc.1",
     "@deepseek-ai/node-addon-system": "~0.1.2",
-    "@deepseek-ai/dsh-sandbox-policy": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.7-rc.1"
+    "@deepseek-ai/dsh-session-projection": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-modules": "0.2.0-rc.1"
   },
   "files": [
     "lib/index.js",