dsh-magpie-connector 0.5.0 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.6.2 — 2026-11-03
+
+- **Accordion instead of an overlay.** Expanding the sidebar usage card no longer covers the session list: the detail grows in flow inside the same card and the list gives up height from the bottom (the list keeps its top anchor, so rows do not jump). No divider line; the card surface and shadow carry the separation.
+- **Header-only interaction.** Only the header row toggles expand/collapse (the refresh button keeps its own action); the card body and the overflow chevron are no longer click targets — the chevron is a passive "more rows" hint.
+- **Configurable auto refresh.** New host setting `sidebarRefreshMinutes` (whole minutes, default `5`, `0` = off, range `0–1440`, non-integers/out-of-range rejected with 400) and a matching "Auto refresh" field in Settings → Magpie → Sidebar usage. The card re-reads silently on that interval, paused while the page is hidden and resumed on visibility; it never sends `POST {all:true}`. With `0` the previous event-driven behaviour (mount, manual refresh, expand, page visible) is unchanged.
+- **README screenshots.** New sidebar usage card screenshot (`usage.png` / `usage.en.png`) and refreshed Settings screenshots showing the sidebar panel with auto refresh; registered in `docs/SCREENSHOTS.md`.
+
+## 0.6.1 — 2026-11-03
+
+- **重置卡改成和 subscriptions 插件一样的折叠列表。** host 现在把网关 `resets.each[]`（每项只保留 `until`/`window`）与 `resets.byWindow`/`fiveHour`/`weekly` 投影给浏览器；卡片上用「用量限制重置 · 可用 N 次」做摘要行，展开后逐张列出「完整重置」/「5 小时」/「每周」和每张的「{时间} 到期」，最早到期那张附相对提示（`N 天后过期` / 不足 24 小时 `N 小时后过期` / 已过期），缺到期时间显示「到期时间不可用」。按窗口发放重置的计划（GLM Coding）摘要显示「5 小时 N 次 · 每周 M 次」。
+- 仍然只读：没有新增按钮，也不调用任何重置端点；网关不给 `each`/`byWindow` 时退回原来的「次数 + `until`」显示。
+- Codex 卡片只显示一个 `7 days` 窗口是网关数据如此：ChatGPT 的 `/wham/usage` 对当前账号只上报周窗口，插件不会补造 5 小时窗口。
+- 规范：`openspec/changes/magpie-reset-card-detail/`。
+
+## 0.6.0 — 2026-11-03
+
+- **Sidebar usage card.** Settings → Magpie gains a 「侧边栏额度 / Sidebar usage」 switch (host setting `sidebarUsage`, default off). When on, the sidebar footer shows a dense card above Settings: one row per upstream with its weekly (`7 days`) window, reading and bar; at most five rows, the rest scroll inside the card, and a double chevron (no divider) appears when more exist. Rows keep the gateway's order, a card with an error shows 「读取失败」 instead of a reading, and the whole card has a single refresh (`{all:true}`).
+- **Expands in place.** Clicking the card grows it upward in place: every upstream with every window, reset time, reset chances, balance and the redacted error. The resident card keeps its flow slot, so the session list keeps its height; the expanded layer is an overlay with the same shadow as the resident card, not a layout change. The title row carries one chevron that both expands and collapses.
+- **Balance-only accounts.** An upstream with no quota windows but a gateway-reported balance shows that balance (for example `¥42.50`) instead of a bare dash.
+- **Collapsed sidebar.** With the sidebar in rail mode only a Magpie icon remains (tooltip 「Magpie 额度」); clicking it opens the same content as a 320px anchored popover.
+- **Event-driven reads.** The card reuses `GET /api/dsh-magpie-connector/cards` with a 60s client cache and reads only on mount, manual refresh, expanding, or the page becoming visible again; no timer polling. The settings page is unchanged and keeps per-card refresh.
+- No host request/route changes; the only host addition is the persisted `sidebarUsage` flag.
+
+## 0.5.1 — 2026-11-02
+
+- README 中英首屏改用 deviceScaleFactor 3 的静态 PNG（3300x1920 / 2400x2400），替换旧的低分辨率图与 GIF；同时改为 markdown 图片写法，商店详情页可直接渲染。
+- 仅文档与图片调整，无代码/行为变更。
+
 ## 0.5.0 — 2026-10-31
 
 - 设置页与速度选择器支持界面语言：新增 `settings.magpie` 的 zh/en 字典（`src/client/locales.ts`），通过 `ctx.locale` 注册并在 `apply()` 绑定；文案不再硬编码中文，跟随 DSH 界面语言（英文界面下为英文）。未绑定翻译器时（单测、无 locale 服务的宿主）仍回退到中文，行为不变。

package/README.md

@@ -2,12 +2,13 @@
 
 English · [简体中文](README.zh.md)
 
-<p align="center">
-  <img src="docs/model-picker.png" alt="Model picker grouped by upstream provider: Magpie (Claude), Magpie (GPT), Magpie (deepseek)" width="49%">
-  <img src="docs/settings.png" alt="Settings: the connection line on top, then models grouped by provider with visibility, default effort and usage cards" width="49%">
-</p>
+![Model picker grouped by upstream provider: Magpie (Claude), Magpie (Codex) and Magpie (Deepseek)](docs/model-picker.en.png)
 
-*Left: model picker grouped by upstream provider. Right: Settings → Magpie — the connection line, then per-provider model visibility, default effort and usage cards. Captured from an isolated DSH host with a local mock Magpie gateway; models and accounts are synthetic.*
+![Settings: the connection line on top, then models grouped by provider with visibility, default effort and usage cards](docs/settings.en.png)
+
+![Sidebar usage card: one weekly row per upstream with readings and bars](docs/usage.en.png)
+
+*Top: model picker grouped by upstream provider. Middle: Settings → Magpie — the connection line, the sidebar usage panel (toggle plus auto-refresh interval in minutes) and per-provider model visibility, default effort and usage cards. Bottom: the resident sidebar usage card (click its header to expand every window). Captured from an isolated DSH host (English UI) with a local mock Magpie gateway; gateway address, models, account and readings are synthetic.*
 
 ![Magpie connector architecture: Web GUI and Host plugin, credentials and settings, Magpie gateway and upstream providers, optionally through Cloudflare Access](docs/architecture.en.svg)
 
