dsh-plugin-core 0.2.14 → 0.4.0

package/docs/help/index.doc.ts

@@ -0,0 +1,79 @@
+// 帮助文档索引 —— 真源（TS 数据模块）。内容全在此一处：md 投影与 demo 站都从这份派生。
+import type { DocTopic } from '../design/doc-format.js'
+
+const doc: DocTopic = {
+  title: { zh: '帮助索引', en: 'Help index' },
+  sections: [
+    {
+      id: 'help-index',
+      heading: { zh: '按你要做的事挑一份', en: 'Pick the one you need' },
+      prose: [
+        {
+          zh: '本索引只回答「读哪一份」。按你要做的事挑一行，跳过去读完就能写代码。',
+          en: 'This index answers one question: which document to read. Pick the row matching your task.',
+        },
+        {
+          zh: '文件都在同一目录（`docs/help/`）：`<主题>.md` 给人读，同名的 `.doc.ts` 是真源。改内容请改真源后重跑 `node scripts/gen-docs.mjs`，`.md` 由它生成。',
+          en: 'Everything lives in `docs/help/`: `<topic>.md` is what you read, the `<topic>.doc.ts` beside it is the source. Edit the source, then rerun `node scripts/gen-docs.mjs` — the `.md` is generated.',
+        },
+      ],
+      api: [
+        {
+          id: 'help-index-table',
+          rows: [
+            {
+              name: '把这个包接进我的插件',
+              type: 'integration.md',
+              def: '—',
+              desc: { zh: '装包、初始化样式、最小可用控件与工具函数、清理，一条龙示例', en: 'Install, style init, minimal working controls and helpers, teardown — end to end' },
+            },
+            {
+              name: '用控件（按钮 / 输入 / 选择器 / 弹窗 / 右侧分栏）',
+              type: 'ui.md',
+              def: '—',
+              desc: { zh: '控件清单与全部 props；弹窗与 PanelDock 的布局约定在此', en: 'Control inventory and every prop; dialog and PanelDock layout contracts are here' },
+            },
+            {
+              name: '建 style kit、覆盖 token、多插件同页隔离',
+              type: 'design.md',
+              def: '—',
+              desc: { zh: 'design 子包的 API：`createStyleKit` / `registerStyle` / 注入机制', en: 'The `design` subpackage API: `createStyleKit` / `registerStyle` / how injection works' },
+            },
+            {
+              name: '处理日期、字符串、字节、HTTP',
+              type: 'utils.md',
+              def: '—',
+              desc: { zh: '纯函数清单与参数，含每个函数的失败返回值', en: 'Pure helpers and their arguments, including each one’s failure return' },
+            },
+            {
+              name: '加工作区文件浏览与预览',
+              type: 'explorer.md',
+              def: '—',
+              desc: { zh: '右侧分栏预览与文件选择器；都要宿主提供的工作区快照', en: 'Right-dock preview and file picker; both need the host workspace snapshot' },
+            },
+            {
+              name: '把一次会话渲染成只读预览',
+              type: 'session.md',
+              def: '—',
+              desc: { zh: '会话数据链与弹窗 props；归档会话同样可读', en: 'The session data chain and dialog props; archived sessions read fine too' },
+            },
+            {
+              name: '查方法的统一口径（失败不抛错、兜底不编造）',
+              type: 'methods.md',
+              def: '—',
+              desc: { zh: '所有 utils 方法的共同行为约定，写调用代码前先看它', en: 'Shared behavior contract of every utils helper — read before writing call sites' },
+            },
+            {
+              name: '用 token、配色或定制皮肤',
+              type: 'style.md',
+              def: '—',
+              desc: { zh: 'token 清单、明暗判据、能改什么改到哪为止', en: 'Token inventory, dark-mode predicate, and how far customization goes' },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+}
+
+export default doc

package/docs/help/index.md

@@ -0,0 +1,28 @@
+<!-- 本文件由 scripts/gen-docs.mjs 自动生成，请勿手改；改对应的 .doc.ts 后重跑 node scripts/gen-docs.mjs -->
+
+# 帮助索引
+
+> EN: Help index
+
+## 按你要做的事挑一份
+
+> EN: Pick the one you need
+
+本索引只回答「读哪一份」。按你要做的事挑一行，跳过去读完就能写代码。
+
+> EN: This index answers one question: which document to read. Pick the row matching your task.
+
+文件都在同一目录（`docs/help/`）：`<主题>.md` 给人读，同名的 `.doc.ts` 是真源。改内容请改真源后重跑 `node scripts/gen-docs.mjs`，`.md` 由它生成。
+
+> EN: Everything lives in `docs/help/`: `<topic>.md` is what you read, the `<topic>.doc.ts` beside it is the source. Edit the source, then rerun `node scripts/gen-docs.mjs` — the `.md` is generated.
+
+| 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
+|---|---|---|---|---|
+| `把这个包接进我的插件` | `integration.md` | — | 装包、初始化样式、最小可用控件与工具函数、清理，一条龙示例 | Install, style init, minimal working controls and helpers, teardown — end to end |
+| `用控件（按钮 / 输入 / 选择器 / 弹窗 / 右侧分栏）` | `ui.md` | — | 控件清单与全部 props；弹窗与 PanelDock 的布局约定在此 | Control inventory and every prop; dialog and PanelDock layout contracts are here |
+| `建 style kit、覆盖 token、多插件同页隔离` | `design.md` | — | design 子包的 API：`createStyleKit` / `registerStyle` / 注入机制 | The `design` subpackage API: `createStyleKit` / `registerStyle` / how injection works |
+| `处理日期、字符串、字节、HTTP` | `utils.md` | — | 纯函数清单与参数，含每个函数的失败返回值 | Pure helpers and their arguments, including each one’s failure return |
+| `加工作区文件浏览与预览` | `explorer.md` | — | 右侧分栏预览与文件选择器；都要宿主提供的工作区快照 | Right-dock preview and file picker; both need the host workspace snapshot |
+| `把一次会话渲染成只读预览` | `session.md` | — | 会话数据链与弹窗 props；归档会话同样可读 | The session data chain and dialog props; archived sessions read fine too |
+| `查方法的统一口径（失败不抛错、兜底不编造）` | `methods.md` | — | 所有 utils 方法的共同行为约定，写调用代码前先看它 | Shared behavior contract of every utils helper — read before writing call sites |
+| `用 token、配色或定制皮肤` | `style.md` | — | token 清单、明暗判据、能改什么改到哪为止 | Token inventory, dark-mode predicate, and how far customization goes |

package/docs/help/integration.doc.ts

@@ -0,0 +1,114 @@
+// 样例：从零接入一个插件 —— 真源（TS 数据模块）。内容全在此一处，demo 与 md 都从这份派生。
+import type { DocTopic } from '../design/doc-format.js'
+
+const install = `pnpm add dsh-plugin-core`
+const initStyle = `// 插件 client 入口
+import { createStyleKit } from 'dsh-plugin-core/design'
+import { ensureControls, setStyleKit } from 'dsh-plugin-core/ui'
+
+const kit = createStyleKit({ id: 'dsh-task-reminder-ui' })
+setStyleKit(kit)
+ensureControls()`
+const useControl = `import { Button, Input, Picker, showToast } from 'dsh-plugin-core/ui'
+
+h(Input, { value: name, onChange: setName, placeholder: '任务名', error: nameError })
+h(Button, { variant: 'primary', onClick: save }, '保存')
+h(Picker, {
+  options: models,                 // [{ value, label }]
+  value: current,
+  onChange: (v) => setCurrent(v as string),
+  searchable: true,
+  clearable: true,
+})
+showToast('已保存', { variant: 'success' })`
+const useUtils = `import { formatDateTime, relativeFuture, formatBytes } from 'dsh-plugin-core/utils'
+
+formatDateTime(task.runAt, { seconds: true })   // 2026-10-18 09:30:05
+relativeFuture(task.runAt, Date.now())          // 3 分钟后（未来时间用这个）
+formatBytes(file.size)                          // 12 KB`
+const useExplorer = `import { openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+
+// 从 ctx 取出这一小块（不要传整个 ctx）
+const workspaceFiles = ctx.remote.workspaceFiles
+
+// 预览某文件：右侧分栏（挤窄 row 左边的主区，不是浮在上面）
+openFilePreview({ mount: pageRowEl, workspaceFiles, sessionId, path: 'docs/requirements.md' })
+
+// 让用户选文件：锚定按钮旁弹模态，Promise 返回 { path, isDir }（工作区相对路径）
+const picked = await pickWorkspaceFile({ workspaceFiles, sessionId, anchor: btn, filter: { exts: ['ts'] } })`
+const useSession = `import { openSessionView, SessionViewModal } from 'dsh-plugin-core/session'
+
+// sessions / uiConversation 同样从 ctx 取出（懒得取就用官方 client 服务）
+const view = openSessionView(sessions, uiConversation, sessionId, 'dsh-task-reminder')
+if (view !== null) {
+  h(SessionViewModal, {
+    sessionId, view,
+    // 关闭必须释放 retain 引用
+    onClose: () => { view.dispose(); setOpen(false) },
+    onOpenFile: (path) => openFilePreview({ mount: pageRowEl, workspaceFiles, sessionId, path }),
+  })
+}`
+const cleanup = `kit.dispose()   // 撤掉 <style> 标签并清空登记域（插件卸载 / HMR）`
+
+const doc: DocTopic = {
+  title: { zh: '样例：从零接入一个插件', en: 'Example: integrate a plugin from scratch' },
+  sections: [
+    {
+      id: 'quickstart',
+      heading: { zh: '从零接入', en: 'Integrate from scratch' },
+      prose: [
+        {
+          zh: '从装包到用上各子包的完整路径，示例都是可直接粘贴的最小可用版。',
+          en: 'The full path from install to every subpackage, with copy-paste-ready minimal examples.',
+        },
+        { zh: '§0 装包：`react` 是 optional peer，只用 `utils` / `design` 的插件不必装。', en: '§0 Install: `react` is an optional peer — plugins using only `utils`/`design` need not install it.' },
+        {
+          zh: '§1 初始化样式（入口一次）：`id` 必须插件内唯一，多插件同页靠它互不覆盖；变量与类名固定 `dshpc` 前缀，不需传参。',
+          en: '§1 Initialize styles (once at entry): `id` must be unique within the plugin so co-mounted plugins don’t clobber; vars and classes use the fixed `dshpc` prefix, no parameter.',
+        },
+        { zh: '§2 用一个控件', en: '§2 Use a control' },
+        { zh: '§3 用通用方法', en: '§3 Use helpers' },
+        {
+          zh: '§4 接工作区浏览：`mount` 必填（预览面板是布局成员，占宽挤窄主区），传页面那层 flex 行。`sessionId` 必须属于该工作区。',
+          en: '§4 Wire workspace browsing: `mount` is required (the preview panel is a layout member that takes width); pass the page’s flex row. `sessionId` must belong to that workspace.',
+        },
+        {
+          zh: '§5 接会话预览：`openSessionView` 返回 `null` 表示该会话不可解析；拿到 view 后交给 `SessionViewModal`，关闭时记得 `dispose()`。',
+          en: '§5 Wire session preview: `openSessionView` returns `null` when the session cannot be resolved; hand the view to `SessionViewModal` and remember `dispose()` on close.',
+        },
+        { zh: '§6 卸载清理（可选）', en: '§6 Teardown (optional)' },
+      ],
+      code: [
+        { id: 'integration-install', lang: 'bash', src: install },
+        { id: 'integration-init-style', lang: 'ts', src: initStyle },
+        { id: 'integration-use-control', lang: 'tsx', src: useControl },
+        { id: 'integration-use-utils', lang: 'ts', src: useUtils },
+        { id: 'integration-use-explorer', lang: 'tsx', src: useExplorer },
+        { id: 'integration-use-session', lang: 'tsx', src: useSession },
+        { id: 'integration-cleanup', lang: 'ts', src: cleanup },
+      ],
+    },
+    {
+      id: 'reference',
+      heading: { zh: '接入坑', en: 'Pitfalls' },
+      prose: [
+        { zh: '按踩频排序的常犯错误：', en: 'Common mistakes, ranked by frequency:' },
+      ],
+      api: [
+        {
+          id: 'integration-pitfalls',
+          rows: [
+            { name: '忘了 setStyleKit 就渲染控件', type: '现象：样式晚一帧或落到默认 style id', def: '—', desc: { zh: '入口处先调，再渲染', en: 'Call it at entry, then render' } },
+            { name: '指望本包帮你引官方 @deepseek-ai/*', type: '现象：Node 下 ERR_MODULE_NOT_FOUND', def: '—', desc: { zh: '本包 ui 零官方依赖；要用官方件请自行处理平台模块', en: 'Our ui has zero official deps; handle platform modules yourself' } },
+            { name: '给 read 少传第三参 range', type: "现象：远端拒：expected 3 business argument(s) … got 2", def: '—', desc: { zh: '一律显式传 {}', en: 'Always pass {} explicitly' } },
+            { name: '用 relativePast 显示未来时间', type: '现象：「3 分钟后」显示成「刚刚」', def: '—', desc: { zh: '用 relativeFuture', en: 'Use relativeFuture' } },
+            { name: '想让组件自己取工作区 / 模型列表', type: '现象：取不到（通道是插件私有的）', def: '—', desc: { zh: '数据经 props 给，宿主能力经接口注入', en: 'Data via props, host capability via injected interface' } },
+            { name: '暗色不跟随宿主', type: '现象：插件固守一种明暗', def: '—', desc: { zh: '判据是 body[data-ds-dark-theme]，别用 prefers-color-scheme', en: 'Predicate is body[data-ds-dark-theme], not prefers-color-scheme' } },
+          ],
+        },
+      ],
+    },
+  ],
+}
+
+export default doc

package/docs/help/integration.md

@@ -0,0 +1,127 @@
+<!-- 本文件由 scripts/gen-docs.mjs 自动生成，请勿手改；改对应的 .doc.ts 后重跑 node scripts/gen-docs.mjs -->
+
+# 样例：从零接入一个插件
+
+> EN: Example: integrate a plugin from scratch
+
+## 从零接入
+
+> EN: Integrate from scratch
+
+从装包到用上各子包的完整路径，示例都是可直接粘贴的最小可用版。
+
+> EN: The full path from install to every subpackage, with copy-paste-ready minimal examples.
+
+§0 装包：`react` 是 optional peer，只用 `utils` / `design` 的插件不必装。
+
+> EN: §0 Install: `react` is an optional peer — plugins using only `utils`/`design` need not install it.
+
+§1 初始化样式（入口一次）：`id` 必须插件内唯一，多插件同页靠它互不覆盖；变量与类名固定 `dshpc` 前缀，不需传参。
+
+> EN: §1 Initialize styles (once at entry): `id` must be unique within the plugin so co-mounted plugins don’t clobber; vars and classes use the fixed `dshpc` prefix, no parameter.
+
+§2 用一个控件
+
+> EN: §2 Use a control
+
+§3 用通用方法
+
+> EN: §3 Use helpers
+
+§4 接工作区浏览：`mount` 必填（预览面板是布局成员，占宽挤窄主区），传页面那层 flex 行。`sessionId` 必须属于该工作区。
+
+> EN: §4 Wire workspace browsing: `mount` is required (the preview panel is a layout member that takes width); pass the page’s flex row. `sessionId` must belong to that workspace.
+
+§5 接会话预览：`openSessionView` 返回 `null` 表示该会话不可解析；拿到 view 后交给 `SessionViewModal`，关闭时记得 `dispose()`。
+
+> EN: §5 Wire session preview: `openSessionView` returns `null` when the session cannot be resolved; hand the view to `SessionViewModal` and remember `dispose()` on close.
+
+§6 卸载清理（可选）
+
+> EN: §6 Teardown (optional)
+
+```bash id="integration-install"
+pnpm add dsh-plugin-core
+```
+
+```ts id="integration-init-style"
+// 插件 client 入口
+import { createStyleKit } from 'dsh-plugin-core/design'
+import { ensureControls, setStyleKit } from 'dsh-plugin-core/ui'
+
+const kit = createStyleKit({ id: 'dsh-task-reminder-ui' })
+setStyleKit(kit)
+ensureControls()
+```
+
+```tsx id="integration-use-control"
+import { Button, Input, Picker, showToast } from 'dsh-plugin-core/ui'
+
+h(Input, { value: name, onChange: setName, placeholder: '任务名', error: nameError })
+h(Button, { variant: 'primary', onClick: save }, '保存')
+h(Picker, {
+  options: models,                 // [{ value, label }]
+  value: current,
+  onChange: (v) => setCurrent(v as string),
+  searchable: true,
+  clearable: true,
+})
+showToast('已保存', { variant: 'success' })
+```
+
+```ts id="integration-use-utils"
+import { formatDateTime, relativeFuture, formatBytes } from 'dsh-plugin-core/utils'
+
+formatDateTime(task.runAt, { seconds: true })   // 2026-10-18 09:30:05
+relativeFuture(task.runAt, Date.now())          // 3 分钟后（未来时间用这个）
+formatBytes(file.size)                          // 12 KB
+```
+
+```tsx id="integration-use-explorer"
+import { openFilePreview, pickWorkspaceFile } from 'dsh-plugin-core/explorer'
+
+// 从 ctx 取出这一小块（不要传整个 ctx）
+const workspaceFiles = ctx.remote.workspaceFiles
+
+// 预览某文件：右侧分栏（挤窄 row 左边的主区，不是浮在上面）
+openFilePreview({ mount: pageRowEl, workspaceFiles, sessionId, path: 'docs/requirements.md' })
+
+// 让用户选文件：锚定按钮旁弹模态，Promise 返回 { path, isDir }（工作区相对路径）
+const picked = await pickWorkspaceFile({ workspaceFiles, sessionId, anchor: btn, filter: { exts: ['ts'] } })
+```
+
+```tsx id="integration-use-session"
+import { openSessionView, SessionViewModal } from 'dsh-plugin-core/session'
+
+// sessions / uiConversation 同样从 ctx 取出（懒得取就用官方 client 服务）
+const view = openSessionView(sessions, uiConversation, sessionId, 'dsh-task-reminder')
+if (view !== null) {
+  h(SessionViewModal, {
+    sessionId, view,
+    // 关闭必须释放 retain 引用
+    onClose: () => { view.dispose(); setOpen(false) },
+    onOpenFile: (path) => openFilePreview({ mount: pageRowEl, workspaceFiles, sessionId, path }),
+  })
+}
+```
+
+```ts id="integration-cleanup"
+kit.dispose()   // 撤掉 <style> 标签并清空登记域（插件卸载 / HMR）
+```
+
+## 接入坑
+
+> EN: Pitfalls
+
+按踩频排序的常犯错误：
+
+> EN: Common mistakes, ranked by frequency:
+
+| 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
+|---|---|---|---|---|
+| `忘了 setStyleKit 就渲染控件` | `现象：样式晚一帧或落到默认 style id` | — | 入口处先调，再渲染 | Call it at entry, then render |
+| `指望本包帮你引官方 @deepseek-ai/*` | `现象：Node 下 ERR_MODULE_NOT_FOUND` | — | 本包 ui 零官方依赖；要用官方件请自行处理平台模块 | Our ui has zero official deps; handle platform modules yourself |
+| `给 read 少传第三参 range` | `现象：远端拒：expected 3 business argument(s) … got 2` | — | 一律显式传 {} | Always pass {} explicitly |
+| `用 relativePast 显示未来时间` | `现象：「3 分钟后」显示成「刚刚」` | — | 用 relativeFuture | Use relativeFuture |
+| `想让组件自己取工作区 / 模型列表` | `现象：取不到（通道是插件私有的）` | — | 数据经 props 给，宿主能力经接口注入 | Data via props, host capability via injected interface |
+| `暗色不跟随宿主` | `现象：插件固守一种明暗` | — | 判据是 body[data-ds-dark-theme]，别用 prefers-color-scheme | Predicate is body[data-ds-dark-theme], not prefers-color-scheme |

package/docs/help/methods.md

@@ -0,0 +1,58 @@
+# 方法规范（`utils`）
+
+> EN: Helper conventions (`utils`)
+
+`utils` 的口径：**解析失败不抛错、给兜底、不编造**。每个方法都按这一页的口径行事，
+你可以据此预期它们的返回值。
+EN: Every helper behaves as follows: **never throws on bad input, returns a fallback, never invents data**.
+Rely on these guarantees when calling them.
+
+## 总口径
+
+> EN: Core contract
+
+| 情形 | 统一行为 |
+|---|---|
+| 输入解析失败（日期 / 数字） | **不抛错**，返回兜底；兜底可传则传，不可传用固定占位 |
+| 固定占位 | 日期类 `—`，时刻类 `-`，体积类 `—`；可用 `opts.fallback` 覆盖 |
+| 空值（`null` / `undefined` / 空串） | 与解析失败同口径，不特殊崩 |
+| 边界值（0 / 负数 / NaN） | 明确处理，不静默通过 |
+| 时区 | 一律**本机时区**；要显式时区请在调用方转换后再传 |
+
+EN: Parse failure → no throw, fallback instead; placeholders `—` / `-`, overridable via `opts.fallback`;
+null/undefined/empty treated like parse failure; edge values handled explicitly; always local timezone.
+
+## 为什么解析失败不抛错
+
+> EN: Why no throw on bad input
+
+这些方法大量用在渲染路径上（列表每一行都调）。一个坏数据让整页崩，不如显示一个占位符。
+**但兜底不编造**：不知道就不显示，绝不猜一个时间。
+EN: These run in render paths, so one bad row should not take the page down. **The fallback never invents data**:
+if the value is unknown it stays blank, never a guessed time.
+
+## 分模块口径
+
+> EN: Per-module behavior
+
+- **日期**：每个函数的失败返回值都列在它自己的参数表里。
+  `relativePast` / `relativeFuture` 是对偶的，别用错。
+- **字符串**：`truncateBytes` 按 **UTF-8 字节**截断，不切半个字（中文场景必须）。
+  `baseNameOf` 处理目录尾斜杠，不会取成空串。
+- **数字**：`formatBytes` 对 0 与负数返回 `—`，不显示「0 B」这种假精确。
+- **HTTP**：默认 10s 超时；超时抛 `AbortError`，非 2xx 抛带 `status` 的 `HttpError`。
+
+EN: Dates: each function’s failure return is listed in its own parameter table; `relativePast`/`relativeFuture`
+are duals. Strings: `truncateBytes` cuts by UTF-8 bytes. Numbers: `formatBytes` returns `—` for 0 and
+negatives. HTTP: 10s timeout, `AbortError` on timeout, `HttpError` with `status` on non-2xx.
+
+## 多语言口径
+
+> EN: Localization
+
+- 本包自带的固定提示语：**内置中英**，`setLocale` 切换。
+- 需要文案的 API 一律可传 `translate: Translate` 覆盖；不传走内置。
+- 插件自己界面的文案由插件自管——本包不提供插件级 i18n 框架。
+
+EN: Built-in prompts ship with zh/en (`setLocale` to switch); any API that renders text takes
+`translate: Translate` to override; your plugin’s own UI copy is yours to manage.

package/docs/help/session.doc.ts

@@ -0,0 +1,154 @@
+// session 子包的使用帮助 —— 真源（TS 数据模块）。内容全在此一处，demo 与 md 都从这份派生。
+import type { DocTopic } from '../design/doc-format.js'
+
+const usage = `import { openSessionView, SessionViewModal } from 'dsh-plugin-core/session'
+
+// 宿主服务由调用方注入：sessions ← dsh-api-session-controller、
+//   uiConversation ← dsh-client-ui-conversation
+const view = openSessionView(sessions, uiConversation, sessionId, 'dsh-task-reminder')
+if (view !== null) {
+  h(SessionViewModal, {
+    sessionId,
+    view,
+    heading: '镜像升级日报',                    // 标题，缺省「会话预览」
+    onClose: () => { view.dispose(); setOpen(false) },   // 关闭必须 dispose
+    // 续聊（可选）：fork 开分支 → 跳官方会话区；两者缺一即不渲染该入口
+    forkSession: (id, atSeq) => sessions.fork({ sessionId: id, increaseTitle: true, atSeq }),
+    openHostSession: (id) => uiWorkspace.openSession(id),
+    // 暂存输入框（可选）：由调用方 fork + 发首轮 + 跳转
+    onContinue: async (message) => {
+      const child = await forkSession(sessionId)
+      await hostContinue(child, message)
+      openHostSession(child)
+    },
+    onOpenFile: (path) => openFilePreview(path), // 文件打开出口
+    archived,                                   // 是否已归档
+    t,                                          // 可选，覆盖文案
+  })
+}`
+
+const dataChain = `// 数据链（越往上越早）：
+//   sessions.retain(id, { source })  物化 scope
+//     → sessions.binding(id)         取绑定
+//     → session.open()               幂等拉历史尾页
+//     → uiConversation.binding(binding).target('chat')
+//                                     拿 ChatSnapshot：order + nodes（keyed 流）
+// 用完必须 view.dispose()，否则会话 scope 不回收。`
+
+const doc: DocTopic = {
+  title: { zh: 'session —— 会话预览', en: 'session — session preview' },
+  exports: ['SessionViewModal', 'openSessionView'],
+  sections: [
+    {
+      id: 'session',
+      heading: { zh: '会话预览', en: 'Session preview' },
+      prose: [
+        {
+          zh: '把一次会话渲染成**只读弹窗**，观感与官方会话页一致。先用 `openSessionView` 建数据链得到 `view`（不可解析返回 `null`），再交给 `SessionViewModal`；**关闭时必须 `view.dispose()`**。',
+          en: 'Renders one session as a **read-only dialog** that looks like the official session page. First `openSessionView` builds the chain and returns a `view` (`null` when unresolvable), then hand it to `SessionViewModal`; **call `view.dispose()` on close**.',
+        },
+        {
+          zh: '数据全由调用方注入，组件不自己取。`archived` 从官方 `workspaces` 快照的 `archivedSessionIds` 读取并订阅刷新。归档会话走同一条链，同样可读。',
+          en: 'All data is injected by the caller; the component fetches nothing. Read `archived` from `archivedSessionIds` on the official `workspaces` snapshot and keep it subscribed. Archived sessions travel the same chain and read fine.',
+        },
+        {
+          zh: '快照只读，框内不能打字续聊。续聊 = `forkSession` 开分支 + `openHostSession` 跳官方会话区；暂存输入框的确定走 `onContinue`（fork + 发首轮 + 跳转）。',
+          en: 'The snapshot is read-only, so you cannot type inside the dialog. Continuing means `forkSession` + `openHostSession`; the staging input’s confirm goes through `onContinue` (fork + first turn + navigate).',
+        },
+        {
+          zh: '文件出口只有一个：工具卡路径、行内引用、交付卡都走 `onOpenFile`；不传则链接降级为纯文本。预览由调用方开在**页面右侧**（`openFilePreview` 的 dock），弹窗不需要任何遮罩参数。',
+          en: 'There is exactly one file exit: tool-card paths, inline mentions and delivered cards all go through `onOpenFile`; without it links degrade to plain text. The caller opens the preview as a **page-level right column** (the `openFilePreview` dock) — the dialog takes no mask props.',
+        },
+        {
+          zh: '限制：官方样式未注入时回退自绘观感（功能不受影响）；长会话一次全渲染，用「加载更早记录」向前翻页；👍👎 反馈走官方 slots，弹窗没有该插槽。',
+          en: 'Limits: without official styles injected, the self-drawn look applies (functionality unaffected); long sessions render whole, paged backward via "load earlier"; 👍👎 feedback goes through official slots, which this dialog lacks.',
+        },
+      ],
+      api: [
+        {
+          id: 'session-view-target',
+          rows: [
+            {
+              name: 'openSessionView',
+              type: '(sessions, uiConversation, id, retainSource?) => SessionViewTarget | null',
+              def: '—',
+              required: '是',
+              desc: { zh: '建数据链：retain → binding → open → target(chat)；不可解析返回 null', en: 'Builds the chain retain → binding → open → target(chat); null when unresolvable' },
+            },
+            {
+              name: 'target',
+              type: 'SnapshotFace<ChatViewFace | undefined>',
+              def: '—',
+              desc: { zh: 'chat 快照订阅面（供 useSyncExternalStore）', en: 'Chat snapshot surface (for useSyncExternalStore)' },
+            },
+            {
+              name: 'session',
+              type: 'SnapshotFace<SessionSnapshotFace>',
+              def: '—',
+              desc: { zh: '会话自身快照（加载态 / 是否翻尽）', en: 'Snapshot of the session itself (loading state, paged-out)' },
+            },
+            {
+              name: 'loadOlder',
+              type: '() => void',
+              def: '—',
+              desc: { zh: '向前翻一页更早的历史', en: 'Page backward through older history' },
+            },
+            {
+              name: 'dispose',
+              type: '() => void',
+              def: '—',
+              desc: { zh: '释放 retain 引用；弹窗关闭必调', en: 'Release the retain reference; call on close' },
+            },
+          ],
+        },
+        {
+          id: 'session-view-modal',
+          rows: [
+            { name: 'sessionId', type: 'string', def: '—', required: '是', desc: { zh: '要预览的会话', en: 'The session to preview' } },
+            { name: 'view', type: 'SessionViewTarget', def: '—', required: '是', desc: { zh: 'openSessionView 的返回值', en: 'What openSessionView returned' } },
+            { name: 'onClose', type: '() => void', def: '—', required: '是', desc: { zh: '关闭回调；由调用方在里面调 view.dispose()', en: 'Close callback; the caller calls view.dispose() inside it' } },
+            { name: 'heading', type: 'string', def: '「会话预览」', required: '否', desc: { zh: '弹窗标题，通常传宿主 sessions.list 的 displayTitle；会话 id 显示在标题下方副标题行（等宽小字）', en: 'Dialog title, usually the displayTitle from the host sessions.list; the session id sits on the monospace subtitle line below it' } },
+            { name: 'archived', type: 'boolean', def: 'false', required: '否', desc: { zh: '已归档时标题旁显示归档徽标，且「继续对话」先弹 fork 确认框；未归档则直跳官方会话页', en: 'When true an archive badge appears beside the title and "Continue" asks to fork first; when false it jumps straight to the official session page' } },
+            {
+              name: 'forkSession',
+              type: '(sessionId, atSeq?) => Promise<string>',
+              def: '—',
+              desc: { zh: '开分支并返回子会话 id；缺 openHostSession 则不渲染「继续对话」', en: 'Fork and resolve the child session id; without openHostSession "Continue" does not render' },
+            },
+            {
+              name: 'openHostSession',
+              type: '(sessionId: string) => void',
+              def: '—',
+              desc: { zh: '跳官方会话区（uiWorkspace.openSession）', en: 'Jump into the official session area (uiWorkspace.openSession)' },
+            },
+            {
+              name: 'onContinue',
+              type: '(message: string) => Promise<void>',
+              def: '—',
+              desc: { zh: '暂存输入框的确定：调用方完成 fork + 发首轮 + 跳转；缺省 = 不渲染输入框', en: 'Staging input confirm: caller forks, sends the first turn, navigates; absent = no input rendered' },
+            },
+            {
+              name: 'onOpenFile',
+              type: '(path: string, sessionId: string) => void',
+              def: '—',
+              desc: { zh: '文件打开出口（工具卡 fileLink / 行内引用 / 交付卡共用）；第二参是文件所属会话 id，别拿别的会话去定位；缺省 = 链接纯文本', en: 'File-open exit shared by fileLinks, mentions and delivered cards; the second arg is the owning session id — locate the file there, not elsewhere; absent = plain text' },
+            },
+            {
+              name: 'onOpenReview',
+              type: '(locator: ChangedFileReviewLocator) => void',
+              def: '—',
+              desc: { zh: '变更文件的审阅出口（等价官方 openReview）；缺省 = 变更卡整张不可点', en: 'Review exit for changed files (equals official openReview); absent = the change card is not clickable' },
+            },
+            { name: 't', type: 'Translate', def: '内置', desc: { zh: '覆盖文案（内置字典已含全部会话文案，中英）', en: 'Override copy (the built-in dictionary has all session copy, zh+en)' } },
+          ],
+        },
+      ],
+      code: [
+        { id: 'session-usage', lang: 'tsx', src: usage },
+        { id: 'session-data-chain', lang: 'ts', src: dataChain },
+      ],
+    },
+  ],
+}
+
+export default doc