@morlay/dsh-client-modules 0.0.0-stage → 0.2.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 morlay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @morlay/dsh-client-modules
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+客户端的**联邦预编译**链：按请求触发、按包产出，把三方包与仓库内的包统一成带版本的地址
+（`/@client-modules/<pkg>@<version>/<export>`），dev 与打包形态共用同一条链、同一套插件。
+
+- **dev**：宿主内起 vite（middleware 模式），裸说明符指向联邦地址、正在改的包逐文件走（HMR）；
+- **打包**：直接跑 rolldown 产出到 profile 的缓存目录，路由按产物清单（`.files.json`）服务。
+
+判据、分工与坑都在 [设计：客户端资源的联邦式预编译](./.agents/designs/20261013-客户端资源的联邦式预编译.md)
+（URL 空间、出口名↔文件名、版本表、拆分配下限、两种形态的差异与 `--prod` 的验证面）。
+
+被 [`@local/dshdev`](../../../devpackages/dshdev/README.md) 经 `@morlay/web-custom-profile` 挂进 profile；上游内部
+文件按需 vendored 到各包的 `src/vendor/`（同步工具见 `@local/upstream-sync`）。
+
+## 浏览器侧：只补上游的 `modules` 服务面
+
+本包的 client 半不做别的事——它只把上游 `modules` 服务补上（`entries.releaseChange` 恒 `undefined`、
+`dismissRelease()` 与 `invalidate()` 空操作），见
+[`src/client/index.ts`](./src/client/index.ts) 的文件头。
+
+原因：上游 `ui-settings-general`（侧栏左下角那个设置入口的占位者）从 0.2.x 起 inject `modules`，
+而上游 `client-modules` 行已被 `web-custom-profile` 停用（模块表 roster 与 `/plugins` 路由由本链取代），
+浏览器侧于是没有这个服务——那一行永远等不到 inject 满足，设置入口整个消失。**停用一行就要补上它对外
+承诺的服务面**，这是本包必须带着 client 半的原因。

package/app-boot/base.css

