# 更新日志

## Unreleased

## [1.6.5] - 2026-10-14

- CI 移除 Node.js 20，改为 Node.js 22 / 24；同步包的 Node 版本要求和中英文开发说明，与 DSH 官方范围 `^22.19.0 || >=24.0.0` 对齐。
- 修复 Node.js 20 CI 中 React 测试缺少 `navigator` 的环境问题，完整恢复测试前的浏览器全局对象；已通过关闭 Node 原生 navigator 的完整测试验证。
- 修复刚保存首条批注后仍覆盖消息操作栏、滚动才恢复的时序问题：贴底时立即补偿新增高度，下一帧重新定位；保留历史阅读位置，取消后不执行迟到滚动。
- 新增 4 项首次保存/滚动生命周期回归测试；完整测试总数为 115。
- 待发送批注数量入口放在输入区左侧的预留行内，避免覆盖上一条消息的正文/操作栏和输入队列；清空、会话切换、输入区替换及停用时恢复原布局。
- 新增 4 项批注布局/生命周期回归测试，并用 Chrome 检查普通和窄窗口的消息/队列避让。
- 单消息与跨消息统一使用批注 / 引用 / 侧边对话工具条，移除独立引用浮窗及隐藏/延迟降级逻辑。
- 修复范围绕过、重复文字锚点跳转、旧按钮状态、快速重选以及失焦后拖拽残留。
- 主动取消清除选区快照；流式重渲染导致缩短或丢失时保留完整摘录，支持引用、批注和侧边对话恢复。
- 修复跨消息选区经过复制 / 状态按钮时被误拦截：仅限制按钮内的选区端点，消息间按钮不再阻止弹窗；流式恢复使用相同规则。
- 新增 26 项选区回归测试，迁移旧浮窗契约。

- 修复独立引用按钮绕过侧边栏范围限制；选区进入侧边栏时清除旧摘录。
- 侧边对话按创建的线程绑定新 tab，并核对已提交 React 组件中的会话、线程和可见状态，拒绝误写其他草稿。
- 停用、热替换和主会话切换取消异步操作与轮询，迟到响应不再改变界面或存储。
- 新增 12 项回归测试（含真实 React 18 受控输入框）；补强原有侧边栏测试。
- 固定 LF 行尾，保证 Windows checkout 的 vendor 原字节哈希与构建一致。

本项目的所有重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。

> 项目名 `dsh-selection-group`（包名 / 插件 id / 仓库名），插件面板显示为 **Selection Toolbar**。
> 仓库的 git 历史从 **1.3.3**（首次公开发布）开始；更早的条目按开发记录重建，按版本倒序排列。

## [1.6.4]

### 修复（发布包）

- **npm 发布包缺构建输入，装下去无法自测**：`files` 白名单里没有 `vendor/`、`patches/`、`scripts/`、`src/`，
  而 `scripts/build.mjs` 第一步就要读它们。实测在解包目录里跑 `npm test`：
  `Error: ENOENT .../src/toolbar.js`（补 `src/` 之前）与 `vendor/manifest.json`（补之前）。
  现在四者都在 `files` 里，发布包大小 103 KB → **204 KB**（26 个文件），
  并在**解包出来的干净目录**里验证过：`npm test` → **69/69 通过**，其中包含 vendor sha256 校验与补丁落盘断言。
- **`build.mjs` 新增 `--check` 模式**：只校验 `client.js` 是否与 `vendor/ + src/` 一致，**不重写文件**。
  `npm test` / `npm run verify` 与 CI 都改用它——否则测试流程可能先把产物"修好"再去断言它，漂移就被洗掉了。
  已实测：无漂移时退出 0 并打印版本号与行数/字节数；人为改动后退出 1 并打印两边尺寸**以及第一处差异**
  （行号、字符偏移、两侧各 24 个字符的上下文）——只报尺寸是不够的：版本号从 1.6.3 换成 1.6.4 时
  两个尺寸完全相同，报告会变成"漂移了但看起来一模一样"。
- `build.mjs` 读取构建输入失败时，现在抛出**指名的诊断**（哪个文件、哪个目录该带上），而不是深层 ENOENT。
- `.gitignore` 忽略 `*.tgz`（本地打包验证用，不提交）。
- **分发方式定为 GitHub**：README 的安装节改成三种来源——`github:` 仓库 URL（推荐）、
  GitHub Release 的 tarball 直链（钉版本）、clone + `link:`（开发），并写明**本项目不通过 npm
  registry 分发**。三者在 pnpm 11.7.0 下均已实测：`github:` 装出的 `client.js` 与仓库里的
  sha256 完全一致，且在该包内 `node scripts/build.mjs --check` 与 69 项测试全部通过。

