@linxin666/dsh-usage 0.4.3 → 0.4.5

package/lib/types/core/holidays.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Chinese public-holiday dates, Beijing calendar days, as `YYYY-MM-DD`.
+ *
+ * The DeepSeek peak rule bills a public holiday off-peak in full, and the
+ * State Council publishes these dates per year, so they cannot be derived
+ * from a rule. This module is that data; `pricing.ts` keeps the arithmetic.
+ *
+ * Adjusted workdays are deliberately absent: the provider counts the
+ * calendar day, so an adjusted Saturday or Sunday is off-peak exactly like
+ * any other weekend and listing it would price it as peak.
+ *
+ * Source: the yearly schedules in bastengao/chinese-holidays-node
+ * (`data/<year>.json`, MIT). Only the `holiday` entries are taken; that
+ * package's runtime code (which fetches over the network) and its
+ * dependencies are not vendored.
+ *
+ * Coverage ends at the newest year below. A year with no entry is priced as
+ * if it had no holidays, which is the documented default of
+ * {@link PublicHolidayCalendar} in `pricing.ts`.
+ * @module @linxin666/dsh-usage/core/holidays
+ */
+/** Public-holiday dates keyed by Beijing calendar year. */
+export declare const CHINESE_PUBLIC_HOLIDAYS: Readonly<Record<string, readonly string[]>>;
+/** The newest year this table covers; later years carry no entry. */
+export declare const HOLIDAY_TABLE_LAST_YEAR = 2026;

package/lib/types/core/ledger.d.ts

@@ -7,6 +7,14 @@
 import { type UsageLedgerDocument, type UsageProviderSummary, type UsageTokenTotals } from './types.ts';
 /** Local-date key (`YYYY-MM-DD`) for an epoch ms timestamp. */
 export declare function localDateKey(ms: number): string;
+/**
+ * Whether `key` is a real local-date key (`YYYY-MM-DD`). The shape check is
+ * round-tripped: an impossible date (9999-99-99) parses to NaN and a rollover
+ * (2026-02-30) lands on another day, so both would otherwise fold into a bogus,
+ * never-pruned bucket. Shared by the persisted-document reader and the day
+ * route's query gate.
+ */
+export declare function isLedgerDateKey(key: string): boolean;
 /** An empty ledger document. */
 export declare function createLedgerDocument(): UsageLedgerDocument;
 /**

package/lib/types/core/pricing.d.ts

@@ -4,10 +4,19 @@
  * at fold time (the provider bills each request in the period the request ran
  * in, so pricing at the fold is the honest estimate).
  *
- * Policy (api-docs.deepseek.com pricing page, effective 2026-09-10 12:00
- * Beijing): peak hours are Beijing time Monday-Friday 09:00-12:00 and
- * 14:00-18:00; every other hour (nights, weekends) is off-peak and billed at
- * half the peak price. All prices here are CNY per million tokens.
+ * Policy (api-docs.deepseek.com pricing page): peak hours are Beijing time
+ * Monday-Friday 09:00-12:00 and 14:00-18:00, excluding Chinese public
+ * holidays; every other hour is off-peak and billed at half the peak price.
+ * The published rule counts a calendar day, not the working schedule: a
+ * Saturday or Sunday is off-peak in full even on an adjusted workday, and a
+ * public holiday is off-peak in full even on a Monday-Friday. All prices
+ * here are CNY per million tokens.
+ *
+ * Public-holiday dates are not derivable from the rule, so the rule takes them as
+ * a `PublicHolidayCalendar`. The default is the published table in `./holidays.ts`,
+ * covering 2020 through ${HOLIDAY_TABLE_LAST_YEAR}; a caller with newer dates
+ * passes its own. A holiday weekday therefore prices off-peak, which is the half
+ * of the published rule that is easy to get wrong.
  *
  * The published rows are `deepseek-flash` (DeepSeek-V4.1-Flash) and
  * `deepseek-v4-pro` (DeepSeek-V4-Pro-0813). The retired flash ids
@@ -17,13 +26,32 @@
  * @module @linxin666/dsh-usage/core/pricing
  */
 import type { UsageTokenTotals } from './types.ts';
