dsh-consumption-badge 1.2.2 → 1.3.2

package/README.md

@@ -2,15 +2,169 @@
 
 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.
+The UI is **bilingual** (follows the shell language, switches live), costs are estimated for
+**33 model entries across 10 providers**, amounts can be shown in **any of 17 major
+currencies**, and one dropdown picks the **model** you want to look at. All of it lives in
+Settings → Usage.
 
 ```
-⛽ 25.6k | ≈¥0.020 | Off-peak
+⛽ 3.2k | ≈¥0.004 | Off-peak | Balance = ¥42.50
 ```
 
-- **Collapsed pill** – session-cumulative tokens, estimated cost (always prefixed `≈`), and the
-  current peak/off-peak tier (red `Peak`, green `Off-peak`), injected into
+- **Collapsed pill** – **that assistant message's own** token count, its **own** estimated cost
+  (always prefixed `≈`), its pricing tier (red `Peak`, green `Off-peak`, attributed to the turn's
+  request start), and the DeepSeek **account balance**; injected into
   `conversation.chat.assistant-actions` right after the shipped copy/branch controls.
+  The two numbers are **this turn's, not the session's**: the slot renders once per turn
+  (`TurnTailNodeView`) and hands the badge that turn's final `messageId`; the host answers with a
+  `messageId → message` map (which carries the turn number) next to the per-turn fold, and the badge
+  renders that turn's folded total. Mapping is resolved in two steps so the pill is right even
+  before the host half is restarted: the host map first, then the `data-turn-tail` attribute the
+  shipped conversation view puts on the turn wrapper. If neither resolves (or the turn has no record
+  yet) the pill falls back to the session-wide figures instead of showing a false zero, and its
+  tooltip names the scope being shown. The balance segment renders `Balance = ¥42.50` when the
+  account API answers, `…` while loading and `—` on failure (the reason rides the tooltip); balance
+  uses the same 60 s cache as the modal, refreshed once a minute. The modal itself still shows the
+  whole session, unchanged.
+- **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, a **model dropdown** in the title bar, and a **per-turn dual-axis line
+  chart** (left axis: tokens, right axis: money) where **each model gets its own colored line** and
+  the legend names them; the hover tooltip shows the model (with its color dot), input-hit /
+  input-miss / output tokens, the turn's cost and its peak/off-peak flag. Picking a model filters the
+  cards + chart to that model and turns the balance hint into "about N tokens left at these prices".
+- **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.
+
+## Models and pricing
+
+Costs are estimated from a **flat price table of 31 model entries** (current generations first,
+legacy entries last so old logs still resolve). Unknown ids fall back to a family guess
+(`pro`/`opus`/`max` → the stronger tier, everything else → DeepSeek V3) and are marked as estimates.
+
+| Provider | Current | Legacy (kept for old logs) |
+| --- | --- | --- |
+| DeepSeek | `deepseek-flash` = **DeepSeek-V4.1-Flash-1017**, `deepseek-v4-pro` = **DeepSeek-V4-Pro-0813** (official ids/versions) | DeepSeek V3.2 |
+| OpenAI | GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, o3 | GPT-4o, GPT-4o mini |
+| Anthropic | Claude Opus 5.5, Sonnet 5.5, Haiku 5.5 | Claude Sonnet 4.6, Opus 4.x |
+| Google | Gemini 3.8 Flash, Gemini 3.1 Pro, Gemini 3 Flash | Gemini 2.5 Flash |
+| Alibaba | Qwen3.8 Max, Qwen3.8 Flash | Qwen3.7 Plus |
+| Zhipu | GLM-5.3, GLM-5.1 | GLM-4.6 |
+| Moonshot | Kimi K3.1 Pro, Kimi K3 | Kimi K2.5 |
+| xAI | Grok 4.7 | Grok 4.3 |
+| Meta | Llama 4 Maverick | — |
+| Mistral | Mistral Large 4 | — |
+
+Rules that follow from the table:
+
+- **Every turn is priced with the model it actually used** — a session that mixed models is not
+  priced with a single rate. Sessions, buckets and charts all keep the per-model split.
+- **Only DeepSeek has peak/off-peak pricing** (×2 in the Beijing-time peak windows). Other vendors
+  are flat; their card hint says so.
+- **Prices are CNY per 1M tokens.** Non-DeepSeek entries are the vendor's USD list price × 7.1
+  (input-cache-read / input / output), taken from OpenRouter's public model catalogue; the two
+  harness-native DeepSeek rows keep DeepSeek's official CNY table. Edit `MODELS` at the top of
+  `lib/client.js` — each entry carries `price {hit, miss, out}`, `peakPricing`, `legacy` and a chart
+  `color`.
+- **Model ids are resolved transparently.** `deepseek-flash` is the id DeepSeek's API currently
+  routes to **DeepSeek-V4.1-Flash-1017** and `deepseek-v4-pro` to **DeepSeek-V4-Pro-0813** (per
+  `api-docs.deepseek.com`), and deprecated ids (`deepseek-v4-flash*`, `deepseek-chat`) route to the
+  same families. Every model label in the UI can therefore be checked against the log: the settings
+  cost card, the modal cost card, the legend tooltip and the per-turn tooltip all print
+  `Family name (Official MODEL VERSION · log id <id>)`, so a mismatch is visible instead of hidden.
+- The **Model** dropdown (panel title bar *and* Settings → Usage, sharing one preference stored in
+  `localStorage: dsh-consumption:model-filter`) lists models **grouped by provider** in
+  `<optgroup>`s; it filters the statistics **and** acts as the pricing fallback for turns whose log
+  entry carries no model. `All models` turns both behaviours off.
+- Charts draw **one line per model** in that model's color (33 distinct colors), with a legend of
+  model chips; the token axis stays a single dashed neutral line.
+
+## Currency
+
+The price table is always **CNY per 1M tokens** (that is what DeepSeek bills in); the currency
+setting only decides how amounts are *displayed*. Pick it in **Settings → Usage → Currency**:
+
+| Aspect | Behavior |
+| --- | --- |
+| Currencies | CNY (default) plus USD, EUR, GBP, JPY, HKD, TWD, KRW, SGD, AUD, CAD, CHF, INR, RUB, BRL, THB, MXN |
+| What converts | every amount in the plugin: pill (`≈# dsh-consumption-badge
+
+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** (follows the shell language, switches live) and amounts can be shown in
+**any of 17 major currencies** — pick one in Settings → Usage.
+
+```
+⛽ 3.2k | ≈¥0.004 | Off-peak | Balance = ¥42.50
+```
+
+- **Collapsed pill** – **that assistant message's own** token count, its **own** estimated cost
+  (always prefixed `≈`), its pricing tier (red `Peak`, green `Off-peak`, attributed to the turn's
+  request start), and the DeepSeek **account balance**; injected into
+  `conversation.chat.assistant-actions` right after the shipped copy/branch controls.
+  The two numbers are **this turn's, not the session's**: the slot renders once per turn
+  (`TurnTailNodeView`) and hands the badge that turn's final `messageId`; the host answers with a
+  `messageId → message` map (which carries the turn number) next to the per-turn fold, and the badge
+  renders that turn's folded total. Mapping is resolved in two steps so the pill is right even
+  before the host half is restarted: the host map first, then the `data-turn-tail` attribute the
+  shipped conversation view puts on the turn wrapper. If neither resolves (or the turn has no record
+  yet) the pill falls back to the session-wide figures instead of showing a false zero, and its
+  tooltip names the scope being shown. The balance segment renders `Balance = ¥42.50` when the
+  account API answers, `…` while loading and `—` on failure (the reason rides the tooltip); balance
+  uses the same 60 s cache as the modal, refreshed once a minute. The modal itself still shows the
+  whole session, unchanged.
 - **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**
@@ -71,6 +225,17 @@ The UI is **bilingual**: it follows the shell language (Chinese or English) and
 
 Everything is an **estimate** for reference only — this plugin is not a billing system of record.
 
+), modal cards and both charts' right axis, the settings cards and footer totals, and the account balance (when the balance API reports CNY) |
+| Rates | 1 CNY = n target currency, cached **6 h**. Primary source `open.er-api.com`, fallback `@fawazahmed0/currency-api` via jsDelivr — fetched through the host route `/api/consumption/rates`, and **directly from the browser** when that route is unavailable (both endpoints send `access-control-allow-origin: *`) |
+| Offline | if no live rate can be fetched, a built-in fallback table is used and the settings hint says so |
+| Preference | `localStorage` key `dsh-consumption:currency`; the settings hint shows the active rate, its source and a timestamp |
+| Unchanged | the pricing table, peak/off-peak rules and every stored record stay in CNY — switching currency never rewrites data |
+
+```
+costCNY = (hit/1e6)*hit + (miss/1e6)*miss + (out/1e6)*out   [×2 at peak]
+shown   = costCNY × rate[currency]
+```
+
 ## Localization
 
 The plugin ships **Chinese and English** copy and follows the DSH shell language live — no reload,
@@ -191,8 +356,9 @@ The host half registers three exact, read-only routes on the DSH web server:
 
 | Route | Returns |
 | --- | --- |
-| `GET /api/consumption/turns?sessionId=<id>` | per-turn `{turn, hit, miss, out, time, model}` (log-length cached) |
+| `GET /api/consumption/turns?sessionId=<id>` | per-turn `{turn, hit, miss, out, time, model}` **plus** per-message `{id, turn, step, hit, miss, out, time, model}` (the `id` is the finalized message id the badge receives as `messageId`); log-length cached |
 | `GET /api/consumption/account` | current provider/model + whether the key is configured |
+| `GET /api/consumption/rates[?force=1]` | `{ok, base:"CNY", rates:{USD:…}, source, fetchedAt, stale}` — 16 curated currencies, 6 h cache; `stale:true` means the built-in fallback table |
 | `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
@@ -222,7 +388,7 @@ 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|Off-peak` pill in the assistant
+5. Open any session and confirm the `⛽ <tokens> | ≈¥<cost> | Peak|Off-peak | Balance = ¥<total>` 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. Keep Settings → Usage open, then switch the shell language between Chinese and English
@@ -255,7 +421,7 @@ plugin by "running" it — a session-scoped dynamic plugin always dies with the
 - 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
+- Self-check without booting DSH: `node check.mjs` (320 assertions over the route contract, the
   client bundle contract, the pricing/aggregation maths and the bilingual copy). It lives outside
   the published `files` list.