@kidli1412/dsh-token-heatmap 0.4.1 → 0.5.0

package/README.md

@@ -31,16 +31,16 @@ GitHub 风格自然年热力图：覆盖所选自然年 1月–12月（`‹ 2026
 
 ### 卡片设置 / In-card settings
 
-![⚙ 设置面板](docs/卡片设置面板.jpg)
+![⚙ 悬浮设置面板](docs/卡片设置面板.jpg)
 
-- ⚙️ **设置就在卡片上**：点标题行最右端的 **⚙**（`刷新 [⚙]`）在卡片底部展开设置面板，再点一次、点面板的 **×**、按 **Esc**、或把焦点移出面板都会收起。**插件不再往 DSH 设置（设置 → 插件 → 插件配置）里注册任何卡片**，所以那里看不到本插件。
-- **配色方案**：六个色板按钮，**点击即时生效**（不需要"保存"）；**默认视图**：年 / 月，决定新会话页面首次打开时显示哪个视图（当次会话手动切换只影响当前页面）。
+- ⚙️ **设置就在卡片上**：点标题行最右端的 **⚙**（`刷新 [⚙]`）弹出**悬浮设置面板** —— 位置在 ⚙ 正上方 8px、水平居中对齐、贴边留 12px，超出视口会自动钳制；点面板外的任意位置、按 **Esc**、或再点一次 ⚙ 都会收起。**插件不再往 DSH 设置（设置 → 插件 → 插件配置）里注册任何卡片**，所以那里看不到本插件。
+- **配色方案**：六个色板按钮，**点击即时生效**（不需要"保存"）；**默认视图**：年 / 月，决定新会话页面首次打开时显示哪个视图（当次会话手动切换只影响当前页面）。面板底部是阈值图例（悬停看各档范围）与一行说明。
 - 写入失败时面板底部会红字提示"保存失败，已回到服务端的值"（settings scope 复核后回滚乐观值）。
-- 配置经 `token-heatmap` settings namespace 持久化到 `<DSH_HOME>/settings.yaml`（0.1.1 及更早版本存在 `<DSH_HOME>/storages/token-heatmap-config.json` 的旧配置会在启动时自动迁移）。
+- 配置作为**本插件的 profile 配置**持久化：DSH 0.2.0 用插件导出的 `Config` schema 生成设置表单，表单以 **profile entry id**（`token-heatmap`）为键，值写进 profile patch（旧的 `<DSH_HOME>/settings.yaml` 段与 0.1.1 及更早的 `<DSH_HOME>/storages/token-heatmap-config.json` 都会在启动时**一次性迁移/抢救**回配置）。
 
 ## 安装 / Install
 
-需要 `web` profile 与 `pnpm`。DSH 兼容版本见下方「兼容性 / Compatibility」；运行于 `@deepseek-ai/dsh >= 0.1.2-alpha.4`（0.1.2 版本线）。
+需要 `web` profile 与 `pnpm`。DSH 兼容版本见下方「兼容性 / Compatibility」；运行于 `@deepseek-ai/dsh ^0.2.0-rc.2`（0.2.0 版本线；0.1.2 线请用 0.4.2）。
 
 从 npm 安装：
 
@@ -68,8 +68,8 @@ dsh plugin --profile web remove @kidli1412/dsh-token-heatmap
 
 ## 工作原理 / How it works
 
-- **服务端**（`lib/index.js` + `lib/usage.js` + `lib/config.js`）：作为 profile bundle 挂载，**实时折叠会话事件**（监听官方 `session/event`，每个 `assistant/chunk`/`assistant/message` 的 `usage` 事件即时写入缓存，不依赖 hero 屏挂载）；启动时一次性补折叠已存在的 live 会话（如 resumed 会话）；请求时 `collectUsage` 再做一次增量同步兜底，并枚举 **已归档（stored）会话**补齐历史——两种 `sessionPersistence` 接口都支持：0.1.2 线的 `listSnapshots()` + `readFrom()`，以及 0.1.3 起取代它们的 `list()` + `open()`/`handle.read()`。同 `(turn, step)` 的重复样本按"替换"语义处理，归属后一天；**fork（`isSeeded`）会话从它的继承切点开始折叠**——日志开头那批属于父会话的事件在父会话侧已折叠，跳过它们才不会把同一批 token 计两次；按天、按模型聚合，缓存到 `<DSH_HOME>/storages/token-heatmap-cache.json`。通过回环受限端点 `GET /api/token-heatmap/usage` 提供；显示配置（配色 + 默认视图）由插件注册的 `token-heatmap` settings namespace 持有（settings.yaml），`GET/POST /api/token-heatmap/config` 作为回环兼容 API 读写同一 namespace（0.1.x 的 `enabled` 开关已废弃，该字段只作为常量 `true` 回给旧客户端），0.1.1 及更早的 `token-heatmap-config.json` 文档在启动时一次性迁移。
-- **客户端**（`lib/client.js`）：手写 `__ModuleLoader__` bundle，注册进会话 `conversation.input.dock` 列表插槽，仅在 `session.blank`（新会话 hero 屏；旧宿主回退 `composerPhase === "blank"`）时渲染——卡片没有显示开关，hero 屏上始终显示。框架真正的"卡片下方"插槽 `conversation.composer.dock` 在 hero 屏被 `!hero` 门控禁用，因此本插件利用 `input.dock` 容器（flex 列）的 CSS `order` 把自己排到输入卡片**之后**。同一份数据由 `buildGrid()`（年，53 列 × 7 行）与 `buildMonthGrid()`（月，7 列 × 5–6 行，带日号）两个纯函数分别铺格，共用 `levelOf()` 的绝对阈值分档与 `palette` 配色；`‹ ›` 按钮按当前视图步进年或月，边界取"当前年/月"与"数据里最早的月"，年/月分段按钮紧跟在步进器后面，**⚙ 设置面板**在卡片底部展开（内嵌面板，动作：⚙ 切换 / × / Esc / 焦点移出）。**不注册 `settings.plugin.item`**（官方"插件配置"页签只渲染"Host 实际 serve 的 namespace ∩ 客户端已注册 key"的卡片，本插件不再占这个位置），只经 settings scope 读写 `token-heatmap` namespace（该 namespace 仍由服务端注册，是配置的校验与持久化管道）。
+- **服务端**（`lib/index.js` + `lib/usage.js` + `lib/config.js`）：作为 profile bundle 挂载，**实时折叠会话事件**（监听官方 `session/event`，每个 `assistant/chunk`/`assistant/message` 的 `usage` 事件即时写入缓存，不依赖 hero 屏挂载）；启动时一次性补折叠已存在的 live 会话（如 resumed 会话）；请求时 `collectUsage` 再做一次增量同步兜底，并枚举 **已归档（stored）会话**补齐历史——两种 `sessionPersistence` 接口都支持：0.1.2 线的 `listSnapshots()` + `readFrom()`，以及 0.1.3 起取代它们的 `list()` + `open()`/`handle.read()`。同 `(turn, step)` 的重复样本按"替换"语义处理，归属后一天；**fork（`isSeeded`）会话从它的继承切点开始折叠**——日志开头那批属于父会话的事件在父会话侧已折叠，跳过它们才不会把同一批 token 计两次；按天、按模型聚合，缓存到 `<DSH_HOME>/storages/token-heatmap-cache.json`。通过回环受限端点 `GET /api/token-heatmap/usage` 提供；显示配置（配色 + 默认视图）由**导出的 `Config` schema** 持有（0.2.0 的设置模型：以 entry id `token-heatmap` 为键的表单，值写进 profile patch），`GET/POST /api/token-heatmap/config` 作为回环兼容 API 读写同一份配置（读经 `settings.describe()`，写经 `settings.update()`；0.1.x 的 `enabled` 开关已废弃，该字段只作为常量 `true` 回给旧客户端），0.1.1 及更早的 `token-heatmap-config.json` 文档在启动时一次性迁移。
+- **客户端**（`lib/client.js`）：手写 `__ModuleLoader__` bundle，注册进会话 `conversation.input.dock` 列表插槽，仅在 `session.blank`（新会话 hero 屏；旧宿主回退 `composerPhase === "blank"`）时渲染——卡片没有显示开关，hero 屏上始终显示。框架真正的"卡片下方"插槽 `conversation.composer.dock` 在 hero 屏被 `!hero` 门控禁用，因此本插件利用 `input.dock` 容器（flex 列）的 CSS `order` 把自己排到输入卡片**之后**。同一份数据由 `buildGrid()`（年，53 列 × 7 行）与 `buildMonthGrid()`（月，7 列 × 5–6 行，带日号）两个纯函数分别铺格，共用 `levelOf()` 的绝对阈值分档与 `palette` 配色；`‹ ›` 按钮按当前视图步进年或月，边界取"当前年/月"与"数据里最早的月"，年/月分段按钮紧跟在步进器后面，**⚙ 设置面板**在卡片底部展开（内嵌面板，动作：⚙ 切换 / × / Esc / 焦点移出）。**不注册 `settings.plugin.item`**（官方"插件配置"页签只渲染"Host 实际 serve 的 namespace ∩ 客户端已注册 key"的卡片，本插件不再占这个位置），配置经 `ctx.configForms.get("token-heatmap")` 读写本插件配置（0.2.0 的设置模型，取代 0.1.x 的 settings scope）。
 - 语义与 `dsh-token-meter` 的 `tokenUsage` 投影一致（参考插件 [dsh-usage-stats](https://github.com/Ychris12138/dsh-usage-stats)，MIT）。
 
 ## 说明 / Notes
@@ -80,10 +80,17 @@ dsh plugin --profile web remove @kidli1412/dsh-token-heatmap
 
 ## 兼容性 / Compatibility
 
-- **DSH**：manifest 通过 `dsh.compatibility.dshReleases` 将官方最新三个版本 `0.1.2-alpha.4`、`0.1.2-alpha.5`、`0.1.2-rc.1` 逐项声明为 `compatible`（DSH STORE 的精确逐版本兼容证据；仅范围声明不会恢复上架）。插件使用的客户端注入（`dsh-api-remotes` / `dsh-client-connection` / `dsh-client-locale` / `dsh-client-ui-conversation` / `dsh-client-ui-settings`）与 Host 服务（`settings` namespace、`webServer` 精确路由）在这条版本线上保持稳定。
+- **DSH**：manifest 通过 `dsh.compatibility.dshReleases` 将当前版本线 `0.2.0-rc.2` 声明为 `compatible`（DSH STORE 的精确逐版本兼容证据；仅范围声明不会恢复上架）。插件使用的客户端注入（`dsh-api-remotes` / `dsh-client-connection` / `dsh-client-locale` / `dsh-client-ui-conversation` / `dsh-client-ui-settings`）、客户端服务（`slots` / `locale` / `configForms`）与 Host 服务（`webServer` 精确路由、`settings.describe` / `settings.update`、`sessions`、`sessionPersistence`）在 0.2.0 版本线上均已在真实安装中核对。
 - **Node**：`^22.19.0 || >=24.0.0`（与 DSH 一致）。
-- **宿主要求（dsh-market 显示）**：`engines.dsh: ^0.1.2-rc.1`，并将运行时依赖的 lockstep 宿主包声明为 `peerDependencies`（`dsh-host-webserver` / `dsh-session` / `dsh-session-persistence` / `dsh-settings` 与客户端模块 `dsh-api-remotes` / `dsh-client-connection` / `dsh-client-locale` / `dsh-client-ui-conversation` / `dsh-client-ui-settings`，均为 `^0.1.2-rc.1`）；插件市场会据此显示"宿主要求"并判断与当前 DSH 是否匹配。
-- **依赖**：`@deepseek-ai/dsh-settings` 自 0.1.3 起提升为 `^0.1.2-rc.1`、`@deepseek-ai/schemastery` 提升为 `^3.18.2`，与 DSH 0.1.2 版本线对齐。npm 的 prerelease 解析规则下 `^0.1.0-rc.7` 不会解析到 `0.1.2-rc.1`（只会装 `0.1.0-rc.8`），因此较低的范围会拉到与新版 DSH 不同 train 的 settings 副本。
+- **宿主要求（dsh-market 显示）**：`engines.dsh: ^0.2.0-rc.2`，并将运行时依赖的 lockstep 宿主包声明为 `peerDependencies`（`dsh-host-webserver` / `dsh-session` / `dsh-session-persistence` / `dsh-settings` 与客户端模块 `dsh-api-remotes` / `dsh-client-connection` / `dsh-client-locale` / `dsh-client-ui-conversation` / `dsh-client-ui-settings`，均为 `^0.2.0-rc.2`）；插件市场会据此显示"宿主要求"并判断与当前 DSH 是否匹配。这些包由 DSH 运行时提供、本插件**从不 import**，所以同时标为 `peerDependenciesMeta.optional`——npm/pnpm 不再把它们装进依赖树（0.2.0 起它们彼此还有 peer 关系，沿用旧的自动安装会直接解析冲突），而"宿主要求"的语义不受影响。
+- **依赖**：`@deepseek-ai/schemastery ^3.18.2`（唯一的真实依赖；`dsh-settings` 自 0.2.0 起不再需要作为 peer 之外的运行时依赖）。
+- **0.5.0（DSH 0.2.0 适配）**：DSH 0.2.0 换了三套契约，宿主兼容闸门会**直接拒绝挂载**声明不符的 bundle（现象：插件在市场里显示"不兼容"、`rows: []`、hero 屏上什么都没有）——
+  1. **宿主要求必须落在 0.2.0 线上**：闸门逐条比对 `peerDependencies` 里的 `@deepseek-ai/dsh*` 与运行时版本（`semver.satisfies(..., { includePrerelease: true })`），`^0.1.2-rc.1` 不满足 `0.2.0-rc.2`，因此本版把 `engines.dsh` 与 9 个宿主 peer 一起提到 `^0.2.0-rc.2`（并把宿主包标为 optional peer，见上）。
+  2. **设置模型重做**：0.1.x 的"插件自建 settings namespace + `settings.register(ns, schema)`"没了，`settings.get(ns)` 也没了。现在**插件导出的 `Config`（schemastery）就是设置表单**，以 **profile entry id**（bundle patch 里的 `id: token-heatmap`）为键；Host 侧读别人用 `settings.describe()`（`serveConfig()` 已改，否则配置端点会静默回默认值）、写自己用 `settings.update(ns, patch)`，浏览器端用 `ctx.configForms.get("token-heatmap")`（`getSnapshot` / `subscribe` / `set`），旧的 `ctx.settingsScope.bind({namespace})` 已从客户端消失。卡片 ⚙ 面板的 UI 与"点击即时生效"完全不变。
+  3. **弹层皮肤同步**：0.2.0 的原生 stat dialog 改用 `border-radius:var(--dsw-radius-lg)` 并加 `backdrop-filter:var(--dsw-menu-backdrop-filter)`，本插件的 ⚙ 悬浮面板跟着改（带 fallback，旧宿主仍渲染 12px 圆角）。
+  > 升级时会**自动抢救旧配置**：DSH 自己的 `settings.yaml` 导入按 entry id 进行，而当时本插件正因上面的 peer 不符被拒挂载，导入失败后值只留在 `~/.dsh/settings.yaml.imported` 里。本版 Host 在启动后（等 Loader settle）读一次该文档，若条目还没有用户值就把非默认的 `colorScheme` / `defaultView` 写进配置——一次性、只读、失败即跳过。（`enabled` 字段自 0.3.0 起已废弃，不参与抢救。）
+  > 另外提醒：0.2.0 给 `dsh web` 的每个请求加了**签名 cookie 鉴权**，插件的两个端点因此只有带 cookie 的同源页面能到达；用 node/curl 直接探端点拿到 401 是 DSH 的鉴权层，**不代表插件没挂载**。Host 侧的 loopback 精确路由 fence 保留为第二道防线。
+- **0.4.0（设置搬进卡片）**：不再注册官方 `settings.plugin.item` 插槽——设置页（设置 → 插件 → 插件配置）里不再有本插件的卡片，配色与默认视图改在卡片自己的 ⚙ 面板里改，**点击即时生效**（去掉了草稿/保存/放弃那套）。当时 Host 侧的 `settings.register("token-heatmap", schema)` 保留下来当 settings.yaml 的校验与持久化管道；**该注册在 0.5.0 已随 0.2.0 的设置模型一起移除**（导出的 `Config` 就是管道）。升级只影响设置入口位置，已有配置不动。
 - **0.1.4（DSH 0.1.2 适配）**：rc.1 起 live session 不再携带 `.events` 数组（改用 `session.seq` + `session.eventAt(seq)`，与官方 `dsh-token-meter` 相同），新会话判断从 `composerPhase === "blank"` 改为布尔 `session.blank`；`sessionPersistence` 的 stored 会话枚举在 0.1.3-alpha.2 被替换（`listSnapshots`/`readFrom` → `list()` + `open()`/`handle.read()`），两条接口见 0.1.6 条目。客户端注入模块列表同步为新架构模块（见上）。
 - **0.1.6（session/event 实时折叠 + stored 会话枚举修复）**：`apply()` 注册官方 `session/event` 监听器，每个 usage 事件即时折叠进缓存，解决 live 会话仅在 hero 屏挂载时才折叠而漏计同一日其他会话用量的问题（表现为当日总量偏小、历史天数丢失）；启动时一次性补折叠已存在的 live 会话（如 resumed 会话）。**stored 会话枚举修复**：0.1.3-alpha.2 起 `sessionPersistence` 移除了 `readFrom()` 与 `listSnapshots()`，只保留 `list()` + `open()`/`handle.read()`；旧实现只探测 `list`/`listSnapshots` 却无条件调用 `readFrom`，导致每个 stored 会话抛错并被吞成一条 warn —— 表现为热力图只剩进程内 live 的几天。现在两条接口都支持（`list()` 的 `revision` 同样用于跳过未变更的日志，增量仍按 `seq` 去重与连续性校验），stored 会话可完整补齐历史；两者都不可用时不再误判为"日志被截断"，而是保留已折叠天数并告警。token 口径与 `dsh-token-meter` 一致（input + output + cacheRead + cacheWrite，不含 reasoningTokens）。
 - **0.2.0（月视图 + 默认视图设置）**：新增 `buildMonthGrid()` 月视图（周一起、5–6 行、日号 + 当日 token 数）与 年/月 分段切换，`‹ ›` 按当前视图步进年或月；settings namespace 新增 `defaultView`（`"year" | "month"`）字段——与 `colorScheme` 的"只约束 shape"不同，**`defaultView` 是枚举校验**（未知视图没有可回退的渲染器），旧 Host 上该字段会被 schema 丢弃、旧客户端读到未知值时回退为"年"。0.1.x 的 `settings.yaml` 无需迁移（缺字段即取默认 `year`）。
@@ -91,6 +98,7 @@ dsh plugin --profile web remove @kidli1412/dsh-token-heatmap
 - **0.4.0（设置搬进卡片）**：不再注册官方 `settings.plugin.item` 插槽——设置页（设置 → 插件 → 插件配置）里不再有本插件的卡片，配色与默认视图改在卡片自己的 ⚙ 面板里改，**点击即时生效**（去掉了草稿/保存/放弃那套）。Host 侧 `settings.register("token-heatmap", schema)` 保留：它是 settings.yaml 的校验与持久化管道，与 UI 卡片无关（官方 `settings` 服务的 `get`/`update` 只对已注册 namespace 生效）。升级只影响设置入口位置，已有配置不动。
 
 - **0.4.1（fork 会话不再重复计入父会话用量）**：DSH 的 fork 子会话（header `isSeeded=true`）日志以父会话事件的完整复制开头，其前 `inheritedEventCount` 个事件是**父会话**的 usage（父会话折叠时已计入）。此前折叠从 seq 0 读整份日志，同一批 token 被计两次——实测 2026-09-14 由 8.34 亿虚增到 13.15 亿。现在三条折叠路径（`collectUsage` 的 live 折叠、`session/event` 实时监听、stored 日志读取）都从 fork 切点开始：live 会话用官方 `session.inheritedEventCount`；stored 日志用最后一个带 `data.inherited === true` 的 `session/end-seed` 的 `seq + 1`（未打标记的 `session/end-seed` 是 compaction 边界，不算切点，与 `dsh-session-format-v2-to-v3` 的切点推导一致）。**resume 不是 fork**：`isSeeded=false` 的会话种子是它自己的历史，仍整份折叠。缓存格式版本提升到 2，旧缓存（可能含重复计入的天数）会被丢弃重建；父会话日志不可得的极端情况下会少计而非多计。
+- **0.4.2（设置改成悬浮面板）**：⚙ 面板从"卡片底部的内嵌条"改为**悬浮面板**——portal 到 `document.body`、`position:fixed`，锚在 ⚙ 上方 8px 且水平居中对齐，按视口钳制（12px 边距），关闭方式为点外部/Esc/再点 ⚙；表面沿用 DSH 原生弹层 token（`--dsw-specific-menu` + `--dsw-elevation-prominent`，配合 `--dsw-elevation-stroke-color` 的发丝边），与底部统计 pill 的弹层一致。为此客户端 bundle 新增 `require("react-dom")`（原生的 `createPortal`），DSH 的模块图里 react-dom 一直存在，旧宿主不受影响。
 
 ## License
 

package/lib/client.js

@@ -7,9 +7,10 @@
  * columns = weeks, rows = Mon..Sun, all seven weekday labels on the left) or a
  * single-month calendar, switchable from the header, plus today / this-month /
  * all-time totals and a ‹period› stepper. The card configures ITSELF through a
- * ⚙ panel (palette + default view) persisted in the `token-heatmap` settings
- * namespace (settings scope); it deliberately does not register into the
- * official `settings.plugin.item` seat (设置 → 插件 → 插件配置), so all of its
+ * ⚙ panel (palette + default view) persisted in this plugin's profile CONFIG —
+ * DSH 0.2.0 derives the form from the Host's exported `Config` and the card
+ * reads/writes it through `ctx.configForms.get("token-heatmap")`; there is no
+ * `settings.plugin.item` card and no settings scope any more, so all of its
  * settings live on the card.
  *
  * The card is shown ONLY on the new-session (hero) screen — gated on the
@@ -37,6 +38,9 @@ window.__ModuleLoader__.load({
 
 		let react = require("react");
 		let react_jsx_runtime = require("react/jsx-runtime");
+		// Only for the settings panel, which is PORTALED to document.body so the
+		// card's own box can never clip it (the pattern the stat pills use).
+		let reactDom = require("react-dom");
 
 		//#region css
 		const css = [
@@ -88,23 +92,25 @@ window.__ModuleLoader__.load({
 			".thm_error{color:var(--dsw-alias-state-error-primary);background:var(--dsw-alias-interactive-bg-hover-danger);border-radius:8px;padding:7px 8px;font-size:11px;line-height:16px;display:flex;justify-content:space-between;align-items:center;gap:8px}",
 			".thm_retry{color:inherit;font:inherit;cursor:pointer;background:0 0;border:none;flex:none;padding:0}",
 			".thm_loading{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px;padding:6px 2px}",
-			// In-card settings panel (⚙ at the row's right end) — the card
-			// configures itself; nothing registers into 设置 → 插件 → 插件配置.
+			// The ⚙ at the row's right end opens a floating pill panel — the
+			// card configures itself; nothing registers into 设置 → 插件 → 插件配置.
 			".thm_gear{cursor:pointer;color:var(--dsw-alias-label-tertiary);background:0 0;border:none;border-radius:6px;align-items:center;padding:2px 4px;display:inline-flex}",
 			".thm_gear:hover{color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-interactive-bg-hover)}",
 			".thm_gear[data-active=true]{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}",
-			// The panel is an inset surface on the card: the light theme resolves
-			// every bg-layer token to the same white, so the fill is a translucent
-			// gray that reads as a nested surface in both themes.
-			".thm_panel{box-sizing:border-box;border:1px solid var(--dsw-alias-border-l2);background:rgba(128,128,128,.08);border-radius:12px;flex-direction:column;gap:10px;margin-top:2px;padding:10px 12px 12px;display:flex}",
-			".thm_panelHead{align-items:center;gap:8px;display:flex}",
-			".thm_panelTitle{color:var(--dsw-alias-label-primary);flex:1;font-size:12px;font-weight:600;line-height:18px}",
-			".thm_panelClose{cursor:pointer;color:var(--dsw-alias-label-tertiary);background:0 0;border:none;border-radius:4px;flex:none;padding:0 5px;font-size:16px;line-height:20px}",
-			".thm_panelClose:hover{color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-interactive-bg-hover)}",
+			// The settings panel mirrors DSH's own pill dialogs: portaled to
+			// document.body, position:fixed (so the card can never clip it),
+			// measure-then-place above the ⚙ and clamped to the viewport, with
+			// the shipped dialog surface + elevation tokens. DSH 0.2.0's stat
+			// dialog moved to `--dsw-radius-lg` and a backdrop filter, so the
+			// surface follows (the fallbacks keep it rendering on an older host).
+			".thm_panel{position:fixed;z-index:1100;box-sizing:border-box;background:var(--dsw-specific-menu,#fff);--dsw-elevation-stroke-color:var(--dsw-alias-border-l1);width:400px;max-width:calc(100vw - 24px);backdrop-filter:var(--dsw-menu-backdrop-filter);box-shadow:var(--dsw-elevation-prominent,0 8px 32px rgba(0,0,0,.16));color:var(--dsw-alias-label-secondary);cursor:default;border:0;border-radius:var(--dsw-radius-lg,12px);padding:16px;font-size:12px;line-height:18px;text-align:left;font-weight:400}",
+			".thm_panelHead{color:var(--dsw-alias-label-primary);justify-content:space-between;align-items:center;gap:16px;margin-bottom:8px;font-weight:500;display:flex}",
+			".thm_panelTitleLabel{align-items:center;gap:6px;display:inline-flex}",
+			".thm_panelTitleLabel svg{flex:none;width:14px;height:14px}",
+			".thm_panelRule{border-top:.5px solid var(--dsw-alias-border-l2);margin-bottom:12px}",
 			".thm_group{flex-direction:column;gap:5px;display:flex}",
+			".thm_group+.thm_group{margin-top:14px}",
 			".thm_groupLabel{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px}",
-			".thm_hint{color:var(--dsw-alias-label-caption);font-size:10px;line-height:14px}",
-			".thm_hintError{color:var(--dsw-alias-state-error-primary)}",
 			".thm_swatches{flex-wrap:wrap;gap:6px;display:flex}",
 			".thm_swatch{cursor:pointer;align-items:center;gap:6px;border:1px solid var(--dsw-alias-border-l2);background:0 0;border-radius:6px;padding:3px 8px;font:inherit;display:flex}",
 			".thm_swatch:hover{border-color:var(--dsw-alias-label-dimmed)}",
@@ -115,7 +121,11 @@ window.__ModuleLoader__.load({
 			".thm_seg{border:1px solid var(--dsw-alias-border-l2);border-radius:8px;align-items:center;display:inline-flex;overflow:hidden;width:max-content}",
 			".thm_segBtn{cursor:pointer;color:var(--dsw-alias-label-tertiary);background:0 0;border:none;padding:1px 10px;font:inherit;font-size:11px;line-height:18px}",
 			".thm_segBtn:hover{color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-interactive-bg-hover)}",
-			".thm_segBtn[data-active=true]{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover);font-weight:600}"
+			".thm_segBtn[data-active=true]{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover);font-weight:600}",
+			".thm_panelFoot{border-top:.5px solid var(--dsw-alias-border-l2);margin-top:14px;padding-top:10px}",
+			".thm_footLegend{align-items:center;gap:3px;font-size:10px;line-height:14px;display:flex;color:var(--dsw-alias-label-tertiary)}",
+			".thm_footRule{color:var(--dsw-alias-label-caption);margin-top:6px;font-size:10px;line-height:14px}",
+			".thm_footError{color:var(--dsw-alias-state-error-primary);margin-top:6px;font-size:10px;line-height:14px}"
 		].join("");
 		const tagId = "@kidli1412/dsh-token-heatmap/TokenHeatmap.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
@@ -162,12 +172,14 @@ window.__ModuleLoader__.load({
 			gear: "thm_gear",
 			settingsPanel: "thm_panel",
 			panelHead: "thm_panelHead",
-			panelTitle: "thm_panelTitle",
-			panelClose: "thm_panelClose",
+			panelTitleLabel: "thm_panelTitleLabel",
+			panelRule: "thm_panelRule",
+			panelFoot: "thm_panelFoot",
+			footLegend: "thm_footLegend",
+			footRule: "thm_footRule",
+			footError: "thm_footError",
 			settingsGroup: "thm_group",
 			settingsGroupLabel: "thm_groupLabel",
-			settingsHint: "thm_hint",
-			settingsHintError: "thm_hintError",
 			settingsSwatches: "thm_swatches",
 			settingsSwatch: "thm_swatch",
 			settingsSwatchCells: "thm_swatchCells",
@@ -217,7 +229,7 @@ window.__ModuleLoader__.load({
 			settingsRed: "红色",
 			settingsPurple: "紫色",
 			settingsTeal: "青色",
-			settingsPaletteHint: "颜色按每天 token 数的绝对阈值分档：{levels}。",
+			settingsThresholdNote: "颜色按每天 token 数的绝对阈值分档（悬停图例看各档范围）。",
 			settingsSaveFailed: "保存失败，已回到服务端的值，请重试。",
 			settingsExpand: "展开设置",
 			settingsCollapse: "收起设置"
@@ -258,7 +270,7 @@ window.__ModuleLoader__.load({
 			settingsRed: "Red",
 			settingsPurple: "Purple",
 			settingsTeal: "Teal",
-			settingsPaletteHint: "Colors follow absolute per-day token thresholds: {levels}.",
+			settingsThresholdNote: "Colors follow absolute per-day token thresholds (hover the legend for each range).",
 			settingsSaveFailed: "Save failed; the server value was restored.",
 			settingsExpand: "Show settings",
 			settingsCollapse: "Hide settings"
@@ -397,13 +409,14 @@ window.__ModuleLoader__.load({
 			return VIEW_MODES.includes(view) ? view : CONFIG_DEFAULTS.defaultView;
 		}
 		/**
-		 * Reactive adapter over one bound settings scope: a
-		 * useSyncExternalStore-compatible store whose snapshot is
-		 * `{ status, colorScheme, defaultView }` derived from the scope.
-		 * `set(patch)` writes the touched fields through scope.set (async; the
-		 * scope fences revisions and reloads on failure), and the snapshot
-		 * only changes after the Host confirms. `reload()` re-reads from the
-		 * Host; `dispose()` removes the subscription.
+		 * Reactive adapter over one config form (`ctx.configForms.get(entryId)`):
+		 * a useSyncExternalStore-compatible store whose snapshot is
+		 * `{ status, colorScheme, defaultView }` derived from the form.
+		 * `set(patch)` writes the touched fields through `form.set(field, value)`
+		 * (async; the form fences revisions and reloads on failure), and the
+		 * snapshot only changes after the Host confirms. `dispose()` removes the
+		 * subscription. (The pre-0.2.0 `reload()` wrapper is gone: the shared
+		 * form re-reads on its own, and its API has no `load()`.)
 		 */
 		function createConfigStore(scope) {
 			const listeners = [];
@@ -445,7 +458,6 @@ window.__ModuleLoader__.load({
 						await scope.set("defaultView", sanitizeView(patch.defaultView));
 					}
 				},
-				reload: () => scope.load(),
 				dispose: () => unsubscribe()
 			};
 		}
@@ -606,16 +618,30 @@ window.__ModuleLoader__.load({
 			// Month-view cursor (`YYYY-MM`); initialised from the current month
 			// and re-anchored when it would fall outside the navigable bounds.
 			const [monthCursor, setMonthCursor] = react.useState(() => monthKey(Date.now()));
-			// In-card settings panel (⚙ at the row's right end); the card
-			// configures itself here instead of living in 设置 → 插件 → 插件配置.
+			// The ⚙ at the row's right end opens the floating settings panel;
+			// the card configures itself here instead of living in
+			// 设置 → 插件 → 插件配置. The panel is PORTALED to document.body and
+			// anchored to this button, so the open state lives here with it.
+			const gearRef = react.useRef(null);
 			const [settingsOpen, setSettingsOpen] = react.useState(false);
 			react.useEffect(() => {
 				if (!settingsOpen) return;
 				const onKeyDown = (event) => {
 					if (event.key === "Escape") setSettingsOpen(false);
 				};
+				const onPointerDown = (event) => {
+					const gear = gearRef.current;
+					if (gear !== null && gear.contains(event.target)) return;
+					const panel = document.querySelector(`.${S.settingsPanel}`);
+					if (panel !== null && panel.contains(event.target)) return;
+					setSettingsOpen(false);
+				};
 				document.addEventListener("keydown", onKeyDown);
-				return () => document.removeEventListener("keydown", onKeyDown);
+				document.addEventListener("pointerdown", onPointerDown, true);
+				return () => {
+					document.removeEventListener("keydown", onKeyDown);
+					document.removeEventListener("pointerdown", onPointerDown, true);
+				};
 			}, [settingsOpen]);
 			const loaderRef = react.useRef(null);
 			if (loaderRef.current === null) loaderRef.current = createLoader();
@@ -805,16 +831,19 @@ window.__ModuleLoader__.load({
 									onClick: load,
 									children: dict("refresh")
 								}),
-								// The setting button owns the row's right end; the ‹ ›
-								// stepper and the view switch sit left of it, the
-								// stepper next to the stats it moves through.
+								// The ⚙ owns the row's right end; the ‹ › stepper
+								// and the view switch sit left of it, the stepper
+								// next to the stats it moves through. This button is
+								// also the settings panel's anchor.
 								react_jsx_runtime.jsx("button", {
 									type: "button",
+									ref: gearRef,
 									className: S.gear,
 									"data-active": settingsOpen,
+									"aria-haspopup": "dialog",
 									"aria-expanded": settingsOpen,
-									"aria-label": dict("settingsTitle"),
-									title: dict("settingsTitle"),
+									"aria-label": dict(settingsOpen ? "settingsCollapse" : "settingsExpand"),
+									title: dict(settingsOpen ? "settingsCollapse" : "settingsExpand"),
 									onClick: () => setSettingsOpen(!settingsOpen),
 									children: react_jsx_runtime.jsx("svg", {
 										width: 14,
@@ -933,6 +962,8 @@ window.__ModuleLoader__.load({
 							store: configStore,
 							palette,
 							translate,
+							legend: levelLegend,
+							anchor: gearRef.current,
 							onClose: () => setSettingsOpen(false)
 						}) : null
 					]
@@ -948,10 +979,45 @@ window.__ModuleLoader__.load({
 		//#endregion
 
 		//#region TokenHeatmapInlineSettings
+		/** Distance between the ⚙ and the panel's bottom edge (native dialog spec). */
+		const PANEL_GAP = 8;
+		/** Viewport margin the placement clamp keeps (native dialog spec). */
+		const PANEL_MARGIN = 12;
+
+		/**
+		 * Place the floating panel above its ⚙ trigger, clamped to the viewport —
+		 * the same measure-then-place flow (and the same 8px gap / 12px margin)
+		 * the built-in stat dialogs use. The panel is `position:fixed` and lives
+		 * in `document.body`, so the card can never clip it.
+		 * @param trigger - the ⚙ button the panel is anchored to.
+		 * @param panel - the `position:fixed` panel element.
+		 */
+		function placePanel(trigger, panel) {
+			const anchor = trigger.getBoundingClientRect();
+			const width = panel.offsetWidth;
+			const height = panel.offsetHeight;
+			if (width === 0 || height === 0) return;
+			const viewportWidth = window.innerWidth;
+			const viewportHeight = window.innerHeight;
+			const left = Math.min(
+				Math.max(PANEL_MARGIN, anchor.left + anchor.width / 2 - width / 2),
+				Math.max(PANEL_MARGIN, viewportWidth - width - PANEL_MARGIN)
+			);
+			let top = anchor.top - height - PANEL_GAP;
+			if (top < PANEL_MARGIN) top = Math.min(anchor.bottom + PANEL_GAP, viewportHeight - height - PANEL_MARGIN);
+			panel.style.left = `${Math.round(left)}px`;
+			panel.style.top = `${Math.round(Math.max(PANEL_MARGIN, top))}px`;
+			panel.style.visibility = "visible";
+		}
+
 		/**
-		 * The card's own settings panel: 配色方案 and 默认视图, edited where the
-		 * card lives instead of inside 设置 → 插件 → 插件配置 (this plugin no
-		 * longer registers into the `settings.plugin.item` seat).
+		 * The card's settings panel: 配色方案 and 默认视图, edited from the card
+		 * itself instead of inside 设置 → 插件 → 插件配置 (this plugin no longer
+		 * registers into the `settings.plugin.item` seat).
+		 *
+		 * It is PORTALED to `document.body` (the card's own box can never clip
+		 * it) and anchored to the ⚙ through `anchor`; the owner closes it on
+		 * outside pointerdown and Escape, so this component only draws.
 		 *
 		 * Every control applies immediately through the bound settings scope —
 		 * there is no draft/save step, so the component owns only a local save
@@ -964,9 +1030,12 @@ window.__ModuleLoader__.load({
 		 * @param props.store - config store (set writes through the scope).
 		 * @param props.palette - active palette (level 0..4 → css color).
 		 * @param props.translate - interpolation helper for translated labels.
-		 * @param props.onClose - collapse the panel (the × button).
+		 * @param props.legend - level labels for the palette footnote.
+		 * @param props.anchor - the ⚙ button the panel is placed against.
+		 * @param props.onClose - collapse the panel.
 		 */
-		function TokenHeatmapInlineSettings({ dict, config, store, palette, translate, onClose }) {
+		function TokenHeatmapInlineSettings({ dict, config, store, palette, translate, legend, anchor, onClose }) {
+			const panelRef = react.useRef(null);
 			const [saveFailed, setSaveFailed] = react.useState(false);
 			const schemes = Object.keys(COLOR_SCHEMES);
 			// Optimistic local echo: the settings scope only reports the new value
@@ -974,6 +1043,26 @@ window.__ModuleLoader__.load({
 			const [pending, setPending] = react.useState({});
 			const scheme = pending.colorScheme ?? config.colorScheme;
 			const defaultView = pending.defaultView ?? config.defaultView;
+			// Place before paint (and again when the palette reflows the panel):
+			// the trigger's box is only meaningful once the card is laid out.
+			react.useLayoutEffect(() => {
+				const panel = panelRef.current;
+				if (panel === null || anchor === null || anchor === void 0) return;
+				placePanel(anchor, panel);
+			});
+			react.useEffect(() => {
+				const replace = () => {
+					const panel = panelRef.current;
+					if (panel === null || anchor === null || anchor === void 0) return;
+					placePanel(anchor, panel);
+				};
+				window.addEventListener("resize", replace);
+				window.addEventListener("scroll", replace, true);
+				return () => {
+					window.removeEventListener("resize", replace);
+					window.removeEventListener("scroll", replace, true);
+				};
+			}, [anchor]);
 			const commit = async (patch) => {
 				setPending((current) => ({ ...current, ...patch }));
 				setSaveFailed(false);
@@ -990,28 +1079,43 @@ window.__ModuleLoader__.load({
 				if (value !== defaultView) commit({ defaultView: value });
 			};
 			const labelOf = (name) => dict(`settings${name[0].toUpperCase()}${name.slice(1)}`);
-			return react_jsx_runtime.jsxs("div", {
+			const title = dict("settingsTitle");
+			const panel = react_jsx_runtime.jsxs("div", {
+				ref: panelRef,
 				className: S.settingsPanel,
-				// Escape and "focus left the panel" both collapse it, so the
-				// panel never lingers behind an unrelated interaction.
-				onBlur: (event) => {
-					if (!event.currentTarget.contains(event.relatedTarget)) onClose();
-				},
+				role: "dialog",
+				"aria-label": title,
+				// Nothing may paint at the viewport origin before placement runs.
+				style: { visibility: "hidden" },
 				children: [
 					react_jsx_runtime.jsxs("div", {
 						className: S.panelHead,
 						children: [
-							react_jsx_runtime.jsx("span", { className: S.panelTitle, children: dict("settingsTitle") }),
-							react_jsx_runtime.jsx("button", {
-								type: "button",
-								className: S.panelClose,
-								"aria-label": dict("settingsCollapse"),
-								title: dict("settingsCollapse"),
-								onClick: onClose,
-								children: "\u00d7"
+							react_jsx_runtime.jsxs("span", {
+								className: S.panelTitleLabel,
+								children: [
+									react_jsx_runtime.jsxs("svg", {
+										width: 14,
+										height: 14,
+										viewBox: "0 0 24 24",
+										fill: "none",
+										stroke: "currentColor",
+										"stroke-width": 2,
+										"stroke-linecap": "round",
+										"stroke-linejoin": "round",
+										"aria-hidden": "true",
+										children: [
+											react_jsx_runtime.jsx("circle", { cx: 12, cy: 12, r: 9 }),
+											react_jsx_runtime.jsx("path", { d: "M12 11v5" }),
+											react_jsx_runtime.jsx("path", { d: "M12 8h.01" })
+										]
+									}),
+									react_jsx_runtime.jsx("span", { children: title })
+								]
 							})
 						]
 					}),
+					react_jsx_runtime.jsx("div", { className: S.panelRule, "aria-hidden": "true" }),
 					react_jsx_runtime.jsxs("div", {
 						className: S.settingsGroup,
 						children: [
@@ -1058,54 +1162,68 @@ window.__ModuleLoader__.load({
 									onClick: () => chooseView(mode),
 									children: dict(mode === "month" ? "viewMonth" : "viewYear")
 								}, mode))
-							}),
-							react_jsx_runtime.jsx("span", {
-								className: S.settingsHint,
-								children: dict("settingsDefaultViewHint")
 							})
 						]
 					}),
-					react_jsx_runtime.jsx("span", {
-						className: saveFailed ? `${S.settingsHint} ${S.settingsHintError}` : S.settingsHint,
-						children: saveFailed
-							? dict("settingsSaveFailed")
-							: translate("settingsPaletteHint", { levels: uiDict().levelLegend.join(" / ") })
+					react_jsx_runtime.jsxs("div", {
+						className: S.panelFoot,
+						children: [
+							react_jsx_runtime.jsxs("div", {
+								className: S.footLegend,
+								children: [
+									dict("less"),
+									...palette.map((color, level) => react_jsx_runtime.jsx("span", {
+										className: S.legendCell,
+										style: { background: color },
+										title: legend[level] ?? ""
+									}, `foot-${level}`)),
+									dict("more")
+								]
+							}),
+							saveFailed ? react_jsx_runtime.jsx("div", {
+								className: S.footError,
+								children: dict("settingsSaveFailed")
+							}) : react_jsx_runtime.jsx("div", {
+								className: S.footRule,
+								children: dict("settingsThresholdNote")
+							})
+						]
 					})
 				]
 			});
+			return reactDom.createPortal(panel, document.body);
 		}
 		//#endregion
 
 		//#region plugin body
 		/**
-		 * Settings namespace the card reads/writes — must match the namespace
-		 * the Host registers (lib/index.js). Spelled here rather than imported:
-		 * a client package must not depend on a Host package.
+		 * Profile entry id this plugin's config form is keyed by. DSH 0.2.0
+		 * replaced the plugin-owned settings namespace with schema-derived plugin
+		 * CONFIG: the Host exports `Config`, the form is keyed by the profile
+		 * entry id — the `id` of the row our bundle patch inserts, which is what
+		 * the browser asks for here. Spelled as a literal rather than imported: a
+		 * client package must not depend on a Host package.
 		 */
 		const SETTINGS_NS = "token-heatmap";
 		/** Services required by the client plugin body. */
-		const inject = ["slots", "locale", "connection", "remote", "settingsScope"];
+		const inject = ["slots", "locale", "configForms"];
 
 		/**
 		 * Client plugin body: register the dictionaries and the input-dock entry
-		 * (the heatmap below the composer card on the new-session screen), backed
-		 * by the `token-heatmap` settings namespace through a bound settings
-		 * scope. The card configures itself through its own ⚙ panel, so this
-		 * plugin does NOT register into `settings.plugin.item` (the official
-		 * 设置 → 插件 → 插件配置 card seat) any more — the Host still serves the
-		 * namespace, it just has no configuration card to dispatch.
+		 * (the heatmap below the composer card on the new-session screen). The
+		 * card configures itself through its own ⚙ panel, which reads and writes
+		 * the plugin's config form (`ctx.configForms.get("token-heatmap")`) —
+		 * the shared form owns transport, revisions, and recovery.
 		 *
 		 * Slot-kind contract: `conversation.input.dock` is a LIST slot, so its
-		 * registration is keyed by `id` (a `settings.plugin.item` registration
-		 * would instead need `key`, the settings namespace the card edits).
+		 * registration is keyed by `id`.
 		 * @param ctx - client root context.
 		 */
 		function apply(ctx) {
-			// Bind the namespace scope on THIS plugin's fiber (settingsScope.bind
-			// registers the disposer itself); the scope auto-loads and refreshes
-			// on settings/document-updated and connection/reset. Requires the
-			// injected connection (transport) and remote (invalidation) services.
-			const scope = ctx.settingsScope.bind({ namespace: SETTINGS_NS });
+			// The shared form for our entry: `getSnapshot()`/`subscribe()` for
+			// reads, `set(field, value)` for writes. `createConfigStore` is
+			// duck-typed over exactly that surface, so the ⚙ panel is unchanged.
+			const scope = ctx.configForms.get(SETTINGS_NS);
 			configStore = createConfigStore(scope);
 			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "token-heatmap: dictionaries");
 			ctx.slots.inject("conversation.input.dock", () => ctx.slots.register({

package/lib/index.js

@@ -11,11 +11,13 @@
  * its own peer-socket loopback fence (the exact route bypasses the RPC trust
  * fence); Host is checked only as an additional defense.
  *
- * Display settings (enabled + colorScheme) are owned by the plugin's
- * `token-heatmap` settings namespace — the config card in
- * 设置 → 插件 → 插件配置 reads/writes it through the settings scope, and the
- * legacy `<DSH_HOME>/storages/token-heatmap-config.json` document is
- * migrated into the namespace once at startup.
+ * Display settings (colorScheme + defaultView) are owned by this plugin's
+ * profile CONFIG — DSH 0.2.0 derives the settings form from the exported
+ * `Config` schema, keys it by the profile entry id (`token-heatmap`, the id of
+ * the row our bundle patch inserts), and the browser edits it through
+ * `ctx.configForms.get("token-heatmap")`. The plugin's own ⚙ panel writes the
+ * same values; the legacy `<DSH_HOME>/storages/token-heatmap-config.json`
+ * document is migrated into it once at startup.
  *
  * Usage aggregation is INCREMENTAL: per-session fold state (day/model
  * buckets plus the last usage sample) is cached in memory and persisted to
@@ -33,6 +35,7 @@
  */
 
 import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { applyUsageDelta, createUsageState, mergeInto, renderUsage, zeroBuckets } from "./usage.js";
@@ -45,24 +48,17 @@ const name = "token-heatmap";
 /** Services required before this plugin activates. */
 const inject = ["webServer", "sessions", "sessionPersistence", "settings"];
 
-//#region settings namespace
+//#region plugin config
 /**
- * Settings namespace owned by this plugin. Registering it makes the Host
- * serve a `token-heatmap` section (resolved from schema defaults, then any
- * composition `base`, then the user settings.yaml layer), which is exactly
- * what the official 设置 → 插件 → 插件配置 tab dispatches on: it renders the
- * card registered into `settings.plugin.item` whose `key` matches a served
- * namespace. The card edits `enabled` + `colorScheme` through the settings
- * scope; the legacy `<DSH_HOME>/storages/token-heatmap-config.json` document
- * is migrated once at startup (see migrateLegacyConfig).
- * DSH 0.1.2 起 `@deepseek-ai/dsh-settings` 不再导出 settingsNamespace 帮助函数：
- * namespace 直接以字面量传入（register/get/update 内部仍按
- * /^[a-z][a-z0-9-]*$/ 校验）。
+ * Profile entry id this plugin's config form is keyed by: the `id` of the row
+ * the bundle patch inserts, which is also what the browser asks
+ * `ctx.configForms.get(...)` for. DSH 0.2.0 derives the form from the exported
+ * `Config` schema, so no registration call exists (nor does `settings.get`).
  */
 const SETTINGS_NAMESPACE = "token-heatmap";
 
 /**
- * Durable display preferences; also the wire envelope the browser scope
+ * Durable display preferences; also the wire envelope the browser form
  * validates against. Scheme membership is deliberately NOT enforced (a newer
  * client may know a palette the server does not — the client falls back to
  * green); only the same shape bounds parseConfig applies: a short, non-blank
@@ -72,10 +68,12 @@ const SETTINGS_NAMESPACE = "token-heatmap";
  * the hero screen, so the field is neither accepted nor served (an old
  * settings.yaml keeps its dead `enabled` key, and nothing reads it).
  */
-const TokenHeatmapSettingsSchema = z.object({
+const Config = z.object({
 	colorScheme: z.string().min(1).max(32).default("green"),
 	defaultView: z.union(VIEW_MODES.map((mode) => z.const(mode))).default("year")
 });
+/** @deprecated 0.1.x name; the schema IS the config now. Kept for old importers. */
+const TokenHeatmapSettingsSchema = Config;
 //#endregion
 
 const USAGE_PATH = "/api/token-heatmap/usage";
@@ -329,14 +327,127 @@ function configPath() {
 	return join(home, "storages", "token-heatmap-config.json");
 }
 
+/** DSH home resolution, mirroring `@deepseek-ai/dsh-home-paths` (no extra peer). */
+function dshHomeDirectory(env = process.env) {
+	const configured = env.DSH_HOME;
+	if (typeof configured === "string" && configured.trim() !== "") return configured.trim();
+	return join(homedir(), ".dsh");
+}
+
+/**
+ * One profile entry's descriptor from the settings service, or undefined when
+ * the service is absent or the entry is not live. DSH 0.2.0 dropped the old
+ * `settings.get(ns)` accessor — a plugin's settings ARE its profile entry
+ * config now — so reads go through the same `describe()` view the settings UI
+ * renders (its `value` is the resolved section, its `user` the raw user layer).
+ * @param ctx - plugin context.
+ * @param entryId - profile entry id (`token-heatmap`).
+ * @returns the descriptor, or undefined.
+ */
+function entryDescriptor(ctx, entryId) {
+	const settings = typeof ctx.get === "function" ? ctx.get("settings") : ctx.settings;
+	if (settings === null || settings === void 0 || typeof settings.describe !== "function") return void 0;
+	try {
+		return settings.describe().find((row) => row.ns === entryId);
+	} catch {
+		return void 0;
+	}
+}
+
+/**
+ * One profile entry's resolved config section, read through the settings
+ * service.
+ * @param ctx - plugin context.
+ * @param entryId - profile entry id (`token-heatmap`).
+ * @returns the resolved section, or undefined when the entry is absent.
+ */
+function entryConfig(ctx, entryId) {
+	const value = entryDescriptor(ctx, entryId)?.value;
+	return value !== null && typeof value === "object" ? value : void 0;
+}
+
+/**
+ * Best-effort read of one scalar out of the pre-0.2.0 `settings.yaml` section
+ * for this entry. DSH's own importer moves those sections into the profile
+ * once, keyed by entry id — and skipped ours while the bundle was refused for
+ * incompatible peers, leaving the value only in the renamed document. This is
+ * a deliberately narrow scan (one top-level section, one scalar) rather than a
+ * YAML dependency: anything it cannot read is simply left for the user.
+ * @param text - contents of `settings.yaml` or `settings.yaml.imported`.
+ * @param section - top-level section name (`token-heatmap`).
+ * @param field - scalar key inside it.
+ * @returns the raw trimmed string value, or null.
+ */
+function legacySettingFromDocument(text, section, field) {
+	if (typeof text !== "string") return null;
+	const lines = text.split(/\r?\n/);
+	const inSection = /^[^\s#][^:]*:/;
+	let inside = false;
+	for (const line of lines) {
+		if (inSection.test(line)) {
+			inside = line.trim() === `${section}:` && !line.startsWith(" ");
+			continue;
+		}
+		if (!inside) continue;
+		const match = /^\s+([A-Za-z0-9_-]+):\s*(.*?)\s*$/.exec(line);
+		if (match === null || match[1] !== field) continue;
+		return match[2].replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "");
+	}
+	return null;
+}
+
+/** Files the legacy value may still live in, newest name first. */
+const LEGACY_SETTINGS_FILES = ["settings.yaml.imported", "settings.yaml"];
+
+/**
+ * One-time rescue of display preferences from the removed settings document.
+ *
+ * DSH 0.2.0 imported the old `settings.yaml` sections per entry id, but this
+ * plugin was refused (incompatible peers) at that moment, so its section —
+ * `colorScheme` / `defaultView`, plus the dead `enabled` — only survives in
+ * the renamed document. Runs only when the entry has no user value yet, only
+ * for non-default fields, best effort, never blocking.
+ * @param ctx - plugin context carrying the settings service.
+ */
+async function rescueRemovedSettingsDocument(ctx) {
+	try {
+		const descriptor = entryDescriptor(ctx, SETTINGS_NAMESPACE);
+		if (descriptor === void 0) return;
+		const settings = typeof ctx.get === "function" ? ctx.get("settings") : ctx.settings;
+		const user = descriptor.user;
+		if (user !== null && typeof user === "object" && (Object.hasOwn(user, "colorScheme") || Object.hasOwn(user, "defaultView"))) return;
+		const home = dshHomeDirectory();
+		let text = null;
+		for (const file of LEGACY_SETTINGS_FILES) {
+			try {
+				text = readFileSync(join(home, file), "utf8");
+			} catch {
+				continue;
+			}
+			if (text !== null) break;
+		}
+		if (text === null) return;
+		const patch = {};
+		const scheme = legacySettingFromDocument(text, SETTINGS_NAMESPACE, "colorScheme");
+		if (scheme !== null && scheme !== DEFAULT_CONFIG.colorScheme) patch.colorScheme = scheme;
+		const view = legacySettingFromDocument(text, SETTINGS_NAMESPACE, "defaultView");
+		if (view !== null && VIEW_MODES.includes(view) && view !== DEFAULT_CONFIG.defaultView) patch.defaultView = view;
+		if (Object.keys(patch).length === 0) return;
+		await settings.update(SETTINGS_NAMESPACE, patch);
+		ctx.logger.info(`token-heatmap: carried ${JSON.stringify(patch)} over from the removed settings.yaml`);
+	} catch (error) {
+		ctx.logger.warn(`token-heatmap: legacy settings rescue skipped: ${String(error)}`);
+	}
+}
+
 /**
  * One-time migration from the legacy config document
- * (`<DSH_HOME>/storages/token-heatmap-config.json`) into the registered
- * settings namespace. Runs once per process, best-effort: when the user has
- * no settings.yaml section yet, non-default values are imported through the
- * settings write path; the legacy file is removed either way (the namespace
- * becomes the single source of truth). A corrupt legacy document is dropped,
- * never imported. Failures are logged and never fatal.
+ * (`<DSH_HOME>/storages/token-heatmap-config.json`) into the plugin config.
+ * Runs once per process, best-effort: when the user has no config value yet,
+ * non-default values are imported through the settings write path; the legacy
+ * file is removed either way (the config entry becomes the single source of
+ * truth). A corrupt legacy document is dropped, never imported. Failures are
+ * logged and never fatal.
  * @param ctx - plugin context carrying the settings service.
  */
 async function migrateLegacyConfig(ctx) {
@@ -355,15 +466,16 @@ async function migrateLegacyConfig(ctx) {
 			await rm(path, { force: true });
 			return;
 		}
-		const descriptor = ctx.settings.describe().find((entry) => entry.ns === SETTINGS_NAMESPACE);
+		const descriptor = entryDescriptor(ctx, SETTINGS_NAMESPACE);
+		const settings = typeof ctx.get === "function" ? ctx.get("settings") : ctx.settings;
 		const userExists = descriptor !== void 0 && descriptor.user !== void 0;
-		if (!userExists) {
+		if (!userExists && settings !== void 0 && typeof settings.update === "function") {
 			const patch = {};
 			// The legacy document's `enabled` switch died with 0.2.0: import only
 			// what the card still owns.
 			if (legacy.colorScheme !== DEFAULT_CONFIG.colorScheme) patch.colorScheme = legacy.colorScheme;
 			if (legacy.defaultView !== DEFAULT_CONFIG.defaultView) patch.defaultView = legacy.defaultView;
-			if (Object.keys(patch).length > 0) await ctx.settings.update(SETTINGS_NAMESPACE, patch);
+			if (Object.keys(patch).length > 0) await settings.update(SETTINGS_NAMESPACE, patch);
 		}
 		await rm(path, { force: true });
 	} catch (error) {
@@ -372,13 +484,13 @@ async function migrateLegacyConfig(ctx) {
 }
 
 /**
- * Serve the resolved settings section (schema defaults + user layer).
+ * Serve the resolved config section (schema defaults + user layer).
  * `enabled` stays in the payload as a constant true: the legacy loopback
  * endpoint is a back-compat API, and a pre-0.2.0 client that reads it must not
  * lose the card over a switch this version no longer has.
  */
 function serveConfig(ctx) {
-	const section = ctx.settings.get(SETTINGS_NAMESPACE);
+	const section = entryConfig(ctx, SETTINGS_NAMESPACE);
 	const scheme = typeof section?.colorScheme === "string" && section.colorScheme.length > 0 ? section.colorScheme : DEFAULT_CONFIG.colorScheme;
 	const view = typeof section?.defaultView === "string" && VIEW_MODES.includes(section.defaultView) ? section.defaultView : DEFAULT_CONFIG.defaultView;
 	return { enabled: true, colorScheme: scheme, defaultView: view };
@@ -687,19 +799,22 @@ async function handleUsage(ctx, req, res) {
 }
 
 /**
- * Plugin body: register the usage and config routes, the settings namespace
- * that backs the plugin configuration card (设置 → 插件 → 插件配置), and the
- * one-time legacy-config migration.
+ * Plugin body: register the usage and config routes and run the two one-time
+ * legacy migrations. DSH 0.2.0 needs no namespace registration — the exported
+ * `Config` is the form — so nothing here touches the settings document beyond
+ * the rescues.
  * @param ctx - plugin context carrying webServer, sessions, sessionPersistence, and settings.
  */
 function apply(ctx) {
-	// The registration is fiber-bound: disposing this plugin removes the
-	// namespace and its observers. `settings` is a hard dependency (inject),
-	// so ctx.settings is available here unconditionally.
-	ctx.settings.register(SETTINGS_NAMESPACE, TokenHeatmapSettingsSchema);
 	// Best-effort, fire-and-forget: import the pre-0.1.2 config document into
-	// the namespace and drop the file (see migrateLegacyConfig).
+	// the config entry and drop the file (see migrateLegacyConfig), then rescue
+	// whatever the removed settings.yaml still holds. The rescue waits for the
+	// Loader to settle, exactly like DSH's own importer did, so the entry it
+	// inspects is the live one.
 	migrateLegacyConfig(ctx);
+	const loader = ctx.root?.loader;
+	const settled = typeof loader?.await === "function" ? Promise.resolve(loader.await()).catch(() => void 0) : Promise.resolve();
+	settled.then(() => rescueRemovedSettingsDocument(ctx)).catch(() => void 0);
 	// Real-time fold: listen to session/event and fold each usage event into
 	// the cache immediately, so live session usage is captured regardless of
 	// whether the hero screen is mounted (the client polls the usage endpoint
@@ -779,4 +894,18 @@ function apply(ctx) {
 	}), "token-heatmap: config route");
 }
 
-export { apply, inject, name, CONFIG_PATH, USAGE_PATH, SETTINGS_NAMESPACE, TokenHeatmapSettingsSchema, migrateLegacyConfig };
+export {
+	apply,
+	inject,
+	name,
+	Config,
+	CONFIG_PATH,
+	USAGE_PATH,
+	SETTINGS_NAMESPACE,
+	TokenHeatmapSettingsSchema,
+	migrateLegacyConfig,
+	entryConfig,
+	dshHomeDirectory,
+	legacySettingFromDocument,
+	rescueRemovedSettingsDocument
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kidli1412/dsh-token-heatmap",
-  "version": "0.4.1",
-  "description": "DSH web plugin: GitHub-style daily token-usage heatmap on the new-session screen with switchable year/month views and six color schemes. The card configures itself (⚙ palette + default view) — no DSH settings card — and shows today / this-month / all-time totals.",
+  "version": "0.5.0",
+  "description": "DSH web plugin: GitHub-style daily token-usage heatmap on the new-session screen with switchable year/month views and six color schemes. The card configures itself through a floating ⚙ panel (palette + default view) — no DSH settings card — and shows today / this-month / all-time totals.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -20,15 +20,26 @@
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-api-remotes": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-connection": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-api-remotes": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.2.0-rc.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-api-remotes": { "optional": true },
+    "@deepseek-ai/dsh-client-connection": { "optional": true },
+    "@deepseek-ai/dsh-client-locale": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-conversation": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-settings": { "optional": true },
+    "@deepseek-ai/dsh-host-webserver": { "optional": true },
+    "@deepseek-ai/dsh-session": { "optional": true },
+    "@deepseek-ai/dsh-session-persistence": { "optional": true },
+    "@deepseek-ai/dsh-settings": { "optional": true }
   },
   "dsh": {
     "bundle": {
@@ -46,9 +57,7 @@
     },
     "compatibility": {
       "dshReleases": {
-        "0.1.2-alpha.4": "compatible",
-        "0.1.2-alpha.5": "compatible",
-        "0.1.2-rc.1": "compatible"
+        "0.2.0-rc.2": "compatible"
       }
     }
   },
@@ -60,7 +69,7 @@
   "license": "MIT",
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": "^0.1.2-rc.1"
+    "dsh": "^0.2.0-rc.2"
   },
   "repository": {
     "type": "git",