@@ -24,7 +25,9 @@ English · [简体中文](README.zh.md)
 | **Grouped by upstream provider** (signature) | Works on stock DSH, no Host extension needed: the plugin registers one real provider route per gateway `owned_by` (`dsh-magpie-connector-claude`, `-codex`, `-opencode-go`, …; missing or invalid ownership goes to `-other`), so the official model picker shows `Magpie (Claude)`, `Magpie (Codex)`, `Magpie (Opencode-go)`, `Magpie (Other)` groups. Settings and usage cards use the same grouping, and a provider that only appears in usage is never dropped. |
 | **Line panel and latency** | Configured lines start collapsed; click a row header to edit it, and reorder/delete are always-visible DSH product-icon buttons with tooltips. Opening Settings measures every saved line with a parseable address once (parallel TCP connect time, ≤600ms per line, no HTTP, no credentials) and shows a 4-bar signal plus milliseconds; timeouts show a timeout reading and failures or older hosts degrade to a dash. Display-only: it never affects automatic line selection, is not persisted, and never polls. |
 | **Per-line Cloudflare Access** | Each line independently chooses Direct or Cloudflare Access. Access-enabled line requests carry the service token pair plus the bearer key; the token is never sent to a plain-HTTP line. |
+| **Read-only usage cards** | Each upstream account shows plan, expiry, window readings and, when the gateway provides them, its Codex reset credits: a folded `Usage limit resets · N available` line that expands to each credit with its expiry and how far off the soonest is (`expires in N days`); plans that hand out one kind per window show `2 five-hour · 1 weekly` in the summary instead. Cards are read once when settings open and only re-read when you press **Refresh** on that card; bars turn orange above 70% and red at 90%. |
 | **Read-only usage cards** | Each upstream account shows plan, expiry, window readings and Codex reset credits when the gateway provides them. Cards are read once when settings open and only re-read when you press **Refresh** on that card; bars turn orange above 70% and red at 90%. |
+| **Sidebar usage card** (0.6.0) | Settings → Magpie has a 「Sidebar usage」 switch (host setting, default off) and an auto-refresh interval (minutes, `0` = off, default 5). When on, a dense card sits above Settings: one weekly (`7 days`) row per upstream with its reading and bar, at most five rows with the rest scrolling inside and a overflow chevron when more exist, and one refresh for the whole card. Clicking the header row toggles an in-flow detail list (every window, reset time/chances, balance, error) that shrinks the session list instead of covering it; in rail mode a single Magpie icon opens the same content as a 320px popover. Reads reuse the existing usage endpoint with a 60s cache; only the configured interval polls, silently and paused while the page is hidden. |
 | **Model visibility and default effort** | Per provider, leave visibility untouched to follow the gateway catalog, or save an explicit allowlist so new models stay hidden. Per model, save a default reasoning effort; DSH applies it on the next request. |
 | **Per-session fast mode** | Models advertising the `priority` service tier get a standard/fast switch next to the composer. The choice is per session and in host memory only; it adds `service_tier: "priority"` to requests. |
 

package/README.zh.md

@@ -2,12 +2,11 @@
 
 [English](README.md) · 简体中文
 
-<p align="center">
-  <img src="docs/model-picker.png" alt="模型选择器：按上游 provider 分组为 Magpie (Claude)、Magpie (GPT)、Magpie (deepseek)" width="49%">
-  <img src="docs/settings.png" alt="设置页：顶部连接线路，下方按 provider 分组的模型可见性、默认 effort 与用量卡片" width="49%">
-</p>
+![模型选择器：按上游 provider 分组为 Magpie (Claude)、Magpie (Codex)、Magpie (Deepseek)](docs/model-picker.png)
 
-*左：按上游 provider 分组的模型选择器；右：设置 → Magpie，顶部连接线路，下方按 provider 分组的模型可见性、默认 effort 与用量卡片。截图来自隔离 DSH 宿主与本地 mock Magpie 网关，模型和账号均为演示数据。*
+![设置页：顶部连接线路，下方按 provider 分组的模型可见性、默认 effort 与用量卡片](docs/settings.png)
+
+*上：按上游 provider 分组的模型选择器；下：设置 → Magpie，顶部连接线路，下方按 provider 分组的模型可见性、默认 effort 与用量卡片。截自隔离 DSH 宿主与本地 mock Magpie 网关，网关地址、模型和账号均为演示数据。*
 
 ![Magpie connector 架构：Web GUI 与 Host 插件、凭据与设置、Magpie 网关与上游 provider，可选经 Cloudflare Access](docs/architecture.zh.svg)
 
@@ -24,7 +23,9 @@
 | **按上游 provider 分组**（特色） | 原版 DSH 即可使用，无需 Host 扩展：插件按网关 `owned_by` 为每个归属注册一个真实 provider route（`dsh-magpie-connector-claude`、`-codex`、`-opencode-go` 等；缺失或不合法归入 `-other`），官方模型选择器因此显示 `Magpie (Claude)`、`Magpie (Codex)`、`Magpie (Opencode-go)`、`Magpie (Other)` 分组。设置页和用量卡片使用同一套分组，只出现在用量里的 provider 也不会被丢弃。 |
 | **线路面板与延迟** | 已配置的线路默认全部收起，点行头部展开编辑；上移 / 下移 / 删除是常驻的 DSH 产品图标按钮（带 tooltip）。打开设置页对每条已保存且地址可解析的线路做一次 TCP 建连测速（并行、单条 ≤600ms、不发 HTTP、不带凭据），用 4 格信号条 + 毫秒显示；超时显示「超时」，旧版宿主或失败显示「—」。只展示当时的网络质量，不参与自动选线、不持久化、不轮询。 |
 | **按线路的 Cloudflare Access** | 每条线路可单独选择「直连」或「Cloudflare Access」。启用后该线路的请求带上服务令牌两项并保留 bearer key；服务令牌永远不会发往明文 HTTP 线路。 |
