@linxin666/dsh-usage 0.3.22 → 0.3.24

package/src/client/UsageSidebarPanel.tsx

@@ -0,0 +1,196 @@
+/**
+ * Sidebar usage panel (issue #1592): the usage body seated directly under the
+ * sidebar entry row. The row carries the panel's controls (refresh, collapse
+ * chevron), so this component renders only the content: expanded, plan
+ * providers show their quota windows and balance-only providers their
+ * remaining amount; collapsed, a one-line strip shows the current session
+ * provider's today usage (tokens, calls, and cost when priced) from the same
+ * /api/dsh-usage/overview document the settings section renders. The open
+ * state lives in the mount (persisted to localStorage) and arrives through
+ * the open face; polling runs at 10s expanded, 30s collapsed, and pauses
+ * while the page is hidden.
+ * @module @linxin666/dsh-usage/client/UsageSidebarPanel
+ */
+
+import { useEffect, useSyncExternalStore, type ReactNode } from 'react'
+import { t } from './locales.ts'
+import styles from './usage.module.css'
+import { formatTokens } from './UsageSectionCard.tsx'
+import type { UsageStoreInstance } from './usage-store.ts'
+import { adapterFor } from '../core/adapters.ts'
+import { totalTokens } from '../core/ledger.ts'
+import type { ProviderSnapshotView, UsageOverviewView, UsageTokenTotals } from '../core/types.ts'
+import { addTotals, emptyTotals } from '../core/types.ts'
+
+/** Expanded-state face the owning mount supplies (subscribe + current value). */
+export interface OpenStateSource {
+  subscribe(listener: () => void): () => void
+  isOpen(): boolean
+}
+
+/** Props of the sidebar panel (the apply body supplies the store and poller). */
+export interface UsageSidebarPanelProps {
+  store: UsageStoreInstance
+  /** Fetch one overview now. */
+  poll: () => void
+  /** Expanded state owned by the mount; false renders nothing and pauses polling. */
+  open: OpenStateSource
+}
+
+/** Poll cadence while the panel is expanded and the page visible. */
+const PANEL_POLL_MS = 10_000
+
+/**
+ * Poll cadence of the collapsed strip: the current session's usage should
+ * stay visibly live, but a collapsed surface pays a relaxed cadence instead
+ * of the expanded one.
+ */
+const COLLAPSED_POLL_MS = 30_000
+
+/** Bar tone, matching the settings section's thresholds. */
+function tone(percent: number): string {
+  if (percent >= 90) return styles.barLow
+  if (percent >= 70) return styles.barWarn
+  return styles.sidebarBarFill
+}
+
+/**
+ * The collapsed-strip facts for the current provider: display name plus
+ * today's adapter-family totals (tokens, calls, cost). The host serves them
+ * strip-ready inside `current`; an older host document is derived against
+ * here. Undefined on a day without usage — a strip about nothing is noise.
+ */
+function collapsedSummary(snapshot: UsageOverviewView): { name: string; totals: UsageTokenTotals } | undefined {
+  const provider = snapshot.current.provider
+  if (provider === undefined) return undefined
+  const name = snapshot.current.displayName
+    ?? snapshot.providers.find((entry) => entry.provider === provider)?.displayName
+    ?? provider
+  if (snapshot.current.today !== undefined) {
+    const totals = snapshot.current.today
+    return totals.calls > 0 && totalTokens(totals) > 0 ? { name, totals } : undefined
+  }
+  const family = adapterFor(provider)
+  let merged = emptyTotals()
+  for (const row of snapshot.usage.today.providers) {
+    const same = family === undefined ? row.provider === provider : adapterFor(row.provider) === family
+    if (same) merged = addTotals(merged, row.totals)
+  }
+  return merged.calls > 0 && totalTokens(merged) > 0 ? { name, totals: merged } : undefined
+}
+
+/** A provider is worth listing when it is configured and carries a fact. */
+function listable(provider: ProviderSnapshotView): boolean {
+  return provider.credential !== 'none' && (provider.plan !== undefined || provider.balance !== undefined)
+}
+
+/** One provider row: plan windows when present, otherwise the balance line. */
+function ProviderBlock(props: { provider: ProviderSnapshotView }): ReactNode {
+  const { provider } = props
+  const windows = provider.plan?.windows ?? []
+  if (windows.length > 0) {
+    return (
+      <div className={styles.sidebarProvider} data-dsh-part="sidebar-provider">
+        <div className={styles.sidebarProviderHead}>
+          <span className={styles.sidebarProviderName}>{provider.displayName}</span>
+        </div>
+        {windows.map((window) => (
+          <div key={window.key} className={styles.sidebarWindowRow} data-dsh-part="sidebar-window">
+            <span>{window.name ?? t(`usage.plan.windows.${window.key}`)}</span>
+            {window.percent !== undefined && (
+              <>
+                <span className={styles.sidebarBar}>
+                  <span className={tone(window.percent)} style={{ width: `${Math.min(100, Math.max(0, window.percent))}%` }} />
+                </span>
+                <span>{window.percent >= 10 ? Math.round(window.percent) : window.percent.toFixed(1)}%</span>
+              </>
+            )}
+          </div>
+        ))}
+      </div>
+    )
+  }
+  if (provider.balance !== undefined) {
+    return (
+      <div className={styles.sidebarProvider} data-dsh-part="sidebar-provider">
+        <div className={styles.sidebarProviderHead}>
+          <span className={styles.sidebarProviderName}>{provider.displayName}</span>
+          <span className={styles.sidebarBalance}>
+            {t('usage.sidebar.balanceLeft', { balance: `${provider.balance.currency} ${provider.balance.totalBalance}` })}
+          </span>
+        </div>
+      </div>
+    )
+  }
+  return null
+}
+
+/**
+ * Render the sidebar usage panel body.
+ * @param props - store, the poll callback, and the mount's open-state face.
+ * @returns the panel content, or null while collapsed.
+ */
+export function UsageSidebarPanel(props: UsageSidebarPanelProps): ReactNode {
+  const { store, poll, open: openState } = props
+  const ui = useSyncExternalStore(store.subscribe, store.getSnapshot)
+  const open = useSyncExternalStore(openState.subscribe, openState.isOpen)
+
+  // The strip stays live at a relaxed cadence while collapsed; the
+  // expanded panel keeps the section's own 10s cadence. A hidden tab always
+  // pauses, matching the settings section's gating.
+  useEffect(() => {
+    poll()
+    const cadence = open ? PANEL_POLL_MS : COLLAPSED_POLL_MS
+    let timer: number | undefined
+    const start = (): void => {
+      if (timer === undefined && document.visibilityState === 'visible') timer = window.setInterval(poll, cadence)
+    }
+    const onVisibility = (): void => {
+      if (document.visibilityState === 'visible') {
+        poll()
+        start()
+      } else if (timer !== undefined) {
+        window.clearInterval(timer)
+        timer = undefined
+      }
+    }
+    start()
+    document.addEventListener('visibilitychange', onVisibility)
+    return () => {
+      if (timer !== undefined) window.clearInterval(timer)
+      document.removeEventListener('visibilitychange', onVisibility)
+    }
+  }, [poll, open])
+
+  const snapshot: UsageOverviewView | null = ui.snapshot
+
+  if (!open) {
+    const summary = snapshot === null ? undefined : collapsedSummary(snapshot)
+    if (summary === undefined) return null
+    return (
+      <div className={styles.sidebarSummary} data-dsh-plugin="usage" data-dsh-part="sidebar-summary">
+        <span className={styles.sidebarSummaryName}>{summary.name}</span>
+        <span className={styles.sidebarSummaryFacts}>
+          {t('usage.sidebar.todayUsage', { tokens: formatTokens(totalTokens(summary.totals)) })}
+          {' · '}
+          {t('usage.calls', { n: summary.totals.calls })}
+          {summary.totals.cost > 0 ? ` · ¥${summary.totals.cost.toFixed(2)}` : ''}
+        </span>
+      </div>
+    )
+  }
+
+  const providers = snapshot === null ? [] : snapshot.providers.filter(listable)
+
+  return (
+    <div className={styles.sidebarPanel} data-dsh-plugin="usage" data-dsh-part="sidebar-panel">
+      {ui.status === 'error'
+        ? <span className={styles.sidebarMuted}>{t('usage.sidebar.error', { error: ui.error ?? '' })}</span>
+        : snapshot === null
+          ? <span className={styles.sidebarMuted}>{t('usage.sidebar.loading')}</span>
+          : providers.length === 0
+            ? <span className={styles.sidebarMuted}>{t('usage.sidebar.empty')}</span>
+            : providers.map((provider) => <ProviderBlock key={provider.provider} provider={provider} />)}
+    </div>
+  )
+}

