# Changelog

本项目的版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)：
`MAJOR.MINOR.PATCH`。词库内容更新（`data/` 同步自上游词光仓库）按 `PATCH` 递增；
新增页面/工具/配置项按 `MINOR` 递增；破坏兼容的安装方式或配置变化按 `MAJOR` 递增。

发布时在 `main` 分支打 `v<version>` 标签，并创建同名 GitHub Release。

## [Unreleased]

## [0.6.6] - 2026-10-29

### Changed

- **复习页状态化引导**，移除禁用死胡同：
  - 有进行中的复习 → 继续复习；
  - 有进行中的今日学习 → 继续当前学习 + 返回今日；
  - 有到期词 → 开始复习（N 个到期词）；
  - 无到期词 → 自由复习已学词 + 去今日学新词。
- **新增自由复习已学词**：从未到期词中优先错词/低稳定度抽取最多 20 个，
  复用 Learn 主动回忆测验；会按答题结果更新 FSRS 排期，界面有说明。
- 复习页文案收敛，主操作放入独立状态卡，不再出现「请先完成当前学习」的灰色按钮。

## [0.6.5] - 2026-10-29

### Changed

- 复习会话过滤掉 `intro`（「认识了」介绍题），复习只保留测验步骤；
- 复习 tab 不再允许继续今日学习会话（避免把带介绍题的学习流程混入复习）：
  - 进行中的复习会话 → 继续复习；
  - 进行中的今日学习 → 提示先完成当前学习；
- 增加冒烟测试：reviewOnly 会话不得包含 intro，且每一步必须是 spell 或带 options 的测验题。

## [0.6.4] - 2026-10-29

### Changed

- 拼写输入改为**逐字母独立原生输入格**（每个非空格字母一个 `<input maxLength=1>`）：
  - 聚焦选中当前字母，输入后自动前进；空格自动跳过；
  - 当前格为空时按退格回到上一格并删除；
  - 粘贴/输入超长只分配到限定格数，多余字符丢弃；不会超过单词字母数；
  - IME composition 期间不自动前进，结束后再处理；
  - 每格原生编辑，避免隐藏 input 的 IME/退格问题。
- 目标中的空格渲染为间隔，不占输入格。
- 版本 v0.6.4。

## [0.6.3] - 2026-10-29

### Changed

- 拼写输入恢复**按字母数分格**的视觉：保留 v0.6.2 的原生可见 input（IME/退格可靠），
  用 CSS 将输入框绘制成逐字母格子；`--count` 控制格数，等宽字体 + letter-spacing
  让字符落在格内；提示字母/退格/composition 仍由原生 input 处理。
- 退出按钮叉号已在 v0.6.2 移除。

## [0.6.2] - 2026-10-29

### Fixed

- 拼写输入改为**原生可见输入框**，不再使用隐藏 input + 自绘字格：
  - IME composition、退格、删除、光标与选区全部交给浏览器原生处理；
  - 修复中文→英文输入法切换后无法删除、继续输入错乱的问题；
  - 居中大号输入框，清晰边框/底色/焦点态；提示字母直接写 DOM value。
- 学习顶栏「退出」按钮移除左侧叉号图标，仅保留文字。

## [0.6.1] - 2026-10-29

### Fixed

- 拼写题输入框在中文/英文输入法切换后无法退格、继续输入错乱：
  - 输入框改为非受控 input，避免 React 受控值在 IME composition 期间覆盖 DOM；
  - 增加 compositionstart/end 处理，composition 期间 Enter 不提交；
  - 提示字母时直接写 input DOM 值并重新聚焦。
- 拼写题布局改为单列居中：插画 → 释义/例句 → 字格全部居中对齐；
- 字格放大（40×48），增强边框/底色对比，当前输入格增加明显高亮；
- 版本 v0.6.1。

## [0.6.0] - 2026-10-29

### Changed

- **复习改为主动回忆测验**：
  - 复习 tab 的「开始复习」不再进入自评页，而是复用 Learn 的四种题型
    （看词选义/看图选词/听音选词/拼写），答完自动按对错、用时、提示情况计算 FSRS 评分；
  - 默认只复习到期词，新词统一从「今日」学习；
  - 首页「只复习」与复习 tab 共用同一套会话逻辑；
  - 会话顶栏显示「今日复习」，完成后回到复习入口；
  - 旧的自评式 ReviewCard / ReviewSummary 删除。