+| **只读用量卡片** | 每个上游账号展示计划、到期时间、各窗口读数和 Codex 重置卡（网关提供时）：折叠行「用量限制重置 · 可用 N 次」，展开逐张看到期时间与最早一张还剩多久（`N 天后过期`）；按窗口发放的计划摘要显示「5 小时 N 次 · 每周 M 次」。打开设置页只读一次，之后只有点单张卡片的「刷新」才会重新读取；用量条超过 70% 变橙、达到 90% 变红。 |
 | **只读用量卡片** | 每个上游账号展示计划、到期时间、各窗口读数和 Codex 重置次数（网关提供时）。打开设置页只读一次，之后只有点单张卡片的「刷新」才会重新读取；用量条超过 70% 变橙、达到 90% 变红。 |
+| **侧栏额度卡**（0.6.0） | 设置 → Magpie 新增「侧边栏额度」开关（host 持久化，默认关闭）与自动刷新间隔（分钟，`0` = 关闭，默认 5）。打开后左侧栏底部常驻一张密集卡片：每个上游一行周窗口（`7 days`）读数与进度条，最多 5 行、多出的在卡内滚动并显示溢出箭头，整张卡只有一个刷新。点标题行在手风琴里展开每个上游的全部窗口、重置时间/机会、余额与错误，占列表高度而不是盖住列表；侧栏收起时只剩一个 Magpie icon，点开是 320px 浮层。读取复用现有用量接口，客户端 60s 缓存，只有配置的间隔会静默轮询，页面隐藏时暂停。 |
 | **模型可见性与默认 effort** | 每个 provider 不设置可见性时跟随网关目录；保存过选择后只显示勾选项，新上架模型默认隐藏。每个模型可保存一个默认推理 effort，DSH 在下一次请求应用。 |
 | **会话级快速档** | 网关声明 `priority` 服务档的模型，输入框旁会出现标准/快速切换。选择按会话保存在 host 内存，快速档会给请求带上 `service_tier: "priority"`。 |
 

package/docs/SCREENSHOTS.md

@@ -1,6 +1,8 @@
 # Screenshots
 
-| file | kind | source | date | reviewer | verdict | note |
-|---|---|---|---|---|---|---|
-| model-picker.png | screenshot | frame 11 of the 2026-10-28 recording (isolated DSH_HOME instance, temp HOME/XDG/DSH_HOME under /tmp, port 3199; local mock Magpie gateway on loopback with demo models; lossless deviceScaleFactor-2 screenshots of the real Web UI, 1500x880 at 1:1), exported losslessly from the global-palette GIF | 2026-10-29 | lead | pass (reviewed frame: demo workspace and mock models only; no hostname, user, path, token or real session) | 106789 bytes; picker open with Magpie (Claude), Magpie (GPT) and Magpie (deepseek) groups; replaces model-picker.gif because the plugin store does not show GIFs by default |
-| settings.png | screenshot | isolated preview home (`git-common-dir/ws/dsh-home/<op>`, port 3202) running the 0.4.0 worktree build against a local loopback mock Magpie gateway (demo models and usage cards); headless Chrome 156 via agent-browser at 1600x1600 CSS pixels | 2026-10-30 | agent (privacy-reviewed; pending lead acceptance) | pass (reviewed: loopback/mock-only addresses 127.0.0.1 and 10.255.255.1, demo@example.com account, demo models and readings; no real hostname, user, key, path, token or session) | 137797 bytes; 0.4.0 connection section with two lines collapsed by default (fast line with 4-bar latency reading, backup line showing timeout), then the claude group with per-model default effort and its usage card with rounded bars; replaces the 0.3.1 screenshot |
+| model-picker.png | screenshot | 0.6.1 build in an isolated DSH_HOME (temp HOME/DSH_HOME under /tmp, port 3255) against a local loopback mock Magpie gateway; Chinese UI; region clip 1100x640 at deviceScaleFactor 3 | 2026-11-02 | agent (privacy-reviewed; pending lead acceptance) | pass (reviewed: Chinese UI, demo workspace, loopback gateway address, mock models only; no hostname, user, key, path or real session) | 3300x1920, 195233 bytes; model picker open with Magpie (Claude), Magpie (Codex) and Magpie (Deepseek) groups; Chinese README first image |
+| settings.png | screenshot | same 0.6.1 isolated host and mock gateway; Chinese UI; settings dialog region 800x786 at deviceScaleFactor 3 | 2026-11-03 | agent (privacy-reviewed; pending lead acceptance) | pass (reviewed: Chinese settings copy, demo@example.com account, loopback gateway address, mock models and readings; no hostname, user, key, path or real session) | 2400x2358, 353740 bytes; connection line, sidebar usage panel with auto-refresh minutes, per-provider models, default effort and the Claude usage card; Chinese README second image |
+| usage.png | screenshot | same 0.6.1 isolated host and mock gateway; Chinese UI; sidebar card region clip 256x164 at deviceScaleFactor 3 | 2026-11-03 | agent (privacy-reviewed; pending lead acceptance) | pass (reviewed: Chinese UI, mock models and readings, synthetic balance; no hostname, user, key, path or real session) | 768x492, 47436 bytes; compact resident card with 5 weekly rows, overflow chevron, balance-only DeepSeek row and an unreadable upstream; Chinese README third image |
+| model-picker.en.png | screenshot | same 0.6.1 isolated host and mock gateway; English UI; region clip 1100x640 at deviceScaleFactor 3 | 2026-11-02 | agent (privacy-reviewed; pending lead acceptance) | pass (reviewed: English UI, demo workspace, loopback gateway address, mock models only; no hostname, user, key, path or real session) | 3300x1920, 188924 bytes; English README first image |
+| settings.en.png | screenshot | same 0.6.1 isolated host and mock gateway; English UI; settings dialog region 800x786 at deviceScaleFactor 3 | 2026-11-03 | agent (privacy-reviewed; pending lead acceptance) | pass (reviewed: English settings copy, demo@example.com account, loopback gateway address, mock models and readings; no hostname, user, key, path or real session) | 2400x2358, 366280 bytes; English README second image |
+| usage.en.png | screenshot | same 0.6.1 isolated host and mock gateway; English UI; sidebar card region clip 256x161 at deviceScaleFactor 3 | 2026-11-03 | agent (privacy-reviewed; pending lead acceptance) | pass (reviewed: English UI, mock models and readings, synthetic balance; no hostname, user, key, path or real session) | 768x483, 47039 bytes; English README third image |

