@linxin666/dsh-usage 0.4.10 → 0.4.12

package/src/client/UsageSectionCard.tsx

@@ -1,34 +1,30 @@
 /**
- * The usage statistics settings section: three tabs (用量: today's usage,
- * balances, trend; 个人套餐: per-provider plan quota windows; Token 银行:
- * the whale-yuan voucher minted from every provider's ledger usage)
- * plus a compact settings row. Data comes from the host's loopback-fenced
- * /api/dsh-usage/overview document; polling runs only while the section is
- * mounted and the tab is visible.
+ * The usage statistics settings page: one family settings card whose header
+ * carries the plugin switch, whose body holds three tabs (用量: today's
+ * usage, balances, trend; 个人套餐: per-provider plan quota windows; Token
+ * 银行: the whale-yuan voucher minted from every provider's ledger usage)
+ * and, under them, the display rows. Data comes from the host's
+ * loopback-fenced /api/dsh-usage/overview document; polling runs only while
+ * the section is mounted and the tab is visible.
  * @module @linxin666/dsh-usage/client/UsageSectionCard
  */
 
 import { useEffect, useRef, useState, useSyncExternalStore, type ReactNode } from 'react'
-import type { ConfigForm, ConfigFormSnapshot } from '@deepseek-ai/dsh-client-ui-settings/client'
 import type { UsageStoreInstance } from './usage-store.ts'
 import { t } from './locales.ts'
 import styles from './usage.module.css'
+import cardCss from './settings-card.module.css'
 import { PeakBadge } from './PeakBadge.tsx'
+import { SegmentGroup } from './SegmentGroup.tsx'
+import { UsagePage } from './UsagePage.tsx'
+import type { UsageSettingsCardFace } from './usage-settings-card.ts'
 import { isDeepSeekProviderRoute } from '../core/adapters.ts'
 import { deepseekPeriodAt } from '../core/pricing.ts'
 import { voucherData, drawVoucher, faceValue, formatDay, formatDenomination, loadVoucherArt } from './voucher.ts'
 import type { ObservedSpendView, ProviderSnapshotView, UsageDayView, UsageOverviewView, UsageProviderSummary, UsageTokenTotals, UsageWindowSummary } from '../core/types.ts'
 import { formatSpend, type SpendDisplay } from '../core/spend.ts'
 