package/src/client/body-mutations.ts

@@ -0,0 +1,133 @@
+// Generated by scripts/sync-shared.mjs from shared/client/body-mutations.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * One `document.body` MutationObserver per page, shared by every family
+ * plugin bundle.
+ *
+ * Family plugins that inject at the DOM level must notice when the shell
+ * re-renders around their injected node: the sidebar entry rows
+ * (sidebar-entry-core), the center-column panel containers
+ * (panel-mount-core), and the aggregate shell's column shims. Each consumer
+ * used to install its OWN `MutationObserver` on `document.body` with
+ * `{ childList: true, subtree: true }`, so a page carrying N family plugins
+ * paid N native observers and N callback invocations for EVERY mutation batch
+ * the app produced — chat token streaming alone produces many per second, and
+ * the count grows with the number of installed plugins.
+ *
+ * This module keeps exactly ONE body observer per page. The registry lives on
+ * `globalThis` under a `Symbol.for` key, so the per-package generated copies
+ * of this file (scripts/sync-shared.mjs) and separately bundled plugins all
+ * reach the same hub at runtime instead of one hub per module instance.
+ * Record subscribers receive the mutations accumulated since the last flush.
+ * Consumers that only re-check their DOM use subscribeBodyInvalidations:
+ * when all subscribers use that path, the hub retains no mutation records
+ * (or detached subtrees) while a background page's animation frames pause.
+ * Both paths run at most once per frame. The last subscriber disconnects the
+ * observer, cancels the pending frame and releases its records.
+ *
+ * Failure policy: without a DOM or `MutationObserver` the subscription is a
+ * no-op disposer (the same silence the per-consumer observers had), and when
+ * `requestAnimationFrame` is unavailable the flush runs synchronously so a
+ * subscriber is never silently dropped. A throwing subscriber cannot stop the
+ * others.
+ */
+
+/** The page-wide hub: one observer plus its subscribers and pending records. */
+interface BodyMutationHub {
+  observer: MutationObserver
+  subscribers: Set<(records: MutationRecord[]) => void>
+  pending: MutationRecord[]
+  scheduled: boolean
+  frame?: number
+}
+
+/** Cross-bundle registry key; `Symbol.for` so every module copy agrees. */
+const HUB_KEY = Symbol.for('dsh-web.body-mutation-hub')
+const INVALIDATION_ONLY = Symbol.for('dsh-web.body-mutation-invalidation')
+type Subscriber = ((records: MutationRecord[]) => void) & { [INVALIDATION_ONLY]?: true }
+
+function needsRecords(subscribers: Set<(records: MutationRecord[]) => void>): boolean {
+  for (const listener of subscribers) {
+    if (!(listener as Subscriber)[INVALIDATION_ONLY]) return true
+  }
+  return false
+}
+
+/**
+ * Subscribe to a coalesced DOM re-check without retaining mutation records.
+ * The marked wrapper also works with an older hub, which delivers records
+ * that it simply ignores until a page reload picks up the updated hub.
+ */
+export function subscribeBodyInvalidations(subscriber: () => void): () => void {
+  const listener: Subscriber = () => { subscriber() }
+  listener[INVALIDATION_ONLY] = true
+  return subscribeBodyMutations(listener)
+}
+
+/**
+ * Subscribe to body-level childList mutations.
+ * @param subscriber - called at most once per animation frame with the records
+ *   collected since the previous flush; must be safe to run repeatedly.
+ * @returns the disposer removing this subscriber (and the observer when it was
+ *   the last one).
+ */
+export function subscribeBodyMutations(subscriber: (records: MutationRecord[]) => void): () => void {
+  if (typeof globalThis === 'undefined' || typeof document === 'undefined') return () => {}
+  if (typeof MutationObserver !== 'function') return () => {}
+  const registry = globalThis as unknown as Record<symbol, unknown>
+  let hub = registry[HUB_KEY] as BodyMutationHub | undefined
+  if (hub === undefined) {
+    const subscribers = new Set<(records: MutationRecord[]) => void>()
+    const created: BodyMutationHub = {
+      observer: undefined as unknown as MutationObserver,
+      subscribers,
+      pending: [],
+      scheduled: false,
+    }
+    const flush = (): void => {
+      created.frame = undefined
+      created.scheduled = false
+      const batch = created.pending
+      created.pending = []
+      for (const listener of [...subscribers]) {
+        if (!subscribers.has(listener)) continue
+        try {
+          listener(batch)
+        } catch {
+          // One subscriber must never break the others; the next flush retries it.
+        }
+      }
+    }
+    const schedule = (): void => {
+      if (created.scheduled) return
+      created.scheduled = true
+      if (typeof requestAnimationFrame === 'function') created.frame = requestAnimationFrame(flush)
+      else flush()
+    }
+    created.observer = new MutationObserver((records) => {
+      if (needsRecords(subscribers)) {
+        for (const record of records) created.pending.push(record)
+      }
+      schedule()
+    })
+    created.observer.observe(document.body ?? document.documentElement, { childList: true, subtree: true })
+    registry[HUB_KEY] = created
+    hub = created
+  }
+  const active = hub
+  active.subscribers.add(subscriber)
+  let subscribed = true
+  return () => {
+    if (!subscribed) return
+    subscribed = false
+    active.subscribers.delete(subscriber)
+    if (!needsRecords(active.subscribers)) active.pending = []
+    if (active.subscribers.size === 0 && registry[HUB_KEY] === active) {
+      active.observer.disconnect()
+      if (active.frame !== undefined && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(active.frame)
+      active.frame = undefined
+      active.pending = []
+      active.scheduled = false
+      delete registry[HUB_KEY]
+    }
+  }
+}

package/src/client/index.ts

@@ -15,8 +15,9 @@ import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 import type {} from '@deepseek-ai/dsh-client-ui-slots'
 // Type-only: pulls the ctx.slots merge (the renderer owns the slot registry since 0.1.2).
 import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
-import { createElement } from 'react'
 import { createUsageStore, type UsageStoreInstance } from './usage-store.ts'
+import { mountSidebarEntry } from './sidebar-entry.ts'
+import { mountUsagePanel } from './sidebar-panel-mount.tsx'
 import { UsageSectionCard, type UsageSectionFace, type UsageSettings } from './UsageSectionCard.tsx'
 import { NS, en, zh } from './locales.ts'
 import type { UsageOverviewView } from '../core/types.ts'
@@ -123,6 +124,26 @@ export function apply(ctx: ClientContext): void {
 
   const face = (): UsageSectionFace => ({ store, poll, refresh, settings: settingsScope })
 
+  // Sidebar surface (issue #1592): the entry row seats the panel's controls
+  // (refresh, collapse chevron); the collapsible panel directly under it reads
+  // the same overview document. The mount owns the persisted open state; the
+  // entry row mirrors it as highlight and chevron direction.
+  const panel = mountUsagePanel({ store, poll })
+  const disposeEntry = mountSidebarEntry({
+    onToggle: () => { panel.toggle() },
+    onRefresh: () => { refresh() },
+    isOpen: () => panel.isOpen(),
+    subscribeOpen: (listener) => panel.subscribe(listener),
+  }, ctx.locale)
+  ctx.effect(() => () => {
+    try {
+      disposeEntry()
+    } catch {
+      // Entry row already gone (teardown race).
+    }
+    panel.dispose()
+  }, 'dsh-usage: sidebar panel')
+
   ctx.slots.inject('settings.section', () => {
     try {
       const unregister = ctx.slots.register({

package/src/client/locales.ts

@@ -48,12 +48,8 @@ export const zh = {
   'usage.config.title': '设置',
   'usage.config.enabled': '启用插件',
   'usage.config.pollIntervalSec': '轮询间隔（秒）',
-  'usage.config.bubbleMode': '宠物气泡',
-  'usage.config.bubbleMode.always': '常驻显示',
-  'usage.config.bubbleMode.change': '仅变化时',
-  'usage.config.bubbleMode.off': '关闭',
   'usage.bank.title': '鲸元券',
-  'usage.bank.hint': '官方 API 每消耗 1000 tokens 铸造 1 鲸元；保存或分享这张票券。',
+  'usage.bank.hint': '官方 API 每消耗 100 万 tokens 铸造 1 鲸元；保存或分享这张票券。',
   'usage.bank.noUsage': '暂无 DeepSeek 官方用量数据（统计自插件启用起）',
   'usage.bank.minted': '累计铸造 {minted} 鲸元（{tokens} tokens）',
   'usage.bank.spend.observed': '官方余额实测花费 ¥{cost}（自 {since} 起）',
@@ -62,6 +58,15 @@ export const zh = {
   'usage.bank.save': '保存图片',
   'usage.bank.share': '分享',
   'usage.bank.drawError': '票券生成失败：{error}',
+  'usage.sidebar.entry.label': '用量',
+  'usage.sidebar.entry.tooltip': '用量面板：套餐配额与余额',
+  'usage.sidebar.toggle.collapse': '折叠',
+  'usage.sidebar.toggle.expand': '展开',
+  'usage.sidebar.empty': '没有已配置的套餐或余额数据。',
+  'usage.sidebar.error': '加载失败：{error}',
+  'usage.sidebar.loading': '正在加载用量数据…',
+  'usage.sidebar.balanceLeft': '剩余 {balance}',
+  'usage.sidebar.todayUsage': '今日 {tokens} tokens',
 }
 
 /** English mirror; every zh key present. */
@@ -105,12 +110,8 @@ export const en: Record<UsageKey, string> = {
   'usage.config.title': 'Settings',
   'usage.config.enabled': 'Enable plugin',
   'usage.config.pollIntervalSec': 'Poll interval (seconds)',
-  'usage.config.bubbleMode': 'Pet bubble',
-  'usage.config.bubbleMode.always': 'Always visible',
-  'usage.config.bubbleMode.change': 'On change',
-  'usage.config.bubbleMode.off': 'Off',
   'usage.bank.title': 'Whale-yuan voucher',
-  'usage.bank.hint': 'Every 1,000 tokens spent on the official API mint one whale yuan; save or share the note.',
+  'usage.bank.hint': 'Every 1,000,000 tokens spent on the official API mint one whale yuan; save or share the note.',
   'usage.bank.noUsage': 'No official DeepSeek usage yet (counting starts when the plugin is enabled)',
   'usage.bank.minted': 'Minted {minted} whale yuan ({tokens} tokens)',
   'usage.bank.spend.observed': 'Spent ¥{cost} observed on the official balance (watching since {since})',
@@ -119,6 +120,15 @@ export const en: Record<UsageKey, string> = {
   'usage.bank.save': 'Save image',
   'usage.bank.share': 'Share',
   'usage.bank.drawError': 'Failed to render the voucher: {error}',
+  'usage.sidebar.entry.label': 'Usage',
+  'usage.sidebar.entry.tooltip': 'Usage panel: plan quotas and balances',
+  'usage.sidebar.toggle.collapse': 'Collapse',
+  'usage.sidebar.toggle.expand': 'Expand',
+  'usage.sidebar.empty': 'No plan or balance data configured.',
+  'usage.sidebar.error': 'Loading failed: {error}',
+  'usage.sidebar.loading': 'Loading usage data…',
+  'usage.sidebar.balanceLeft': '{balance} left',
+  'usage.sidebar.todayUsage': '{tokens} tokens today',
 }
 
 export type UsageKey = keyof typeof zh