## [1.6.3]

### 修复（**范围收紧**：只在聊天里生效）

- **在侧边栏打开的文件里选文字，也会弹出这个框。** 现在整个插件**只在对话内容里生效**；右侧栏
  （文件树 / 文件查看器 / 侧边对话 / 终端 / 任务）与**任何文件内容**——不管在右侧栏还是中间主区打开
  ——都**不再出现**这个框。
- **根因是我自己的补丁，不是上游**：上游 annotation 的 settle 里有 `if (rootEl === null) return` 这道
  "这算不算可批注的根"的门；我为了"选中当回合立即出框"（`immediate-toolbar`）重写了那段，**把这道门漏掉了**。
  而这个工具条只在**点击动作时**才用到 `ui.selectionRoot`，画框从不检查它——所以任何选区都会被画上框。
  现在把 `rootEl === null` 的判断**原样保留**在立即绘制之前。
- 同时按要求把**文件正文路径也关掉**：上游 annotation 本来主动支持宿主文本预览（`DOCUMENT_TEXT` +
  `[data-textpreview-url]`），而 `dsh-better-sidebar` 自己已经在文件查看器上提供「添加到对话」——
  两套叠在一起既有噪音、动作又是错语境的，所以合并包彻底不做文件选区。
- **右侧栏整体拒绝**：注解包里任何落在 `[data-slot="sidebar"]` / `sidebar.*` 子树内的选区都返回"没有根"，
  这样即使是一个聊天行被渲染在右侧栏（例如侧边对话视图），也不会弹框。

### 测试

69 项（原 66 项）。新增三条：**文件预览里选文字 → 完全没有框**（且独立「引用」按钮保持隐藏）；
**先选文件再选对话 → 对话照常出框**（确认不是一刀切关掉）；**右侧栏里的聊天行也不出框**
（按列拒绝，而不是只按行类型判断）。

## [1.6.2]

### 变更

- 按钮文案从「◧ 放进侧边对话」改回 **「◧ 侧边对话」**（英文 `◧ Side chat`）——功能不变，
  只是名字更短。悬浮提示仍写明"不自动发出、发送与否由你决定"。

## [1.6.1]

### 修复（实测两次踩空：输入框定位）

- **「放进侧边对话」在真机上完全没生效**：提示"输入框 4 秒内没有出现"。我按结构定位那个输入框的**四条规则全错**，
  而且每一条都被我自己写的**过浅测试桩**放过了：

  | 我写的规则 | 真实情况 |
  |---|---|
  | 卡片的**第一个子元素是按钮** | 第一个子元素是 `<textarea>`，按钮在第 3 层 → 永远不匹配 |
  | 按钮的 `closest('div')` 就是卡片 | 落到了卡片**内层的 bar**，那里没有输入框 |
  | 从 textarea 往上找"包含按钮的祖先" | 爬过了界，**把选中文字写进了同页无关的文本编辑器**（探针实测） |
  | 容器必须**直接**拥有按钮 | 按钮是 **bar** 的子元素，不是卡片的 → 仍不匹配 |

- **现在的规则**：从每个 `<textarea>` 出发，它**自己所在的那个容器**里必须在**两层内**存在发送按钮
  （`title="发送"` / `"Send"`，这是那个插件自己的本地化文案）；若多个候选，取**离按钮最近**的那个 textarea。
  这样既匹配真实结构（字段与 bar 是兄弟，按钮是 bar 的子元素），又不会跨容器误抓。
- **测试桩换成真实嵌套**：之前那个桩把按钮放在卡片第一层，让错规则也能"通过"。现在桩复刻真实结构
  （textarea 是卡片第一个子元素、按钮在 bar 里），并新增两条：**同页更早位置放一个无关编辑器 textarea**
  时只有侧边对话输入框被写、编辑器分毫不动；**没有发送按钮**时必须判定为"没有输入框"，绝不猜一个。

## [1.6.0]

> 已被 **1.6.1** 修复：1.6.0 的输入框定位有误，真机上不会生效。

### 变更

- **去掉引用外壳，选中文字原样放进侧边对话输入框**：不再包 `**引用自主对话：**` 标题与 `> ` 前缀，
  就是把选中文字**当纯文本**放进那个输入框（光标在末尾）。读起来和你自己粘进去的一样，随手可改。