-/** The settings fields this section edits (immediate-apply semantics). */
-export interface UsageSettings {
-  enabled?: boolean
-  pollIntervalSec?: number
-  /** Currency the spend figures are displayed in; the ledger stays CNY. */
-  spendCurrency?: 'CNY' | 'USD'
-  /** CNY per USD, consulted only while the display currency is USD. */
-  cnyPerUsd?: number
-}
+export type { UsageSettings } from './usage-settings-card.ts'
 
 /** The registration-side face the section's slot entry injects. */
 export interface UsageSectionFace {
@@ -44,8 +40,8 @@ export interface UsageSectionFace {
    * 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>
+  /** The settings card over the usage namespace: the plugin switch and the display rows. */
+  settingsCard: UsageSettingsCardFace
 }
 
 export interface UsageSectionProps extends UsageSectionFace {
@@ -98,28 +94,28 @@ function isConfigured(provider: ProviderSnapshotView): boolean {
 function TotalsRow(props: { totals: UsageTokenTotals }): ReactNode {
   const { totals } = props
   return (
-    <div className={styles.statRow}>
-      <div className={styles.stat}>
+    <div className={styles.statRow} data-dsh-layout="usage-totals">
+      <div className={styles.stat} data-dsh-stat="total">
         <span className={styles.statValue}>{formatTokens(totals.inputTokens + totals.cacheReadTokens + totals.cacheWriteTokens + totals.outputTokens)}</span>
         <span className={styles.statLabel}>{t('usage.tokens.total')}</span>
       </div>
-      <div className={styles.stat}>
+      <div className={styles.stat} data-dsh-stat="input">
         <span className={styles.statValue}>{formatTokens(totals.inputTokens + totals.cacheReadTokens + totals.cacheWriteTokens)}</span>
         <span className={styles.statLabel}>{t('usage.tokens.input')}</span>
       </div>
-      <div className={styles.stat}>
+      <div className={styles.stat} data-dsh-stat="output">
         <span className={styles.statValue}>{formatTokens(totals.outputTokens)}</span>
         <span className={styles.statLabel}>{t('usage.tokens.output')}</span>
       </div>
-      <div className={styles.stat}>
+      <div className={styles.stat} data-dsh-stat="cache-read">
         <span className={styles.statValue}>{formatTokens(totals.cacheReadTokens)}</span>
         <span className={styles.statLabel}>{t('usage.tokens.cacheRead')}</span>
       </div>
-      <div className={styles.stat}>
+      <div className={styles.stat} data-dsh-stat="cache-write">
         <span className={styles.statValue}>{formatTokens(totals.cacheWriteTokens)}</span>
         <span className={styles.statLabel}>{t('usage.tokens.cacheWrite')}</span>
       </div>
-      <div className={styles.stat}>
+      <div className={styles.stat} data-dsh-stat="calls">
         <span className={styles.statValue}>{formatTokens(totals.calls)}</span>
         <span className={styles.statLabel}>{t('usage.calls', { n: totals.calls })}</span>
       </div>
@@ -225,31 +221,26 @@ function DayPicker(props: {
 
 /** The section component; the slot merges the face into these props. */
 export function UsageSectionCard(props: UsageSectionProps): ReactNode {
-  const { store, poll, refresh, loadDay, settings } = props
+  const { store, poll, refresh, loadDay, settingsCard } = props
   const ui = useSyncExternalStore(store.subscribe, store.getSnapshot)
-  const settingsSnapshot = settings.getSnapshot()
-  const settingsValue = settingsSnapshot.value ?? {}
-  const [tab, setTab] = useState<'usage' | 'plans' | 'bank'>('usage')
+  // The card store republishes the Host's accepted value, so the poll below
+  // starts and stops with the switch without waiting for an unrelated render.
+  const card = useSyncExternalStore(settingsCard.store.subscribe, settingsCard.store.getSnapshot)
+  const [tab, setTab] = useState<UsageTab>('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,
-  // and the poll starts and stops with it instead of waiting for an unrelated
-  // render.
-  const [, bumpSettings] = useState(0)
-  useEffect(() => settings.subscribe(() => bumpSettings((count) => count + 1)), [settings])
-  const enabled = settingsValue.enabled ?? true
+  const enabled = card.enabled.text !== 'false'
 
   // Poll while mounted, enabled and visible; the overview is cheap (no probes —
   // the host's own cycle owns those) so 10 s keeps balances fresh-ish between
   // manual refreshes.
   useEffect(() => {
     // A disabled plugin deregisters its host routes, so the poll must stop with
-    // it; the section re-enables by writing the flag back through the checkbox.
+    // it; the section re-enables by writing the flag back through the switch.
     if (!enabled) return undefined
     poll()
     let timer: number | undefined
@@ -310,21 +301,20 @@ export function UsageSectionCard(props: UsageSectionProps): ReactNode {
     }
   }
 
-  // Disabled, failed and still-loading states keep the settings row mounted:
-  // it owns the enable checkbox, so replacing the whole panel would leave the
-  // user no way back from the UI.
+  // Disabled, failed and still-loading states keep the card mounted: its
+  // header owns the switch, so replacing the whole page would leave the user
+  // no way back from the UI.
   if (!enabled || ui.status === 'error' || snapshot === null) {
     return (
-      <div className={styles.section} data-dsh-plugin="usage">
-        <span className={styles.muted} data-dsh-part="status-line">
-          {!enabled
-            ? t('usage.disabled')
-            : ui.status === 'error'
-              ? t('usage.error', { error: ui.error ?? '' })
-              : t('usage.loading')}
-        </span>
-        <SettingsRow settings={settings} snapshot={settingsSnapshot.status === 'ready' ? settingsSnapshot : undefined} value={settingsValue} />
-      </div>
+      <UsagePage card={card} face={settingsCard} enabled={enabled}>
+        {enabled
+          ? (
+            <span className={styles.muted} data-dsh-part="status-line">
+              {ui.status === 'error' ? t('usage.error', { error: ui.error ?? '' }) : t('usage.loading')}
+            </span>
+          )
+          : null}
+      </UsagePage>
     )
   }
 
@@ -343,135 +333,146 @@ export function UsageSectionCard(props: UsageSectionProps): ReactNode {
   const planProviders = snapshot.providers.filter((provider) => isConfigured(provider) && (provider.planSupported === true || (provider.planSupported === undefined && provider.plan !== undefined)))
 
   return (
-    <div className={styles.section} data-dsh-plugin="usage">
-      <div className={styles.header} data-dsh-part="header">
-        <span className={styles.currentProvider}>
-          {currentProvider !== undefined
-            ? `${currentProvider.displayName}${current.model !== undefined && current.model !== '' ? ' · ' + current.model : ''}`
-            : t('usage.noData')}
-        </span>
-        <span style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
-          <span className={styles.muted}>{t('usage.updated', { time: formatTime(snapshot.updatedAt) })}</span>
-          <button type="button" className={styles.refreshBtn} onClick={onRefresh} disabled={refreshing}>
-            {refreshing ? t('usage.refreshing') : t('usage.refresh')}
-          </button>
-        </span>
-      </div>
+    <UsagePage card={card} face={settingsCard} enabled={enabled}>
+      <div className={styles.section}>
+        <div className={styles.header} data-dsh-part="header">
+          {/* The cards below already say when there is no usage; without a current route the slot stays empty. */}
+          <span className={styles.currentProvider}>
+            {currentProvider !== undefined
+              ? `${currentProvider.displayName}${current.model !== undefined && current.model !== '' ? ' · ' + current.model : ''}`
+              : null}
+          </span>
+          <span className={styles.headerActions}>
+            <span className={styles.muted}>{t('usage.updated', { time: formatTime(snapshot.updatedAt) })}</span>
+            <button type="button" className={styles.refreshBtn} onClick={onRefresh} disabled={refreshing}>
+              {refreshing ? t('usage.refreshing') : t('usage.refresh')}
+            </button>
+          </span>
+        </div>
+
+        <SegmentGroup className={styles.tabs} role="tablist" aria-label={t('usage.title')} data-dsh-part="tabs">
+          {USAGE_TABS.map((entry) => (
+            <button
+              key={entry}
+              type="button"
+              role="tab"
+              aria-selected={tab === entry}
+              className={`${cardCss.segment} ${styles.tab}`}
+              data-active={tab === entry ? '' : undefined}
+              onClick={() => setTab(entry)}
+            >
+              {t(`usage.tab.${entry}`)}
+            </button>
+          ))}
+        </SegmentGroup>
+
+        {tab === 'usage' && (
+          <>
+            <div className={styles.usageSummaryGrid} data-dsh-layout="summary-grid">
+            <div className={styles.card} data-dsh-part="today-card">
+              <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 && (
+                <PeakBadge peak={deepseekPeriod.peak} boundaryMs={deepseekPeriod.boundaryMs} variant="full" />
+              )}
+              {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}>{isToday ? t('usage.today.cost') : t('usage.day.cost')}</span>
+                  <span className={styles.providerTokens}>{formatSpend(day?.totals.cost ?? 0, snapshot.display)}</span>
+                </div>
+              )}
+              {(day?.providers.length ?? 0) > 0 && (
+                <div data-dsh-part="provider-list">
+                  {(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}
+                        {current.provider === row.provider && <span className={styles.currentBadge}>{t('usage.current')}</span>}
+                      </span>
+                      <span className={styles.providerTokens}>{formatTokens(row.totals.inputTokens + row.totals.cacheReadTokens + row.totals.cacheWriteTokens + row.totals.outputTokens)} · {t('usage.calls', { n: row.totals.calls })}{row.totals.cost > 0 ? ` · ${formatSpend(row.totals.cost, snapshot.display)}` : ''}</span>
+                    </div>
+                  ))}
+                </div>
+              )}
+            </div>
 
-      <div className={styles.tabs} role="tablist" data-dsh-part="tabs">
-        <button type="button" role="tab" aria-selected={tab === 'usage'} className={tab === 'usage' ? `${styles.tab} ${styles.tabActive}` : styles.tab} onClick={() => setTab('usage')}>
-          {t('usage.tab.usage')}
-        </button>
-        <button type="button" role="tab" aria-selected={tab === 'plans'} className={tab === 'plans' ? `${styles.tab} ${styles.tabActive}` : styles.tab} onClick={() => setTab('plans')}>
-          {t('usage.tab.plans')}
-        </button>
-        <button type="button" role="tab" aria-selected={tab === 'bank'} className={tab === 'bank' ? `${styles.tab} ${styles.tabActive}` : styles.tab} onClick={() => setTab('bank')}>
-          {t('usage.tab.bank')}
-        </button>
-      </div>
+            <div className={styles.card} data-dsh-part="balance-card">
+              <span className={styles.cardTitle}>{t('usage.balance')}</span>
+              {(() => {
+                const configured = snapshot.providers.filter(isConfigured)
+                // Include rows whose balance is deliberately not applicable
+                // (another origin's endpoint): the row itself explains why, which
+                // a single generic line cannot (#1688).
+                const rows = configured.filter((provider) => provider.balanceSupported === true || provider.balanceSupported === false || (provider.balanceSupported === undefined && provider.supported))
+                if (rows.length === 0) {
+                  return <span className={styles.muted}>{configured.length === 0 ? t('usage.balance.noneConfigured') : t('usage.balance.unsupported')}</span>
+                }
+                return rows.map((provider) => (
+                  <ProviderRow key={provider.provider} provider={provider} current={current.provider} />
+                ))
+              })()}
+              {snapshot.providers.some((provider) => isConfigured(provider) && provider.error !== undefined) && (
+                <span className={styles.errorLine}>
+                  {snapshot.providers.filter((provider) => isConfigured(provider) && provider.error !== undefined).map((provider) => `${provider.displayName}: ${t('usage.provider.error', { error: provider.error ?? '' })}`).join(t('usage.errorListSeparator'))}
+                </span>
+              )}
+            </div>
+            </div>
+
+            <RangeCard range={snapshot.usage.range} providers={snapshot.providers} currentProvider={current.provider} />
+          </>
+        )}
+
+        {tab === 'plans' && (
+          planProviders.length === 0
+            ? <div className={styles.card}><span className={styles.muted}>{t('usage.plan.noneConfigured')}</span></div>
+            : planProviders.map((provider) => <PlanCard key={provider.provider} provider={provider} current={current.provider} />)
+        )}
 
-      {tab === 'usage' && (
-        <>
-          <div className={styles.card} data-dsh-part="today-card">
-            <span className={styles.cardTitle}>{isToday ? t('usage.today') : t('usage.day.title', { date: selectedDay ?? '' })}</span>
+        {tab === 'bank' && (
+          <>
             <DayPicker
-              part="usage"
-              value={selectedDay ?? ''}
+              part="bank"
+              value={bankSelection ?? BANK_ALL_DAYS}
               options={dayOptions}
               today={todayDate ?? ''}
-              onSelect={(date) => { setUsageDay(date === todayDate ? undefined : date) }}
+              leading={{ value: BANK_ALL_DAYS, label: t('usage.bank.windowAll') }}
+              onSelect={(date) => { setBankDay(date === BANK_ALL_DAYS ? undefined : date) }}
             />
-            {deepseekVisible && (
-              <PeakBadge peak={deepseekPeriod.peak} boundaryMs={deepseekPeriod.boundaryMs} variant="full" />
-            )}
-            {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}>{isToday ? t('usage.today.cost') : t('usage.day.cost')}</span>
-                <span className={styles.providerTokens}>{formatSpend(day?.totals.cost ?? 0, snapshot.display)}</span>
-              </div>
-            )}
-            {(day?.providers.length ?? 0) > 0 && (
-              <div data-dsh-part="provider-list">
-                {(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}
-                      {current.provider === row.provider && <span className={styles.currentBadge}>{t('usage.current')}</span>}
-                    </span>
-                    <span className={styles.providerTokens}>{formatTokens(row.totals.inputTokens + row.totals.cacheReadTokens + row.totals.cacheWriteTokens + row.totals.outputTokens)} · {t('usage.calls', { n: row.totals.calls })}{row.totals.cost > 0 ? ` · ${formatSpend(row.totals.cost, snapshot.display)}` : ''}</span>
-                  </div>
-                ))}
-              </div>
-            )}
-          </div>
-
-          <div className={styles.card} data-dsh-part="balance-card">
-            <span className={styles.cardTitle}>{t('usage.balance')}</span>
-            {(() => {
-              const configured = snapshot.providers.filter(isConfigured)
-              // Include rows whose balance is deliberately not applicable
-              // (another origin's endpoint): the row itself explains why, which
-              // a single generic line cannot (#1688).
-              const rows = configured.filter((provider) => provider.balanceSupported === true || provider.balanceSupported === false || (provider.balanceSupported === undefined && provider.supported))
-              if (rows.length === 0) {
-                return <span className={styles.muted}>{configured.length === 0 ? t('usage.balance.noneConfigured') : t('usage.balance.unsupported')}</span>
-              }
-              return rows.map((provider) => (
-                <ProviderRow key={provider.provider} provider={provider} current={current.provider} />
-              ))
-            })()}
-            {snapshot.providers.some((provider) => isConfigured(provider) && provider.error !== undefined) && (
-              <span className={styles.errorLine}>
-                {snapshot.providers.filter((provider) => isConfigured(provider) && provider.error !== undefined).map((provider) => `${provider.displayName}: ${t('usage.provider.error', { error: provider.error ?? '' })}`).join(t('usage.errorListSeparator'))}
-              </span>
-            )}
-          </div>
-
-          <RangeCard range={snapshot.usage.range} providers={snapshot.providers} currentProvider={current.provider} />
-
-          <SettingsRow settings={settings} snapshot={settingsSnapshot.status === 'ready' ? settingsSnapshot : undefined} value={settingsValue} />
-        </>
-      )}
-
-      {tab === 'plans' && (
-        planProviders.length === 0
-          ? <div className={styles.card}><span className={styles.muted}>{t('usage.plan.noneConfigured')}</span></div>
-          : planProviders.map((provider) => <PlanCard key={provider.provider} provider={provider} current={current.provider} />)
-      )}
-
-      {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'}
-            display={snapshot.display}
-            {...(bankDayLoad?.status === 'error' ? { error: bankDayLoad.error ?? '' } : {})}
-          />
-        </>
-      )}
-    </div>
+            <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'}
+              display={snapshot.display}
+              {...(bankDayLoad?.status === 'error' ? { error: bankDayLoad.error ?? '' } : {})}
+            />
+          </>
+        )}
+      </div>
+    </UsagePage>
   )
 }
 