- 复习入口保留到期/今日已复习/已学/已掌握统计与目标记忆率设置。

## [0.5.8] - 2026-10-29

### Changed

- 复习引导页移除顶部装饰圆形图标（sparkle/orbit）；
- 移除底部「复习进度会自动保存到本机 $DSH_HOME/word-atlas-dsh/progress.json」提示；
  保存逻辑不变。

## [0.5.7] - 2026-10-28

### Changed / Fixed

- **统一查词卡片**：新增共享 `WordLookupCard`，短文/例句查词与书籍阅读器点词浮窗
  全部采用同一设计：大号单词 + 音标 + 英/美发音 + 释义列表 + 底部「收藏 / 查看词卡」；
  未收录词显示 surface 与提示；统一 outside-click / Esc 关闭与定位。
- 词条详情页头部：
  - 移除右上角收藏按钮，右上角只保留关闭；
  - 收藏改为底部「收藏 / 已收藏」按钮，与「标记为已学」并列，样式与查词卡片一致；
  - 修复收藏/关闭在右上角拥挤、对齐异常的问题。

## [0.5.6] - 2026-10-28

### Changed / Fixed

- 词条详情弹窗头部整理：
  - 移除分享按钮及 `shareWordCard` 引用；
  - 收藏按钮放入 `.wa-detail-head-actions` 右对齐，修复此前多图标导致的对齐错乱；
  - 返回（上一个词）按钮不再被 `margin-left:auto` 推到右边。
- 短文阅读器：英文段落改用现有 `LookupText` 渲染，**所有英文词都可点查**：
  - 未标注词与变形词通过词库索引回退；
  - 弹出音标/释义/发音/查看词卡；未收录词显示提示；
  - 保留双语切换与理解题。
- 版本 v0.5.6。

## [0.5.5] - 2026-10-28

### Fixed / Added

- 「查词」按钮不再换行：顶栏工具列改为自适应宽度，按钮 `white-space: nowrap`，
  窄屏隐藏按钮文字。
- 查词模式下**所有英文词都可查**：
  - 除章节标注词外，正文中未标注词 token 也生成可点按钮；
  - 变形/未标注词通过 `getLookupIndex().resolve()` 回退到词库词条；
  - 词库确实未收录时，弹层显示该 surface 并提示。
- 查词词义卡片新增**直接收藏 / 已收藏**按钮，写入 `progress.bookmarks`，
  与词条详情、生词本同步。
- 额外修复：progress.bookmarks 缺失时不再导致查词典崩溃。

## [0.5.4] - 2026-10-28

### Changed

- **阅读交互重构**：
  - 阅读模式下单击任意句子 → 从该句开始朗读；正文中的雅思重点词只保留虚线下划线提示，不再拦截点击；
  - 顶栏新增「查词」模式：开启后所有单词可点并弹出词义，句子点播暂时关闭；再点「查词」返回；
  - 词义弹层移除全屏 backdrop，点击外部关闭且不吞掉这次点击，解决「点词/点句互相遮挡」。
- **朗读加载反馈**：
  - 首次加载音频时播放按钮显示 spinner，状态显示「正在加载…」，再点可取消加载；
  - 每次播放使用 token 作废旧 canplay 回调，快速连点句子不会串位/卡住；
  - waiting/stalled 显示加载中，播放错误显示在播放器状态行；
  - 聆听模式播放按钮同样显示加载状态。

## [0.5.3] - 2026-10-28

### Fixed

- **播放时白屏**：`BookReader` 中 `activeItem` 在 `queue` 声明之前引用，初始 `active=-1`
  时不会触发；一旦播放设置 `active >= 0`，render 访问尚未初始化的 `queue`
  抛出 `ReferenceError`，阅读模式的播放器与聆听模式共用该组件，因此两者都会整页白屏。
  已把 `activeItem` / `activeSentenceId` 移到 `queue` 之后，并用真实浏览器 harness
  （headless Chrome + 实际章节/音频）验证播放、聆听、切换阅读方式均无 JS 错误。

## [0.5.2] - 2026-10-28

### Fixed