package/lib/client/SettingsPage.js

@@ -5,6 +5,7 @@ import { lineLatency, parseLatency } from './latency.js';
 import { settingsCss } from './styles.js';
 import { UsageCard } from './UsageCard.js';
 import { t } from './locales.js';
+import { DEFAULT_REFRESH_MINUTES, MAX_REFRESH_MINUTES, setSidebarPreference } from './sidebar-preference.js';
 import { cacheIds, cardKey, checkDiff, checkSignature, formatTime, parseCards, parseCheck, providerOrder, readTime, sameTarget, } from './view-model.js';
 /**
  * Magpie settings section: connection (with an advanced access mode), then
@@ -281,7 +282,7 @@ export function MagpieSettings({ api }) {
     const groupNote = (provider) => noteScope === provider ? { notice, alert: usageAlert } : {};
     return h('div', { className: 'dmg-settings' }, h('style', null, settingsCss), h('p', { className: 'dmg-intro' }, t('intro')), settingsError ? h('p', { className: 'dmg-error', role: 'alert' }, t('settingsReadFailed', { error: settingsError })) : null, settings ? h(Connection, { settings, saving: savingSettings, mutateSettings, api, latency, onRefreshLatency: (lineId) => { void readLatency(lineId); },
         usage: h(UsageStatus, { cards, busy, ...(noteScope === undefined ? { notice, alert: usageAlert } : {}), onFetchAll: () => { void fetchAll(); }, saving: savingSettings }) })
-        : settingsError ? null : h('p', { role: 'status', className: 'dmg-hint' }, t('readingSettings')), ...providerOrder(groups, cardList).map(provider => h(ProviderGroup, {
+        : settingsError ? null : h('p', { role: 'status', className: 'dmg-hint' }, t('readingSettings')), settings ? h(SidebarUsagePreference, { settings, saving: savingSettings, mutateSettings }) : null, ...providerOrder(groups, cardList).map(provider => h(ProviderGroup, {
         key: provider, provider,
         group: groups.find(g => g.provider === provider),
         settings,
@@ -640,3 +641,56 @@ function ModelLine({ model, visible, effort, disabled, onVisible, onEffort }) {
         value: effort ?? '', onChange: (e) => onEffort(e.target.value === '' ? null : e.target.value),
     }, h('option', { value: '' }, t('defaultEffortNone')), stale ? h('option', { value: effort, disabled: true }, t('effortStale', { effort })) : null, ...efforts.map(id => h('option', { key: id, value: id }, id))) : null);
 }
+/**
+ * The sidebar preference: one host-persisted flag. The host is the source of
+ * truth; the module store is updated so the already-mounted sidebar card
+ * follows the toggle without a reload.
+ */
+function SidebarUsagePreference({ settings, saving, mutateSettings }) {
+    const [failed, setFailed] = useState('');
+    const enabled = settings.sidebarUsage === true;
+    const savedMinutes = settings.sidebarRefreshMinutes ?? DEFAULT_REFRESH_MINUTES;
+    const [draft, setDraft] = useState(String(savedMinutes));
+    useEffect(() => { setDraft(String(savedMinutes)); }, [savedMinutes]);
+    const toggle = async () => {
+        setFailed('');
+        const next = !enabled;
+        const result = await mutateSettings({ sidebarUsage: next });
+        if (result?.error) {
+            setFailed(result.error);
+            return;
+        }
+        setSidebarPreference({ usage: result?.view === undefined ? next : result.view.sidebarUsage === true });
+    };
+    const commitMinutes = async () => {
+        setFailed('');
+        const raw = draft.trim();
+        if (!/^\d+$/.test(raw)) {
+            setDraft(String(savedMinutes));
+            return;
+        }
+        const minutes = Math.min(MAX_REFRESH_MINUTES, Number(raw));
+        if (minutes !== savedMinutes) {
+            const result = await mutateSettings({ sidebarRefreshMinutes: minutes });
+            if (result?.error) {
+                setFailed(result.error);
+                setDraft(String(savedMinutes));
+                return;
+            }
+            setSidebarPreference({ refreshMinutes: result?.view === undefined ? minutes : result.view.sidebarRefreshMinutes ?? minutes });
+        }
+        setDraft(String(minutes));
+    };
+    return h('section', { className: 'dmg-panel', 'data-sidebar-usage': '' }, h('h3', null, t('sidebarPanelTitle')), h('p', { className: 'dmg-hint' }, t('sidebarToggleHint')), h('div', { className: 'dmg-switch-row' }, h('span', null, t('sidebarToggle')), h('button', {
+        type: 'button', className: 'dmg-switch', role: 'switch', disabled: saving,
+        'aria-checked': enabled, 'aria-label': t('sidebarToggle'), 'data-sidebar-usage-switch': '',
+        onClick: () => { void toggle(); },
+    }, h('i', null))), h('div', { className: 'dmg-refresh-row' }, h('span', null, t('sidebarRefreshLabel')), h('span', { className: 'dmg-refresh-control' }, h('input', {
+        type: 'number', className: 'dmg-refresh-input', min: 0, max: MAX_REFRESH_MINUTES, step: 1,
+        value: draft, disabled: saving, 'data-sidebar-refresh': '', 'aria-label': t('sidebarRefreshLabel'),
+        onChange: (event) => setDraft(event.target.value),
+        onBlur: () => { void commitMinutes(); },
+        onKeyDown: (event) => { if (event.key === 'Enter')
+            event.currentTarget.blur(); },
+    }), h('span', { className: 'dmg-refresh-unit' }, t('sidebarRefreshUnit')))), h('p', { className: 'dmg-hint' }, t('sidebarRefreshHint')), failed ? h('p', { className: 'dmg-error', role: 'alert' }, failed) : null);
+}

package/lib/client/SidebarUsage.d.ts

