dsh-plugin-core 0.28.0 → 0.29.0

package/docs/help/session.doc.ts

@@ -1,7 +1,7 @@
 // session 子包的使用帮助 —— 真源（TS 数据模块）。内容全在此一处，demo 与 md 都从这份派生。
 import type { DocTopic } from '../design/doc-format.js'
 
-const usage = `import { openSessionView, SessionViewModal } from 'dsh-plugin-core/session'
+const usage = `import { openSessionView, openSessionReview, SessionViewModal } from 'dsh-plugin-core/session'
 
 // 宿主服务由调用方注入：sessions ← dsh-api-session-controller、
 //   uiConversation ← dsh-client-ui-conversation
@@ -23,6 +23,8 @@ if (view !== null) {
     },
     // 文件打开出口：给一个落点即可（元素或选择器），核心自带右侧分栏
     onOpenFile: (path, sid) => openFilePreview({ mount: '#page-row', path, sessionId: sid }),
+    // 变更文件审阅：一行打开那次改动的 diff（面板 / 关闭钮全归核心）
+    onOpenReview: (locator) => openSessionReview({ mount: '#page-row', locator }),
     archived,                                   // 是否已归档
     t,                                          // 可选，覆盖文案
   })
@@ -38,7 +40,7 @@ const dataChain = `// 数据链（越往上越早）：
 
 const doc: DocTopic = {
   title: { zh: 'session —— 会话预览', en: 'session — session preview' },
-  exports: ['SessionViewModal', 'openSessionView'],
+  exports: ['SessionViewModal', 'openSessionView', 'openSessionReview', 'ChangedFileDiff'],
   sections: [
     {
       id: 'session',
@@ -60,6 +62,10 @@ const doc: DocTopic = {
           zh: '文件出口只有一个：工具卡路径、行内引用、交付卡都走 `onOpenFile`；不传则链接降级为纯文本（可以点但没有出口，不是坏了）。自己已有预览面的，在回调里调你自己的（核心一个 DOM 都不碰）；没有的，一行接上核心自带的右侧分栏：`onOpenFile: (path, sid) => openFilePreview({ mount: \'#page-row\', path, sessionId: sid })`——落点给元素或选择器都行，弹窗不需要任何遮罩参数。',
           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 (clickable-looking but no exit — not a break). If you already own a preview surface, call yours inside the callback (core touches no DOM); otherwise wire core’s dock in one line: `onOpenFile: (path, sid) => openFilePreview({ mount: \'#page-row\', path, sessionId: sid })` — the mount takes an element or a selector, and the dialog needs no mask props.',
         },
+        {
+          zh: '变更文件的审阅出口是 `onOpenReview`，落点用 `openSessionReview({ mount, locator })` 一行接上：`locator`（sessionId / seq / index / display）到 diff 的拼装归会话域，调用方不挑组件、不塞节点、不补 ✕。面板关闭钮由 dock 出；`ChangedFileDiff.onClose` 只给自带壳的容器，不是关面板的手段。',
+          en: 'The review exit for changed files is `onOpenReview`; wire it with one line, `openSessionReview({ mount, locator })`. Turning the locator (sessionId / seq / index / display) into a diff belongs to the session domain — pick no components, pass no nodes, add no ✕. The panel close belongs to the dock; `ChangedFileDiff.onClose` is for containers that own their own chrome, not a way to close the panel.',
+        },
         {
           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.',
@@ -138,7 +144,7 @@ const doc: DocTopic = {
               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' },
+              desc: { zh: '变更文件的审阅出口（等价官方 openReview）；落点用 `openSessionReview({ mount, locator })` 一行接上；缺省 = 变更卡整张不可点', en: 'Review exit for changed files (equals official openReview); wire it with `openSessionReview({ mount, locator })`; 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)' } },
           ],

package/docs/help/session.md

@@ -4,7 +4,7 @@
 
 > EN: session — session preview
 
-导出：SessionViewModal、openSessionView
+导出：SessionViewModal、openSessionView、openSessionReview、ChangedFileDiff
 
 ## 会话预览
 
@@ -26,6 +26,10 @@
 
 > 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 (clickable-looking but no exit — not a break). If you already own a preview surface, call yours inside the callback (core touches no DOM); otherwise wire core’s dock in one line: `onOpenFile: (path, sid) => openFilePreview({ mount: '#page-row', path, sessionId: sid })` — the mount takes an element or a selector, and the dialog needs no mask props.
 
+变更文件的审阅出口是 `onOpenReview`，落点用 `openSessionReview({ mount, locator })` 一行接上：`locator`（sessionId / seq / index / display）到 diff 的拼装归会话域，调用方不挑组件、不塞节点、不补 ✕。面板关闭钮由 dock 出；`ChangedFileDiff.onClose` 只给自带壳的容器，不是关面板的手段。
+
+> EN: The review exit for changed files is `onOpenReview`; wire it with one line, `openSessionReview({ mount, locator })`. Turning the locator (sessionId / seq / index / display) into a diff belongs to the session domain — pick no components, pass no nodes, add no ✕. The panel close belongs to the dock; `ChangedFileDiff.onClose` is for containers that own their own chrome, not a way to close the panel.
+
 限制：官方样式未注入时回退自绘观感（功能不受影响）；长会话一次全渲染，用「加载更早记录」向前翻页；👍👎 反馈走官方 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.
@@ -49,11 +53,11 @@
 | `openHostSession` | `(sessionId: string) => void` | — | — | 跳官方会话区（uiWorkspace.openSession） | Jump into the official session area (uiWorkspace.openSession) |
 | `onContinue` | `(message: string) => Promise<void>` | — | — | 暂存输入框的确定：调用方完成 fork + 发首轮 + 跳转；缺省 = 不渲染输入框 | Staging input confirm: caller forks, sends the first turn, navigates; absent = no input rendered |
 | `onOpenFile` | `(path: string, sessionId: string) => void` | — | — | 文件打开出口（工具卡 fileLink / 行内引用 / 交付卡共用）；第二参是文件所属会话 id，别拿别的会话去定位；缺省 = 链接纯文本 | 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 |
-| `onOpenReview` | `(locator: ChangedFileReviewLocator) => void` | — | — | 变更文件的审阅出口（等价官方 openReview）；缺省 = 变更卡整张不可点 | Review exit for changed files (equals official openReview); absent = the change card is not clickable |
+| `onOpenReview` | `(locator: ChangedFileReviewLocator) => void` | — | — | 变更文件的审阅出口（等价官方 openReview）；落点用 `openSessionReview({ mount, locator })` 一行接上；缺省 = 变更卡整张不可点 | Review exit for changed files (equals official openReview); wire it with `openSessionReview({ mount, locator })`; absent = the change card is not clickable |
 | `t` | `Translate` | — | 内置 | 覆盖文案（内置字典已含全部会话文案，中英） | Override copy (the built-in dictionary has all session copy, zh+en) |
 
 ```tsx id="session-usage"
-import { openSessionView, SessionViewModal } from 'dsh-plugin-core/session'
+import { openSessionView, openSessionReview, SessionViewModal } from 'dsh-plugin-core/session'
 
 // 宿主服务由调用方注入：sessions ← dsh-api-session-controller、
 //   uiConversation ← dsh-client-ui-conversation
@@ -75,6 +79,8 @@ if (view !== null) {
     },
     // 文件打开出口：给一个落点即可（元素或选择器），核心自带右侧分栏
     onOpenFile: (path, sid) => openFilePreview({ mount: '#page-row', path, sessionId: sid }),
+    // 变更文件审阅：一行打开那次改动的 diff（面板 / 关闭钮全归核心）
+    onOpenReview: (locator) => openSessionReview({ mount: '#page-row', locator }),
     archived,                                   // 是否已归档
     t,                                          // 可选，覆盖文案
   })

package/docs/help/ui.doc.ts

@@ -979,7 +979,7 @@ const doc: DocTopic = {
             { name: 'title / icon', type: 'ReactNode', def: '—', desc: { zh: '内置头的标题与标题前图标', en: 'Built-in header title and icon before it' } },
             { name: 'extra', type: 'ReactNode', def: '—', desc: { zh: '标题右侧的任意内容（不只是按钮）', en: 'Any content to the right of the title (not just buttons)' } },
             { name: 'header', type: 'ReactNode | null', def: '—', desc: { zh: '整块替换头部：不传 = 内置头；null = 不要头部；其他 = 你的头', en: 'Whole-header replacement: omitted = built-in; null = no header; else = your header' } },
-            { name: 'closable / closeButton / closeIcon', type: '—', def: '—', desc: { zh: '关钮开关；位置 auto/header/floating/none', en: 'Close-button toggle; position auto/header/floating/none' } },
+            { name: 'closable / closeButton / closeIcon', type: '—', def: '—', desc: { zh: '关钮开关；位置 auto/header/floating/none。`floating` 钉在面板右上（6px 偏移、20×20），无头内容要给右上留 28px', en: 'Close-button toggle; position auto/header/floating/none. `floating` sits at the panel’s top-right (6px offset, 20×20) — headerless content must leave 28px there' } },
             { name: 'width / minWidth / maxWidth', type: 'number', def: '—', desc: { zh: '宽度与可拖动区间', en: 'Width and draggable range' } },
             { name: 'ariaLabel', type: 'string', def: '—', desc: { zh: '无头部时的无障碍名', en: 'A11y name when no header' } },
           ],

package/docs/help/ui.md

@@ -840,7 +840,7 @@ h(SideSheet, {
 | `title / icon` | `ReactNode` | — | 内置头的标题与标题前图标 | Built-in header title and icon before it |
 | `extra` | `ReactNode` | — | 标题右侧的任意内容（不只是按钮） | Any content to the right of the title (not just buttons) |
 | `header` | `ReactNode \| null` | — | 整块替换头部：不传 = 内置头；null = 不要头部；其他 = 你的头 | Whole-header replacement: omitted = built-in; null = no header; else = your header |
-| `closable / closeButton / closeIcon` | `—` | — | 关钮开关；位置 auto/header/floating/none | Close-button toggle; position auto/header/floating/none |
+| `closable / closeButton / closeIcon` | `—` | — | 关钮开关；位置 auto/header/floating/none。`floating` 钉在面板右上（6px 偏移、20×20），无头内容要给右上留 28px | Close-button toggle; position auto/header/floating/none. `floating` sits at the panel’s top-right (6px offset, 20×20) — headerless content must leave 28px there |
 | `width / minWidth / maxWidth` | `number` | — | 宽度与可拖动区间 | Width and draggable range |
 | `ariaLabel` | `string` | — | 无头部时的无障碍名 | A11y name when no header |
 

package/docs/requirements.md

@@ -160,6 +160,7 @@ dsh-plugin-core/
     类并补 `display:flex`，关闭时还原；子项规则只让第一个非预览子项伸展，不要传 `document.body`；
   - 依据：插件沙箱里没有 `fs`，读字节唯一通道是 ctx 注入的服务对象 ⇒ 服务只能「接线一次」交进来，
     不能每次调用各传一遍（这是权限边界，不是能力缺口）。
+- **关闭钮归面板壳**（2026-11-04 用户拍板）：`openFilePreview` 的 dock 一律用壳的浮动 ✕（`closeButton: 'floating'`，文件 / content 两种模式位置一致），`FileBrowser` 不再接 `onClose`（它的 `onClose` 只留给无壳的 picker 弹窗）；内容组件（`ChangedFileDiff` 等）不画关，只在右上让 28px。根因：关在内容上曾是可选 prop，漏传即整块面板无关闭钮（dsh-task-ledger 报的缺陷）。`content` 与 `path` 同传 ⇒ warn 并忽略 `path`（`handle.path` 不再回报未生效的路径）。
 - 控件纪律（2026-10-21）：核心有的控件一律核心（`Button` ghost 面包屑 / `IconButton` / `Segmented` / `MarqueeText` / `PanelDock`）；核心没有的那一项（▾ 选层浮层）严格按兄弟项目度量照抄
 - 选工作区（`WorkspacePicker`）在 `ui`，不在这里；`FilePicker` 已删（2026-10-20）
 
@@ -169,6 +170,7 @@ dsh-plugin-core/
 - `variant` 决定承载方式：弹窗 / 侧栏 / 整页（**承载可换**是硬要求）
 - 必须预留定制扩展点
 - 文件出口只有一个 `onOpenFile(path, sessionId)`（工具卡 / 行内引用 / 交付卡共用）：不传 ⇒ 链接纯文本。已有预览面的调用方在回调里开自己的；没有的一行接 `openFilePreview({ mount, path, sessionId })`。**不做「给个 id 让核心塞进第三方面板」**（2026-11-04 定：核心只认识自己的 `PanelDock`，按 id 塞 = 两套布局互相拽）
+- 变更文件的审阅出口是 `onOpenReview`，落点用 `openSessionReview({ mount, locator })`（2026-11-04 定）：`locator`（sessionId / seq / index / display）属会话领域知识，locator → diff 的拼装留在 `session`（依赖方向 session → explorer 本就存在，反向不许），调用方不挑组件、不塞节点、不补 ✕。`openFilePreview({ content })` 保留为逃生口，不再是推荐路径。
 - 会话区自动贴底只在两种情况下发生：**首次打开**、**有新内容且当时就在底部**；本地展开 / 折叠历史分组（如「已完成」）改变高度不算新内容，不许把视图拽走（2026-11-04 用户二次拍板）
 
 ## 3. 不进（业务，各插件自己写）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-core",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "packageManager": "pnpm@12.3.4",
   "description": "Shared base for DSH plugins: design tokens, UI controls, utils, workspace explorer, session preview",
   "keywords": [