- 按钮文案随之改为 **「◧ 放进侧边对话」**（英文 `◧ Send to side chat`）；行为不变——**不自动发送、
  零 token**，上下文仍要等你按发送才提交。
- 诊断里 `sidechatLast` 的 `quoted` 改名为 **`inserted`**（语义变准了）。

## [1.5.0]

### 变更（**行为变更**：不再自动发送）

- **第三个动作改为「◧ 侧边引用」，且不再直接发出**：选中文字后，新建一条**空的**侧边对话线程，并把
  选中文字作为**引用块写进那个 tab 自己的输入框**，光标停在末尾——**发不发、什么时候发由你决定**。
  点这个按钮**不再消耗任何 token**：线程是最小创建（`question: ''`），上下文要等你按发送才提交。
  这修掉了 1.4.0 的行为：当时点一下就把选中文字当第一条消息发出去，等于替你付了一次上下文注入的钱。
- 写进输入框的引用块形状（那个输入框是纯 `<textarea>`，没有 chip 机制；**1.6.0 已去掉这层外壳**）：

  ```
  **引用自主对话：**
  > 选中的第一行
  > 选中的第二行
  ```

  输入框里已有草稿时**追加**，不覆盖。

### 实现要点

- **React 受控输入框**：那个输入框是 React 18 受控组件（元素上装了自己的 `value` 访问器，
  直接 `field.value = …` 会被下一次渲染抹掉）。写入必须走**原型链上的 `value` setter**（绑定到元素本身）
  再派发 `input` 事件，React 才会当成用户输入接收。
- **不靠类名定位输入框**：该插件的 CSS 模块类名带哈希、重建即变。改为按**结构**定位——
  "最后一个子元素是 `<textarea>`、第一个子元素是按钮"的卡片；因此不会误抓会话输入框（contenteditable）
  或侧栏文件编辑器。找不到时明确提示（"请先展开右侧底部工作台"），不会假装引用放进去了。

### 诊断

- `sidechatLast` 取值改为 **`quoted` / `no-composer` / `no-session` / `failed`**（1.4.0 的 `sent` 已不存在）。
- 排障表新增一行「有按钮但引用没进输入框」；`window.__DSH_SELECTION_GROUP_SIDECHAT_POLL_MS__`
  可改等待输入框出现的时长（默认 4000ms，测试用）。

### 修复（实测到的崩溃）

- **`SIDECHAT_DRAFT_POLL_MS is not defined`**：重构时把常量声明改成了函数，却把默认分支读的那个常量
  留成了纯引用，于是**第一次真机点按钮就报**"侧边对话失败：SIDECHAT_DRAFT_POLL_MS is not defined"。
  浏览器 bundle 没有构建期符号检查，而当时**所有测试都设了 window 覆盖值**，正好绕过出问题的那条路径
  ——所以 62 项全绿也没抓到。现在：常量补回；测试默认**不再设置覆盖值**（只在需要缩短等待的那条用例里设），
  并新增一条不设任何覆盖的用例，断言默认路径会真的等满 4 秒后才报"输入框没出现"（若常量缺失，
  会在同一个微任务里立刻变成 `failed`）；另加一条**静态审计**（`test/contract.test.mjs`），
  扫描 glue 里所有 `大写_下划线` 标识符，凡是用到却没声明的一律测试失败。

### 测试

64 项（原 59 项）。新增：空线程创建（`question` 为空、**没有任何 prompt 请求**）、引用块内容与
「已有草稿则追加」、React 受控路径（模拟 React 18 的 own `value` 访问器，断言写入经原型 setter 生效）、
输入框不存在时提示、「选中文字绝不上线」、**不设任何 window 覆盖值跑默认路径**（崩过一次的正是这条），
以及 glue 常量声明的**静态审计**。

## [1.4.0]

### 新增

- **第三个动作「◧ 侧边对话」**（**已被 1.5.0 取代**：当时是"把选中文字作为第一条消息直接发出"）
  在 `dsh-better-sidebar` 的侧边对话里新建线程。对接方式（不去改那个插件）：
  `POST sidebar/api/sidechat.start` 建线程 → 把线程 id 写进它自己的 `dsh-sidebar:v1:sidechat-thread` 键
  （**先写后开**）→ 用它的扩展服务 `ctx.betterSidebar.openTab({ type: 'sidechat' }, { sessionId })` 打开 tab。