- 聆听模式顶栏标题被 macOS 窗口按钮遮挡：聆听浮层由 `fixed` 改为阅读器内 `absolute`，
  遵循根节点的标题栏安全区，同时不再覆盖宿主侧栏。
- 阅读方式与朗读语言不一致：阅读方式为英文/中文时，朗读语言自动跟随；
  仅「中英对照」模式显示英文/中文朗读语言选择，避免「阅读英文却出现中文朗读选项」的困惑。
- 聆听模式内无法选择阅读方式：新增「英文 / 中英对照 / 中文」切换，文本即时按当前模式显示；
  中英对照模式下可同时切换朗读语言。
- 阅读 ↔ 聆听切换：
  - 书籍顶栏新增「聆听」按钮，无需先滚到播放器；
  - 聆听模式顶部新增「返回阅读」；
  - 关闭聆听后保持朗读位置与正文跟随滚动。
- 单音轨章节不再显示不可用的语言选项，自动修正历史偏好。
- 聆听文本按阅读方式显示：英文 / 仅中文 / 双语。

## [0.5.1] - 2026-10-28

### Added

- **书架阅读与朗读体验复刻**（#42）：
  - 书架改为封面 hero + 简介/首句 + 阅读进度 + 「继续阅读」+ 章节星路（星点、已读/当前标记），替代平铺章节按钮；
  - 进入章节阅读时隐藏插件导航，使用书籍自己的顶部栏（返回书架/书名/章节/阅读设置），形成沉浸式书页；
  - 章节题图、罗马章节号、居中章节标题；英文 / 中英对照 / 中文三种阅读方式，5 档字号、3 档行距，设置持久化；
  - 正文按句切分，点击句子可从该句开始朗读；
  - 正文中每个词可点击查词：弹出音标/释义、英式/美式发音、打开词卡；
  - 底部朗读播放器：播放/暂停、上一句/下一句、句数与进度、0.8/1/1.2× 速度、跟随高亮滚动、全屏「聆听模式」（大字号逐句 + 译文）；
  - 空格播放/暂停、左右方向键切句、Esc 关闭浮层；
  - 章节结尾：本章雅思词列表、读完本章、下一章；
  - 阅读位置按段落保存，书架显示上次进度，进入章节时自动恢复；
  - 阅读进度写入 `progress.readings`，不影响 FSRS。

## [0.5.0] - 2026-10-28

v0.5.0：今日阅读与书房复刻。

### Added

- **今日阅读**：Today 页新增今日短文卡片（按每日种子 + 当前等级选一篇），显示中文标题/英文标题/CEFR/话题/未学重点词数，直接进入阅读器。
- **书房页**（导航新增「书房」tab）：
  - 短文：732 篇内置索引，可按 CEFR 筛选、分页加载，显示已读状态与未学重点词数；
  - 短文阅读器：双语/英文切换、正文生词内联点击查词、T/F/NG 理解题与解析、完成阅读记录进度；
  - 书架：书目（小王子）封面/简介/章节列表，按章阅读，逐段朗读、完成记录；
- **内容获取**：
  - 打包 `data/readings-index.json`（732 篇）与 `data/books-index.json`；
  - Host 新增 `/readings/index.json`、`/readings/<id>.json`、`/books/index.json`、
    `/books/<id>/<ch>.json`、`/read-assets/<path>` 路由；正文/章节/封面本机仓库优先，
    否则代理官方站点（10 分钟内存缓存，避免 CORS）；
  - `scripts/sync-reading.mjs` 同步索引。
- 阅读进度写入 `progress.readings`，Host/store/导入导出均保留；不改动 FSRS 复习进度。
- 新图标：library / clock / languages / bookmark（Lucide）。

## [0.4.2] - 2026-10-28

### Changed

- 打字练习移除可见输入框（v0.4.1 新增的那个空白大框），恢复为目标句直接打字；
  输入框仍保留键盘输入能力、点击题目区域聚焦；v0.4.1 的空格忽略判分与空格标记保持不变。

## [0.4.1] - 2026-10-28

### Fixed

- 打字练习：句子 / 听写中空格被输入法吞掉（或多打空格）时被误判为整句错误。
  - 句子练习的判分与 WPM 统计**忽略空白**：`My grandmother…` 与 `Mygrandmother…` 视为一致；
  - 目标句中空格改为虚线下划线标记，明确“这里是空格”；
  - 打字输入框改为**可见输入框**，可以直接看到自己打出的内容（含空格）；
  - 提示文案说明“空格不参与判分，输入法吞掉空格也没关系”。

