@chenmiao8563/dsh-token-ledger 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -8,6 +8,31 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Nothing yet.
 
+## [0.2.0] - 2026-09-10
+
+### Added
+
+- **A settings page.** The browser half registers a `settings.section`, so the
+  ledger appears in the settings sidebar beside every other section. It shows:
+  - range totals for **this month**, **this year** and the **last 7 days**, each
+    with total tokens, cache hit rate and call count, plus the bucket breakdown;
+  - **today**, live, which moves as steps complete;
+  - a **usage calendar** switchable between year, month and week, where the week
+    view is a bar chart rather than a heatmap;
+  - the per-model breakdown with its own cache hit rates.
+- `lib/overview.js`, a pure function from a ledger snapshot to the payload the
+  page renders, and `lib/route.js`, the read-only
+  `GET /api/token-ledger/summary` route that serves it.
+- The browser half is hand-written against the client's module loader and
+  requires nothing but `react`, so the package still installs with no build step.
+
+### Changed
+
+- The overview is served over an HTTP route rather than a settings namespace.
+  A namespace would need a schema — a real dependency — and would rewrite
+  `settings.yaml` on every debounce with data that is derived and reproducible.
+  The ledger file remains the only store of record.
+
 ## [0.1.1] - 2026-09-10
 
 Both fixes come from mounting the plugin in a real DSH host, which is the only
@@ -63,6 +88,7 @@ so both now have regression tests.
 - Zero runtime dependencies, zero peer dependencies and no install scripts, so
   the package installs without a build step.
 
-[Unreleased]: https://github.com/chenmiao8563/dsh-token-ledger/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/chenmiao8563/dsh-token-ledger/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/chenmiao8563/dsh-token-ledger/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/chenmiao8563/dsh-token-ledger/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/chenmiao8563/dsh-token-ledger/releases/tag/v0.1.0

package/README.md

@@ -144,6 +144,33 @@ audit useless. The ledger's own `updatedAt` settles it:
          (1 calls, 5100 tokens not yet flushed)
 ```
 
+## Settings page
+
+The browser half adds a **Token ledger** section to the settings sidebar:
+
+- **Range totals** for this month, this year and the last 7 days — total tokens,
+  cache hit rate, call count, and the bucket breakdown behind them. The cache hit
+  rate is `cacheRead / (cacheRead + uncachedInput)`: the share of input the prompt
+  cache absorbed, so a route with no caching reads 0% rather than undefined.
+- **Today, live** — today's tokens, hit rate and calls, which move as steps
+  complete.
+- **A usage calendar** switchable between year, month and week. Year and month are
+  heatmaps; the week view is a bar chart. Heat levels are relative to the busiest
+  day in the window and square-rooted, so one huge day cannot flatten the rest.
+- **Per model** totals, each with its own hit rate.
+
+The page reads one read-only route, `GET /api/token-ledger/summary`, and polls it
+every 15 seconds. The route refuses a non-loopback peer, so it stays private even
+if the web server is bound to `0.0.0.0`.
+
+It needs a profile with a web server (the `web` or `desktop` profile). Without one,
+`/tokens` and the CLI still work, and the section says so instead of failing.
+
+The overview is deliberately **not** published through a settings namespace. That
+would need a schema — a real dependency, and this package has none — and would
+rewrite `settings.yaml` on every debounce with data that is derived and
+reproducible. The ledger file stays the only store of record.
+
 ## Configuration
 
 Override the composition entry by its `id`:
@@ -186,7 +213,8 @@ The ledger file is left alone on purpose — delete
 ## Development
 
 ```bash
-npm test            # 49 tests, no dependencies to install
+npm install         # devDependencies only: react, react-dom, and the slot registry DSH runs
+npm test            # 106 tests
 npm run verify      # packaging invariants (dependency-free, no install scripts, no bare imports)
 ```
 
@@ -194,6 +222,15 @@ npm run verify      # packaging invariants (dependency-free, no install scripts,
 spawning a child process per test file is blocked, use
 `npm run test:single-process`.
 
+The devDependencies are **test-only**. They are never installed for a consumer:
+the package ships with no dependencies, no peer dependencies and no install
+scripts, and `pnpm` does not install a dependency's devDependencies. They exist
+so the browser half can be checked against the real thing — React renders it, so
+a hook-order or DOM-prop mistake fails instead of passing silently, and
+`@deepseek-ai/dsh-client-ui-slots` validates the registration against the very
+registry that DSH runs. Without them installed the affected tests skip with a
+stated reason, so `npm test` still works from a fresh clone with no network.
+
 See [docs/VERIFICATION.md](docs/VERIFICATION.md) for what was actually verified
 and how, including the evidence behind the fork rule.
 

package/README.zh.md

@@ -136,6 +136,29 @@ dsh-token-ledger export  [选项]       导出 CSV 与 JSON
          (1 calls, 5100 tokens not yet flushed)
 ```
 
