dsh-token-total 1.0.0 → 1.0.2

package/src/client/StatsLineEnhanced.tsx

@@ -55,10 +55,8 @@ import {
   type ConversationNodeLike, type PartialAssistantLike, type UseProjection, type WindowStats,
 } from './stats-line-core.ts'
 import { formatTokens } from './format.ts'
-import {
-  billedTotal, hasAnyTokens, useSessionUsage,
-  type SessionTreeReading,
-} from './use-session-usage.ts'
+import { useSessionUsage, type SessionTreeReading } from './use-session-usage.ts'
+import { billedTotal, hasAnyTokens, sessionUsageForDisplay } from './session-usage-core.ts'
 import type { SessionUsageTotals } from '../wire.ts'
 import css from './StatsLineEnhanced.module.css'
 
@@ -299,7 +297,7 @@ function TimePill({ stats, t, dialog, useChat, scale, dock }: {
     )
   }
   return (
-    <span ref={rootRef} className={anchorClass(dock)}>
+    <span ref={rootRef} className={anchorClass(dock)} data-dsh-token-total-stat>
       <button
         type="button"
         className={css.pill}
@@ -363,10 +361,8 @@ function TimePill({ stats, t, dialog, useChat, scale, dock }: {
 }
 
 function UsagePill({ usage, tree, t, dialog, dock }: {
-  usage: Parameters<typeof billedInputTokens>[0]
-  /** The whole session tree (main + subagents) from the host, when it has
-   *  answered. Subagent spend is invisible to the native projection, so the
-   *  pill's total and its dialog both switch to this once it carries any. */
+  usage: Parameters<typeof billedInputTokens>[0] | undefined
+  /** Descendant spend from the host; the main-agent figure stays live. */
   tree?: SessionTreeReading
   t: T
   /** The row's shared exclusive slot; omitted by a split-mode entry. */
@@ -375,20 +371,10 @@ function UsagePill({ usage, tree, t, dialog, dock }: {
   dock: boolean
 }) {
   const { open, setOpen, rootRef, panelRef, pos } = useStatDialog(dialog)
-  // The native projection is the main agent of THIS session; the tree adds
-  // every subagent session delegated from it. Prefer the tree as soon as it
-  // reports any subagent spend — otherwise the two are identical and the
-  // native figure (which is live to the frame) stays authoritative.
-  const nativeTotals: SessionUsageTotals = {
-    uncachedInputTokens: usage.uncachedInputTokens,
-    outputTokens: usage.outputTokens,
-    cacheReadTokens: usage.cacheReadTokens,
-    cacheWriteTokens: usage.cacheWriteTokens,
-  }
-  const treeTotals = tree?.totals ?? null
-  const subagentTotals = tree?.tree?.subagents
-  const showSubagents = subagentTotals !== undefined && hasAnyTokens(subagentTotals)
-  const billed = showSubagents && treeTotals !== null ? treeTotals : nativeTotals
+  const display = sessionUsageForDisplay(usage, tree?.tree ?? null)
+  const subagentTotals = display.subagents
+  const showSubagents = display.subagentSessions > 0
+  const billed = display.total
   // Same aggregate as the official pill total: every prompt-side billing bucket plus output.
   const total = billedTotal(billed)
   const totalText = t('message.turnUsage.count', { count: formatTokensCompact(total) })
@@ -397,7 +383,7 @@ function UsagePill({ usage, tree, t, dialog, dock }: {
   const exactCount = (value: number): string =>
     t('message.turnUsage.count', { count: formatTokens(value) })
   return (
-    <span ref={rootRef} className={anchorClass(dock)}>
+    <span ref={rootRef} className={anchorClass(dock)} data-dsh-token-total-stat>
       <button
         type="button"
         className={css.pill}
@@ -461,10 +447,10 @@ function UsagePill({ usage, tree, t, dialog, dock }: {
             <dd>{exactCount(billed.outputTokens)}</dd>
             {/* The split that the native figure cannot show: this session's own
                 main agent against every subagent it delegated to. */}
-            {showSubagents && treeTotals !== null && (
+            {showSubagents && (
               <>
                 <dt>{t('stats.dialog.main')}</dt>
-                <dd>{exactCount(billedTotal(nativeTotals))}</dd>
+                <dd>{exactCount(billedTotal(display.self))}</dd>
                 <dt>{t('stats.dialog.subagents')}</dt>
                 <dd>
                   {exactCount(billedTotal(subagentTotals))}
@@ -472,7 +458,7 @@ function UsagePill({ usage, tree, t, dialog, dock }: {
                   {t('stats.dialog.subagentCount', { count: tree?.tree?.subagentSessions ?? 0 })}
                 </dd>
                 <dt>{t('stats.dialog.treeTotal')}</dt>
-                <dd>{exactCount(billedTotal(treeTotals))}</dd>
+                <dd>{exactCount(billedTotal(billed))}</dd>
               </>
             )}
           </dl>
@@ -506,13 +492,10 @@ export const StatsLineEnhanced = memo(function StatsLineEnhanced(
   // density predicted for the same text. 1 (the raw prior) until a settled step
   // carries both, so the first stream of a session still reads sensibly.
   const tokenScale = useMemo(() => measuredTokenScale(settledNodes ?? []) ?? 1, [settledNodes])
-  // The whole session tree (main + subagents). Re-asked whenever the native
-  // usage figure moves, which is exactly when a main-agent call settled.
+  // Refresh on main-agent settlements and poll for child-only activity.
   const tree = useSessionUsage(sessionId, usageSignature(usage, stats.steps))
-  // Gated on actual token activity: a session whose steps all settled without
-  // billing (e.g. every request failed) shows its counts without a usage pill.
-  const hasTokens = usage !== undefined
-    && (billedInputTokens(usage) > 0 || usage.outputTokens > 0)
+  // A delegated-only session must still show its usage pill.
+  const hasTokens = hasAnyTokens(sessionUsageForDisplay(usage, tree.tree).total)
   if (stats.steps === 0 && !hasTokens) return null
   // data-composer-stats: through host 0.1.6-alpha.1 InputBar tightened the
   // composer bottom clearance while this row rendered (the official pills'
@@ -585,8 +568,7 @@ export const StatsUsageEntry = memo(function StatsUsageEntry(
 ) {
   const usage = useProjection('tokenUsage')
   const tree = useSessionUsage(sessionId, usageSignature(usage, usage === undefined ? 0 : 1))
-  const hasTokens = usage !== undefined
-    && (billedInputTokens(usage) > 0 || usage.outputTokens > 0)
+  const hasTokens = hasAnyTokens(sessionUsageForDisplay(usage, tree.tree).total)
   if (!hasTokens) return null
   return (
     <UsagePill

package/src/client/TokenTotalPanel.module.css

@@ -499,11 +499,26 @@
   font-size: 11px;
 }
 
-.modelList {
-  list-style: none;
-  margin: 0;
-  padding: 0;
-  flex: 1 1 260px;
+/* Two ranking cards, side by side: MODELS left, PROVIDERS right. Both are
+   always on screen (no lens/tab switch), so they share one row grid and
+   stretch to a common height; a narrow pane stacks them instead. */
+.rankCards {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+}
+
+@media (max-width: 720px) {
+  .rankCards {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
+/* Each card is the bordered surface its rows live in; the title is a recessed
+   header strip, so the two rankings read as two equal panels. */
+.rankCard {
+  display: flex;
+  flex-direction: column;
   min-width: 0;
   border: 1px solid var(--dsw-alias-border-l1);
   border-radius: 10px;
@@ -511,6 +526,29 @@
   overflow: hidden;
 }
 
+.rankCardTitle {
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--dsw-alias-border-l1);
+  background: color-mix(in srgb, var(--dsw-alias-bg-layer-2) 55%, transparent);
+  color: var(--dsw-alias-label-secondary);
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.rankList {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+/* Every row opens a hover tip (the cross-dimension detail), so it carries the
+   same hover affordance as the chart marks. */
+.modelRow:hover {
+  background: color-mix(in srgb, var(--dsw-alias-bg-layer-2) 60%, transparent);
+}
+
 /* Position column: the row's rank inside its section. The Other bucket holds
    no single rank, so it renders an empty (but equally wide) cell. */
 .modelRank {
@@ -667,6 +705,35 @@
   margin-bottom: 4px;
 }
 
+/* A provider row's raw route id, kept out of the row label but reachable on
+   hover (the row shows the display name). */
+.tipSubtitle {
+  margin: -2px 0 4px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+}
+
+/* Breakdown heading inside a row tip: names the cross-dimension list under it
+   ("By provider" under a model, "By model" under a provider). */
+.tipLabel {
+  margin-bottom: 2px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+}
+
+/* The breakdown line pushes its volume to the right edge of the plate. */
+.tipName {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.tipValue {
+  margin-left: auto;
+  padding-left: 12px;
+  color: var(--dsw-alias-label-secondary);
+  font-variant-numeric: tabular-nums;
+}
+
 .tipRow {
   display: flex;
   align-items: center;

package/src/client/TokenTotalPanel.tsx

@@ -20,7 +20,7 @@
  */
 import { Fragment, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type RefObject } from 'react'
 import clsx from 'clsx'
-import { Activity, ArrowDownToLine, ArrowUpFromLine, ChevronDown, ChevronRight, Coins, Database, MessagesSquare } from 'lucide-react'
+import { Activity, ArrowDownToLine, ArrowUpFromLine, Coins, Database, MessagesSquare } from 'lucide-react'
 import { Button, Input, Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { DailyTokenUsage, ModelTokenUsage, ProviderTokenUsage, TokenTotalRange, TokenTotalRequest } from '../wire.ts'
 import { fetchRange, UsageApiError } from './api.ts'
@@ -52,8 +52,8 @@ const TOP_MODELS = 10
 const OTHER_MODEL = '\u0000other' // sentinel; cannot collide with a real model ref
 const OTHER_COLOR = 'var(--dsw-chart-other)'
 
-/** How many rows each bottom breakdown tab lists (requirement 下部: 展示前 5). */
-const TOP_BREAKDOWN = 5
+/** How many rows each ranking card lists (扩展到 8 个排行). */
+const TOP_BREAKDOWN = 8
 
 /** Shared empty key set: one stable identity for a collapsed expand state. */
 const NO_KEYS: ReadonlySet<string> = new Set()
@@ -254,7 +254,14 @@ export function TokenTotalPanel({ t }: { t: Translator }): JSX.Element {
           <StatCards stats={stats} t={t} />
           <Heatmap daily={heatDaily} from={heatWindow.from} to={heatWindow.to} t={t} panelRef={panelRef} />
           <DailyTrend models={trendModels} daily={trendDaily} granularity={stats?.granularity ?? 'day'} t={t} colorForModel={colorForModel} panelRef={panelRef} />
-          <UsageBreakdown models={stats.models} providers={stats.providers} total={stats.tokens} t={t} />
+          <UsageBreakdown
+            models={stats.models}
+            providers={stats.providers}
+            total={stats.tokens}
+            providerNames={stats.providerNames}
+            t={t}
+            panelRef={panelRef}
+          />
           {stats.to && (
             <div className={css.foot}>
               {t('asOf')} {stats.to}
@@ -275,7 +282,7 @@ export function TokenTotalPanel({ t }: { t: Translator }): JSX.Element {
  *  (zero input/output but real cache hits) or a failed-call day (requests
  *  but no tokens) both carry real usage and must not read as "no data". */
 function isEmptyRange(stats: TokenTotalRange): boolean {
-  return stats.tokens === 0 && stats.cacheHit === 0 && stats.requests === 0 && stats.turns === 0
+  return stats.tokens === 0 && stats.cacheHit === 0 && stats.requests === 0 && stats.failures === 0 && stats.turns === 0
 }
 
 function StatCards({ stats, t }: { stats: TokenTotalRange; t: Translator }) {
@@ -292,8 +299,10 @@ function StatCards({ stats, t }: { stats: TokenTotalRange; t: Translator }) {
     { icon: Database, label: t('cacheTokens'), value: formatCompact(stats.cacheTokens), sub: `${formatTokens(stats.cacheTokens)} ${t('tokensUnit')}` },
     // 缓存命中率 —cached share of all prompt tokens in the range.
     { icon: Activity, label: t('cacheRate'), value: cacheRateText(stats.cacheHit, stats.cacheMiss), hint: t('cacheRateHint'), sub: `${formatCompact(stats.cacheHit)} ${t('cachedTokens')}` },
-    // 请求数量 —provider calls (tokens or not).
-    { icon: MessagesSquare, label: t('requests'), value: String(stats.requests) },
+    // 请求数量 —provider calls (tokens or not). The failed share sits
+    // underneath, and only when there were any: a healthy range stays a
+    // single line. Failed calls are a SUBSET of requests, never additive.
+    { icon: MessagesSquare, label: t('requests'), value: String(stats.requests), sub: stats.failures > 0 ? `${t('requestsFailed')} ${stats.failures} · ${formatPercent((stats.failures / Math.max(stats.requests, 1)) * 100)}` : undefined },
   ]
   return (
     <div className={css.cards}>
@@ -683,104 +692,243 @@ function DailyTrend({ models, daily, granularity, t, colorForModel, panelRef }:
   )
 }
 
-// ── Section 6: bottom breakdown — top 5 by model / by provider ────────
+// ── Section 6: bottom ranking — top 8 by model / by provider ──────────────
 //
-// Requirement 下部: two tabs, one ranking by MODEL and one by PROVIDER, each
-// listing the top 5 names with total tokens and the cache hit rate.
+// Two side-by-side cards, always on screen (no tabs): the left card ranks
+// MODELS, the right ranks PROVIDERS, each listing its top 8 rows.
 //
-// The by-model tab aggregates by MODEL NAME, not by the provider/model ref:
+// The by-model card aggregates by MODEL NAME, not by the provider/model ref:
 // the same model served through two providers must show as ONE row
-// (同名模型不同供应商需要聚合). The by-provider tab is already aggregated by
-// provider upstream, so it ranks the provider rows the host returned.
+// (同名模型不同供应商需要聚合). The by-provider card is already aggregated by
+// provider upstream, so it ranks the provider rows the host returned, labelled
+// with the selector's display name (`providerNames`).
+//
+// Both cards keep the same row anatomy — rank, swatch, name, tokens, share,
+// cache hit rate — and move the cross-dimension detail into the hover tip: a
+// model row explains which providers served it, a provider row explains which
+// models it served. Hovering therefore never displaces the share column.
+
+/** One child line of a row's hover detail (a provider under a model, or a
+ *  model under a provider). `tokens` is null when the host payload predates
+ *  the cross-dimension split and only the source NAME is known. */
+interface RankChild {
+  key: string
+  name: string
+  tokens: number | null
+  color: string
+}
+
+/** The hover detail of one ranked row. The tip itself renders once, in
+ *  UsageBreakdown, so only one row can be explained at a time. */
+interface RankTip {
+  anchor: Element
+  title: string
+  /** The raw route id, set only when it differs from the display label. */
+  subtitle?: string
+  tokens: number
+  cacheHit: number
+  cacheMiss: number
+  breakdownLabel: string
+  breakdown: RankChild[]
+}
 
 interface BreakdownRow {
   key: string
   name: string
-  detail?: string
+  subtitle?: string
   tokens: number
   cacheHit: number
   cacheMiss: number
   color: string
+  breakdownLabel: string
+  breakdown: RankChild[]
 }
 
-function UsageBreakdown({ models, providers, total, t }: {
+/** Provider hues run 1..5 then the gray tail (a provider beyond the palette is
+ *  rare: the card lists 8 rows, the palette names 5). */
+function providerColor(index: number): string {
+  return index < 5 ? `var(--dsw-provider-${index + 1})` : 'var(--dsw-provider-other)'
+}
+
+/** Model hues run 1..10 then the gray Other step (mirrors colorForModel). */
+function modelColor(index: number): string {
+  return index < TOP_MODELS ? `var(--dsw-chart-${index + 1})` : OTHER_COLOR
+}
+
+function UsageBreakdown({ models, providers, total, providerNames, t, panelRef }: {
   models: ModelTokenUsage[]
   providers: ProviderTokenUsage[]
   total: number
+  providerNames?: Record<string, string>
   t: Translator
+  panelRef: RefObject<HTMLDivElement | null>
 }) {
-  const [tab, setTab] = useState<'model' | 'provider'>('model')
+  const [tip, setTip] = useState<RankTip | null>(null)
+
+  // The display label for a provider route: the host-resolved selector name
+  // when there is one, else the raw historical id (a deleted/renamed route).
+  // The typeof guard keeps a prototype-shaped key ("constructor") from being
+  // read as a label.
+  const providerLabel = useCallback((provider: string): string => {
+    const named = providerNames?.[provider]
+    return typeof named === 'string' && named.trim() !== '' ? named : provider
+  }, [providerNames])
+
+  const shareText = (n: number): string => (total > 0 ? formatPercent((n / total) * 100) : '—')
 
   const modelRows = useMemo<BreakdownRow[]>(() => {
-    const byName = new Map<string, { tokens: number; cacheHit: number; cacheMiss: number; providers: Set<string> }>()
+    const byName = new Map<string, {
+      tokens: number
+      cacheHit: number
+      cacheMiss: number
+      /** Provider -> tokens, from the host's cross-dimension split. */
+      split: Map<string, number>
+      /** Every provider the host named, split or not. */
+      sources: Set<string>
+    }>()
     for (const m of models) {
       const name = m.model
-      const acc = byName.get(name) ?? { tokens: 0, cacheHit: 0, cacheMiss: 0, providers: new Set<string>() }
+      const acc = byName.get(name) ?? { tokens: 0, cacheHit: 0, cacheMiss: 0, split: new Map<string, number>(), sources: new Set<string>() }
       acc.tokens += m.tokens
       acc.cacheHit += m.cacheHit
       acc.cacheMiss += m.cacheMiss
-      for (const provider of m.providers ?? [m.provider]) acc.providers.add(provider)
+      for (const item of m.providerTokens ?? []) {
+        acc.split.set(item.provider, (acc.split.get(item.provider) ?? 0) + item.tokens)
+      }
+      for (const provider of m.providers ?? (m.provider === '' ? [] : [m.provider])) acc.sources.add(provider)
       byName.set(name, acc)
     }
     return [...byName.entries()]
       .sort((a, b) => b[1].tokens - a[1].tokens)
       .slice(0, TOP_BREAKDOWN)
-      .map(([name, acc], i) => ({
-        key: name,
-        name,
-        detail: acc.providers.size > 1 ? [...acc.providers].join(', ') : undefined,
-        tokens: acc.tokens,
-        cacheHit: acc.cacheHit,
-        cacheMiss: acc.cacheMiss,
-        color: `var(--dsw-chart-${i + 1})`,
-      }))
-  }, [models])
+      .map(([name, acc], i) => {
+        const split: RankChild[] = [...acc.split.entries()]
+          .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+          .map(([provider, tokens], j) => ({ key: provider, name: providerLabel(provider), tokens, color: providerColor(j) }))
+        // A payload from before the split still names its sources; list them
+        // without a volume rather than inventing a number.
+        const known = new Set(split.map((child) => child.key))
+        const named: RankChild[] = [...acc.sources]
+          .filter((provider) => !known.has(provider))
+          .sort()
+          .map((provider, j) => ({ key: provider, name: providerLabel(provider), tokens: null, color: providerColor(split.length + j) }))
+        return {
+          key: name,
+          name,
+          tokens: acc.tokens,
+          cacheHit: acc.cacheHit,
+          cacheMiss: acc.cacheMiss,
+          color: modelColor(i),
+          breakdownLabel: t('byProvider'),
+          breakdown: [...split, ...named],
+        }
+      })
+  }, [models, providerLabel, t])
 
   const providerRows = useMemo<BreakdownRow[]>(() => {
     return [...providers]
       .filter((p) => p.tokens > 0)
       .sort((a, b) => b.tokens - a.tokens)
       .slice(0, TOP_BREAKDOWN)
-      .map((p, i) => ({
-        key: p.provider,
-        name: p.provider,
-        tokens: p.tokens,
-        cacheHit: p.cacheHit,
-        cacheMiss: p.cacheMiss,
-        color: `var(--dsw-provider-${i + 1})`,
-      }))
-  }, [providers])
-
-  const rows = tab === 'model' ? modelRows : providerRows
-  const share = (n: number): string => (total > 0 ? formatPercent((n / total) * 100) : '—')
+      .map((p, i) => {
+        const label = providerLabel(p.provider)
+        return {
+          key: p.provider,
+          name: label,
+          // Keep the route id reachable: the row shows the display name only.
+          subtitle: label === p.provider ? undefined : p.provider,
+          tokens: p.tokens,
+          cacheHit: p.cacheHit,
+          cacheMiss: p.cacheMiss,
+          color: providerColor(i),
+          breakdownLabel: t('byModel'),
+          breakdown: [...(p.modelTokens ?? [])]
+            .sort((a, b) => b.tokens - a.tokens || a.model.localeCompare(b.model))
+            .map((m, j) => ({ key: m.model, name: m.model, tokens: m.tokens, color: modelColor(j) })),
+        }
+      })
+  }, [providers, providerLabel, t])
 
   return (
     <section className={css.section}>
       <div className={css.sectionHead}>
-        {/* One title for both tabs: the section is ONE ranking, seen through
-            two lenses (by model / by provider), so the heading names the
-            section rather than the current lens. */}
+        {/* One heading for the whole section: both rankings are always on
+            screen, side by side, so there is no lens to switch. */}
         <h3 className={css.sectionTitle}>{t('usageRanking')}</h3>
-        <div className={css.group} role="tablist" aria-label={t('usageRanking')}>
-          <Button size="sm" variant="ghost" role="tab" aria-selected={tab === 'model'} className={clsx(css.segItem, tab === 'model' && css.segActive)} onClick={() => setTab('model')}>
-            {t('byModel')}
-          </Button>
-          <Button size="sm" variant="ghost" role="tab" aria-selected={tab === 'provider'} className={clsx(css.segItem, tab === 'provider' && css.segActive)} onClick={() => setTab('provider')}>
-            {t('byProvider')}
-          </Button>
-        </div>
       </div>
+      <div className={css.rankCards}>
+        <RankCard title={t('byModel')} rows={modelRows} total={total} t={t} onTip={setTip} />
+        <RankCard title={t('byProvider')} rows={providerRows} total={total} t={t} onTip={setTip} />
+      </div>
+      <ChartTip anchor={tip?.anchor ?? null} panelRef={panelRef}>
+        {tip && (
+          <>
+            <div className={css.tipTitle}>{tip.title}</div>
+            {tip.subtitle !== undefined && <div className={css.tipSubtitle}>{tip.subtitle}</div>}
+            <div className={css.tipRow}>{t('total')} {formatTokens(tip.tokens)} · {shareText(tip.tokens)}</div>
+            <div className={css.tipRow}>{t('cacheRateColumn')} {cacheRateText(tip.cacheHit, tip.cacheMiss)}</div>
+            {tip.breakdown.length > 0 && (
+              <div className={css.tipBreakdown}>
+                <div className={css.tipLabel}>{tip.breakdownLabel}</div>
+                {tip.breakdown.map((child) => (
+                  <div key={child.key} className={css.tipRow}>
+                    <i className={css.legendSwatch} style={{ background: child.color }} />
+                    <span className={css.tipName}>{child.name}</span>
+                    <span className={css.tipValue}>
+                      {child.tokens === null ? '' : `${formatCompact(child.tokens)} · ${shareText(child.tokens)}`}
+                    </span>
+                  </div>
+                ))}
+              </div>
+            )}
+          </>
+        )}
+      </ChartTip>
+    </section>
+  )
+}
+
+/** One ranking card: a titled list whose rows explain themselves on hover.
+ *  The tip is owned by UsageBreakdown (one open tip at a time), so a row only
+ *  reports which row it is, never where to draw. */
+function RankCard({ title, rows, total, t, onTip }: {
+  title: string
+  rows: BreakdownRow[]
+  total: number
+  t: Translator
+  onTip: (tip: RankTip | null) => void
+}) {
+  const share = (n: number): string => (total > 0 ? formatPercent((n / total) * 100) : '—')
+  return (
+    <div className={css.rankCard}>
+      <div className={css.rankCardTitle}>{title}</div>
       {rows.length === 0 ? (
         <div className={css.empty}>{t('empty')}</div>
       ) : (
-        <ul className={css.modelList} data-dsh-usage-glass="list">
+        <ul className={css.rankList} data-dsh-usage-glass="list">
           {rows.map((r, rank) => (
-            <li key={r.key} className={css.modelRow}>
+            <li
+              key={r.key}
+              className={css.modelRow}
+              onMouseEnter={(e) => onTip({
+                anchor: e.currentTarget,
+                title: r.name,
+                subtitle: r.subtitle,
+                tokens: r.tokens,
+                cacheHit: r.cacheHit,
+                cacheMiss: r.cacheMiss,
+                breakdownLabel: r.breakdownLabel,
+                breakdown: r.breakdown,
+              })}
+              onMouseLeave={() => onTip(null)}
+            >
               <span className={css.modelRank} aria-hidden="true">{rank + 1}</span>
               <i className={css.legendSwatch} style={{ background: r.color }} />
               <div className={css.modelId}>
                 <span className={css.modelName}>{r.name}</span>
-                <span className={css.modelProvider}>{r.detail ?? share(r.tokens)}</span>
+                {/* The share keeps its own line: the hover detail never
+                    displaces it (悬浮详情不占用百分比的位置). */}
+                <span className={css.modelProvider}>{share(r.tokens)}</span>
               </div>
               <div className={css.modelValues}>
                 <span className={css.modelTokens}>{formatCompact(r.tokens)}</span>
@@ -790,7 +938,7 @@ function UsageBreakdown({ models, providers, total, t }: {
           ))}
         </ul>
       )}
-    </section>
+    </div>
   )
 }
 

package/src/client/context-meter-core.ts

@@ -0,0 +1,54 @@
+export interface ContextPressureLike {
+  projectedTokens?: number
+  pressureTokens?: number
+  contextWindow?: number
+}
+
+export interface ContextBreakdownLike {
+  systemTokens: number
+  toolsTokens: number
+  messageTokens: number
+}
+
+export interface ContextOccupancy {
+  percent: number
+  usedTokens: number
+  contextWindow: number
+}
+
+/** Mirrors the host meter's occupancy calculation exactly. */
+export function contextOccupancy(pressure: ContextPressureLike | undefined): ContextOccupancy | null {
+  const usedTokens = pressure?.projectedTokens ?? pressure?.pressureTokens
+  if (usedTokens === undefined || pressure?.contextWindow === undefined) return null
+  return {
+    percent: Math.min(100, Math.round(usedTokens / pressure.contextWindow * 100)),
+    usedTokens,
+    contextWindow: pressure.contextWindow,
+  }
+}
+
+export function contextBreakdownTotal(breakdown: ContextBreakdownLike | undefined): number {
+  return breakdown === undefined ? 0 : breakdown.systemTokens + breakdown.toolsTokens + breakdown.messageTokens
+}
+
+export function contextBreakdownSegments(
+  percent: number,
+  breakdown: ContextBreakdownLike | undefined,
+): Array<{ key: string; width: number }> {
+  const total = contextBreakdownTotal(breakdown)
+  if (breakdown === undefined || total === 0) return [{ key: 'total', width: percent }]
+  return [
+    { key: 'systemTokens', width: percent * breakdown.systemTokens / total },
+    { key: 'toolsTokens', width: percent * breakdown.toolsTokens / total },
+    { key: 'messageTokens', width: percent * breakdown.messageTokens / total },
+  ].filter(segment => segment.width > 0)
+}
+
+export function formatContextTokens(value: number, units: { thousand: string; million: string }): string {
+  const scaled = (candidate: number): string => candidate >= 100
+    ? String(Math.round(candidate))
+    : String(Math.round(candidate * 10) / 10)
+  if (value < 1e3) return String(value)
+  if (value < 1e6) return units.thousand.replace('{value}', scaled(value / 1e3))
+  return units.million.replace('{value}', scaled(value / 1e6))
+}

package/src/client/context-takeover.ts

@@ -0,0 +1,35 @@
+/** The host ContextMeter is hard-coded beside composer.dock, not a slot.
+ * Suppress only that recognizable sibling while our replacement is mounted;
+ * never hide a whole dock, slot wrapper, or another plugin's readout. */
+export function installContextTakeover(anchor: HTMLElement): () => void {
+  const dock = anchor.closest<HTMLElement>('[data-composer-dock]')
+  const view = anchor.ownerDocument.defaultView
+  if (dock === null || view === null) return () => {}
+  const hidden = new Map<HTMLElement, { display: string; priority: string }>()
+  const reconcile = (): void => {
+    for (const sibling of Array.from(dock.children)) {
+      if (!(sibling instanceof view.HTMLElement) || sibling.tagName !== 'SPAN'
+        || sibling.contains(anchor) || sibling.hasAttribute('data-slot-entry')
+        || sibling.hasAttribute('data-dsh-token-total-stat')
+        || hidden.has(sibling)) continue
+      // ContextMeter's stable SVG geometry, not a private CSS-module hash or
+      // a translated label. Current hosts mount its span directly in the dock.
+      if (sibling.querySelector('button[aria-haspopup="dialog"] svg[viewBox="0 0 14 14"] circle[cx="7"][cy="7"][r="5.5"]') === null) continue
+      hidden.set(sibling, { display: sibling.style.getPropertyValue('display'), priority: sibling.style.getPropertyPriority('display') })
+      sibling.setAttribute('data-dsh-token-total-native-context', '')
+      sibling.style.setProperty('display', 'none', 'important')
+    }
+  }
+  reconcile()
+  const observer = new view.MutationObserver(reconcile)
+  observer.observe(dock, { childList: true, subtree: true })
+  return () => {
+    observer.disconnect()
+    for (const [element, previous] of hidden) {
+      element.removeAttribute('data-dsh-token-total-native-context')
+      if (previous.display === '') element.style.removeProperty('display')
+      else element.style.setProperty('display', previous.display, previous.priority)
+    }
+    hidden.clear()
+  }
+}