## [0.4.0] - 2026-10-28

v0.4.0：练习、星图与分享/命令面板（#10 / #11 / #12）。

### Added

- **Practice 打字练习**（移植上游 `src/pages/Practice.tsx` + `src/lib/typing.ts`）：
  - 三种模式：单词（看图写词）、例句（照抄）、听写（只听声音写整句）
  - 四种词源：最近学过 / 错词本 / 收藏 / 学习路线
  - 实时 WPM / 准确率（标准每 5 字符 1 词），逐字符高亮，完成后自动进入下一项
  - 每轮 10 项，成绩写入 `progress.typing`，显示最佳速度与完成轮次
- **Galaxy 词汇星图**（移植上游 `src/galaxy/{layout,engine,Galaxy}`）：
  - WebGL2 星系渲染：19 个话题旋臂、CEFR 越难越靠外
  - 学习状态亮度（未学 / 学习中 / 已掌握）、拖拽旋转、滚轮/双指缩放、键盘方向键
  - 悬停星星显示词卡提示，点击飞行并打开词条；无 WebGL2 时 2D 降级
  - 重置视角、随机飞到已点亮星、保存星图 PNG
- **分享卡**：词条详情新增「生成分享卡」，Canvas 渲染 1080×1350 PNG（插画、单词、音标、释义、例句、授权）
- **命令面板**：`⌘K / Ctrl+K` 打开，可搜索词条或跳转今日/图鉴/星图/复习/练习/生词本/我的
- 导航新增「星图」「练习」tab；图标继续使用 Lucide。

## [0.3.6] - 2026-10-28

### Fixed

- 听音辨词播放图标偏上、看起来“变形”：按钮内有一个遗留的空 `<span />` 作为第二个
  grid item，把图标挤到第一行（不是 110px 圆钮中心）。删除该空节点后 Lucide 图标居中。

## [0.3.5] - 2026-10-28

### Fixed

- 听音辨词的播放图标改为 **Lucide `volume-2`**（ISC License）的官方路径，
  替换手绘 SVG；图标轮廓与重心更规整，播放圆钮内图标放大到 44px。
- 插件内所有图标统一改用 Lucide 图标库路径（搜索 / 星标 / 心形 / 关闭 /
  左右箭头 / 书本 / 刷新 / 勾选 / 信息 / 播放 / 暂停 / 用户 / 地球等），
  避免手绘路径在大尺寸下的几何误差。
- `src/client/icons.js` 自动生成并内联进 `client.js`，不新增运行时依赖；
  Lucide ISC 授权已写入 `THIRD_PARTY_NOTICES.md` 与 README。

## [0.3.4] - 2026-10-28

### Fixed

- 听音辨词的圆形播放按钮被渲染为方圆形（squircle）：DSH 宿主样式在 Chrome 139+
  给按钮设置了 `corner-shape: squircle`，导致 `border-radius: 50%` 变成超椭圆。
  插件根作用域内统一 `corner-shape: round`，恢复圆形/圆角控件的设计意图；
  不支持的浏览器会忽略该声明。

## [0.3.3] - 2026-10-28

### Fixed

- **macOS Desktop 窗口安全区**：新增 `useTitlebarInset`（参考 qiaomu-rss 的检测方式）——
  `dsh-app:` + Mac + 根节点贴窗口左上角（侧栏收起）时，页面顶部让出 40px 安全区，
  顶部 38px 设为可拖拽区，交互控件 `no-drag`；浏览器 Web 版不受影响。
- **Learn 专属 slim 顶部栏**：通栏栏高 56px，左侧退出、中间「今日学习 + 进度条」、
  右侧当前步数；题目在栏下方滚动，640px 内容列不变；完成页与空状态复用同一顶部栏。
  Learn 页不再直接顶到窗口最上方。

### Changed

- Learn 内容区水平 padding 调整，顶部栏与题目内容共用 680/640px 对齐关系。

## [0.3.2] - 2026-10-28

### Added