@@ -0,0 +1,187 @@
+/* 挂载默认样式：`html, body, #root` 撑满、字体栈、灰度抗锯齿与基础配色。
+ *
+ * 这几条本来由上游 shell 的挂载面带来（`@deepseek-ai/dsh-client-web/src/base.css`），而我们自研入口
+ * 不走 shell——那就**自己带一份**：包名是唯一的寻址入口，而 `dsh-client-web` 是上游 web 应用的包，
+ * 不在我们的部署闭包（`@deepseek-ai/dsh-client-web` 解析成 `0.0.0` 就是没装）。语义照它抄，
+ * 主题 token（`--dsw-*`）仍由 `ui-theme` 的 client 半在运行时注入——这里的回退值只是"注入之前别闪"。 */
+
+html,
+body,
+#root {
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  font-family: var(
+    --dsw-font-family,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    "PingFang SC",
+    "Hiragino Sans GB",
+    "Microsoft YaHei",
+    "Helvetica Neue",
+    Helvetica,
+    Arial,
+    sans-serif
+  );
+  /* 灰度抗锯齿优于次像素渲染：WebKit/Blink 与 Firefox 在 macOS 上的等价写法，其余引擎忽略这两行。 */
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  color: var(--dsw-alias-label-primary, #0f1115);
+  background: var(--dsw-alias-bg-base, #fff);
+}
+
+/* ---- 启动页（`boot-page.ts`）：与上游 `@deepseek-ai/dsh-client-web/src/boot-page.module.css` 一致。
+ *
+ * 这份**不能**依赖主题注入成功——它的职责正是"主题/插件还没到"的那段；`--dsw-*` 有就取，没有就用这里的
+ * 回退值（深色模式按 `body[data-ds-dark-theme]` 换一组）。 */
+
+.dsh-boot {
+  --dsh-boot-label-primary: #0f1115;
+  --dsh-boot-label-secondary: #61666b;
+  --dsh-boot-label-tertiary: #81858c;
+  --dsh-boot-border: rgb(0 0 0 / 10%);
+  --dsh-boot-brand: #0f1115;
+
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: var(--dsw-alias-bg-base, var(--dsh-boot-bg, Canvas));
+}
+
+body[data-ds-dark-theme] .dsh-boot {
+  --dsh-boot-label-primary: #f9fafb;
+  --dsh-boot-label-secondary: #cfd3d6;
+  --dsh-boot-label-tertiary: #adb2b8;
+  --dsh-boot-border: rgb(255 255 255 / 12%);
+  --dsh-boot-brand: #f9fafb;
+}
+
+.dsh-boot-card {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+}
+
+.dsh-boot-wordmark {
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  color: var(--dsw-alias-label-primary, var(--dsh-boot-label-primary));
+}
+
+.dsh-boot-hint {
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-tertiary, var(--dsh-boot-label-tertiary));
+}
+
+.dsh-boot-spinner {
+  position: relative;
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  corner-shape: round;
+  border: 2px solid var(--dsw-alias-border-l2, var(--dsh-boot-border));
+  animation: dsh-boot-spin 0.8s linear infinite;
+}
+
+.dsh-boot-spinner::after {
+  content: "";
+  position: absolute;
+  inset: -2px;
+  border-radius: inherit;
+  background: conic-gradient(
+    var(--dsw-alias-brand-primary, var(--dsh-boot-brand)) var(--dsh-boot-arc, 72deg),
+    transparent 0
+  );
+  -webkit-mask: radial-gradient(farthest-side, transparent calc(100% - 2px), #000 0);
+  mask: radial-gradient(farthest-side, transparent calc(100% - 2px), #000 0);
+}
+
+@keyframes dsh-boot-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.dsh-boot-failed {
+  max-width: 480px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.dsh-boot-failed-title {
+  font-size: 14px;
+  line-height: 22px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary, var(--dsh-boot-label-primary));
+}
+
+.dsh-boot-failed-item {
+  font-family: var(--ds-font-family-code, "SF Mono", "JetBrains Mono", Consolas, Menlo, monospace);
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-secondary, var(--dsh-boot-label-secondary));
+  white-space: pre-wrap;
+}
+
+/* ---- macOS 桌面：**唯一的拖拽声明**（与上游 `@deepseek-ai/dsh-client-web/src/base.css` 一致）。
+ *
+ * 我们不走上游 shell，这几条得自己带。一条 chrome row 在 markup 里标 `data-window-drag`，它自己的盒子就是
+ * 可拖拽几何（不必再让某条固定高度的带子去对齐）——侧边栏顶部那条 strip 就是这么标的：在 macOS 上拖它
+ * 即拖窗口，而它上面的按钮照常点击（这就是"穿透"）。
+ *
+ * Electron 按**几何**合成 app-region 而不是命中测试，所以盖在 row 上的浮层要自己减掉：`body` 的直接子元素
+ * （除 `#root`）与 `#root` 里的交互控件（原生元素、ARIA role、tabindex 的自定义件）一条选择器统一减，
+ * 不必每个组件各自 opt-out。`data-window-drag-recall` 是"某条 row 的盒子动过、要 Electron 重收拖拽矩形"
+ * 的那一帧脉冲（electron#32341）。 */
+
+html[data-platform="darwin"] [data-window-drag] {
+  -webkit-app-region: drag;
+}
+
+html[data-platform="darwin"] [data-window-drag-recall] {
+  -webkit-app-region: no-drag;
+}
+
+html[data-platform="darwin"] body > :not(#root) {
+  -webkit-app-region: no-drag;
+}
+
+html[data-platform="darwin"]
+  :is(
+    button,
+    a,
+    input,
+    select,
+    textarea,
+    summary,
+    [contenteditable="true"],
+    [tabindex],
+    [role="dialog"],
+    [role="alertdialog"],
+    [role="menu"],
+    [role="listbox"],
+    [role="tooltip"],
+    [role="button"],
+    [role="link"],
+    [role="tab"],
+    [role="menuitem"],
+    [role="menuitemcheckbox"],
+    [role="menuitemradio"],
+    [role="option"],
+    [role="checkbox"],
+    [role="radio"],
+    [role="switch"],
+    [role="slider"],
+    [role="combobox"],
+    [role="textbox"]
+  ) {
+  -webkit-app-region: no-drag;
+}

package/app-boot/boot-page.ts

@@ -0,0 +1,110 @@
+/**
+ * 启动页与失败报告：**framework-free**，与上游 `@deepseek-ai/dsh-client-web/src/boot-page` 一致。
+ *
+ * 插件开始注册到 UI 渲染器接管挂载点之间，页面上先是它——React 要等 `ui-renderer` 才到，那之前必须有个
+ * 不依赖框架的东西能把"正在加载"与"失败了"显示出来（否则就是白屏，而原因只有 console 里看得见）。
+ *
+ * @module @morlay/dsh-client-modules/app-boot/boot-page
+ */
+/** 装配期一行的状态投影（对应上游的 `LoaderEntryState`，这里只关心这四态）。 */
+export type BootEntryState = "pending" | "loading" | "active" | "failed";
+
+/** Create a div with one module class and optional text. */
+function div(className: string | undefined, text?: string): HTMLDivElement {
+  const el = document.createElement("div");
+  el.className = className ?? "";
+  if (text !== undefined) el.textContent = text;
+  return el;
+}
+
+/** 内核自己的启动页：挂在应用挂载点里面，直到 UI 渲染器接管。 */
+export class BootPage {
+  private readonly root: HTMLDivElement;
+  private readonly card: HTMLDivElement;
+  private readonly wordmark: HTMLDivElement;
+  private readonly spinner: HTMLDivElement;
+  private readonly hint: HTMLDivElement;
+  private readonly states = new Map<string, BootEntryState>();
+  private readonly active = new Set<string>();
+  private total = 0;
+  private failure: string | undefined;
+
+  /**
+   * Build and attach the boot page.
+   *
+   * @param container - Application mount point.
+   */
+  constructor(container: HTMLElement) {
+    this.root = div("dsh-boot");
+    this.root.dataset["dshBoot"] = "";
+    this.card = div("dsh-boot-card");
+    this.wordmark = div("dsh-boot-wordmark", "HARNESS");
+    this.spinner = div("dsh-boot-spinner");
+    this.spinner.dataset["dshBootSpinner"] = "";
+    this.hint = div("dsh-boot-hint", "Loading plugins…");
+    this.card.append(this.wordmark, this.spinner, this.hint);
+    this.root.append(this.card);
+    container.append(this.root);
+    this.updateProgress();
+  }
+
+  /**
+   * Set the number of assembly rows represented by the progress arc.
+   *
+   * @param total - Complete boot roster size.
+   */
+  setTotal(total: number): void {
+    this.total = total;
+    this.updateProgress();
+  }
+
+  /**
+   * Project one row's state.
+   *
+   * @param id - Row (package) name.
+   * @param state - Projected state.
+   */
+  setState(id: string, state: BootEntryState): void {
+    this.states.set(id, state);
+    if (state === "active") this.active.add(id);
+    this.updateProgress();
+    this.render();
+  }
+
+  /**
+   * Display the boot failure report.
+   *
+   * @param message - Failure report text.
+   */
+  fail(message: string): void {
+    this.failure = message;
+    this.render();
+  }
+
+  /** Detach the page before or after the UI renderer takes the mount point. */
+  dispose(): void {
+    this.root.remove();
+  }
+
+  /** Redraw the state-dependent content below the wordmark. */
+  private render(): void {
+    const failed = [...this.states].filter(([, state]) => state === "failed").map(([id]) => id);
+    if (this.failure === undefined && failed.length === 0) {
+      if (this.spinner.parentElement !== this.card) {
+        this.card.replaceChildren(this.wordmark, this.spinner, this.hint);
+      }
+      return;
+    }
+    const report = div("dsh-boot-failed");
+    report.append(div("dsh-boot-failed-title", "Failed to load plugins"));
+    for (const id of failed) report.append(div("dsh-boot-failed-item", id));
+    if (this.failure !== undefined) report.append(div("dsh-boot-failed-item", this.failure));
+    this.card.replaceChildren(this.wordmark, report);
+  }
+
+  /** Grow the rotating arc monotonically as rows activate. */
+  private updateProgress(): void {
+    const ratio = this.total === 0 ? 0 : Math.min(this.active.size / this.total, 1);
+    this.spinner.style.setProperty("--dsh-boot-arc", `${String(Math.round(72 + ratio * 216))}deg`);
+  }
+}

package/app-boot/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>DSH Local Build</title>
+  </head>
+  <body>
+    <!-- 容器与上游一致：`#root`（`apps/web/index.html`）。挂载点换名字会让上游按 `#root` 写的样式失效。 -->
+    <div id="root"></div>
+    <!-- vite 的入口：它自己会把 index.ts 转译、解析依赖、并挂上 HMR。这里是 **root 相对**路径
+         （vite 的 root 就是这个目录）——HTML 里的 `src` 是 URL，不走 alias 解析。 -->
+    <script type="module" src="./index.ts"></script>
+  </body>
+</html>

package/app-boot/index.ts

@@ -0,0 +1,101 @@
+/**
+ * dev 客户端的应用入口（真实文件，由 vite 当普通入口处理）。
+ *
+ * 它只做装配：从虚拟模块 `virtual:dsh-client-rows` 拿行清单（各 client 行的源码入口由插件解析），
+ * 按 `dsh.client.inject` 的顺序 `ctx.plugin(...)`，最后等 `root` slot 就绪再挂载。
+ *
+ * 页面 HTML 与入口都是**真实文件**——vite 的 root 指向仓库根，它按自己的机制转译、预打包依赖、挂 HMR，
+ * 我们不再自己生成脚本、也不再自己拦路由。
+ */
+// 品牌字体样式：上游的 Web 入口同样单独引这一份（`apps/web/src/main.ts`）；其余全局样式表由 `ui-theme`
+// 的 client 半用 `?inline` 在运行时注入。
+//
+// **按包名引**（与上游 `main.ts` 一致），不写 `@/vendor/…` 这类仓库路径：包名是唯一的寻址入口，走哪条
+// 链（联邦产物 / 源码）由解析规则决定——写仓库路径等于把 vendor 的目录布局抄进代码，还会把一份样式
+// 拆成一串 `/vendor/…` 的逐文件请求。
+import "@deepseek-ai/dsh-client-ui-theme/brand-font.css";
+// 挂载默认样式（`html, body, #root { height: 100%; margin: 0 }` 与 body 的字体/颜色/抗锯齿）：这份
+// 自己带——上游由 shell 的 `client/web/src/boot.ts` 引入，而**我们不走 shell**；`dsh-client-web` 是上游
+// web 应用的包，不在我们的部署闭包里（按包名引会解析成 `0.0.0` 而 404）。
+import "./base.css";
+import { BootPage } from "./boot-page.ts";
+import { Context } from "@deepseek-ai/cordis";
+// @ts-expect-error 虚拟模块由 devkit 的 vite 插件提供
+import rows from "dsh-client-rows";
+
+declare global {
+  // eslint-disable-next-line no-var -- 调试面：e2e 与人工排查都从这里读装配结果。
+  var __DSH_CTX__: Context | undefined;
+}
+
+const ctx = new Context();
+globalThis.__DSH_CTX__ = ctx;
+console.log("[dsh] entry: context created", rows.length, "rows");
+
+// cordis 把 fiber 内的失败交给 `ctx.logger.error`，而它在浏览器里默认不落 console —— 接到 console，
+// 装配期的失败才看得见（否则只有"页面空白 + 无报错"）。
+const originalError = ctx.logger?.error?.bind(ctx.logger);
+if (ctx.logger !== undefined) {
+  ctx.logger.error = (...args) => {
+    console.error("[dsh] cordis error", ...args);
+    if (originalError !== undefined) originalError(...args);
+  };
+}
+
+// 容器与上游一致：`#root`（`apps/web/index.html`）。挂载点与启动页都在注册**之前**取好。
+const container = document.getElementById("root");
+if (container === null) throw new Error("[dsh] entry: #root 挂载点不存在");
+
+// **启动页**（与上游一致）：React 要等 `ui-renderer` 才到，那之前由它显示"正在加载 / 失败了"——没有它就是
+// 白屏，而失败原因只在 console 里。它挂在 `#root` 里面，渲染器接管时摘掉。
+const boot = new BootPage(container);
+boot.setTotal(rows.length);
+
+// **按模块身份去重**：行清单里可能出现两条指向同一个包的 entry（包名写法不同，如带 `/client` 后缀），
+// 那样同一个模块会被 `ctx.plugin` 两次——第二次 `apply` 就撞上"同 namespace 的 locale 已注册"这类
+// 重复注册断言。
+const plugged = new Set<unknown>();
+for (const [index, row] of rows.entries()) {
+  const mod = row.module;
+  if (plugged.has(mod)) {
+    console.warn("[dsh] 同一模块出现在多行，跳过", row.id);
+    continue;
+  }
+  plugged.add(mod);
+  // client 行的导出有两种形状：`{ apply, inject }` 与 `{ default: X }`。整块交给 cordis——不要自己拼
+  // `{ apply: factory.apply }`：default 形状上没有 `apply`，那样会取到 `Function.prototype.apply`。
+  const plugin = typeof mod.apply === "function" ? mod : (mod.default ?? undefined);
+  if (plugin === undefined) {
+    console.warn("[dsh] skip (no apply/default)", row.id);
+    continue;
+  }
+  try {
+    console.log("[dsh] plugin", index, row.id, "inject:", JSON.stringify(plugin.inject ?? []));
+    ctx.plugin(plugin, { name: plugin.name ?? row.id });
+    boot.setState(row.id, "active");
+  } catch (error) {
+    console.error("[dsh] plugin failed", row.id, error);
+    boot.setState(row.id, "failed");
+    boot.fail(String(error));
+  }
+}
+console.log("[dsh] entry: plugins registered");
+
+// 容器与上游一致：`#root`（`apps/web/index.html`）。
+
+// 等 **'root' slot 真的注册**再挂载：`layout` 服务在注册 slot 之前就已提供（`provide('layout')` 早于
+// `slots.register({name:'root'})`），所以等 uiRenderer 就绪不够——那时挂载会渲染一棵空树，之后注册也不会补渲。
+// 上层（`ui-layout` 的 apply）是异步的，这里给一个上限轮询。
+for (let attempt = 0; attempt < 300; attempt += 1) {
+  if ((ctx.slots?.entries?.("root")?.length ?? 0) > 0) break;
+  await new Promise((resolve) => setTimeout(resolve, 20));
+}
+console.log("[dsh] entry: root slot ready");
+
+// 渲染器接管挂载点：启动页摘掉（挂在它里面会跟着一起被替换，这里显式收尾）。
+boot.dispose();
+
+await ctx.inject(["uiRenderer"], (scope) => {
+  scope.effect(() => scope.uiRenderer.mount(container), "dev entry: application mount");
+});
+console.log("[dsh] entry: mounted");

package/app-boot/node-stub.cjs

@@ -0,0 +1,19 @@
+// 联邦构建（rolldown，CJS 产物）用的 `node:*` 替身。
+//
+// 与同目录的 `node-stub.ts`（dev 逐文件服务用的 ESM 形态）**同一语义**：这些 API 在浏览器里本不该被
+// 调用，但模块求值不该中断。形态为什么要分两份：ESM 的具名导入在构建期要**校验存在性**（缺了就
+// `MISSING_EXPORT`），而 CJS 不校验——联邦产物的 `require("node:fs")` 需要的就是后者。
+//
+// 缺了这个文件时，构建报的是 `UNLOADABLE_DEPENDENCY`，整包构建失败、页面上那一路直接 404。
+module.exports = {
+  Readable: class {},
+  Writable: class {},
+  Duplex: class {},
+  Transform: class {},
+  PassThrough: class {},
+  pipeline: (...args) => {
+    const done = args.at(-1);
+    if (typeof done === "function") done();
+  },
+  promises: {},
+};

package/app-boot/node-stub.ts

@@ -0,0 +1,23 @@
+/**
+ * 浏览器里的 `node:*` 替身。
+ *
+ * 宿主半的代码有时被**同包的相对导入**拖进 client 图（典型是 `client/connection` 的 client 半引到
+ * `src/loopback-hostname.ts`、再链到 `src/http-bridge.ts`，那里 `import { Readable } from 'node:stream'`）。
+ * vite 默认把 `node:*` 换成 browser-external 代理，**读取成员时抛错**，于是一整条入口求值中断——页面白屏
+ * 且只有一条难以归因的报错。这里给出求值安全的空实现：这些 API 在浏览器里本不该被调用，但模块求值不应中断。
+ *
+ * **两份形态、同一语义**：dev 形态逐文件服务，缺失的具名导入只是 undefined（运行期），这份 ESM 够用；
+ * 联邦构建走 rolldown，它把"没有该具名导出"当**构建错误**（`MISSING_EXPORT`），那里得用 CJS 形态的
+ * `node-stub.cjs`——CJS 的具名导入不校验存在性。
+ */
+export class Readable {}
+export class Writable {}
+export class Duplex {}
+export class Transform {}
+export class PassThrough {}
+export const pipeline = (...args: unknown[]): void => {
+  const done = args.at(-1);
+  if (typeof done === "function") (done as () => void)();
+};
+export const promises = {};
+export default { Readable, Writable, Duplex, Transform, PassThrough, pipeline, promises };

package/dist/client.cjs

@@ -0,0 +1,65 @@
+window.__ModuleLoader__.load({
+	id: "@morlay/dsh-client-modules",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		//#region src/client/index.ts
+		/** 恒 `undefined` 的可订阅快照（`useSyncExternalStore` 的入参形状）。 */
+		const NO_RELEASE_CHANGE = {
+			getSnapshot: () => void 0,
+			subscribe: () => () => {}
+		};
+		/**
+		* 浏览器侧的根插件。
+		*
+		* @param ctx - 浏览器侧根上下文。
+		*/
+		function apply(ctx) {
+			ctx.reflect.provide("modules", {
+				entries: {
+					releaseChange: NO_RELEASE_CHANGE,
+					dismissRelease: () => {}
+				},
+				invalidate: () => {}
+			});
+			installTerminalRecovery(ctx);
+		}
+		/**
+		* 终端恢复兜底：`view` 之前先**对账**，把宿主已经不认的终端 id 当新 tab 处理。
+		*
+		* 上游 `TerminalView` 的语义是「新 tab 才分配」（`createWhenMissing = saved === undefined`），而
+		* `saved = terminalId ?? bindings.get(sessionId, contentId)`：UI 传的 `terminalId` 实测是 `undefined`，
+		* 所以决定权全在 `bindings` —— 它不随宿主侧关闭状态失效。清单里没有这个 id（宿主重启过、或那个终端被
+		* 关过）时删掉这条 binding，让上游按新 tab 分配；清单里有则原样透传，恢复能力不变。清单**没加载**时按
+		* 「不在」处理：那时用户要的就是打开一个终端，让它重新分配比卡在死状态里强。
+		*
+		* 注意：`bindings` / `inventories` 是上游 Service 的私有字段，`view` 在其原型上（实例属性覆盖无效，
+		* 见 cordis 的 Service 代理）——所以这里改的是原型。这是**绕过上游缺陷**，等上游把 binding 与关闭状态
+		* 对上账就该删掉。
+		*
+		* @param ctx - 浏览器侧根上下文。
+		*/
+		function installTerminalRecovery(ctx) {
+			ctx.inject(["webTerminals"], (scope) => {
+				const terminals = scope.get("webTerminals");
+				if (terminals === void 0) return;
+				const proto = Object.getPrototypeOf(terminals);
+				if (proto.view === void 0 || proto.__terminalRecovery === true) return;
+				proto.__terminalRecovery = true;
+				const original = proto.view;
+				proto.view = function(sessionId, key, contentId, terminalId, shellPath) {
+					const bound = terminalId ?? this.bindings?.get?.(sessionId, contentId);
+					if (!(bound === void 0 || this.inventories?.get(sessionId)?.items?.has(bound) === true)) {
+						this.bindings?.delete?.(sessionId, contentId);
+						return original.call(this, sessionId, key, contentId, void 0, shellPath);
+					}
+					return original.call(this, sessionId, key, contentId, terminalId, shellPath);
+				};
+			});
+		}
+		//#endregion
+		exports.apply = apply;
+		return module.exports;
+	}
+});