@@ -0,0 +1,22 @@
+import { type Api } from './api.js';
+/**
+ * Sidebar usage card (`sidebar.footer.action`, owner prop `wide`).
+ *
+ * Wide sidebar: an accordion. The header row is the only interactive surface
+ * (except the refresh button): clicking it toggles the detail, which grows in
+ * flow and takes height away from the session list instead of covering it.
+ * Collapsed, it shows one weekly row per upstream (at most five) plus a
+ * decorative overflow chevron. Collapsed sidebar: one icon that opens the same
+ * content as a 320px anchored popover.
+ *
+ * Reads are event-driven through `sidebar-api` (60s TTL); no timers.
+ */
+export interface SidebarUsageProps {
+    api?: Api;
+    wide?: boolean;
+}
+export declare function SidebarUsage({ api, wide }: SidebarUsageProps): import("react").FunctionComponentElement<import("react").FragmentProps> | import("react").DetailedReactHTMLElement<{
+    className: string;
+    'data-dmg-sidebar': string;
+    'data-open': boolean;
+}, HTMLElement> | null;

package/lib/client/SidebarUsage.js

@@ -0,0 +1,283 @@
+import { createElement as h, Fragment, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { useAnchoredPosition, useDismissOnOutsidePointer } from '@deepseek-ai/dsh-client-ui-primitives';
+import { errorText } from './api.js';
+import { settingsCss } from './styles.js';
+import { t } from './locales.js';
+import { loadCards, refreshCards } from './sidebar-api.js';
+import { DEFAULT_REFRESH_MINUTES, hydrateSidebarPreference, readSidebarPreference, subscribeSidebarPreference } from './sidebar-preference.js';
+import { ageMinutes, cardIdentity, cardReadTime, formatResetShort, formatUsed, sidebarRows, unchangedReads, usedLevel, } from './sidebar-view.js';
+import { formatTime } from './view-model.js';
+const MAX_ROWS = 5;
+const RAIL_POPOVER_WIDTH = 320;
+export function SidebarUsage({ api, wide = true }) {
+    const [preference, setPreference] = useState(() => readSidebarPreference());
+    const [view, setView] = useState(undefined);
+    const [open, setOpen] = useState(false);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState('');
+    const [notice, setNotice] = useState('');
+    const anchorRef = useRef(null);
+    const bodyRef = useRef(null);
+    const [bodyMax, setBodyMax] = useState(undefined);
+    const panelRef = useRef(null);
+    const viewRef = useRef(undefined);
+    viewRef.current = view;
+    // Follow the host preference (hydrated once per page, then kept live by the
+    // settings toggle through the module store).
+    useEffect(() => {
+        const unsubscribe = subscribeSidebarPreference(value => setPreference(value));
+        void hydrateSidebarPreference(api).then(() => setPreference(readSidebarPreference()));
+        return unsubscribe;
+    }, [api]);
+    const enabled = preference?.usage;
+    const refreshMinutes = preference?.refreshMinutes ?? DEFAULT_REFRESH_MINUTES;
+    useEffect(() => {
+        if (enabled !== true || api === undefined)
+            return;
+        let alive = true;
+        void loadCards(api).then(next => { if (alive)
+            setView(next); }, reason => { if (alive)
+            setError(errorText(reason)); });
+        return () => { alive = false; };
+    }, [enabled, api]);
+    // Show exactly MAX_ROWS rows: measure the fifth row's bottom instead of
+    // assuming a per-row height (host font metrics and rows without a bar differ).
+    useLayoutEffect(() => {
+        const element = bodyRef.current;
+        if (element === null || typeof ResizeObserver === 'undefined')
+            return;
+        const measure = () => {
+            const fifth = element.children[MAX_ROWS - 1];
+            if (element.children.length <= MAX_ROWS || !(fifth instanceof HTMLElement)) {
+                setBodyMax(undefined);
+                return;
+            }
+            const height = Math.round(fifth.getBoundingClientRect().bottom - element.getBoundingClientRect().top);
+            if (height > 0)
+                setBodyMax(height);
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        for (const child of Array.from(element.children))
+            if (child instanceof HTMLElement)
+                observer.observe(child);
+        return () => observer.disconnect();
+    }, [enabled, open, view]);
+    // Returning to the page re-reads once (the 60s TTL suppresses it otherwise).
+    useEffect(() => {
+        if (enabled !== true || api === undefined)
+            return;
+        const onVisibilityChange = () => {
+            if (document.visibilityState !== 'visible')
+                return;
+            void loadCards(api).then(setView, () => { });
+        };
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        return () => document.removeEventListener('visibilitychange', onVisibilityChange);
+    }, [enabled, api]);
+    // Auto refresh: only when the card is enabled and the interval is positive.
+    // A chained timeout avoids overlap; a hidden page only reschedules (the
+    // visibility listener above still re-reads once the page returns).
+    useEffect(() => {
+        if (enabled !== true || api === undefined || refreshMinutes <= 0)
+            return;
+        let timer;
+        let stopped = false;
+        const interval = refreshMinutes * 60_000;
+        const read = () => { void loadCards(api, { force: true }).then(setView, () => { }); };
+        const schedule = () => {
+            timer = setTimeout(() => {
+                if (stopped)
+                    return;
+                if (document.visibilityState === 'visible')
+                    read();
+                schedule();
+            }, interval);
+        };
+        schedule();
+        return () => { stopped = true; if (timer !== undefined)
+            clearTimeout(timer); };
+    }, [enabled, api, refreshMinutes]);
+    const railOpen = open && !wide;
+    const pos = useAnchoredPosition({ open: railOpen, anchorRef, panelRef, side: 'top', align: 'start', gap: 8, margin: 12 });
+    useDismissOnOutsidePointer(anchorRef, railOpen, setOpen, panelRef);
+    useEffect(() => {
+        if (!open)
+            return;
+        const onKeyDown = (event) => { if (event.key === 'Escape')
+            setOpen(false); };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    }, [open]);
+    const refresh = async () => {
+        if (api === undefined || busy)
+            return;
+        setBusy(true);
+        setError('');
+        setNotice('');
+        try {
+            const result = await refreshCards(api);
+            if (!result.ok) {
+                setError(result.error);
+                return;
+            }
+            const previous = viewRef.current?.cards ?? [];
+            setView(result.view);
+            setNotice(unchangedReads(previous, result.view.cards) ? t('notReread') : '');
+        }
+        catch (reason) {
+            setError(errorText(reason));
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    const expand = () => {
+        setOpen(true);
+        if (api === undefined)
+            return;
+        void loadCards(api).then(setView, () => { });
+    };
+    const collapse = () => { setOpen(false); setNotice(''); };
+    const toggle = () => { if (open)
+        collapse();
+    else
+        expand(); };
+    if (enabled !== true)
+        return null;
+    const now = Date.now();
+    const cards = view?.cards ?? [];
+    const rows = sidebarRows(cards);
+    const latest = cards.map(cardReadTime).filter((value) => typeof value === 'string').sort().at(-1);
+    const status = statusText(view, error);
+    const style = h('style', null, settingsCss);
+    const head = () => h('div', { className: 'dmg-sidebar-head', onClick: toggle }, h('span', { className: 'dmg-sidebar-bird', 'aria-hidden': true }), h('span', { className: 'dmg-sidebar-title' }, t('sidebarTitle')), latest === undefined ? null : h('span', { className: 'dmg-sidebar-fresh' }, ageText(latest, now)), refreshButton(refresh, busy), h('button', {
+        type: 'button', className: 'dmg-sidebar-icon', 'data-dmg-sidebar-toggle': '',
+        'aria-label': open ? t('sidebarCollapse') : t('sidebarExpand'), 'aria-expanded': open,
+        title: open ? t('sidebarCollapse') : t('sidebarExpand'),
+    }, chevron(open)));
+    if (!wide) {
+        return h(Fragment, null, style, h('button', {
+            type: 'button', className: 'dmg-sidebar-rail is-button', 'data-dmg-sidebar-rail': '',
+            ref: (node) => { anchorRef.current = node; },
+            title: t('sidebarTitle'), 'aria-label': t('sidebarTitle'), 'aria-haspopup': 'dialog', 'aria-expanded': open,
+            onClick: () => { if (open)
+                setOpen(false);
+            else
+                expand(); },
+        }, h('span', { className: 'dmg-sidebar-bird', 'aria-hidden': true })), open ? createPortal(h('div', {
+            ref: panelRef, className: 'dmg-sidebar-popover', role: 'dialog', 'aria-label': t('sidebarTitle'), 'data-dmg-sidebar-popover': '',
+            style: { ...(pos ?? { visibility: 'hidden', left: 0, top: 0 }), width: RAIL_POPOVER_WIDTH },
+        }, head(), h('div', { className: 'dmg-sidebar-rule', 'aria-hidden': true }), notice !== '' ? h('p', { className: 'dmg-sidebar-status', role: 'status' }, notice) : null, detail(cards, now, status)), document.body) : null);
+    }
+    const scrollable = rows.length > MAX_ROWS;
+    return h('div', { className: 'dmg-sidebar', 'data-dmg-sidebar': '', 'data-open': open }, style, h('div', { className: 'dmg-sidebar-card' }, head(), open
+        ? h(Fragment, null, notice !== '' ? h('p', { className: 'dmg-sidebar-status', role: 'status' }, notice) : null, h('div', { className: 'dmg-sidebar-detail', 'data-dmg-sidebar-expanded': '' }, detail(cards, now, status)))
+        : h(Fragment, null, h('div', {
+            className: `dmg-sidebar-body${scrollable ? ' is-scroll' : ''}`,
+            ref: (node) => { bodyRef.current = node; },
+            ...(bodyMax === undefined ? {} : { style: { maxHeight: bodyMax } }),
+        }, status !== undefined
+            ? h('p', { className: 'dmg-sidebar-status', role: 'status' }, status)
+            : rows.map(row => compactRow(row))), scrollable ? h('div', { className: 'dmg-sidebar-more', 'aria-hidden': true, 'data-dmg-sidebar-more': '' }, doubleChevron()) : null)));
+}
+/** One compact row: name, weekly window, reading, bar (or the failure text). */
+function compactRow(row) {
+    const reading = rowReading(row);
+    const level = row.used === undefined || row.failed ? undefined : usedLevel(row.used);
+    return h('div', { className: 'dmg-sidebar-row', 'data-dmg-sidebar-row': row.card.provider, key: cardIdentity(row.card) }, h('div', { className: 'dmg-sidebar-row-line' }, h('span', { className: 'dmg-sidebar-name' }, row.card.name ?? row.card.provider), row.failed || row.window?.name === undefined ? null : h('span', { className: 'dmg-sidebar-window' }, row.window.name), h('span', {
+        className: 'dmg-sidebar-pct', 'data-reading': '', ...(level === undefined ? {} : { 'data-level': level }),
+        ...(row.failed || row.used !== undefined || row.display !== undefined || row.unlimited === true || row.balance === undefined
+            ? {}
+            : { 'data-balance': '', title: `${t('usageBalance')} ${row.balance}` }),
+    }, reading)), row.failed || row.used === undefined
+        ? null
+        : h('div', { className: 'dmg-sidebar-bar', 'aria-hidden': true }, h('i', { ...(level === undefined ? {} : { 'data-level': level }), style: { width: `${row.used}%` } })));
+}
+/** Expanded content: every upstream with every window, reset, balance and error. */
+function detail(cards, now, status) {
+    if (status !== undefined)
+        return h('p', { className: 'dmg-sidebar-status', role: 'status' }, status);
+    return h(Fragment, null, ...cards.map(card => h('section', {
+        className: 'dmg-sidebar-prov', 'data-provider': card.provider, key: cardIdentity(card),
+    }, h('div', { className: 'dmg-sidebar-prov-head' }, h('strong', null, card.name ?? card.provider), h('span', { className: 'dmg-sidebar-meta' }, providerMeta(card, now))), card.error !== undefined
+        ? h('p', { className: 'dmg-sidebar-error' }, card.error)
+        : (card.windows ?? []).map((window, index) => {
+            const used = typeof window.used === 'number' && Number.isFinite(window.used) ? Math.min(100, Math.max(0, window.used)) : undefined;
+            const level = used === undefined ? undefined : usedLevel(used);
+            return h('div', { className: 'dmg-sidebar-win', key: index }, h('div', { className: 'dmg-sidebar-win-line' }, h('span', { className: 'dmg-sidebar-win-name' }, window.name ?? '—'), h('span', { className: 'dmg-sidebar-pct', ...(level === undefined ? {} : { 'data-level': level }) }, windowReading(window)), resetShort(window.resetsAt, now) === undefined ? null : h('span', { className: 'dmg-sidebar-reset', title: window.resetsAt }, resetShort(window.resetsAt, now))), used === undefined ? null : h('div', { className: 'dmg-sidebar-bar', 'aria-hidden': true }, h('i', { 'data-level': level, style: { width: `${used}%` } })));
+        }), card.resets !== undefined || card.balance !== undefined
+        ? h('div', { className: 'dmg-sidebar-foot' }, typeof card.resets?.count === 'number' ? h('span', null, resetLine(card.resets.count)) : null, card.resets?.until === undefined ? null : h('span', null, formatTime(card.resets.until)), card.balance === undefined ? null : h('span', null, t('usageBalance'), ' ', h('b', null, String(card.balance)))) : null)));
+}
+const statusText = (view, error) => {
+    if (error !== '')
+        return t('usageError');
+    if (view === undefined)
+        return t('usageReading');
+    if (view.status === 'forbidden')
+        return t('usageForbidden');
+    if (view.status === 'unconfigured')
+        return t('usageUnconfigured');
+    if (view.status === 'error')
+        return view.error ?? t('usageError');
+    if (view.cards.length === 0)
+        return t('usageEmpty');
+    return undefined;
+};
+const providerMeta = (card, now) => {
+    const parts = [];
+    if (card.plan !== undefined)
+        parts.push(card.plan);
+    const read = cardReadTime(card);
+    if (read !== undefined) {
+        const age = ageText(read, now);
+        if (card.asOf !== undefined)
+            parts.push(`${t('usageReadAtStale')} ${formatTime(read)}`);
+        else
+            parts.push(age ?? formatTime(read));
+    }
+    return parts.join(' · ');
+};
+const resetShort = (resetsAt, now) => formatResetShort(resetsAt, now);
+const resetLine = (count) => count === 1 ? t('resetCountLineOne') : t('resetCountLineMany', { n: count });
+const windowReading = (window) => {
+    if (window.unlimited === true)
+        return t('unlimited');
+    if (window.display !== undefined && window.display !== '')
+        return window.display;
+    if (typeof window.used === 'number' && Number.isFinite(window.used))
+        return formatUsed(Math.min(100, Math.max(0, window.used)));
+    return '—';
+};
+const rowReading = (row) => {
+    if (row.failed)
+        return t('usageReadingFailed');
+    if (row.used === undefined && row.display === undefined && row.unlimited !== true && row.balance !== undefined)
+        return row.balance;
+    return windowReading({ ...(row.used === undefined ? {} : { used: row.used }), ...(row.display === undefined ? {} : { display: row.display }), ...(row.unlimited === true ? { unlimited: true } : {}) });
+};
+const ageText = (readAt, now) => {
+    const minutes = ageMinutes(readAt, now);
+    if (minutes === undefined)
+        return undefined;
+    if (minutes < 1)
+        return t('sidebarJustNow');
+    if (minutes < 60)
+        return t('sidebarMinutesAgo', { n: minutes });
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return t('sidebarHoursAgo', { n: hours });
+    return t('sidebarDaysAgo', { n: Math.floor(hours / 24) });
+};
+const refreshButton = (refresh, busy) => h('button', {
+    type: 'button', className: 'dmg-sidebar-icon', 'data-dmg-sidebar-refresh': '', 'aria-label': t('refresh'), title: t('refresh'),
+    disabled: busy, onClick: (event) => { event.stopPropagation(); void refresh(); },
+}, refreshIcon());
+const refreshIcon = () => h('svg', { viewBox: '0 0 16 16', fill: 'none', stroke: 'currentColor', strokeWidth: '1.4', 'aria-hidden': true }, h('path', { d: 'M13 8a5 5 0 1 1-1.6-3.7' }), h('path', { d: 'M13 2.4V5h-2.6' }));
+const chevron = (open) => h('svg', {
+    viewBox: '0 0 16 16', fill: 'none', stroke: 'currentColor', strokeWidth: '1.4', 'aria-hidden': true,
+    className: `dmg-sidebar-chevron${open ? ' is-open' : ''}`,
+}, h('path', { d: 'M4 6.5l4 4 4-4' }));
+const doubleChevron = () => h('svg', { viewBox: '0 0 16 16', fill: 'none', stroke: 'currentColor', strokeWidth: '1.4', 'aria-hidden': true }, h('path', { d: 'M4 6l4 4 4-4' }), h('path', { d: 'M4 10l4 4 4-4', opacity: '.55' }));

package/lib/client/UsageCard.js

@@ -1,15 +1,21 @@
 import { createElement as h } from 'react';
-import { formatTime, readTime, windowReading } from './view-model.js';
+import { expiryHint, formatTime, readTime, windowReading } from './view-model.js';
 import { t } from './locales.js';
 /**
  * One read-only usage card. Every gateway string is a React text child (never
  * HTML), absent fields are omitted, and the only control is "刷新" — there is
- * deliberately no reset action (the Codex reset count is display-only).
+ * deliberately no reset action (the Codex reset credits are display-only).
  */
 const time = (raw) => h('time', { dateTime: raw }, formatTime(raw));
+/** A reset credit's expiry: the localized instant, "expires …", in one machine-readable `<time>`. */
+const expiryTime = (raw) => h('time', { dateTime: raw }, t('resetCreditExpires', { date: formatTime(raw) }));
 const fact = (field, label, value) => h('span', { 'data-field': field, key: field }, h('b', null, `${label} `), h('span', { 'data-value': '' }, value));
 const scalar = (value) => typeof value === 'boolean' ? (value ? t('yes') : t('no')) : String(value);
 const present = (value) => value !== undefined && value !== null && value !== '';
+/** Children on one line, separated by the page's inline separator. */
+const inline = (nodes) => nodes.flatMap((node, index) => index === 0 ? [node] : [' · ', node]);
+/** Which window a reset credit is for, when the gateway names one it knows. */
+const windowLabel = (window) => window === 'fiveHour' ? t('resetWindowFiveHour') : window === 'weekly' ? t('resetWindowWeekly') : undefined;
 /** Bar colour: ≤70% normal (blue), above 70 and below 90 warn (orange), 90% and above high (red). */
 export const usageLevel = (used) => used >= 90 ? 'high' : used > 70 ? 'warn' : 'normal';
 function WindowRow({ window }) {
@@ -18,6 +24,41 @@ function WindowRow({ window }) {
     const used = typeof window.used === 'number' && reading?.endsWith('%') ? Math.max(0, Math.min(100, window.used)) : undefined;
     return h('div', { className: 'dmg-window', 'data-window': '' }, h('div', { className: 'dmg-window-line' }, h('span', null, present(window.name) ? h('span', { 'data-window-name': '' }, window.name) : null, present(window.name) && reading !== undefined ? ' ' : null, reading !== undefined ? h('span', { 'data-reading': '' }, reading) : null), showReset ? h('span', null, t('usageResetAt'), time(window.resetsAt)) : null), used !== undefined ? h('div', { className: 'dmg-track', 'aria-hidden': true }, h('div', { className: 'dmg-fill', 'data-level': usageLevel(used), style: { width: `${used}%` } })) : null);
 }
+/** The count half of the reset summary: one count, or a count per window for plans handing out one kind each. */
+function resetCount(resets) {
+    if (resets.byWindow === true) {
+        const parts = inline([
+            ...(typeof resets.fiveHour === 'number' && resets.fiveHour > 0 ? [h('span', { 'data-reset-five-hour': '' }, t('resetFiveHour', { n: resets.fiveHour }))] : []),
+            ...(typeof resets.weekly === 'number' && resets.weekly > 0 ? [h('span', { 'data-reset-weekly': '' }, t('resetWeekly', { n: resets.weekly }))] : []),
+        ]);
+        return parts.length ? h('span', { 'data-reset-count': '' }, ...parts) : null;
+    }
+    return typeof resets.count === 'number'
+        ? h('span', { 'data-reset-count': '' }, t('resetCreditsAvailable', { n: resets.count }))
+        : null;
+}
+/** One reset credit: which kind it is, when it runs out and, for the soonest, how far off that is. */
+function resetItem(item, soonest, key) {
+    const at = item.until;
+    const hint = present(at) && soonest !== undefined && Date.parse(at) === soonest ? expiryHint(at) : undefined;
+    return h('div', { className: 'dmg-reset-item', 'data-reset-item': '', key }, h('span', null, windowLabel(item.window) ?? t('resetCreditFull')), h('span', null, present(at) ? expiryTime(at) : t('resetCreditExpiryUnknown'), hint === undefined ? null : [' · ', hint]));
+}
+/**
+ * The card's reset credits, folded like the subscriptions plugin does: the count
+ * on the summary line, every credit and its expiry when opened. Read-only —
+ * spending a credit is not offered here.
+ */
+function ResetLine({ resets }) {
+    const each = resets.each ?? [];
+    const items = each.length ? each : present(resets.until) ? [{ until: resets.until }] : [];
+    const times = items.flatMap(item => { const at = present(item.until) ? Date.parse(item.until) : NaN; return Number.isNaN(at) ? [] : [at]; });
+    // The soonest credit carries the relative hint; it is the one worth not wasting.
+    const soonest = times.length ? Math.min(...times) : undefined;
+    const count = resetCount(resets);
+    if (count === null && items.length === 0)
+        return null;
+    return h('details', { className: 'dmg-resets', 'data-field': 'resets' }, h('summary', null, h('span', { className: 'dmg-chevron', 'aria-hidden': true }, '▸'), h('span', null, t('resetCreditsTitle')), count === null ? null : h('span', { className: 'dmg-resets-count' }, count)), items.length ? h('div', { className: 'dmg-reset-items' }, ...items.map((item, index) => resetItem(item, soonest, `reset-${index}`))) : null);
+}
 export function UsageCard({ card, busy, onRefresh }) {
     const read = readTime(card);
     const facts = [
@@ -29,5 +70,5 @@ export function UsageCard({ card, busy, onRefresh }) {
         present(read) && fact('readAt', card.asOf !== undefined ? t('usageReadAtStale') : t('usageReadAt'), time(read)),
     ].filter(Boolean);
     const resets = card.resets;
-    return h('article', { className: 'dmg-card', 'data-card': '' }, h('div', { className: 'dmg-card-title' }, h('strong', null, present(card.name) ? card.name : card.provider), h('button', { type: 'button', className: 'dmg-button', disabled: busy, onClick: onRefresh }, t('refresh'))), facts.length ? h('div', { className: 'dmg-facts' }, ...facts) : null, ...(card.windows ?? []).map((window, index) => h(WindowRow, { key: index, window })), resets && typeof resets.count === 'number' ? h('div', { className: 'dmg-facts', 'data-field': 'resets' }, h('span', null, h('b', null, t('resetCountLabel')), t('resetRemaining'), h('span', { 'data-reset-count': '' }, String(resets.count)), t('resetRemainingSuffix')), present(resets.until) ? h('span', null, h('b', null, t('resetExpiresLabel')), time(resets.until)) : null) : null, present(card.error) ? h('p', { className: 'dmg-error', 'data-field': 'error', role: 'alert' }, card.error) : null);
+    return h('article', { className: 'dmg-card', 'data-card': '' }, h('div', { className: 'dmg-card-title' }, h('strong', null, present(card.name) ? card.name : card.provider), h('button', { type: 'button', className: 'dmg-button', disabled: busy, onClick: onRefresh }, t('refresh'))), facts.length ? h('div', { className: 'dmg-facts' }, ...facts) : null, ...(card.windows ?? []).map((window, index) => h(WindowRow, { key: `window-${index}`, window })), resets ? h(ResetLine, { resets }) : null, present(card.error) ? h('p', { className: 'dmg-error', 'data-field': 'error', role: 'alert' }, card.error) : null);
 }

package/lib/client/index.d.ts

@@ -10,7 +10,7 @@ interface SlotRegistration {
     id: string;
     order: number;
     label?: () => string;
-    inject?: (sessionId: string) => unknown;
+    inject?: (owner?: unknown) => unknown;
 }
 /** Minimal locale face: register the dictionaries once and bind a translator. */
 interface LocaleService {