- 诊断新增 `sidechatEnabled / sidechatService / sidechatLast / sidechatLastThread / sidechatLastError`。

### 设计取舍（1.5.0 仍然成立的部分）

- **邻居是可选依赖，不是依赖**：`dsh-better-sidebar` 不存在（或没启用）时，该动作**根本不发布**，
  框里仍是「批注 + 引用」。因为服务在**每次渲染**时重查（而不是 `inject` 一个可选服务——那会让整个
  fiber 等一个可能永远不来的邻居），所以它**之后才挂载也能被接上**。
- **失败一律出声**：主会话没在运行时那条路由会拒绝（409）、路由取不到、答案不是 JSON、
  `childId` 缺失——每一种都给出**带原因的提示**并**不开 tab**；线程建好但 tab 打不开则明说"线程已建好、
  tab 没打开"（它仍能从工作台的线程菜单里找到）。
- **截断**：选中超过 4000 个码点只放前 4000 个（尾部 `…`）。
- **请求只在按下时发生**：这是本包唯一的网络请求（同源一条路由）；「批注 / 引用」两个动作不含网络请求。

## [1.3.8]

### 修复

- **一次失败不再让 CI 整个卡住**：测试里断言失败会跳过清理，留下的 jsdom 窗口与插件定时器
  会一直占住进程——所以 CI 从来只表现为"卡住"，而不是红色失败（三次挂起、交替出现在两格上，
  根因就是这个）。现在：插件里的所有定时器一律 `unref()`（浏览器没有该 API，自动成为空操作），
  测试用 `afterEach` **无条件关闭窗口**。用一个"故意失败且不清理"的临时测试验证过：
  进程正常退出并报红（`pass 34 / fail 1`），而不是挂住。
- **随之暴露并修掉的偶发失败**：`diagnostics expire by themselves…` 用固定 500ms 等一个 150ms 的过期定时器，
  在 CI 负载下定时器会晚到。测试里的固定等待改为**等条件**（`waitFor`，含 250ms 节流写入的最后一份快照）。
  本地连跑 4 次全绿，并在 4 路 CPU 负载下再跑 2 次全绿。

## [1.3.7]

### 修复

- **卸载后不再残留定时器**：1.3.6 引入的 3 分钟过期定时器没有任何地方取消，插件卸载后页面仍在等它
  ——CI 的 Node 20 那一格因此挂了 11 分钟不结束。现在最后一个实例卸载时会一并清掉过期定时器、
  截止时间记录与待写快照。
- 验证方式改为**不带 `--test-force-exit`** 运行，句柄泄漏不再被掩盖（CI 同款命令本地 11.9 秒干净退出）。

## [1.3.6]

### 新增

- 诊断默认**只跑 3 分钟**：到点后还原 `console` 包装与 window 错误监听、停止采样与写盘，
  并写入最后一份快照（含 `diagnosticsMode: "expired"` 与 `diagnosticsExpiredAt`）。
- 两个开关（在插件加载前设置）：
  `window.__DSH_SELECTION_GROUP_DIAGNOSTICS__ = true | false`、
  `window.__DSH_SELECTION_GROUP_DIAGNOSTICS_TTL_MS__`（毫秒）。

### 变更

- 每页只有一个过期截止时间，热插拔不会重置计时。
- 标记、观察者、动作 hook、拖拽跟踪与 rAF 兜底垫片属于功能，**不随开关关闭**。

### 性能

- 空闲开销：诊断全量运行时 ~18 次 DOM 查询/秒（有写盘）→ **过期或关闭后 ~8 次/秒、零写盘**。

### 修复

- 快照只在内容真正变化时写入（`sampledAt` 与 `tick` 不再让快照"看起来总在变"，空闲时不再反复落盘）。

## [1.3.5]

### 修复

- **框还在屏上时，待引用摘录不再莫名丢失**：上游在"选区失效"（文本变空、矩形测不到——流式输出时
  聊天区重渲染就会如此）或"任何滚动"（流式输出会自动滚动）时会丢弃摘录，而批注的框此时**不会关**，
  于是按「引用」会得到"摘录已保留，请选中原文重试"。现在只要合并工具条仍在接管，这两类情形都不丢弃
  摘录；Escape、点框外、独立模式下的滚动保持上游语义。

## [1.3.4]

### 修复

- **按住鼠标期间独立「引用」按钮保持隐藏**：共享框既然要等松手，宽限期就不能成为隐藏它的理由，
  否则按住停顿超过 300ms 就会露出那颗孤立按钮。指针按下状态改存到 window 级（所有热插拔副本共享），
  并参与隐藏判定本身。