- **Today 学习首页改版**（#24）：
  - 品牌插画 Hero（`/word-atlas/brand/*` 路由，本机 `public/brand/` 优先、缺失 302 官方站点）+
    今日计划 / 继续旅程 / 只复习 / 新词缩略图；
  - 今日目标圆环（已答 / 目标）+ 连续天数 / 已点亮 / 长期记住统计；
  - 本周柱状图增加数值、今日高亮与零值基线；
  - 今日一词升级为较大插画 + 英/美发音 + 例句朗读 + 点击打开词卡；
  - 学习路线改为 A1–C2 横向站点路径，标出起点，显示已学/长期记住比例；
  - 新增 19 个话题卡片（品牌话题插画），点击直接筛选图鉴；
  - 两列布局平衡，去掉空列与大面积空白。
- Host 新增 `/word-atlas/brand/<file>` 静态路由（webp/jpg/png/svg）。
- 「今日阅读」与书房页面按计划推迟到 v0.5；iOS 内测二维码等线上运营内容不移植。

## [0.3.1] - 2026-10-28

### Fixed

- Learn 页统一内容列（640px）：顶栏、步骤提示、题目、选项与反馈卡左右对齐；
  顶栏不再比题目内容宽 100px。
- 看图补句改为单列：插画居中（最大 300px）+ 全宽 cloze，不再出现「提示靠左、图片/句子偏右」的割裂。
- 反馈卡改为固定三段式（缩略图 / 文字 / 操作），长例句不再把「继续」按钮挤走；例句最多两行。
- 学习进度条轨道加深，1/55 时也能看清进度。
- 重练步骤的状态点补上警告色；选项正确/错误状态加强，并补充读屏标签；
  答错时的反馈直接显示「正确答案是 …」。
- 选项列最大宽度收敛到 600px，减少宽屏留白。
- 完成页词条 chip 固定最小高度、释义单行省略，行高不再参差。
- 我的页 20 周热力图零值对比度提高（浅色主题不再接近纯白）。

## [0.3.0] - 2026-10-28

v0.3.0：学习闭环移植（#7 / #8 / #9）。

### Added

- **Learn 学习会话**（移植上游 `src/pages/Learn.tsx` + `src/store/session.ts`）：
  intro 词卡 → 四种题型（看义选词 / 看图补句 / 听音辨词 / 拼写），干扰项按难度与拼写相似度生成，
  首答计分、答错插入重试（最多 2 次、不重复计分），FSRS 评分与错词记录，会话持久化 / 恢复，
  键盘快捷键（1–4 选项、Enter/Space 继续），完成页统计与「再练错词」。
- **Today 今日页**（对齐上游 `src/pages/Today.tsx`）：问候与日期、今日计划（到期 / 新词 / 预计分钟）、
  继续旅程 / 只复习 / 再学 5 个、连续天数、本周柱状、今日一词、A1–C2 学习路线进度。
- **Me 我的页**（扩展上游 `src/pages/Me.tsx`）：已点亮 / 长期记住 / 首次正确率 / 学习时长统计条，
  20 周热力图、未来 7 天复习量预测、错词本（可打开词卡），原有设置 / 离线素材 / 备份 / 关于分区保留。
- 新增 `src/client/session.js`（纯函数化的会话与题型逻辑）、`Today.jsx`、`Learn.jsx`；
  `lookup.js` 增加 `headwordPattern / gap / shuffle / hashSeed / normalize`（移植上游 `src/lib/text.ts`）。
- 进度新增 `session` 字段（Host 保存时保留），刷新页面后可继续未完成的学习会话。

### Changed

- 插件默认视图改为「今日」；导航为「今日 / 图鉴 / 复习 / 生词本 / 我的」。
- 学习会话期间隐藏页头与 tab，使用专注布局。

## [0.2.3] - 2026-10-28

### Fixed

- 复习卡片中「显示答案」与音标/发音行挤在同一行：发音行改为块级 flex 行，
  「显示答案」独立成行并与上下内容保持间距（窄屏换行正常）。

## [0.2.2] - 2026-10-28

### Fixed

- 词条详情弹窗内容较长时右侧无法滚动：卡片改为固定高度 + 内部滚动区，
  页头/标题固定、正文在容器内滚动、页脚（记忆信息与标记/上一个/下一个）吸底常显。