+/** The statistics tabs, in their order on the page. */
+const USAGE_TABS = ['usage', 'plans', 'bank'] as const
+type UsageTab = (typeof USAGE_TABS)[number]
+
 /** How many model sub-bars render under one provider bar. */
 const CHART_MODEL_CAP = 3
 
@@ -492,7 +493,7 @@ function RangeCard(props: { range?: UsageOverviewView['usage']['range']; provide
       <span className={styles.cardTitle}>{t('usage.trend')}</span>
       {range.providers.length === 0 || grandTotal === 0
         ? <span className={styles.muted}>{t('usage.noData')}</span>
-        : <div className={styles.chart} data-dsh-part="usage-chart">
+        : <div className={styles.chart} data-dsh-part="usage-chart" data-dsh-layout="trend-grid">
             {range.providers.map((row) => (
               <ChartProviderRow key={row.provider} row={row} name={nameOf(row.provider)} max={maxProvider} current={currentProvider === row.provider} />
             ))}
@@ -510,7 +511,7 @@ function ChartProviderRow(props: { row: UsageProviderSummary; name: string; max:
   const total = totalOf(row.totals)
   const maxModel = Math.max(1, ...row.models.slice(0, CHART_MODEL_CAP).map((model) => totalOf(model.totals)))
   return (
-    <div className={styles.chartProvider}>
+    <div className={styles.chartProvider} data-dsh-layout="trend-provider">
       <span className={styles.chartHead}>
         <span className={styles.providerName}>
           {name}
@@ -680,101 +681,3 @@ function PlanCard(props: { provider: ProviderSnapshotView; current?: string }):
     </div>
   )
 }
-
-/**
- * The compact settings row. Both controls write through the shared form the
- * moment the user changes them, and the Host answers each write with a
- * boolean: a refused (or transport-failed) write is surfaced as a failed save,
- * because a value that did not land must never read as applied.
- */
-function SettingsRow(props: {
-  settings: UsageSectionProps['settings']
-  snapshot?: ConfigFormSnapshot<UsageSettings>
-  value: UsageSettings
-}): ReactNode {
-  const { settings, snapshot, value } = props
-  const disabled = snapshot === undefined || !snapshot.writable
-  const [failure, setFailure] = useState<string | undefined>(undefined)
-
-  const write = (field: 'enabled' | 'pollIntervalSec' | 'spendCurrency' | 'cnyPerUsd', next: boolean | number | 'CNY' | 'USD'): void => {
-    setFailure(undefined)
-    let answer: Promise<boolean>
-    try {
-      answer = settings.set(field, next)
-    } catch (error) {
-      setFailure(error instanceof Error ? error.message : String(error))
-      return
-    }
-    // false is the contract's refusal/skip answer (the Host rejected the value,
-    // the entry is not writable, or the write was dropped); a rejecting
-    // transport reports through the same failed-save surface.
-    Promise.resolve(answer).then(
-      (accepted) => { if (!accepted) setFailure('') },
-      (error: unknown) => { setFailure(error instanceof Error ? error.message : String(error)) },
-    )
-  }
-
-  return (
-    <div className={styles.card} data-dsh-part="settings-row">
-      <span className={styles.cardTitle}>{t('usage.config.title')}</span>
-      <div className={styles.settingsGrid}>
-        <label className={styles.settingItem}>
-          <input
-            type="checkbox"
-            checked={value.enabled ?? true}
-            disabled={disabled}
-            onChange={(event) => { write('enabled', event.target.checked) }}
-          />
-          {t('usage.config.enabled')}
-        </label>
-        <label className={styles.settingItem}>
-          {t('usage.config.pollIntervalSec')}
-          <input
-            type="number"
-            min={30}
-            max={3600}
-            value={typeof value.pollIntervalSec === 'number' ? value.pollIntervalSec : 60}
-            disabled={disabled}
-            onChange={(event) => {
-              const parsed = Number(event.target.value)
-              if (Number.isFinite(parsed) && parsed >= 30 && parsed <= 3600) write('pollIntervalSec', Math.round(parsed))
-            }}
-          />
-        </label>
-        <label className={styles.settingItem}>
-          {t('usage.config.spendCurrency')}
-          <select
-            value={value.spendCurrency === 'USD' ? 'USD' : 'CNY'}
-            disabled={disabled}
-            onChange={(event) => { write('spendCurrency', event.target.value === 'USD' ? 'USD' : 'CNY') }}
-          >
-            <option value="CNY">CNY</option>
-            <option value="USD">USD</option>
-          </select>
-        </label>
-        <label className={styles.settingItem}>
-          {t('usage.config.cnyPerUsd')}
-          <input
-            type="number"
-            min={0.01}
-            max={1000}
-            step={0.01}
-            value={typeof value.cnyPerUsd === 'number' ? value.cnyPerUsd : 7.2}
-            disabled={disabled}
-            onChange={(event) => {
-              const parsed = Number(event.target.value)
-              // An unusable rate is simply not written: the stored value stays,
-              // and rendering falls back to the documented default rate.
-              if (Number.isFinite(parsed) && parsed >= 0.01 && parsed <= 1000) write('cnyPerUsd', Math.round(parsed * 100) / 100)
-            }}
-          />
-        </label>
-      </div>
-      {failure !== undefined && (
-        <span className={styles.errorLine} role="status">
-          {t('usage.config.saveFailed')}{failure === '' ? '' : ' - ' + failure}
-        </span>
-      )}
-    </div>
-  )
-}

package/src/client/index.ts

@@ -19,9 +19,11 @@ import type {} from '@deepseek-ai/dsh-client-ui-slots'
 import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import { createUsageStore, type UsageStoreInstance } from './usage-store.ts'
 import { UsageSectionCard, type UsageSectionFace, type UsageSettings } from './UsageSectionCard.tsx'
-import { mountUsageFootCard, openUsageSettings, settingsShellStore } from './foot-card-mount.tsx'
-import { NS, en, zh, t } from './locales.ts'
+import { mountUsageFootCard } from './foot-card-mount.tsx'
+import { NS, en, zh } from './locales.ts'
+import { installUsageSection, openIntegratedUsageSettings } from './section-integration.ts'
 import { createServedEntryForm } from './settings-entry-form.ts'
+import { UsageSettingsCardController } from './usage-settings-card.ts'
 import type { UsageDayResponse, UsageDayView, UsageOverviewView } from '../core/types.ts'
 
 /** The host usage API as the browser sees it (same-origin JSON endpoints). */
@@ -68,9 +70,6 @@ const USAGE_ENTRY_IDS: readonly string[] = [AGGREGATE_ENTRY_ID, 'usage', USAGE_S
 /** First-level nav position: directly below the Workshop section (order 150). */
 const SECTION_ORDER = 151
 
-/** The section's nav row id — what the shell's store selects when the card opens. */
-const USAGE_SECTION_ID = 'dsh-usage'
-
 /** Required services. */
 export const inject = ['slots', 'locale', 'connection', 'configForms', 'remote']
 
@@ -167,7 +166,13 @@ export function apply(ctx: ClientContext): void {
   // 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 })
+  // The card form lives as long as the plugin, like the store: the page reads
+  // its last state on reopen, and a write in flight settles after the page closes.
+  const settingsCard = new UsageSettingsCardController(settingsForm)
+  ctx.effect(() => () => { settingsCard.dispose() }, 'dsh-usage: settings card')
+  const settingsCardFace = settingsCard.inject()
+
+  const face = (): UsageSectionFace => ({ store, poll, refresh, loadDay, settingsCard: settingsCardFace })
 
   // 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
@@ -177,13 +182,7 @@ export function apply(ctx: ClientContext): void {
     store,
     poll,
     settings: settingsForm,
-    onOpen: () => {
-      openUsageSettings({
-        id: USAGE_SECTION_ID,
-        label: () => t('usage.title'),
-        store: settingsShellStore(ctx.slots),
-      })
-    },
+    onOpen: () => { openIntegratedUsageSettings(ctx) },
     locale: ctx.locale,
   })
   ctx.effect(() => () => {
@@ -194,21 +193,11 @@ export function apply(ctx: ClientContext): void {
     }
   }, 'dsh-usage: sidebar foot card')
 
-  ctx.slots.inject('settings.section', () => {
-    try {
-      const unregister = ctx.slots.register({
-        name: 'settings.section',
-        id: USAGE_SECTION_ID,
-        order: SECTION_ORDER,
-        label: () => ctx.locale.bind(NS)('usage.title'),
-        locale: NS,
-        inject: face,
-      }, UsageSectionCard)
-      return () => {
-        unregister()
-      }
-    } catch {
-      return () => {}
-    }
-  })
+  ctx.effect(() => installUsageSection(ctx, {
+    order: SECTION_ORDER,
+    label: () => ctx.locale.bind(NS)('usage.title'),
+    locale: NS,
+    inject: face,
+    component: UsageSectionCard,
+  }), 'dsh-usage: settings page')
 }