## [1.3.3]

- 首次公开发布：MIT 许可、`.gitignore`、CI（Node 20/22 矩阵）、`npm test`、完整英文 README。
- 插件面板**名称改为英文**（`Selection Toolbar`），简介保持中文——面板对名称与简介分别按语言取值。

## 1.3.2

### 修复

- **拖选不再闪烁**：按住鼠标期间两条绘制路径（当回合绘制与 120ms 的 settle）都让路，
  `pointerup` 在当回合补发一次 `selectionchange`——既没有闪烁，也不用等 settle。

## 1.3.1

### 变更

- **工具栏改为事件驱动**：`selectionchange` 当回合打标记，`MutationObserver`
  （body / head / annotation host）跟随框与编辑卡片的出现与消失，宽限期用一次性 timeout，
  1 秒的定时器只做兜底（自愈 + 采样）。空闲 DOM 查询从 ~110 次/秒降到 ~18 次/秒。

### 修复

- 观察者的首次安装：annotation host 尚不存在时，不再因为 `null === null` 提前返回而**什么都没观察**。
- 空闲时不再重复写 localStorage 快照。

## 1.3.0

### 修复（热插拔与竞态，来自一次独立代码评审）

- **热插拔不再永久杀死「引用」**：挂载内联的 quote 之前先退休它已注册的旧状态——该插件在旧状态存在时
  会直接 early-return，而旧实例随后的清理又会删掉按钮，导致「引用」直到重启都是死的。
- **引用失败不再静默**：没有待引用摘录时，上游改为显示自己的失败提示，且 glue **保持框打开**供重试。
- **捕获按窗口单次安装**：`console` 包装与 window 错误监听不再每次热插拔叠加；最后一个实例卸载时还原。
- **资源归属权 + 自愈**：热插拔时后继实例的样式表/动作 hook 不会被前驱的清理摘掉；心跳会补回被删掉的资源。
- **监听器按实例分配**：`addEventListener` 对同一函数对象会去重，之前一个实例销毁会把另一个的监听一并摘掉。
- 编辑卡片打开期间也隐藏独立按钮；rAF 探测结论闩锁（迟到的回调不再覆盖诊断）；
  `en-US` 不再回落到中文。

## 1.2.2

### 修复

- 点「引用」后与点「批注」行为一致地**收起悬停框**（把上游内部的 `closeToolbar` 暴露给注入的动作）。

## 1.2.1

### 修复

- 热插拔的资源归属：后继实例复用样式表时，前驱的清理不再把它删掉（否则独立按钮会重新出现）。

## 1.2.0

### 新增

- 悬停框随选区**当回合**出现（当回合绘制补丁），拖选期间只移动不重建。
- 点击「批注」时从**实时选区**重取摘录，避免刚结束拖选就点击时批到旧文本。

## 1.1.2

### 修复

- 隐藏独立「引用」按钮改为在**选中同一回合**打标记，消除"先闪一下引用、再出现共享框"。

## 1.1.1

### 修复

- `ctx.effect` 用法错误：cordis 的 `effect(cb)` 会**立即执行** `cb` 并把它的返回值当作清理器，
  而原先直接传入 disposer，导致插件**挂载后约 1ms 自毁**（表现为"一个按钮都不出现"）。

## 1.1.0

### 变更

- 改为**一个悬停框 + 构建期补丁注入第二个动作**，取代 1.0.0 的"归位层"：不再搬运任何 DOM 节点，
  没有容器、没有定位接管、没有帧调度。

## 1.0.0

### 变更

- 把两个插件的浏览器半边**逐字内联**进本包（`vendor/` + 构建期补丁），不再要求它们处于启用状态。

## 0.2.0

### 变更

- DOM 适配层：把两个插件各自的悬浮按钮搬进同一个容器（当时需要两个插件都已启用）。

[1.3.7]: https://github.com/jabingu/dsh-selection-group/commit/9efe98f
[1.3.6]: https://github.com/jabingu/dsh-selection-group/commit/cbf7c05
[1.3.5]: https://github.com/jabingu/dsh-selection-group/commit/f2e93e8
[1.3.4]: https://github.com/jabingu/dsh-selection-group/commit/a3fcc86
[1.3.3]: https://github.com/jabingu/dsh-selection-group/commit/ca24650
[1.3.8]: https://github.com/jabingu/dsh-selection-group/releases/tag/v1.3.8