+## 设置页
+
+浏览器端会在设置侧边栏注册一个 **用量账本** 分区：
+
+- **区间总计**：本月 / 本年 / 近 7 天三档可切换，每档显示 Token 总计、缓存命中率、
+  调用次数，以及背后的四桶明细。缓存命中率定义为
+  `缓存读入 / (缓存读入 + 未命中输入)`——即输入中被缓存吸收的比例，因此完全不缓存的
+  路由读数是 0%，而不是空白。
+- **今日实时**：今天的 Token、命中率与调用次数，随每一步完成而变动。
+- **用量热力图**：年 / 月 / 一周三档可切换；年和月是热力图，切到一周改为柱状图。
+  热力档位相对窗口内最忙的一天取平方根，避免某一天特别大把其余全部压成最淡档。
+- **按模型**：各模型的用量与各自命中率。
+
+页面只读一个路由 `GET /api/token-ledger/summary`，每 15 秒轮询一次。
+该路由会拒绝非回环来源，因此即使 web 服务器绑定到 `0.0.0.0` 也不会外泄。
+
+它需要带 web 服务器的 profile（`web` 或 `desktop`）。没有的话 `/tokens` 与 CLI
+照常可用，分区会明确说明而不是直接失败。
+
+概览**刻意不**通过设置命名空间下发：那需要 schema（一个真实依赖，而本包零依赖），
+而且每次防抖都会用可推导、可重放的数据重写一遍 `settings.yaml`。
+账本文件始终是唯一的记录来源。
+
 ## 配置
 
 按 `id` 覆盖组合条目：
@@ -172,13 +195,20 @@ dsh plugin --profile web remove @chenmiao8563/dsh-token-ledger
 ## 开发
 
 ```bash
-npm test            # 49 个测试，无需安装任何依赖
+npm install         # 两个 devDependency：react 与 react-dom，供渲染测试使用
+npm test            # 96 个测试
 npm run verify      # 打包不变式（零依赖、无安装脚本、无裸模块说明符）
 ```
 
 `npm test` 使用 Node 内置测试运行器。在禁止逐文件 spawn 子进程的受限环境里，
 改用 `npm run test:single-process`。
 
+React **只是 devDependency**，消费者永远不会安装它：本包不带任何依赖、任何 peer
+依赖、任何安装脚本，而 pnpm 不会为依赖安装其 devDependencies。它在这里的作用是让
+浏览器端能用**真库**渲染并断言——这能抓到替身抓不到的东西：hook 顺序违规与非法
+DOM 属性，React 会报出来，而手写的 `createElement` 会默默接受。没装它时这些渲染
+测试会带明确原因**跳过而不是失败**，所以全新克隆、无网络也能跑 `npm test`。
+
 实际验证了什么、怎么验证的（包括 fork 规则背后的证据）见
 [docs/VERIFICATION.md](docs/VERIFICATION.md)。
 

package/docs/VERIFICATION.md

@@ -220,6 +220,83 @@ sessions against the 72 logs carrying a `session/end-seed` marker and the 29
 declaring a parent. The 61 sessions outside both sets turned out to be
 four-record logs with no usage at all, which is why they correctly have no entry.
 