- 词条详情左侧插画不再被 `object-fit: cover` 纵向裁切：1:1 插画完整显示，
  左栏改为「插画居中 + 编号/复习状态在下」，窄屏下用 `max-height: 30vh` 完整缩放。
- 窄屏单列布局同步调整为「插画自适应高度 + 正文占满剩余高度」。

## [0.2.1] - 2026-10-28

### Fixed

- 浅色主题下主按钮文字不可见（开始下载 / 查看词卡 / 开始复习等）：基础按钮样式不再覆盖
  `.wa-btn-primary` 的白色文字。
- 离线素材状态行在检测到本机词光仓库时正确显示「本机词光仓库」并点亮状态点。
- 复习页与离线面板的行内代码改为 `<code>` 渲染，不再显示反引号。

## [0.2.0] - 2026-10-28

### Added

- **例句点词查询**（对齐线上版）：例句英文 token 可点击，浮窗显示缩略插画、音标、中文释义、
  播放发音与「查看词卡」；未收录词提示；词形还原移植上游 `IRREGULAR` 表并补充后缀规则；
  详情 / 复习例句均已接入，支持返回上一个词。
- **离线素材包**（Host）：`GET/POST/DELETE /word-atlas/api/offline*`，按「缩略图 84 MB /
  完整插画 199 MB / 发音 418 MB」分档下载（共 37,501 个文件），支持本机词光仓库导入、
  断点续传、进度/速度/失败统计、取消与清理；媒体路由按「本机仓库 → 离线包 → 按需缓存 →
  官方站点回退」逐文件解析，下载中即可生效，无需重启。
- **按需缓存**（可选，`config.autoCache`）：浏览时把缩略图/插画/发音落盘到
  `$DSH_HOME/word-atlas-dsh/cache`，超过 `cacheMaxBytes` 按时间 LRU 清理。
- **「我的」页**：学习设置（每日新词 / 起点难度 / 目标记忆率 / 发音偏好 / 拼写题 / 自动播放）、
  离线素材面板、备份导出与导入、清空学习记录、版本与授权信息。
- 备份与上游词光格式兼容（`app/version/progress/settings`），可导入线上版导出的备份；
  Host 进度现在也保留 `mistakes` / `typing` 字段。

### Changed

- 图鉴侧边栏改为「图鉴 / 复习 / 生词本 / 我的」四个 tab；顶部信息按钮改为打开「我的」页。
- 作品详情页增加返回上一个词的能力（点词查询跳转后可用）。

## [0.1.0] - 2026-10-28

首个版本。

### Added

- DSH 插件形态：Host bundle + Web Client，注册 `main` 面板（key `word-atlas`）与
  `sidebar.panellist` 入口（order 22），侧边栏「词光」一键打开。
- 图鉴页：7,298 个雅思词条、19 个话题、CEFR A1–C2 筛选、中英/音标搜索、缩略图网格与无限加载。
- 词条详情：插画、英/美音标与发音、两条例句及朗读、搭配、词族、近/反义、用法提示、收藏与上一个/下一个导航。
- FSRS 复习：`ts-fsrs` 调度、Again/Hard/Good/Easy 间隔预览、每日新词与目标记忆率设置、本组统计。
- 生词本、已学/待复习统计、连续学习天数。
- Host 数据路由 `/word-atlas/atlas/*`：索引、词条分块、缩略图/插画、UK/US/例句 mp3（支持 Range）。
- 复习进度沉淀：`GET/POST /word-atlas/api/progress`，写入 `$DSH_HOME/word-atlas-dsh/progress.json`，
  localStorage 镜像兜底。
- Agent 工具：`word_atlas_lookup`、`word_atlas_search`（Host 无 `tools` 服务时自动跳过，`config.tools: false` 可关闭）。
- 素材回退：优先本机词光仓库 `public/atlas/`，缺失时 302 到官方站点；内置 7.1 MB 词库保证无素材也能浏览全部词条。
- 构建与测试：`npm run build`（esbuild + ts-fsrs 内联）、`npm test`（客户端渲染 / Host 路由 / 进度 / 工具冒烟）、
  GitHub Actions CI。
- 授权说明：插件代码 MIT，词库/插画/录音 CC BY 4.0（见 `THIRD_PARTY_NOTICES.md`）。