package/dist/client.d.cts

@@ -0,0 +1,9 @@
+import { Context } from "@deepseek-ai/cordis";
+//#region src/client/index.d.ts
+/**
+ * 发布 `modules` 服务（上游同名的服务面，见文件头）。
+ *
+ * @param ctx - 浏览器侧根上下文。
+ */
+export declare function apply(ctx: Context): void;
+//#endregion

package/dist/client.d.mts

@@ -0,0 +1,9 @@
+import { Context } from "@deepseek-ai/cordis";
+//#region src/client/index.d.ts
+/**
+ * 发布 `modules` 服务（上游同名的服务面，见文件头）。
+ *
+ * @param ctx - 浏览器侧根上下文。
+ */
+export declare function apply(ctx: Context): void;
+//#endregion

package/dist/client.mjs

@@ -0,0 +1,56 @@
+//#region src/client/index.ts
+/** 恒 `undefined` 的可订阅快照（`useSyncExternalStore` 的入参形状）。 */
+const NO_RELEASE_CHANGE = {
+	getSnapshot: () => void 0,
+	subscribe: () => () => {}
+};
+/**
+* 浏览器侧的根插件。
+*
+* @param ctx - 浏览器侧根上下文。
+*/
+function apply(ctx) {
+	ctx.reflect.provide("modules", {
+		entries: {
+			releaseChange: NO_RELEASE_CHANGE,
+			dismissRelease: () => {}
+		},
+		invalidate: () => {}
+	});
+	installTerminalRecovery(ctx);
+}
+/**
+* 终端恢复兜底：`view` 之前先**对账**，把宿主已经不认的终端 id 当新 tab 处理。
+*
+* 上游 `TerminalView` 的语义是「新 tab 才分配」（`createWhenMissing = saved === undefined`），而
+* `saved = terminalId ?? bindings.get(sessionId, contentId)`：UI 传的 `terminalId` 实测是 `undefined`，
+* 所以决定权全在 `bindings` —— 它不随宿主侧关闭状态失效。清单里没有这个 id（宿主重启过、或那个终端被
+* 关过）时删掉这条 binding，让上游按新 tab 分配；清单里有则原样透传，恢复能力不变。清单**没加载**时按
+* 「不在」处理：那时用户要的就是打开一个终端，让它重新分配比卡在死状态里强。
+*
+* 注意：`bindings` / `inventories` 是上游 Service 的私有字段，`view` 在其原型上（实例属性覆盖无效，
+* 见 cordis 的 Service 代理）——所以这里改的是原型。这是**绕过上游缺陷**，等上游把 binding 与关闭状态
+* 对上账就该删掉。
+*
+* @param ctx - 浏览器侧根上下文。
+*/
+function installTerminalRecovery(ctx) {
+	ctx.inject(["webTerminals"], (scope) => {
+		const terminals = scope.get("webTerminals");
+		if (terminals === void 0) return;
+		const proto = Object.getPrototypeOf(terminals);
+		if (proto.view === void 0 || proto.__terminalRecovery === true) return;
+		proto.__terminalRecovery = true;
+		const original = proto.view;
+		proto.view = function(sessionId, key, contentId, terminalId, shellPath) {
+			const bound = terminalId ?? this.bindings?.get?.(sessionId, contentId);
+			if (!(bound === void 0 || this.inventories?.get(sessionId)?.items?.has(bound) === true)) {
+				this.bindings?.delete?.(sessionId, contentId);
+				return original.call(this, sessionId, key, contentId, void 0, shellPath);
+			}
+			return original.call(this, sessionId, key, contentId, terminalId, shellPath);
+		};
+	});
+}
+//#endregion
+export { apply };