+## Browser half (0.2.0)
+
+What is checked here and what is not, because the difference is large.
+
+**Checked by test.** `lib/overview.js` and `lib/route.js` are pure or near-pure
+and are tested directly: range boundaries, cache-hit-rate arithmetic, gap-filled
+series, the loopback and origin guard, method handling, and the 500-on-fault
+path. The browser half is loaded through a stand-in module loader with a
+stand-in React, which exercises the module wrapper, the registration contract,
+and the whole render tree — formatting, heat levels, week-bar slicing, view
+switching, and the empty, malformed and stale-data paths.
+`scripts/verify-package.mjs` additionally fails the build if the browser half
+requires anything the loader does not provide, if its module id stops matching
+the package name, if it stops compiling as a classic script, or if a declared
+client dependency is outside the client-half namespace.
+
+**Checked by reading DSH's own source, not by inference.** The contracts the
+browser half depends on were read out of the shipped bundles rather than copied
+from a third-party plugin:
+
+| Contract | Where it was read | Result |
+| --- | --- | --- |
+| The `settings.section` registration shape | the sections DSH ships — `dsh-client-ui-settings-models` (order 10), `-settings-plugins` (15) and `-ui-agent-preset` (20) — plus the shell in `-settings-general` that renders them via `renderSlot("settings.section", …, { only: active })` | identical field set; `locale` is optional, proven by `-settings-models` omitting it; the sidebar rows come from `id`, `order` and `label`, all of which this plugin supplies |
+| The client module format | every `@deepseek-ai/dsh-client-*/lib/client.js` | byte-identical wrapper: `window.__ModuleLoader__.load({ id, factory })` with `var module = { exports: {} }` and `exports.apply`/`exports.inject` |
+| When the factory runs | `dsh-client-modules` module docs | only registration happens at script execution; body side effects, styles included, run at materialization — which is why the stylesheet is installed inside `apply()` |
+| The `dsh.client` declaration | `parseDshClient` in `dsh-client-modules/lib/index.js` | `platform` must be a string and only `web` is loaded; `inject` and `external` are optional string arrays; `external` — not `inject` — is what orders the module graph |
+| What `dsh.client.inject` **contains** | the five `dsh.client` declarations DSH ships, two of them non-empty: `dsh-client-locale` and `dsh-client-ui-settings-general` | **package/entry ids, not service names.** A module's own exported `inject` is the separate service list. This plugin lists the two packages whose services it uses, which is the same convention, and an empty list is also legal (`dsh-client-connection` uses one) |
+| What `external` contains | the module-graph walk in `dsh-client-modules/lib/client.js`, which runs every entry through `stripClientSuffix` before resolving it | module specifiers for *other rows*. This plugin requires only `react`, which the loader provides and no row owns, so it declares none |
+| How `exports["./client"]` is located | `clientExportOf` in `dsh-client-modules/lib/index.js` | a plain string or an object with a string `default`; anything else throws. A plain string is used here, and `verify-package.mjs` pins it |
+| Whether a **scoped** package id survives | `stripClientSuffix` in `dsh-client-modules/lib/client.js` | it removes only a trailing `/client`, so `@chenmiao8563/dsh-token-ledger` passes through intact. DSH's own client packages are scoped too, so the transport already carries ids containing `/` |
+
+That reading corrected two real mistakes in the first draft of this half, both of
+which would have been a silent failure rather than an error:
+
+- `@deepseek-ai/dsh-client-ui-slots` was listed as a client dependency. It is a
+  pure core library (its manifest exports only `.`, and it declares no
+  `dsh.client`), so it is never a client module row.
+- The settings shell package was listed as `-ui-settings`, which holds the
+  namespace-scope service; the section slot is declared and rendered by
+  `-ui-settings-general`.
+
+**Checked under the real React.** `test/client-render.test.mjs` renders the
+presentation component with React 18.3.1 — the same major version DSH bundles —
+through `react-dom/server`, and asserts the actual markup: the range tabs and
+their active state, the totals, hit rate and call count for each range, today's
+block surviving a year-range selection, the year heat grid (one cell per day plus
+five legend swatches), the month grid (every day of March), the week bars (seven,
+with inline heights), bounded heat levels drawn from a five-entry palette,
+proportional model bars, and the loading, error, stale and empty states. It also
+captures `console.error` and `console.warn` and **fails if React complained at
+all**, which is what catches an invalid DOM prop or a hook-order violation — the
+class of defect a hand-rolled `createElement` accepts silently.
+
+React is a devDependency, so this runs in CI and under `prepublishOnly`. Without
+it installed the file skips with a stated reason rather than failing, which keeps
+`npm test` working from a fresh clone with no network.
+
+**Checked against the real slot registry.** `test/slot-registration.test.mjs`
+feeds the registration `apply` actually builds into
+`@deepseek-ai/dsh-client-ui-slots` — the registry DSH itself runs, pinned as a
+devDependency to `0.1.2-rc.1`, the exact version this DSH bundles (`latest` on
+npm is an older `0.0.1-rc.1`, so the version is pinned rather than ranged). It
+asserts that the registry accepts the entry, that `resolveSlotLabel` resolves the
+label thunk to a non-empty string — a label it could not resolve would render as
+a blank sidebar row — that the entry id does not collide with the three sections
+DSH ships, that a duplicate id is refused, that disposing retires the entry, and
+that registering into an undeclared slot is refused, which is why the plugin uses
+`slots.inject` rather than registering blind.
+
+**Not checked.** Whether the client module loader accepts the file, whether the
+shell renders the section, and how any of it looks. Nothing here executes
+`window.__ModuleLoader__` or mounts the component into a DOM: the module's shape
+is asserted to match every bundle DSH ships, and the registration is validated by
+the real registry, but no single process loads the plugin the way the browser
+does. The remaining risk is integration and visual — a first-run surprise, not a
+contractual one.
+
 ## Not verified
 
 Stated plainly, because a verification file that only lists successes is not