+/**
+ * Supplies the Chinese public-holiday dates the peak rule excludes. The dates
+ * are not derivable from any rule (the State Council publishes them per year),
+ * so this repository ships no table of its own: the default calendar is empty,
+ * and a caller that has real dates passes them in. A date is compared as a
+ * Beijing-time `YYYY-MM-DD` string, which is the granularity the published
+ * rule needs (a holiday is off-peak for the whole day, so times never matter).
+ */
+export interface PublicHolidayCalendar {
+    /** True when the Beijing-time calendar day `date` is a Chinese public holiday. */
+    isPublicHoliday(date: string): boolean;
+}
+/**
+ * The default calendar: the published Chinese public-holiday table, so a holiday
+ * weekday prices off-peak instead of over-reporting at the peak rate. A year the
+ * table does not cover holds no dates and falls back to peak on weekdays, which
+ * is the safe direction to be wrong in: the estimate reads high rather than low.
+ */
+export declare const CN_PUBLIC_HOLIDAYS: PublicHolidayCalendar;
 /**
  * The DeepSeek billing period at `ms`, plus when it next flips. The clock is
  * Beijing time regardless of the host timezone (UTC+8 has no DST, so a fixed
  * shift is exact). `boundaryMs` is the instant the current period ends — the
  * window's close while peaking, the next window's open otherwise.
  */
