dsh-consumption-badge 1.1.0 → 1.2.2

package/README.md

@@ -2,22 +2,93 @@
 
 A **persistent** DSH (DeepSeek Harness) Web UI plugin that puts a live consumption badge
 next to every assistant message, and opens a detail panel with the session's spend curve.
+The UI is **bilingual**: it follows the shell language (Chinese or English) and switches live.
 
 ```
-⛽ 25.6k | ≈¥0.020 | valley
+⛽ 25.6k | ≈¥0.020 | Off-peak
 ```
 
 - **Collapsed pill** – session-cumulative tokens, estimated cost (always prefixed `≈`), and the
-  current peak/valley tier (red `peak`, green `valley`), injected into
+  current peak/off-peak tier (red `Peak`, green `Off-peak`), injected into
   `conversation.chat.assistant-actions` right after the shipped copy/branch controls.
 - **Detail modal** (centered, blurred backdrop, `Esc` or backdrop-click to close):
   cumulative tokens with hit/miss/output split, estimated cost, current pricing tier,
   DeepSeek account balance, and a **per-turn dual-axis line chart**
   (left axis: tokens, right axis: ¥) with a hover tooltip showing the model,
-  input-hit / input-miss / output tokens, and the turn's peak/valley flag.
+  input-hit / input-miss / output tokens, and the turn's peak/off-peak flag.
+- **Settings page · Usage** (`settings.section`, id `balance-dsh-consumption`, order 26):
+  a top row of four cards — **Total tokens** (with hit/miss/output split, all-history totals),
+  **Estimated cost**, **Current window** (peak/off-peak) and **Account balance** (reusing the
+  badge's cached balance) — then **all-session history** as one line chart, filterable by time range
+  (Today / Last 7 days / Last 30 days / Last 12 months), by workspace
+  (All workspaces + every registered workspace + Unassigned), and by an explicit
+  calendar range that overrides the dropdown. Bucket size follows the range:
+  **hourly for today and any single-day calendar range**, daily for multi-day ranges, and
+  monthly for the last 12 months. Left axis (tokens) is hidden until you
+  toggle it in the legend; the right axis (¥) is always on. Hovering a point shows its
+  total, its peak/off-peak split and the models involved; the footer sums the current
+  selection. No data in range → a plain "No usage recorded in this range" note instead of an
+  empty chart. The cards are **all-history** totals (independent of the filters); the footer is the
+  filtered total, so the two numbers differ by design.
+- **Personalization integration** (auto-detected, no configuration): when
+  [`dsh-plugin-personalization`](https://www.npmjs.com/package/dsh-plugin-personalization) is
+  installed alongside this plugin, a **Usage popup** block is appended to its settings page —
+  same `pp-block` / `pp-field` / `pp-modes` layout and the same `Pill` primitive as the shipped
+  personalization rows — offering four backgrounds for the consumption modal:
+  **Default / Glass / Custom image / Solid color**.
+  - **Default** keeps the themed surface; **Glass** is real `backdrop-filter` glass — both the veil
+    behind the modal and the panel itself are theme-derived (`--dsw-alias-bg-base`), so light themes
+    get a light haze and dark themes a dark one instead of the panel painting a dark slab over the
+    page; **Custom image** takes an image URL *or* a local image plus an **Opacity** slider
+    (0–100 %, default 85 %) that sets the background layer's own `opacity` — the same semantic as the
+    other personalization background rows, so lowering it fades the image over the themed panel
+    instead of dimming it; **Solid color** takes a hex colour and derives a light/dark ink palette so
+    the cards, chart and tooltips stay readable (the palette also overrides the tooltip surface).
+  - A **Glass** switch appears for Custom image and Solid color, so glass composites with them:
+    on an image it blurs the image itself (frosted photo), on a solid it makes the colour
+    translucent over a blurred page. A **Glass strength** slider (0–48 px, default 22 px) sets the
+    blur radius of the panel. The overlay behind the modal is deliberately never blurred.
+  - **Clear** wipes the image, the URL field and the file picker in one go. The image row shows a
+    **thumbnail** plus the live save state (Saving… / Saved on this device / `error: …`), and
+    failures are logged with a `[consumption-badge]` tag instead of failing silently. The picker is a
+    button (Choose image… / Change image…), not a raw file input, so saving never leaves a
+    misleading "no file chosen" label behind.
+  - Local images are **stored on this machine with no size limit**: the picked file is written as a
+    Blob into IndexedDB (`dsh-consumption-assets` → `images`), and the preference only keeps a small
+    key — so a 20 MB wallpaper no longer blows the `localStorage` quota. On startup the blob is read
+    back into a `blob:` URL for the modal; **Clear** deletes the stored record as well.
+    If IndexedDB is unavailable the file is read as a data URL instead, and the row says so.
+  - The choice is a local preference (`dsh-consumption:modal-style`) and is applied to the open
+    modal immediately. Nothing about the conversation or sidebar backgrounds is touched.
+- **Update notice** (same shape as `dsh-plugin-personalization`'s): ~2.5 s after the page loads the
+  plugin asks `https://registry.npmjs.org/dsh-consumption-badge/latest` for the newest version
+  (24 h cache, 5 s timeout, fails silently). If the installed version is older — and that version
+  was not ignored — a non-blocking card appears in the bottom-right corner with
+  **current → latest**, the exact `dsh plugin --profile web update dsh-consumption-badge` command,
+  and three actions: **Copy update command**, **Ignore this version** (remembered on this machine)
+  and **Remind me later** (this page load only). It never blocks the conversation and never covers
+  controls.
 
 Everything is an **estimate** for reference only — this plugin is not a billing system of record.
 
+## Localization
+
+The plugin ships **Chinese and English** copy and follows the DSH shell language live — no reload,
+no second settings page.
+
+| Aspect | How it works |
+| --- | --- |
+| Source of truth | The client-side `locale` service (`@deepseek-ai/dsh-client-locale`, `ctx.get('locale')`) |
+| Dictionary | `DICT_EN` in `lib/client.js`, keyed by the **Chinese copy itself**; under `zh` no dictionary is needed because the key is the text, and any key missing from `DICT_EN` falls back to that Chinese text (never a blank string) |
+| Live switching | Slot outlets re-render on a locale switch (the shell subscribes to the locale revision), so `tt()` picks up the new language during the next render; the personalization page block renders in its own React root and subscribes to the locale face itself |
+| Slot labels | The action-row label and the settings tab title are **thunks**, resolved by the slot system at read time, so the tab renames itself on a switch |
+| Late service | If the `locale` service is provided after this plugin's `apply()` ran (boot order differs per composition), the first render retries the bind |
+| Missing service | Without the locale service everything falls back to Chinese — the plugin still works standalone |
+| Host errors | `lib/index.js` never returns localized prose: failures carry a language-neutral `code` + `detail` (and an English `error` for logs). The client maps `code` → copy in the active language, and prints the host's `error` only for an unknown code |
+
+Adding a language means adding one dictionary next to `DICT_EN`; the lookup order is
+*active locale → key*, so untranslated keys degrade to Chinese rather than breaking.
+
 ## Requirements
 
 | Capability | Why |
@@ -73,7 +144,7 @@ deployments where the bundle layer does mount. Keep only **one** of the two acti
 | Data | Source |
 | --- | --- |
 | Per-turn tokens | `assistant/message.usage` events in the session log, folded per turn (`cacheReadTokens` → hit, `inputTokens + cacheWriteTokens` → miss, `outputTokens` → output; multi-step turns are summed) |
-| Turn timing | `turn/start` event time (peak/valley is attributed to **request start**) |
+| Turn timing | `turn/start` event time (peak/off-peak is attributed to **request start**) |
 | Model per turn | `request/context` / `request/header.config`; falls back to the agent default model, then `deepseek-flash` |
 | Session totals | the shipped `tokenUsage` projection when present, otherwise the folded turns |
 | Balance | `GET https://api.deepseek.com/user/balance` via curl, 60s cache |
@@ -82,6 +153,14 @@ Turn records are also mirrored into browser `localStorage` under
 `dsh-consumption:<sessionId>:<turn>` so the chart survives reloads. Persistence writes are
 scheduled off the render path (`requestIdleCallback`), and the aggregation is O(turns).
 
+The settings page reads **those same records** (no second store, no new field): workspace
+attribution is resolved at read time from DSH's own accounting ledger
+(`WorkspaceView.sessionIds` from `useWorkspaces`), so historical records are attributed without
+any backfill. Records whose session no longer exists land in the **Unassigned** bucket.
+Above 5000 records the aggregation runs in a Web Worker (built from the pure aggregator's own
+source, so both paths are the same code); if the browser refuses the Worker it silently falls
+back to the main thread, where 6000 records aggregate in ~6 ms.
+
 ## Pricing model
 
 Off-peak prices in **CNY per 1M tokens**; peak multiplies everything by **2**.
@@ -96,7 +175,7 @@ cost = (hit/1e6)*hit_price + (miss/1e6)*miss_price + (out/1e6)*out_price   [×2
 ```
 
 **Peak** = Beijing time (UTC+8), Monday–Friday, 09:00–12:00 and 14:00–18:00, excluding statutory
-holidays. Everything else, plus weekends, is **valley**.
+holidays. Everything else, plus weekends, is **off-peak**.
 
 Unrecognised model ids are priced as `deepseek-flash` (or `deepseek-v4-pro` when the id contains
 `pro`) and the UI marks the figure as an estimate. The table lives in `PRICES` at the top of
@@ -114,7 +193,12 @@ The host half registers three exact, read-only routes on the DSH web server:
 | --- | --- |
 | `GET /api/consumption/turns?sessionId=<id>` | per-turn `{turn, hit, miss, out, time, model}` (log-length cached) |
 | `GET /api/consumption/account` | current provider/model + whether the key is configured |
-| `GET /api/consumption/balance[?force=1]` | `{ok, available, currency, total, granted, toppedUp}`; `is_available:false` renders a red “insufficient balance” |
+| `GET /api/consumption/balance[?force=1]` | `{ok, available, currency, total, granted, toppedUp}`; `is_available:false` renders a red "insufficient balance" |
+
+Failures are `{ok:false, code, detail, error}`: `code` is language-neutral
+(`no-credentials`, `no-key`, `key-read-failed`, `no-subprocess`, `curl-empty`, `spawn-failed`,
+`bad-response`, `balance-request-failed`, `missing-session-id`, `log-unavailable`), `detail` is raw
+text, `error` is an English fallback for logs.
 
 These routes are **unauthenticated**. If your DSH web server binds `0.0.0.0`, anyone on the
 network can read the balance and token figures; keep it on `127.0.0.1` unless you need otherwise.
@@ -138,10 +222,20 @@ Install the DSH plugin "dsh-consumption-badge" into my web profile and prove it
    `{"ok":true,...}`. Verify the client half:
    `curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:<port>/plugins/dsh-consumption-badge/client.js`
    must return `200`.
-5. Open any session and confirm the `⛽ <tokens> | ≈¥<cost> | peak|valley` pill in the assistant
+5. Open any session and confirm the `⛽ <tokens> | ≈¥<cost> | Peak|Off-peak` pill in the assistant
    action row; click it and confirm the modal shows the four cards, the dual-axis chart, the
    balance, and that Esc closes it.
-6. Report which step failed and paste the boot log lines that mention `consumption-badge`.
+6. Keep Settings → Usage open, then switch the shell language between Chinese and English
+   (Settings → General → Language) and confirm every visible string in the badge, the modal, the
+   settings page and the personalization block switches without a reload.
+7. On the Usage page switch the time range (Today / Last 7 days / Last 30 days / Last 12 months),
+   switch the workspace (All workspaces → a specific workspace → Unassigned), set the calendar range
+   and confirm both the chart and the footer totals update, and that the Token axis only appears
+   after clicking its legend chip.
+8. If `dsh-plugin-personalization` is installed, open Settings → Personalization and confirm a
+   Usage popup block appears at the bottom; switch it to Glass / Solid color / Custom image and
+   confirm the ⛽ modal (click a badge) re-renders with that background.
+9. Report which step failed and paste the boot log lines that mention `consumption-badge`.
 
 Rules while doing this: never write to the DSH credentials file yourself (ask me for
 DEEPSEEK_API_KEY), never bind a second server to the same port, and do not try to persist the
@@ -158,12 +252,16 @@ plugin by "running" it — a session-scoped dynamic plugin always dies with the
   `require("react")` — React must stay external (a second React instance breaks slot rendering).
 - `lib/index.js` imports nothing at all (no `@deepseek-ai/cordis`), so it does not depend on the
   profile being able to resolve Cordis; it exports plain `name` / `inject` / `apply`.
-- Self-check without booting DSH: `node check.mjs` (46 assertions over the route contract and the
-  client bundle contract). It lives outside the published `files` list.
+- Do not hard-code user-visible English or Chinese in new JSX: call `tt('…')` with the Chinese copy
+  as the key and add the English entry to `DICT_EN`. `check.mjs` fails if any `tt()` key has no
+  English translation or if a translation still contains Chinese.
+- Self-check without booting DSH: `node check.mjs` (224 assertions over the route contract, the
+  client bundle contract, the pricing/aggregation maths and the bilingual copy). It lives outside
+  the published `files` list.
 
 ## Known limitations
 
-- All amounts are **estimates** — price table, peak/valley rules and model detection can drift
+- All amounts are **estimates** — price table, peak/off-peak rules and model detection can drift
   from your actual invoice.
 - One chart point per turn; multiple steps in a turn are summed.
 - Balance parsing depends on DeepSeek's `/user/balance` response shape; failures only affect the
@@ -171,6 +269,7 @@ plugin by "running" it — a session-scoped dynamic plugin always dies with the
 - The chart covers turns present in the session log fold (whole log), while the pill's total uses
   the shipped `tokenUsage` projection — both are whole-session, but a heavily-compacted session may
   differ by the tokens lost to compaction.
+- Only `zh` and `en` are shipped; any other shell locale falls back to `zh` (the dictionary keys).
 
 ## License