-export declare function deepseekPeriodAt(ms: number): {
+export declare function deepseekPeriodAt(ms: number, calendar?: PublicHolidayCalendar): {
     peak: boolean;
     boundaryMs: number;
 };
@@ -33,4 +61,4 @@ export declare function deepseekPeriodAt(ms: number): {
  * row; ids from other providers never reach this function (the service gates
  * by route family). Rounded to micro-CNY so the ledger stays readable.
  */
-export declare function deepseekModelSpend(model: string, totals: Readonly<UsageTokenTotals>, atMs: number): number;
+export declare function deepseekModelSpend(model: string, totals: Readonly<UsageTokenTotals>, atMs: number, calendar?: PublicHolidayCalendar): number;

package/lib/types/core/types.d.ts

@@ -52,6 +52,24 @@ export interface UsageDaySummary {
     date: string;
     totals: UsageTokenTotals;
 }
+/**
+ * One local day aggregated per provider and model. The overview serves today
+ * through this shape and the day route serves any retained day with it, so a
+ * day the user picks in the browser and the live today card are the same
+ * document.
+ */
+export interface UsageDayView {
+    /** Local-date key `YYYY-MM-DD`. */
+    date: string;
+    totals: UsageTokenTotals;
+    /** Per-provider rows, heaviest by total tokens first. */
+    providers: UsageProviderSummary[];
+}
+/** The day route's response body. */
+export interface UsageDayResponse {
+    ok: true;
+    day: UsageDayView;
+}
 /** A balance fact normalized from a provider probe. */
 export interface BalanceView {
     /** ISO 4217 code the provider bills in (`CNY`, `USD`, ...). */
@@ -139,13 +157,16 @@ export interface UsageOverviewView {
         today?: UsageTokenTotals;
     };
     usage: {
-        today: {
-            date: string;
-            totals: UsageTokenTotals;
-            providers: UsageProviderSummary[];
-        };
+        today: UsageDayView;
         /** Last N local days ascending, including today. */
         days: UsageDaySummary[];
+        /**
+         * Every retained local day that recorded usage, ascending — the day
+         * picker's option list, reaching past the trend cap to the whole
+         * retention window. Optional so an older host document still renders
+         * (the section then offers no picker).
+         */
+        availableDays?: string[];
         /**
          * The same window aggregated per provider and model — the trend card's
          * bar-chart data. Optional so an older host document still renders.

package/lib/types/host/routes.d.ts

@@ -13,6 +13,17 @@ export declare const USAGE_API_PREFIX = "/api/dsh-usage";
  * @returns the route.
  */
 export declare function makeUsageOverviewRoute(ctx: Context, service: UsageService): WebRoute;
+/**
+ * One retained day route: `GET /api/dsh-usage/day?date=YYYY-MM-DD` answers
+ * that local day's per-provider and per-model totals, so the section's day
+ * pickers can show a past day instead of only today. Same trust fence as the
+ * overview route, and a key that is not a real local date is refused with 400
+ * rather than folded into a bogus day.
+ * @param ctx - host context; may expose remoteWebUiPairing.
+ * @param service - the usage service.
+ * @returns the route.
+ */
+export declare function makeUsageDayRoute(ctx: Context, service: UsageService): WebRoute;
 /**
  * Manual refresh: forces one probe cycle now and answers with the fresh
  * overview. Same trust fence as the overview route.

package/lib/types/host/usage-service.d.ts

@@ -7,7 +7,7 @@
  * @module @linxin666/dsh-usage/host/usage-service
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { UsageOverviewView } from '../core/types.ts';
+import type { UsageDayView, UsageOverviewView } from '../core/types.ts';
 /**
  * Persisted accrual state for the official DeepSeek family's real spend:
  * consecutive observations of the official CNY balance, decreases counted
@@ -78,6 +78,14 @@ export declare class UsageService {
      * a strip about nothing is noise, not information.
      */
     private currentView;
+    /**
+     * One retained local day aggregated per provider and model, as the day
+     * route serves it. A day the ledger never held — pruned by retention, or
+     * simply without usage — reads as a zeroed day rather than an error, so a
+     * picker selection that aged out degrades to "no usage" instead of a broken
+     * panel. The route gates the key's shape before it gets here.
+     */
+    day(dateKey: string): UsageDayView;
     /** One local day aggregated per provider. */
     private daySummary;
     /**
@@ -153,4 +161,8 @@ export declare class UsageService {
     private piAiProfile;
     /** The DeepSeek official adapter's credential reference name. */
     private deepseekApiKeyEnv;
+    /** The DeepSeek official adapter's configured baseURL. */
+    private deepseekBaseUrl;
+    /** The effective base URL for a provider route (pi-ai or deepseek). */
+    private routeBaseUrl;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-usage",
   "description": "Usage statistics plugin for the dsh web GUI: per-provider balance and coding-plan quota detection plus a live token usage ledger, with a compact price glance card above the sidebar's Settings row",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "icon": "icon.svg",
   "type": "module",
   "engines": {
@@ -33,7 +33,7 @@
   "license": "Apache-2.0",
   "dsh": {
     "engines": {
-      "dsh": ">=0.1.7-rc.2"
+      "dsh": ">=0.2.0-rc.2"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -53,22 +53,22 @@
     "@deepseek-ai/schemastery": "^3.18.4"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh": ">=0.1.7-rc.2",
+    "@deepseek-ai/dsh": ">=0.2.0-rc.2",
     "react": "^18.2.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-credentials": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-connection": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-store": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-settings": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-credentials": "^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-store": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.2.0-rc.2",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.20.0",

package/src/client/UsageSectionCard.tsx

@@ -16,7 +16,7 @@ import styles from './usage.module.css'
 import { isDeepSeekProviderRoute } from '../core/adapters.ts'
 import { deepseekPeriodAt } from '../core/pricing.ts'
 import { deepseekVoucherData, drawVoucher, faceValue, formatDay, formatDenomination, loadVoucherArt } from './voucher.ts'
-import type { ObservedSpendView, ProviderSnapshotView, UsageOverviewView, UsageProviderSummary, UsageTokenTotals, UsageWindowSummary } from '../core/types.ts'
+import type { ObservedSpendView, ProviderSnapshotView, UsageDayView, UsageOverviewView, UsageProviderSummary, UsageTokenTotals, UsageWindowSummary } from '../core/types.ts'
 
 /** The settings fields this section edits (immediate-apply semantics). */
 export interface UsageSettings {
@@ -32,6 +32,12 @@ export interface UsageSectionFace {
   poll: () => void
   /** Force a host probe cycle now (resolves with the fresh overview). */
   refresh: () => void
+  /**
+   * Fetch one retained local day (YYYY-MM-DD) from the host. The overview
+   * only carries today plus the list of recorded days, so a day the user picks
+   * is one small on-demand request.
+   */
+  loadDay: (date: string) => Promise<UsageDayView>
   /** The shared configuration form this section's settings row reads and writes. */
   settings: ConfigForm<UsageSettings>
 }
@@ -44,6 +50,12 @@ export interface UsageSectionProps extends UsageSectionFace {
 /** Poll cadence while the section is open. */
 const SECTION_POLL_MS = 10_000
 
+/**
+ * The Token bank's default window: the whole retained ledger. It is a select
+ * value rather than a date, so it can never collide with a day key.
+ */
+const BANK_ALL_DAYS = 'all'
+
 /** Compact token count: 12345 -> 12.3k, 1234567 -> 1.23M. */
 export function formatTokens(value: number): string {
   if (!Number.isFinite(value) || value <= 0) return '0'
@@ -149,13 +161,87 @@ function ProviderRow(props: { provider: ProviderSnapshotView; current?: string }
   )
 }
 
+/** One day the pickers selected, as its fetch progresses. */
+interface DayLoad {
+  status: 'loading' | 'ready' | 'error'
+  /** The served day, once the host answered. */
+  view?: UsageDayView
+  /** Transport error message, on a failed load. */
+  error?: string
+}
+
+/**
+ * Fetch the day a picker selected, or stay idle for the default window. Today
+ * never fetches: the overview already carries it live, so switching back to
+ * today is instant and keeps counting with the poll. A superseded selection
+ * never lands (the effect cancels), and a failed load reports its own message
+ * instead of leaving the card on a stale day.
+ */
+function useDayView(loadDay: (date: string) => Promise<UsageDayView>, date: string | undefined, today: string | undefined): DayLoad | undefined {
+  const [load, setLoad] = useState<DayLoad | undefined>(undefined)
+  useEffect(() => {
+    if (date === undefined || date === today) {
+      setLoad((previous) => (previous === undefined ? previous : undefined))
+      return undefined
+    }
+    let cancelled = false
+    setLoad({ status: 'loading' })
+    loadDay(date).then(
+      (view) => { if (!cancelled) setLoad({ status: 'ready', view }) },
+      (error: unknown) => { if (!cancelled) setLoad({ status: 'error', error: error instanceof Error ? error.message : String(error) }) },
+    )
+    return () => { cancelled = true }
+  }, [date, today, loadDay])
+  return load
+}
+
+/**
+ * The day picker: today plus every retained day that recorded usage, newest
+ * first (the host serves the list ascending). Without that list (an older host
+ * document) no picker renders and the card stays on its default window.
+ */
+function DayPicker(props: {
+  value: string
+  options: string[]
+  today: string
+  /** An extra leading option; the Token bank passes its whole-ledger window. */
+  leading?: { value: string; label: string }
+  onSelect: (date: string) => void
+  /** Namespaces the element id, so the two tabs keep one control each. */
+  part: string
+}): ReactNode {
+  const { value, options, today, leading, onSelect, part } = props
+  if (options.length === 0) return null
+  return (
+    <div className={styles.dayPicker}>
+      <label className={styles.dayPickerLabel} htmlFor={'dsh-usage-day-' + part}>{t('usage.day.label')}</label>
+      <select
+        id={'dsh-usage-day-' + part}
+        className={styles.daySelect}
+        value={value}
+        onChange={(event) => { onSelect(event.target.value) }}
+      >
+        {leading !== undefined && <option value={leading.value}>{leading.label}</option>}
+        {options.map((date) => (
+          <option key={date} value={date}>{date === today ? t('usage.day.today') : date}</option>
+        ))}
+      </select>
+    </div>
+  )
+}
+
 /** The section component; the slot merges the face into these props. */
 export function UsageSectionCard(props: UsageSectionProps): ReactNode {
-  const { store, poll, refresh, settings } = props
+  const { store, poll, refresh, loadDay, settings } = props
   const ui = useSyncExternalStore(store.subscribe, store.getSnapshot)
   const settingsSnapshot = settings.getSnapshot()
   const settingsValue = settingsSnapshot.value ?? {}
   const [tab, setTab] = useState<'usage' | 'plans' | 'bank'>('usage')
+  // Undefined means "the default window of this tab": today on the usage tab,
+  // the whole retained ledger in the Token bank. A date switches that tab to
+  // one retained day instead.
+  const [usageDay, setUsageDay] = useState<string | undefined>(undefined)
+  const [bankDay, setBankDay] = useState<string | undefined>(undefined)
   const [refreshing, setRefreshing] = useState(false)
   // The enable checkbox writes through the shared form, so subscribing here
   // keeps the flag below live: the form republishes the Host's accepted value,
@@ -195,6 +281,31 @@ export function UsageSectionCard(props: UsageSectionProps): ReactNode {
   }, [poll, enabled])
 
   const snapshot = ui.snapshot
+  const todayDate = snapshot?.usage.today.date
+  // Every retained day that recorded usage, newest first, plus today so the
+  // default window is always one of the options even before it has usage.
+  const dayOptions = snapshot === null
+    ? []
+    : [...new Set([todayDate, ...(snapshot.usage.availableDays ?? [])]
+      .filter((date): date is string => date !== undefined))].sort().reverse()
+  // A selection retention no longer holds falls back to the tab's default
+  // window, so a picker can never keep displaying a day the host dropped.
+  const usageSelection = usageDay !== undefined && dayOptions.includes(usageDay) ? usageDay : undefined
+  const bankSelection = bankDay !== undefined && dayOptions.includes(bankDay) ? bankDay : undefined
+  const selectedDay = usageSelection ?? todayDate
+  const isToday = selectedDay === todayDate
+  const usageDayLoad = useDayView(loadDay, usageSelection, todayDate)
+  const bankDayLoad = useDayView(loadDay, bankSelection, todayDate)
+  // A selected day rides its own fetch; the default windows ride the overview.
+  const day = isToday ? snapshot?.usage.today : usageDayLoad?.view
+  const bankDayView = bankSelection === undefined
+    ? undefined
+    : bankSelection === todayDate ? snapshot?.usage.today : bankDayLoad?.view
+  const bankWindow = bankSelection === undefined
+    ? snapshot?.usage.all ?? snapshot?.usage.range
+    : bankDayView === undefined
+      ? undefined
+      : { from: bankDayView.date, to: bankDayView.date, totals: bankDayView.totals, providers: bankDayView.providers }
 
   const onRefresh = (): void => {
     setRefreshing(true)
@@ -227,10 +338,11 @@ export function UsageSectionCard(props: UsageSectionProps): ReactNode {
   const current = snapshot.current
   const currentProvider = snapshot.providers.find((provider) => provider.provider === current.provider)
   // Peak-period line: only when the official DeepSeek family is in play this
-  // session (the current route, or spend recorded under one today).
+  // session (the current route, or spend recorded under one today). It
+  // describes the pricing window now, so a past day's card drops it.
   const deepseekPeriod = deepseekPeriodAt(Date.now())
-  const deepseekVisible = (current.provider !== undefined && isDeepSeekProviderRoute(current.provider))
-    || snapshot.usage.today.providers.some((row) => isDeepSeekProviderRoute(row.provider))
+  const deepseekVisible = isToday && ((current.provider !== undefined && isDeepSeekProviderRoute(current.provider))
+    || snapshot.usage.today.providers.some((row) => isDeepSeekProviderRoute(row.provider)))
   // Plans tab: only configured routes with a real coding-plan/subscription
   // adapter (planSupported; an older host without the flag falls back to "has
   // a plan fact"). Balance-only providers (DeepSeek, ZenMux, ...) and
@@ -268,24 +380,35 @@ export function UsageSectionCard(props: UsageSectionProps): ReactNode {
       {tab === 'usage' && (
         <>
           <div className={styles.card} data-dsh-part="today-card">
-            <span className={styles.cardTitle}>{t('usage.today')}</span>
+            <span className={styles.cardTitle}>{isToday ? t('usage.today') : t('usage.day.title', { date: selectedDay ?? '' })}</span>
+            <DayPicker
+              part="usage"
+              value={selectedDay ?? ''}
+              options={dayOptions}
+              today={todayDate ?? ''}
+              onSelect={(date) => { setUsageDay(date === todayDate ? undefined : date) }}
+            />
             {deepseekVisible && (
               <span className={styles.muted} data-dsh-part="peak-status">
                 {t(deepseekPeriod.peak ? 'usage.peak.on' : 'usage.peak.off', { time: formatClock(deepseekPeriod.boundaryMs) })}
               </span>
             )}
-            {snapshot.usage.today.totals.calls === 0
-              ? <span className={styles.muted}>{t('usage.noData')}</span>
-              : <TotalsRow totals={snapshot.usage.today.totals} />}
-            {snapshot.usage.today.totals.cost > 0 && (
+            {usageDayLoad?.status === 'error'
+              ? <span className={styles.errorLine}>{t('usage.day.error', { error: usageDayLoad.error ?? '' })}</span>
+              : day === undefined
+                ? <span className={styles.muted}>{t('usage.day.loading')}</span>
+                : day.totals.calls === 0
+                  ? <span className={styles.muted}>{isToday ? t('usage.noData') : t('usage.day.empty')}</span>
+                  : <TotalsRow totals={day.totals} />}
+            {(day?.totals.cost ?? 0) > 0 && (
               <div className={styles.providerRow} data-dsh-part="today-cost">
-                <span className={styles.providerName}>{t('usage.today.cost')}</span>
-                <span className={styles.providerTokens}>{formatCost(snapshot.usage.today.totals.cost)}</span>
+                <span className={styles.providerName}>{isToday ? t('usage.today.cost') : t('usage.day.cost')}</span>
+                <span className={styles.providerTokens}>{formatCost(day?.totals.cost ?? 0)}</span>
               </div>
             )}
-            {snapshot.usage.today.providers.length > 0 && (
+            {(day?.providers.length ?? 0) > 0 && (
               <div data-dsh-part="provider-list">
-                {snapshot.usage.today.providers.map((row) => (
+                {(day?.providers ?? []).map((row) => (
                   <div key={row.provider} className={styles.providerRow}>
                     <span className={styles.providerName}>
                       {snapshot.providers.find((provider) => provider.provider === row.provider)?.displayName ?? row.provider}
@@ -332,7 +455,27 @@ export function UsageSectionCard(props: UsageSectionProps): ReactNode {
           : planProviders.map((provider) => <PlanCard key={provider.provider} provider={provider} current={current.provider} />)
       )}
 
-      {tab === 'bank' && <VoucherCard window={snapshot.usage.all ?? snapshot.usage.range} observedSpend={snapshot.usage.observedSpend} />}
+      {tab === 'bank' && (
+        <>
+          <DayPicker
+            part="bank"
+            value={bankSelection ?? BANK_ALL_DAYS}
+            options={dayOptions}
+            today={todayDate ?? ''}
+            leading={{ value: BANK_ALL_DAYS, label: t('usage.bank.windowAll') }}
+            onSelect={(date) => { setBankDay(date === BANK_ALL_DAYS ? undefined : date) }}
+          />
+          <VoucherCard
+            window={bankWindow}
+            // The observed-spend watch accrues from its own first balance
+            // reading, so it describes the whole window only: a single day's
+            // voucher falls back to that day's fold-time estimate.
+            observedSpend={bankSelection === undefined ? snapshot.usage.observedSpend : undefined}
+            loading={bankSelection !== undefined && bankDayLoad?.status === 'loading'}
+            {...(bankDayLoad?.status === 'error' ? { error: bankDayLoad.error ?? '' } : {})}
+          />
+        </>
+      )}
     </div>
   )
 }
@@ -408,15 +551,16 @@ function totalOf(totals: UsageTokenTotals): number {
 
 /**
  * The Token 银行 card: the DeepSeek official family's retained-ledger usage
- * minted onto the whale-yuan note at 1,000,000 tokens per whale yuan. The window
- * prefers the host's whole-ledger aggregate and falls back to the 30-day
- * trend when an older host serves no `all`; the spend line prefers the
- * official balance watch and falls back to the fold-time estimate; the
- * artwork draw failure degrades to an error line and never takes the
- * section down.
+ * minted onto the whale-yuan note at 1,000,000 tokens per whale yuan. The
+ * window is the whole retained ledger by default (the host's aggregate,
+ * falling back to the 30-day trend when an older host serves no `all`) or the
+ * single day the user picked; the spend line prefers the official balance
+ * watch (whole window only) and falls back to the fold-time estimate; the
+ * artwork draw failure degrades to an error line and never takes the section
+ * down.
  */
-function VoucherCard(props: { window?: UsageWindowSummary; observedSpend?: ObservedSpendView }): ReactNode {
-  const { window: ledger, observedSpend } = props
+function VoucherCard(props: { window?: UsageWindowSummary; observedSpend?: ObservedSpendView; loading?: boolean; error?: string }): ReactNode {
+  const { window: ledger, observedSpend, loading, error } = props
   const data = deepseekVoucherData(ledger)
   const canvasRef = useRef<HTMLCanvasElement | null>(null)
   const [drawError, setDrawError] = useState<string | undefined>(undefined)
@@ -478,9 +622,13 @@ function VoucherCard(props: { window?: UsageWindowSummary; observedSpend?: Obser
   return (
     <div className={styles.card} data-dsh-part="bank-card">
       <span className={styles.cardTitle}>{t('usage.bank.title')}</span>
-      {data === undefined
-        ? <span className={styles.muted}>{t('usage.bank.noUsage')}</span>
-        : <>
+      {error !== undefined
+        ? <span className={styles.errorLine}>{t('usage.day.error', { error })}</span>
+        : loading === true
+          ? <span className={styles.muted}>{t('usage.day.loading')}</span>
+          : data === undefined
+            ? <span className={styles.muted}>{t('usage.bank.noUsage')}</span>
+            : <>
             <span className={styles.muted}>{t('usage.bank.hint')}</span>
             <div className={styles.voucherPreview} data-dsh-part="voucher-preview">
               <canvas ref={canvasRef} aria-label={t('usage.bank.title')} />

package/src/client/index.ts

@@ -22,11 +22,13 @@ import { UsageSectionCard, type UsageSectionFace, type UsageSettings } from './U
 import { mountUsageFootCard, openUsageSettings } from './foot-card-mount.tsx'
 import { NS, en, zh, t } from './locales.ts'
 import { createServedEntryForm } from './settings-entry-form.ts'
-import type { UsageOverviewView } from '../core/types.ts'
+import type { UsageDayResponse, UsageDayView, UsageOverviewView } from '../core/types.ts'
 
 /** The host usage API as the browser sees it (same-origin JSON endpoints). */
 interface UsageHttpApi {
   overview(): Promise<UsageOverviewView>
+  /** One retained local day (YYYY-MM-DD), the day pickers' detail fetch. */
+  day(date: string): Promise<UsageDayView>
   refresh(): Promise<UsageOverviewView>
 }
 
@@ -47,6 +49,7 @@ const usageApi: UsageHttpApi = {
   // `<base href="./">`, so a sub-path deployment resolves these against its
   // entry directory instead of escaping to the origin root.
   overview: () => usageFetch('api/dsh-usage/overview', 'GET'),
+  day: async (date: string) => (await usageFetch<UsageDayResponse>('api/dsh-usage/day?date=' + encodeURIComponent(date), 'GET')).day,
   refresh: () => usageFetch('api/dsh-usage/refresh', 'POST'),
 }
 
@@ -156,7 +159,12 @@ export function apply(ctx: ClientContext): void {
     })
   }
 
-  const face = (): UsageSectionFace => ({ store, poll, refresh, settings: settingsForm })
+  // The day pickers fetch their own day: the overview carries today (always
+  // live) plus the list of recorded days, and one selected day is a single
+  // small local request the 10 s poll has no reason to repeat.
+  const loadDay = (date: string): Promise<UsageDayView> => usageApi.day(date)
+
+  const face = (): UsageSectionFace => ({ store, poll, refresh, loadDay, settings: settingsForm })
 
   // Sidebar foot card: the compact usage glance seated below the shell's
   // Settings row. It shares the section's store and poll path (the sequence

package/src/client/locales.ts

@@ -22,6 +22,13 @@ export const zh = {
   'usage.current': '当前',
   'usage.today': '今日用量',
   'usage.today.cost': '今日消费（估算）',
+  'usage.day.label': '查看日期',
+  'usage.day.today': '今日',
+  'usage.day.title': '{date} 用量',
+  'usage.day.cost': '当日消费（估算）',
+  'usage.day.empty': '该日没有用量记录',
+  'usage.day.loading': '正在加载该日用量…',
+  'usage.day.error': '该日用量加载失败：{error}',
   'usage.peak.on': 'DeepSeek 高峰时段：计价 ×2，{time} 结束',
   'usage.peak.off': 'DeepSeek 空闲时段：计价为高峰一半，{time} 进入高峰',
   'usage.calls': '{n} 次调用',
@@ -56,6 +63,7 @@ export const zh = {
   'usage.bank.spend.observed': '官方余额实测花费 ¥{cost}（自 {since} 起）',
   'usage.bank.spend.estimated': '消费估算：约 ¥{cost}',
   'usage.bank.window': '统计窗口 {from} ~ {to}',
+  'usage.bank.windowAll': '全部保留期',
   'usage.bank.save': '保存图片',
   'usage.bank.share': '分享',
   'usage.bank.drawError': '票券生成失败：{error}',
@@ -81,6 +89,13 @@ export const en: Record<UsageKey, string> = {
   'usage.current': 'Current',
   'usage.today': 'Today',
   'usage.today.cost': 'Today spend (estimated)',
+  'usage.day.label': 'Day',
+  'usage.day.today': 'Today',
+  'usage.day.title': 'Usage · {date}',
+  'usage.day.cost': 'Day spend (estimated)',
+  'usage.day.empty': 'No usage recorded on this day',
+  'usage.day.loading': 'Loading that day…',
+  'usage.day.error': 'Failed to load that day: {error}',
   'usage.peak.on': 'DeepSeek peak hours: 2x pricing, ends {time}',
   'usage.peak.off': 'DeepSeek off-peak: half of peak pricing, peak returns {time}',
   'usage.calls': '{n} calls',
@@ -115,6 +130,7 @@ export const en: Record<UsageKey, string> = {
   'usage.bank.spend.observed': 'Spent ¥{cost} observed on the official balance (watching since {since})',
   'usage.bank.spend.estimated': 'Estimated spend: about ¥{cost}',
   'usage.bank.window': 'Window {from} - {to}',
+  'usage.bank.windowAll': 'All retained days',
   'usage.bank.save': 'Save image',
   'usage.bank.share': 'Share',
   'usage.bank.drawError': 'Failed to render the voucher: {error}',