Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🎨 feat: Color the Context Gauge by Category and Collapse its Breakdown (#14855)

Danny Avila530a935a7476
diff --git a/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx b/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx
index cf5eff2c97..0a975ca73f 100644
--- a/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx
+++ b/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx
@@ -1,5 +1,8 @@
import '@testing-library/jest-dom/extend-expect';
-import { render, screen } from '@testing-library/react';
+import { Provider } from 'jotai';
+import userEvent from '@testing-library/user-event';
+import { Constants, Tools } from 'librechat-data-provider';
+import { render, screen, within } from '@testing-library/react';
import type { TokenUsageView } from '~/hooks/Chat/useTokenUsage';
import Breakdown from './Breakdown';
@@ -37,22 +40,199 @@ const view = {
messagesPruned: false,
} as TokenUsageView;
+/** A snapshot-backed branch: messages, instructions, and one tool per group,
+ * with a deferred entry on both the system and MCP families. */
+const snapshotView = {
+ ...view,
+ usedTokens: 1000,
+ maxTokens: 2000,
+ percent: 50,
+ isEstimate: false,
+ snapshotActive: true,
+ effectiveInstructionTokens: 0,
+ snapshot: {
+ anchorMessageId: 'message-1',
+ effectiveInstructionTokens: 400,
+ breakdown: {
+ maxContextTokens: 2000,
+ instructionTokens: 400,
+ systemMessageTokens: 100,
+ dynamicInstructionTokens: 20,
+ toolSchemaTokens: 280,
+ summaryTokens: 50,
+ toolCount: 5,
+ messageCount: 4,
+ messageTokens: 550,
+ availableForMessages: 1600,
+ toolTokenCounts: {
+ web_search: 90,
+ deferred_tool: 30,
+ [`server${Constants.mcp_delimiter}tool`]: 80,
+ [`server${Constants.mcp_delimiter}lazy`]: 40,
+ [Tools.skill]: 25,
+ [Constants.SUBAGENT]: 15,
+ },
+ deferredToolNames: ['deferred_tool', `server${Constants.mcp_delimiter}lazy`],
+ },
+ },
+} as unknown as TokenUsageView;
+
+const renderBreakdown = (props: Partial<React.ComponentProps<typeof Breakdown>> = {}) =>
+ render(
+ <Provider>
+ <Breakdown view={view} showCost={false} {...props} />
+ </Provider>,
+ );
+
+const toggle = () => screen.getByTestId('context-breakdown-toggle');
+
+beforeEach(() => {
+ localStorage.clear();
+});
+
describe('TokenUsage Breakdown', () => {
- it('renders the Langfuse session as an external link when available', () => {
- const url = 'https://cloud.langfuse.com/project/project-1/sessions/conversation-1';
+ describe('collapse', () => {
+ it('opens showing only the gauge, with the detail behind the disclosure', () => {
+ renderBreakdown();
+
+ expect(toggle()).toHaveAttribute('aria-expanded', 'false');
+ expect(screen.getByRole('progressbar')).toBeInTheDocument();
+ expect(screen.queryByTestId('token-usage-totals')).not.toBeInTheDocument();
+ });
+
+ it('reveals the detail once expanded', async () => {
+ renderBreakdown();
+
+ await userEvent.click(toggle());
+
+ expect(toggle()).toHaveAttribute('aria-expanded', 'true');
+ expect(screen.getByTestId('token-usage-totals')).toBeInTheDocument();
+ });
+
+ it('persists the expanded choice across mounts', async () => {
+ const { unmount } = renderBreakdown();
+ await userEvent.click(toggle());
+ unmount();
+
+ renderBreakdown();
+
+ expect(toggle()).toHaveAttribute('aria-expanded', 'true');
+ expect(screen.getByTestId('token-usage-totals')).toBeInTheDocument();
+ });
+
+ it('keeps the gauge readout visible while collapsed', () => {
+ renderBreakdown({ view: snapshotView });
+
+ expect(within(toggle()).getByText('1K / 2K (50%)')).toBeInTheDocument();
+ });
+ });
+
+ describe('segments', () => {
+ it('stacks the segments in slot order, deferred beside its parent', () => {
+ renderBreakdown({ view: snapshotView });
+
+ const segments = Array.from(screen.getByRole('progressbar').children) as HTMLElement[];
- render(<Breakdown view={view} showCost={false} langfuseSessionUrl={url} />);
+ expect(
+ segments.map(
+ (segment) => /(?:bg-series-\d(?:\/25)?)/.exec(segment.className)?.[0] ?? 'none',
+ ),
+ ).toEqual([
+ 'bg-series-1/25', // messages
+ 'bg-series-2', // system prompt
+ 'bg-series-3', // system tools
+ 'bg-series-3', // system tools, deferred
+ 'bg-series-4', // mcp tools
+ 'bg-series-4', // mcp tools, deferred
+ 'bg-series-5', // skills
+ 'bg-series-6', // subagents
+ 'bg-series-7', // summary
+ ]);
+ });
- expect(screen.getByRole('link', { name: 'com_ui_langfuse_view_session' })).toHaveAttribute(
- 'href',
- url,
- );
- expect(screen.getByRole('link')).toHaveAttribute('target', '_blank');
+ it('drops a category that contributes nothing', () => {
+ const noSkills = JSON.parse(JSON.stringify(snapshotView)) as TokenUsageView;
+ delete noSkills.snapshot?.breakdown.toolTokenCounts?.[Tools.skill];
+
+ renderBreakdown({ view: noSkills });
+
+ expect(screen.getByRole('progressbar').children).toHaveLength(8);
+ expect(screen.getByRole('progressbar').querySelector('.bg-series-5')).toBeNull();
+ });
+
+ it('gives the deferred rows their family slot and a hatch', async () => {
+ renderBreakdown({ view: snapshotView });
+ await userEvent.click(toggle());
+
+ const breakdown = screen.getByTestId('context-breakdown');
+ const rowFor = (label: string) =>
+ within(breakdown).getByText(label).parentElement as HTMLElement;
+
+ const system = rowFor('com_ui_context_tools_system').firstElementChild as HTMLElement;
+ const deferred = rowFor('com_ui_context_tools_system_deferred')
+ .firstElementChild as HTMLElement;
+
+ expect(system).toHaveClass('bg-series-3');
+ expect(deferred).toHaveClass('bg-series-3');
+ expect(system.getAttribute('style') ?? '').not.toContain('repeating-linear-gradient');
+ expect(deferred.getAttribute('style')).toContain('repeating-linear-gradient');
+ });
+
+ it('marks Messages as the one translucent, edged segment', async () => {
+ renderBreakdown({ view: snapshotView });
+ await userEvent.click(toggle());
+
+ const messages = within(screen.getByTestId('context-breakdown')).getByText(
+ 'com_ui_context_messages',
+ ).parentElement?.firstElementChild as HTMLElement;
+
+ expect(messages).toHaveClass('bg-series-1/25');
+ expect(messages).toHaveClass('ring-series-1');
+ });
+
+ it('leaves the estimate path unsegmented, with no swatches on its rows', async () => {
+ renderBreakdown();
+ await userEvent.click(toggle());
+
+ const estimate = screen.getByTestId('context-estimate');
+
+ expect(estimate).toBeInTheDocument();
+ expect(estimate.querySelector('[class*="bg-series-"]')).toBeNull();
+ });
+ });
+
+ describe('totals', () => {
+ it('labels the usage section so the numbers are not read as context', async () => {
+ renderBreakdown();
+ await userEvent.click(toggle());
+
+ expect(
+ within(screen.getByTestId('token-usage-totals')).getByRole('heading', {
+ name: 'com_ui_context_totals',
+ }),
+ ).toBeInTheDocument();
+ });
});
- it('omits the Langfuse session link when no traced message is available', () => {
- render(<Breakdown view={view} showCost={false} />);
+ describe('langfuse', () => {
+ const url = 'https://cloud.langfuse.com/project/project-1/sessions/conversation-1';
+
+ it('renders the Langfuse session as an external link when available', async () => {
+ renderBreakdown({ langfuseSessionUrl: url });
+ await userEvent.click(toggle());
+
+ expect(screen.getByRole('link', { name: 'com_ui_langfuse_view_session' })).toHaveAttribute(
+ 'href',
+ url,
+ );
+ expect(screen.getByRole('link')).toHaveAttribute('target', '_blank');
+ });
+
+ it('omits the Langfuse session link when no traced message is available', async () => {
+ renderBreakdown();
+ await userEvent.click(toggle());
- expect(screen.queryByRole('link')).not.toBeInTheDocument();
+ expect(screen.queryByRole('link')).not.toBeInTheDocument();
+ });
});
});
diff --git a/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx b/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx
index ec9a7ee462..02b5983836 100644
--- a/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx
+++ b/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx
@@ -1,25 +1,52 @@
-import { Button } from '@librechat/client';
-import { ExternalLink } from 'lucide-react';
+import { useAtom } from 'jotai';
+import { ChevronDown, ExternalLink } from 'lucide-react';
+import {
+ Button,
+ Collapsible,
+ MeterSwatch,
+ SegmentedMeter,
+ CollapsibleContent,
+ CollapsibleTrigger,
+} from '@librechat/client';
+import type { MeterSegment } from '@librechat/client';
import type { TokenUsageView } from '~/hooks/Chat/useTokenUsage';
import type { CurrencyConfig } from '~/utils';
import { groupToolTokens, formatTokens, formatCost } from '~/utils';
+import { contextBreakdownExpandedAtom } from '~/store/usage';
import { useLocalize } from '~/hooks';
+/** Row text lifts to primary ink while the row is hovered or holds focus. */
+const HOVER_INK =
+ 'transition-colors group-hover:text-text-primary group-focus-within:text-text-primary';
+
interface RowProps {
label: string;
value: number;
max?: number;
+ /** Present only when the row corresponds to real estate in the meter */
+ segment?: Pick<MeterSegment, 'slot' | 'hatched' | 'outlined'>;
+ /** The free-space remainder, keyed to the bare track rather than a series */
+ track?: boolean;
}
-function Row({ label, value, max }: RowProps) {
+function Row({ label, value, max, segment, track }: RowProps) {
const percent = max != null && max > 0 ? Math.min((value / max) * 100, 100) : null;
return (
- <div className="flex items-center justify-between gap-4 text-sm">
- <span className="text-text-secondary">{label}</span>
+ <div className="group flex items-center justify-between gap-4 text-sm">
+ <span className="flex min-w-0 items-center gap-2">
+ {segment != null && <MeterSwatch segment={segment} />}
+ {track === true && (
+ <span
+ aria-hidden="true"
+ className="size-2 flex-none rounded-sm bg-surface-tertiary ring-1 ring-inset ring-border-medium"
+ />
+ )}
+ <span className={`text-text-secondary ${HOVER_INK}`}>{label}</span>
+ </span>
<span className="font-medium text-text-primary">
{formatTokens(value)}
{percent != null && (
- <span className="ml-1 text-xs text-text-secondary" aria-hidden="true">
+ <span className={`ml-1 text-xs text-text-secondary ${HOVER_INK}`} aria-hidden="true">
({Math.round(percent)}%)
</span>
)}
@@ -42,6 +69,7 @@ export default function Breakdown({
langfuseSessionUrl,
}: BreakdownProps) {
const localize = useLocalize();
+ const [expanded, setExpanded] = useAtom(contextBreakdownExpandedAtom);
const { usedTokens, maxTokens, percent, snapshot, snapshotActive, branchUsage, hasUsage } = view;
/** Show the all-branches total only when it (a) exceeds the active branch —
* epsilon guards against float summation order surfacing a spurious row in an
@@ -66,175 +94,240 @@ export default function Breakdown({
breakdown?.toolTokenCounts != null
? groupToolTokens(breakdown.toolTokenCounts, breakdown.deferredToolNames)
: null;
- const toolRows =
- groups == null
- ? null
- : ([
- [localize('com_ui_context_tools_system'), groups.system],
- [localize('com_ui_context_tools_mcp'), groups.mcp],
- [localize('com_ui_skills'), groups.skills],
- [localize('com_ui_context_subagents'), groups.subagents],
- [localize('com_ui_context_tools_system_deferred'), groups.systemDeferred],
- [localize('com_ui_context_tools_mcp_deferred'), groups.mcpDeferred],
- ] as const);
- return (
- <div className="w-64 space-y-3" role="region" aria-label={localize('com_ui_context_usage')}>
- <div className="flex items-center justify-between">
- <span className="text-sm font-medium text-text-primary">
- {localize('com_ui_context_window')}
- </span>
- <span className="text-xs font-medium text-text-secondary">
- {maxTokens != null
- ? `${formatTokens(usedTokens)} / ${formatTokens(maxTokens)} (${Math.round(percent)}%)`
- : formatTokens(usedTokens)}
- </span>
- </div>
+ /** Single source of truth for both the meter and its legend: a row carries a
+ * swatch if and only if it is a segment, so the two can never disagree.
+ * Deferred tools keep their family's slot and are hatched — same identity,
+ * held out of the active set. */
+ const segments: Array<MeterSegment & { label: string }> =
+ breakdown == null
+ ? []
+ : [
+ {
+ id: 'messages',
+ label: localize('com_ui_context_messages'),
+ value: messageTokens,
+ slot: 1,
+ outlined: true,
+ },
+ { id: 'system', label: localize('com_ui_context_system'), value: systemTokens, slot: 2 },
+ ...(groups == null
+ ? [
+ {
+ id: 'tools',
+ label: localize('com_ui_context_tools'),
+ value: breakdown.toolSchemaTokens,
+ slot: 3,
+ },
+ ]
+ : [
+ {
+ id: 'tools-system',
+ label: localize('com_ui_context_tools_system'),
+ value: groups.system,
+ slot: 3,
+ },
+ {
+ id: 'tools-system-deferred',
+ label: localize('com_ui_context_tools_system_deferred'),
+ value: groups.systemDeferred,
+ slot: 3,
+ hatched: true,
+ },
+ {
+ id: 'tools-mcp',
+ label: localize('com_ui_context_tools_mcp'),
+ value: groups.mcp,
+ slot: 4,
+ },
+ {
+ id: 'tools-mcp-deferred',
+ label: localize('com_ui_context_tools_mcp_deferred'),
+ value: groups.mcpDeferred,
+ slot: 4,
+ hatched: true,
+ },
+ { id: 'skills', label: localize('com_ui_skills'), value: groups.skills, slot: 5 },
+ {
+ id: 'subagents',
+ label: localize('com_ui_context_subagents'),
+ value: groups.subagents,
+ slot: 6,
+ },
+ ]),
+ {
+ id: 'summary',
+ label: localize('com_ui_context_summary'),
+ value: breakdown.summaryTokens,
+ slot: 7,
+ },
+ ];
- <div
- role="progressbar"
- aria-valuemin={0}
- aria-valuemax={100}
- aria-valuenow={maxTokens != null ? Math.round(percent) : undefined}
- aria-label={localize('com_ui_context_usage')}
- className="h-2 w-full overflow-hidden rounded-full bg-surface-tertiary"
- >
- {percent > 0 && (
- <div
- className="h-full rounded-full bg-text-primary transition-all duration-300"
- style={{ width: `${Math.min(percent, 100)}%` }}
- />
- )}
- </div>
+ /** The estimate path knows the total but not the composition, so it keeps a
+ * single unsegmented fill and its rows carry no swatches. */
+ const meterSegments: MeterSegment[] =
+ segments.length > 0 ? segments : [{ id: 'used', value: usedTokens, slot: 1, outlined: true }];
- <div
- className="space-y-1.5"
- data-testid={breakdown ? 'context-breakdown' : 'context-estimate'}
- >
- {breakdown ? (
- <>
- <Row
- label={localize('com_ui_context_messages')}
- value={messageTokens}
- max={maxTokens}
+ return (
+ <div className="w-72" role="region" aria-label={localize('com_ui_context_usage')}>
+ <Collapsible open={expanded} onOpenChange={setExpanded} className="space-y-3">
+ <CollapsibleTrigger
+ className="group flex w-full items-center justify-between gap-2 rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring-primary"
+ data-testid="context-breakdown-toggle"
+ >
+ <span className="whitespace-nowrap text-sm font-medium text-text-primary">
+ {localize('com_ui_context_window')}
+ </span>
+ <span className="flex items-center gap-1 whitespace-nowrap text-xs font-medium text-text-secondary">
+ <span className={HOVER_INK}>
+ {maxTokens != null
+ ? `${formatTokens(usedTokens)} / ${formatTokens(maxTokens)} (${Math.round(percent)}%)`
+ : formatTokens(usedTokens)}
+ </span>
+ <ChevronDown
+ aria-hidden="true"
+ className="size-3.5 shrink-0 text-text-tertiary transition-transform duration-200 group-data-[state=open]:rotate-180 motion-reduce:transition-none"
/>
- {systemTokens > 0 && (
- <Row label={localize('com_ui_context_system')} value={systemTokens} max={maxTokens} />
- )}
- {toolRows != null ? (
- toolRows.map(
- ([label, value]) =>
- value > 0 && <Row key={label} label={label} value={value} max={maxTokens} />,
- )
- ) : (
- <Row
- label={localize('com_ui_context_tools')}
- value={breakdown.toolSchemaTokens}
- max={maxTokens}
- />
- )}
- {breakdown.summaryTokens > 0 && (
- <Row
- label={localize('com_ui_context_summary')}
- value={breakdown.summaryTokens}
- max={maxTokens}
- />
- )}
- {freeTokens != null && (
- <Row label={localize('com_ui_context_free')} value={freeTokens} max={maxTokens} />
- )}
- </>
- ) : (
- <>
- {view.branchTotals.summaryBaseline > 0 && (
- <Row
- label={localize('com_ui_context_summary')}
- value={view.branchTotals.summaryBaseline}
- max={maxTokens}
- />
- )}
- {view.messagesPruned ? (
- /** Over-window: the per-category split no longer describes what's
- * sent, so show the pruned message total (incl. in-flight). */
- <Row
- label={localize('com_ui_context_messages')}
- value={view.messageTokens + view.liveTokens}
- max={maxTokens}
- />
+ </span>
+ </CollapsibleTrigger>
+
+ <SegmentedMeter
+ segments={maxTokens != null ? meterSegments : []}
+ max={maxTokens ?? 1}
+ role="progressbar"
+ aria-valuemin={0}
+ aria-valuemax={100}
+ aria-valuenow={maxTokens != null ? Math.round(percent) : undefined}
+ aria-label={localize('com_ui_context_usage')}
+ />
+
+ <CollapsibleContent className="space-y-3 overflow-hidden data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down motion-reduce:animate-none">
+ <div
+ className="space-y-1.5"
+ data-testid={breakdown ? 'context-breakdown' : 'context-estimate'}
+ >
+ {breakdown ? (
+ <>
+ {segments.map(
+ ({ id, label, value, ...segment }) =>
+ value > 0 && (
+ <Row key={id} label={label} value={value} max={maxTokens} segment={segment} />
+ ),
+ )}
+ {freeTokens != null && (
+ <Row
+ label={localize('com_ui_context_free')}
+ value={freeTokens}
+ max={maxTokens}
+ track
+ />
+ )}
+ </>
) : (
<>
- <Row label={localize('com_ui_input')} value={view.branchTotals.input} />
- <Row
- label={localize('com_ui_output')}
- value={view.branchTotals.output + view.liveTokens}
- />
- {view.estimatedTokens > 0 && (
- <Row label={localize('com_ui_context_estimated')} value={view.estimatedTokens} />
+ {view.branchTotals.summaryBaseline > 0 && (
+ <Row
+ label={localize('com_ui_context_summary')}
+ value={view.branchTotals.summaryBaseline}
+ max={maxTokens}
+ />
+ )}
+ {view.messagesPruned ? (
+ /** Over-window: the per-category split no longer describes what's
+ * sent, so show the pruned message total (incl. in-flight). */
+ <Row
+ label={localize('com_ui_context_messages')}
+ value={view.messageTokens + view.liveTokens}
+ max={maxTokens}
+ />
+ ) : (
+ <>
+ <Row label={localize('com_ui_input')} value={view.branchTotals.input} />
+ <Row
+ label={localize('com_ui_output')}
+ value={view.branchTotals.output + view.liveTokens}
+ />
+ {view.estimatedTokens > 0 && (
+ <Row
+ label={localize('com_ui_context_estimated')}
+ value={view.estimatedTokens}
+ />
+ )}
+ </>
)}
+ {view.overheadTokens > 0 && (
+ <Row label={localize('com_ui_context_system')} value={view.overheadTokens} />
+ )}
+ {maxTokens == null && (
+ <p className="text-xs text-text-secondary">
+ {localize('com_ui_context_unknown')}
+ </p>
+ )}
+ <p className="text-xs italic text-text-secondary">{localize('com_ui_estimated')}</p>
</>
)}
- {view.overheadTokens > 0 && (
- <Row label={localize('com_ui_context_system')} value={view.overheadTokens} />
- )}
- {maxTokens == null && (
- <p className="text-xs text-text-secondary">{localize('com_ui_context_unknown')}</p>
- )}
- <p className="text-xs italic text-text-secondary">{localize('com_ui_estimated')}</p>
- </>
- )}
- </div>
-
- {hasUsage && (
- <>
- <div className="border-t border-border-light" role="separator" />
- <div className="space-y-1.5" data-testid="token-usage-totals">
- <Row label={localize('com_ui_input')} value={branchUsage.input} />
- <Row label={localize('com_ui_output')} value={branchUsage.output} />
- {branchUsage.cacheRead > 0 && (
- <Row label={localize('com_ui_cache_read')} value={branchUsage.cacheRead} />
- )}
- {branchUsage.cacheWrite > 0 && (
- <Row label={localize('com_ui_cache_write')} value={branchUsage.cacheWrite} />
- )}
</div>
- </>
- )}
- {showCost && hasUsage && branchUsage.costKnown && (
- <>
- <div className="border-t border-border-light" role="separator" />
- <div className="space-y-1.5" data-testid="token-usage-cost">
- <div className="flex items-center justify-between text-sm">
- <span className="text-text-secondary">
- {showTotal
- ? localize('com_ui_context_cost_branch')
- : localize('com_ui_context_cost')}
- </span>
- <span className="font-medium text-text-primary">
- {formatCost(view.branchCost, currency)}
- </span>
- </div>
- {showTotal && (
- <div className="flex items-center justify-between text-xs">
- <span className="text-text-secondary">{localize('com_ui_context_cost_total')}</span>
- <span className="text-text-secondary">{formatCost(view.totalCost, currency)}</span>
+ {hasUsage && (
+ <>
+ <div className="border-t border-border-light" role="separator" />
+ <div className="space-y-1.5" data-testid="token-usage-totals">
+ <h3 className="text-xs font-semibold uppercase tracking-wider text-text-tertiary">
+ {localize('com_ui_context_totals')}
+ </h3>
+ <Row label={localize('com_ui_input')} value={branchUsage.input} />
+ <Row label={localize('com_ui_output')} value={branchUsage.output} />
+ {branchUsage.cacheRead > 0 && (
+ <Row label={localize('com_ui_cache_read')} value={branchUsage.cacheRead} />
+ )}
+ {branchUsage.cacheWrite > 0 && (
+ <Row label={localize('com_ui_cache_write')} value={branchUsage.cacheWrite} />
+ )}
+ </div>
+ </>
+ )}
+
+ {showCost && hasUsage && branchUsage.costKnown && (
+ <>
+ <div className="border-t border-border-light" role="separator" />
+ <div className="space-y-1.5" data-testid="token-usage-cost">
+ <div className="group flex items-center justify-between text-sm">
+ <span className={`text-text-secondary ${HOVER_INK}`}>
+ {showTotal
+ ? localize('com_ui_context_cost_branch')
+ : localize('com_ui_context_cost')}
+ </span>
+ <span className="font-medium text-text-primary">
+ {formatCost(view.branchCost, currency)}
+ </span>
+ </div>
+ {showTotal && (
+ <div className="group flex items-center justify-between text-xs">
+ <span className={`text-text-secondary ${HOVER_INK}`}>
+ {localize('com_ui_context_cost_total')}
+ </span>
+ <span className={`text-text-secondary ${HOVER_INK}`}>
+ {formatCost(view.totalCost, currency)}
+ </span>
+ </div>
+ )}
</div>
- )}
- </div>
- </>
- )}
+ </>
+ )}
- {langfuseSessionUrl && (
- <>
- <div className="border-t border-border-light" role="separator" />
- <Button asChild variant="link" className="h-auto w-full justify-between gap-2 p-0">
- <a href={langfuseSessionUrl} target="_blank" rel="noopener noreferrer">
- <span>{localize('com_ui_langfuse_view_session')}</span>
- <ExternalLink className="size-4 shrink-0" aria-hidden="true" />
- </a>
- </Button>
- </>
- )}
+ {langfuseSessionUrl && (
+ <>
+ <div className="border-t border-border-light" role="separator" />
+ <Button asChild variant="link" className="h-auto w-full justify-between gap-2 p-0">
+ <a href={langfuseSessionUrl} target="_blank" rel="noopener noreferrer">
+ <span>{localize('com_ui_langfuse_view_session')}</span>
+ <ExternalLink className="size-4 shrink-0" aria-hidden="true" />
+ </a>
+ </Button>
+ </>
+ )}
+ </CollapsibleContent>
+ </Collapsible>
</div>
);
}
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index e816dd43b9..7fec0a248b 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -1028,6 +1028,7 @@
"com_ui_context_tools_mcp_deferred": "MCP tools (deferred)",
"com_ui_context_tools_system": "System tools",
"com_ui_context_tools_system_deferred": "System tools (deferred)",
+ "com_ui_context_totals": "Totals",
"com_ui_context_unknown": "Context size unknown",
"com_ui_context_usage": "Context usage",
"com_ui_context_usage_label": "Context window: {{0}} of {{1}} tokens used ({{2}}%)",
diff --git a/client/src/store/usage.ts b/client/src/store/usage.ts
index 8d5e666baf..15eeaffd89 100644
--- a/client/src/store/usage.ts
+++ b/client/src/store/usage.ts
@@ -3,6 +3,14 @@ import { atom, getDefaultStore } from 'jotai';
import type { TMessage, TContextUsageEvent } from 'librechat-data-provider';
import type { BranchTotals, BranchUsage } from '~/utils/tokens';
import { EMPTY_BRANCH, EMPTY_USAGE } from '~/utils/tokens';
+import { createStorageAtom } from './jotai-utils';
+
+/** Sticky preference: does the context popover open with the breakdown showing?
+ * The gauge alone is the default; a user who wants the detail sets it once. */
+export const contextBreakdownExpandedAtom = createStorageAtom<boolean>(
+ 'contextBreakdownExpanded',
+ false,
+);
/** Latest backend context snapshot, anchored to the run's user message for staleness checks */
export interface ContextSnapshot extends TContextUsageEvent {
diff --git a/client/src/style.css b/client/src/style.css
index bb45a39c03..748354a531 100644
--- a/client/src/style.css
+++ b/client/src/style.css
@@ -215,6 +215,15 @@ html {
--status-neutral-border: var(--gray-300);
--text-on-status: var(--white);
+ /* Categorical series scale — slot order is the CVD-safety mechanism */
+ --series-1: 5 110 189;
+ --series-2: 233 86 13;
+ --series-3: 0 148 142;
+ --series-4: 182 123 5;
+ --series-5: 216 90 142;
+ --series-6: 126 35 205;
+ --series-7: 1 131 1;
+
--surface-inverted: var(--gray-850);
--surface-inverted-hover: var(--gray-700);
--text-inverted: var(--white);
@@ -299,6 +308,15 @@ html {
--status-neutral-border: var(--gray-700);
--text-on-status: var(--white);
+ /* Categorical series scale — same hues, stepped for the dark surface */
+ --series-1: 9 140 238;
+ --series-2: 217 87 35;
+ --series-3: 6 158 152;
+ --series-4: 200 133 12;
+ --series-5: 213 82 130;
+ --series-6: 171 104 254;
+ --series-7: 80 167 49;
+
--surface-inverted: var(--white);
--surface-inverted-hover: var(--gray-100);
--text-inverted: var(--gray-850);
diff --git a/client/tailwind.config.cjs b/client/tailwind.config.cjs
index e8f326f8c6..3f0df2fac5 100644
--- a/client/tailwind.config.cjs
+++ b/client/tailwind.config.cjs
@@ -36,6 +36,15 @@ module.exports = {
from: { height: 'var(--radix-accordion-content-height)' },
to: { height: 0 },
},
+ /** Radix Collapsible exposes its own height variable, not the accordion one. */
+ 'collapsible-down': {
+ from: { height: 0 },
+ to: { height: 'var(--radix-collapsible-content-height)' },
+ },
+ 'collapsible-up': {
+ from: { height: 'var(--radix-collapsible-content-height)' },
+ to: { height: 0 },
+ },
'slide-in-right': {
'0%': { transform: 'translateX(100%)' },
'100%': { transform: 'translateX(0)' },
@@ -75,6 +84,8 @@ module.exports = {
'fade-in': 'fadeIn 0.5s ease-out forwards',
'accordion-down': 'accordion-down 0.2s ease-out',
'accordion-up': 'accordion-up 0.2s ease-out',
+ 'collapsible-down': 'collapsible-down 0.2s ease-out',
+ 'collapsible-up': 'collapsible-up 0.2s ease-out',
'slide-in-right': 'slide-in-right 300ms cubic-bezier(0.25, 0.1, 0.25, 1)',
'slide-in-left': 'slide-in-left 300ms cubic-bezier(0.25, 0.1, 0.25, 1)',
'slide-out-left': 'slide-out-left 300ms cubic-bezier(0.25, 0.1, 0.25, 1)',
diff --git a/e2e/specs/mock/usage.spec.ts b/e2e/specs/mock/usage.spec.ts
index 94b203e713..b8e5464af6 100644
--- a/e2e/specs/mock/usage.spec.ts
+++ b/e2e/specs/mock/usage.spec.ts
@@ -1,5 +1,5 @@
import { expect, test } from '@playwright/test';
-import type { Page } from '@playwright/test';
+import type { Page, Locator } from '@playwright/test';
import {
mockReply,
sendMessage,
@@ -18,12 +18,26 @@ async function expectGaugeAboveZero(page: Page) {
await expect(gaugeMeter(page)).toHaveAttribute('aria-valuenow', /[1-9]/, { timeout: 20000 });
}
-/** Opens the gauge breakdown popover (click, not hover) and returns its region. */
+/** The popover opens showing the gauge alone; the detail sits behind a
+ * disclosure whose state is remembered per user. Idempotent, so it is safe to
+ * call after a reload that restored an already-expanded preference. */
+async function expandBreakdown(popover: Locator) {
+ const toggle = popover.getByTestId('context-breakdown-toggle');
+ await expect(toggle).toBeVisible({ timeout: 10000 });
+ if ((await toggle.getAttribute('aria-expanded')) === 'false') {
+ await toggle.click();
+ }
+ await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+}
+
+/** Opens the gauge breakdown popover (click, not hover), expands the detail,
+ * and returns its region. */
async function openBreakdown(page: Page) {
await expectGaugeAboveZero(page);
await gauge(page).click();
const popover = page.getByRole('region', { name: 'Context usage' });
await expect(popover).toBeVisible({ timeout: 10000 });
+ await expandBreakdown(popover);
return popover;
}
@@ -64,9 +78,7 @@ test.describe('context usage gauge', () => {
/** Breakdown popover: context section always; the usage section is
* scoped by testid since the pre-snapshot fallback renders its own
* Input/Output rows when the lib predates on_context_usage */
- await gauge(page).click();
- const popover = page.getByRole('region', { name: 'Context usage' });
- await expect(popover).toBeVisible({ timeout: 10000 });
+ const popover = await openBreakdown(page);
await expect(popover.getByText('Context window')).toBeVisible();
const usageSection = popover.getByTestId('token-usage-totals');
await expect(usageSection).toBeVisible({ timeout: 10000 });
@@ -197,6 +209,47 @@ test.describe('context usage gauge', () => {
await expect(costSection.getByText(/\$\d|<\$0\.01/).first()).toBeVisible();
});
+ test('opens to the gauge alone and remembers an expanded breakdown', async ({ page }) => {
+ test.setTimeout(120000);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
+
+ await sendAndAwaitReply(page, 'hello');
+ await expectGaugeAboveZero(page);
+
+ /** Default view is the gauge: the meter and its readout, nothing else. */
+ await gauge(page).click();
+ const popover = page.getByRole('region', { name: 'Context usage' });
+ await expect(popover).toBeVisible({ timeout: 10000 });
+ const toggle = popover.getByTestId('context-breakdown-toggle');
+ await expect(toggle).toHaveAttribute('aria-expanded', 'false');
+ await expect(popover.getByRole('progressbar')).toBeVisible();
+ await expect(popover.getByTestId('token-usage-totals')).toHaveCount(0);
+ await expect(popover.getByTestId('context-breakdown')).toHaveCount(0);
+
+ /** Expanding reveals the detail, and the usage section is labelled so its
+ * numbers are not read as part of the context composition. */
+ await toggle.click();
+ await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+ const totals = popover.getByTestId('token-usage-totals');
+ await expect(totals).toBeVisible({ timeout: 10000 });
+ await expect(totals.getByRole('heading', { name: 'Totals' })).toBeVisible();
+ await page.keyboard.press('Escape');
+
+ /** The choice is a stored preference, so a reload reopens expanded with no
+ * second click — the part a component test cannot reach. */
+ await page.reload({ timeout: 15000 });
+ await expect(mockReply(page)).toBeVisible({ timeout: 20000 });
+ await expectGaugeAboveZero(page);
+ await gauge(page).click();
+ await expect(popover).toBeVisible({ timeout: 10000 });
+ await expect(popover.getByTestId('context-breakdown-toggle')).toHaveAttribute(
+ 'aria-expanded',
+ 'true',
+ );
+ await expect(popover.getByTestId('token-usage-totals')).toBeVisible({ timeout: 10000 });
+ });
+
test('hides on a new chat, then reveals snapshot on hover and breakdown on click', async ({
page,
}) => {
diff --git a/e2e/specs/real/usage.spec.ts b/e2e/specs/real/usage.spec.ts
index f7cedbe1ae..75e1c4a20b 100644
--- a/e2e/specs/real/usage.spec.ts
+++ b/e2e/specs/real/usage.spec.ts
@@ -38,7 +38,15 @@ function parseTokens(text: string): number {
}
async function readUsageTotals(page: Page): Promise<{ input: number; output: number }> {
- await gauge(page).hover();
+ /** Click, not hover: hover only surfaces the compact snapshot tooltip. The
+ * popover then opens to the gauge alone, with the totals behind a remembered
+ * disclosure — idempotent, since the preference survives the previous turn. */
+ await gauge(page).click();
+ await expect(popover(page)).toBeVisible({ timeout: 15000 });
+ const toggle = popover(page).getByTestId('context-breakdown-toggle');
+ if ((await toggle.getAttribute('aria-expanded')) === 'false') {
+ await toggle.click();
+ }
const section = popover(page).getByTestId('token-usage-totals');
await expect(section).toBeVisible({ timeout: 15000 });
const rows = section.locator('div');
diff --git a/packages/client/src/components/SegmentedMeter.spec.tsx b/packages/client/src/components/SegmentedMeter.spec.tsx
new file mode 100644
index 0000000000..d235a18f76
--- /dev/null
+++ b/packages/client/src/components/SegmentedMeter.spec.tsx
@@ -0,0 +1,215 @@
+import '@testing-library/jest-dom';
+import { render, screen } from '@testing-library/react';
+import type { ThemeDefinition } from '../theme/types';
+import type { MeterSegment } from './SegmentedMeter';
+import { resolveTheme, validateThemeDefinition, THEME_VERSION } from '../theme/registry';
+import { applyResolvedTheme, clearAppliedTheme } from '../theme/utils/applyTheme';
+import { SegmentedMeter, MeterSwatch, SERIES_SLOT_COUNT } from './SegmentedMeter';
+import { createTailwindColors } from '../theme/utils/createTailwindColors';
+
+const segments: MeterSegment[] = [
+ { id: 'a', value: 500, slot: 1, outlined: true },
+ { id: 'b', value: 250, slot: 2 },
+ { id: 'c', value: 10, slot: 2, hatched: true },
+];
+
+const renderMeter = (props: Partial<React.ComponentProps<typeof SegmentedMeter>> = {}) =>
+ render(<SegmentedMeter segments={segments} max={1000} data-testid="meter" {...props} />);
+
+const children = () => Array.from(screen.getByTestId('meter').children) as HTMLElement[];
+
+/** The CSS serializer folds `0.5 * 100%` down to `50%`, so read the parts back
+ * out of the declaration rather than matching the authored string. */
+const sizing = (el: HTMLElement): { fraction: number; gapShare: number } => {
+ const width = el.style.width;
+ const fraction = Number(/([\d.]+)%/.exec(width)?.[1]) / 100;
+ const gapShare = Number(/-\s*([\d.]+)px/.exec(width)?.[1] ?? 0);
+ return { fraction, gapShare };
+};
+
+describe('SegmentedMeter', () => {
+ it('sizes each segment against max and leaves the shortfall as bare track', () => {
+ renderMeter();
+
+ expect(children().map((child) => sizing(child).fraction)).toEqual([0.5, 0.25, 0.01]);
+ expect(screen.getByTestId('meter')).toHaveClass('bg-surface-tertiary');
+ });
+
+ it('takes the gaps out of the fill, not out of the free track', () => {
+ renderMeter();
+
+ /** Three segments touch across two 2px gaps. Each gives up its share of that
+ * 4px, so fills + gaps span exactly the 76% that is actually used — a bar
+ * reading three-quarters full means three-quarters of the window is gone. */
+ const parts = children().map(sizing);
+ const filled = parts.reduce((sum, part) => sum + part.fraction, 0);
+ const surrendered = parts.reduce((sum, part) => sum + part.gapShare, 0);
+
+ /** Shares are rounded to 3dp on the way into the declaration. */
+ expect(filled).toBeCloseTo(0.76, 5);
+ expect(surrendered).toBeCloseTo(4, 2);
+ parts.forEach((part) => expect(part.gapShare).toBeCloseTo((4 * part.fraction) / filled, 2));
+ });
+
+ it('reserves no gap share for a lone segment', () => {
+ renderMeter({ segments: [{ id: 'only', value: 500, slot: 1 }] });
+
+ expect(sizing(children()[0])).toEqual({ fraction: 0.5, gapShare: 0 });
+ });
+
+ it('floors every rendered segment so a present category cannot vanish', () => {
+ renderMeter({ segments: [{ id: 'tiny', value: 1, slot: 3 }], max: 1_000_000 });
+
+ expect(children()[0].style.minWidth).toBe('2px');
+ });
+
+ it('drops segments that contribute nothing', () => {
+ renderMeter({
+ segments: [
+ { id: 'a', value: 0, slot: 1 },
+ { id: 'b', value: -5, slot: 2 },
+ { id: 'c', value: 5, slot: 3 },
+ ],
+ });
+
+ expect(children()).toHaveLength(1);
+ expect(children()[0]).toHaveClass('bg-series-3');
+ });
+
+ it('never lets a segment exceed the full track', () => {
+ renderMeter({ segments: [{ id: 'over', value: 5000, slot: 1 }], max: 1000 });
+
+ expect(sizing(children()[0])).toEqual({ fraction: 1, gapShare: 0 });
+ });
+
+ it('renders the outlined variant as a tint plus a solid edge', () => {
+ renderMeter();
+
+ expect(children()[0]).toHaveClass('bg-series-1/25');
+ expect(children()[0]).toHaveClass('ring-1', 'ring-inset', 'ring-series-1');
+ expect(children()[1]).toHaveClass('bg-series-2');
+ expect(children()[1].className).not.toContain('ring-series');
+ });
+
+ it('hatches without changing the slot, and reads the stripe from the theme', () => {
+ renderMeter();
+
+ const [, solid, hatched] = children();
+
+ expect(hatched).toHaveClass('bg-series-2');
+ expect(solid.style.backgroundImage).toBe('');
+ expect(hatched.style.backgroundImage).toContain('repeating-linear-gradient');
+ expect(hatched.style.backgroundImage).toContain('var(--surface-tertiary)');
+ /** A literal colour here would not follow a theme swap. */
+ expect(hatched.style.backgroundImage).not.toMatch(/#[0-9a-f]{3,8}/i);
+ });
+
+ it('wraps slots past the end of the scale instead of rendering untinted', () => {
+ renderMeter({
+ segments: [
+ { id: 'wrap', value: 1, slot: SERIES_SLOT_COUNT + 1 },
+ { id: 'zero', value: 1, slot: 0 },
+ ],
+ });
+
+ expect(children()[0]).toHaveClass('bg-series-1');
+ expect(children()[1]).toHaveClass(`bg-series-${SERIES_SLOT_COUNT}`);
+ });
+
+ it('leaves the accessible description to the caller', () => {
+ renderMeter({ role: 'progressbar', 'aria-valuenow': 75, 'aria-label': 'Context usage' });
+
+ const meter = screen.getByRole('progressbar', { name: 'Context usage' });
+
+ expect(meter).toHaveAttribute('aria-valuenow', '75');
+ children().forEach((child) => expect(child).toHaveAttribute('aria-hidden', 'true'));
+ });
+});
+
+describe('MeterSwatch', () => {
+ it('paints the same treatment as the segment it keys', () => {
+ render(
+ <>
+ <MeterSwatch segment={{ slot: 1, outlined: true }} data-testid="outlined" />
+ <MeterSwatch segment={{ slot: 2, hatched: true }} data-testid="hatched" />
+ <MeterSwatch segment={{ slot: 3 }} data-testid="plain" />
+ </>,
+ );
+
+ expect(screen.getByTestId('outlined')).toHaveClass('bg-series-1/25', 'ring-series-1');
+ expect(screen.getByTestId('hatched')).toHaveClass('bg-series-2');
+ expect(screen.getByTestId('hatched').style.backgroundImage).toContain(
+ 'var(--surface-tertiary)',
+ );
+ expect(screen.getByTestId('plain')).toHaveClass('bg-series-3');
+ expect(screen.getByTestId('plain').style.backgroundImage).toBe('');
+ });
+});
+
+/** CLAUDE.md requires a deliberately different reference theme, to prove the
+ * component follows theme data rather than the bundled LibreChat values. */
+const referenceTheme: ThemeDefinition = {
+ version: THEME_VERSION,
+ name: 'reference',
+ modes: {
+ light: {
+ colors: {
+ 'rgb-series-1': '12 34 56',
+ 'rgb-series-2': '210 5 90',
+ 'rgb-series-3': '7 199 111',
+ 'rgb-series-4': '250 250 10',
+ 'rgb-series-5': '99 0 200',
+ 'rgb-series-6': '1 2 3',
+ 'rgb-series-7': '240 120 0',
+ 'rgb-surface-tertiary': '30 30 30',
+ },
+ },
+ },
+};
+
+describe('reference theme', () => {
+ afterEach(() => {
+ clearAppliedTheme();
+ });
+
+ it('is accepted by the registry, so a theme author can retint the scale', () => {
+ expect(validateThemeDefinition(referenceTheme)).toEqual([]);
+ });
+
+ it('carries the reference values through to the applied CSS variables', () => {
+ applyResolvedTheme(resolveTheme(referenceTheme, 'light'));
+
+ const root = document.documentElement;
+
+ expect(root.style.getPropertyValue('--series-1')).toBe('12 34 56');
+ expect(root.style.getPropertyValue('--series-7')).toBe('240 120 0');
+ expect(root.style.getPropertyValue('--surface-tertiary')).toBe('30 30 30');
+ });
+
+ it('paints every mark from those variables, with no value of its own', () => {
+ applyResolvedTheme(resolveTheme(referenceTheme, 'light'));
+ const { container } = render(
+ <>
+ <SegmentedMeter segments={segments} max={1000} data-testid="meter" />
+ <MeterSwatch segment={{ slot: 3 }} data-testid="swatch" />
+ </>,
+ );
+
+ /** Nothing in the rendered tree may carry a colour the theme cannot reach:
+ * no literal colours, and every hatch stripe read from a theme variable. */
+ const markup = container.innerHTML;
+ expect(markup).not.toMatch(/#[0-9a-f]{3,8}\b/i);
+ expect(markup).not.toMatch(/\brgba?\((?!var\()/);
+
+ const colours = createTailwindColors();
+ const meter = screen.getByTestId('meter');
+ const slotOf = (el: Element) => /\bbg-series-(\d)\b/.exec(el.className)?.[1];
+
+ [...meter.children, screen.getByTestId('swatch')].forEach((el) => {
+ const slot = slotOf(el) ?? /\bbg-series-(\d)\/25\b/.exec(el.className)?.[1];
+ expect(slot).toBeDefined();
+ /** The utility the mark wears resolves to the variable the theme just set. */
+ expect(colours[`series-${slot}`]).toBe(`rgb(var(--series-${slot}) / <alpha-value>)`);
+ });
+ });
+});
diff --git a/packages/client/src/components/SegmentedMeter.tsx b/packages/client/src/components/SegmentedMeter.tsx
new file mode 100644
index 0000000000..bdbadd7674
--- /dev/null
+++ b/packages/client/src/components/SegmentedMeter.tsx
@@ -0,0 +1,159 @@
+import * as React from 'react';
+import { cn } from '~/utils';
+
+/** Static class lookups — Tailwind cannot see an interpolated `bg-series-${n}`. */
+const SERIES_FILL = [
+ 'bg-series-1',
+ 'bg-series-2',
+ 'bg-series-3',
+ 'bg-series-4',
+ 'bg-series-5',
+ 'bg-series-6',
+ 'bg-series-7',
+] as const;
+
+const SERIES_TINT = [
+ 'bg-series-1/25',
+ 'bg-series-2/25',
+ 'bg-series-3/25',
+ 'bg-series-4/25',
+ 'bg-series-5/25',
+ 'bg-series-6/25',
+ 'bg-series-7/25',
+] as const;
+
+const SERIES_EDGE = [
+ 'ring-series-1',
+ 'ring-series-2',
+ 'ring-series-3',
+ 'ring-series-4',
+ 'ring-series-5',
+ 'ring-series-6',
+ 'ring-series-7',
+] as const;
+
+export const SERIES_SLOT_COUNT: number = SERIES_FILL.length;
+
+/** Wraps out-of-range slots so a caller can never render an untinted segment. */
+const slotIndex = (slot: number): number =>
+ (((Math.trunc(slot) - 1) % SERIES_SLOT_COUNT) + SERIES_SLOT_COUNT) % SERIES_SLOT_COUNT;
+
+export interface MeterSegment {
+ /** Stable identity for keys; also the legend key's pairing id */
+ id: string;
+ value: number;
+ /** 1-based slot in the categorical series scale */
+ slot: number;
+ /** Same hue, hatched — present but held out of the active set */
+ hatched?: boolean;
+ /** Translucent fill with a solid edge, for the one segment that grows */
+ outlined?: boolean;
+}
+
+/** A hatch can't be expressed with semantic utilities; the stripe colour is
+ * still read from the theme at paint time so it follows every theme. */
+const hatchStyle = (spacing: string): React.CSSProperties => ({
+ backgroundImage: `repeating-linear-gradient(135deg, transparent 0 ${spacing}, rgb(var(--surface-tertiary)) ${spacing} calc(${spacing} + 2px))`,
+});
+
+export function seriesSwatchClass(segment: Pick<MeterSegment, 'slot' | 'outlined'>): string {
+ const index = slotIndex(segment.slot);
+ return segment.outlined
+ ? cn(SERIES_TINT[index], 'ring-1 ring-inset', SERIES_EDGE[index])
+ : SERIES_FILL[index];
+}
+
+/** The legend key. Lives beside the meter so a row and its segment cannot drift. */
+export interface MeterSwatchProps extends React.ComponentPropsWithoutRef<'span'> {
+ segment: Pick<MeterSegment, 'slot' | 'hatched' | 'outlined'>;
+}
+
+export function MeterSwatch({
+ segment,
+ className,
+ ...props
+}: MeterSwatchProps): React.ReactElement {
+ return (
+ <span
+ aria-hidden="true"
+ className={cn('size-2 flex-none rounded-sm', seriesSwatchClass(segment), className)}
+ style={segment.hatched ? hatchStyle('1.5px') : undefined}
+ {...props}
+ />
+ );
+}
+
+export interface SegmentedMeterProps extends React.ComponentPropsWithoutRef<'div'> {
+ segments: MeterSegment[];
+ /** Denominator for every segment width; the shortfall renders as free track */
+ max: number;
+}
+
+/** Surface gap between touching fills, and the floor that keeps a present
+ * category from rendering as nothing. Both in px. */
+const SEGMENT_GAP = 2;
+const SEGMENT_MIN = 2;
+
+/**
+ * A part-to-whole meter: one tinted segment per series, free space left as
+ * bare track.
+ *
+ * Each segment surrenders its share of the gap budget, so the fills and the
+ * gaps between them together span exactly the used fraction — a bar reading
+ * half full means half the window is used, however many categories are in it.
+ *
+ * The one deliberate overshoot is the {@link SEGMENT_MIN} floor: a category
+ * present but too small to see is rounded up, and that rounding comes out of
+ * free space, never out of a neighbouring category. It is bounded by
+ * `SEGMENT_MIN` per sub-pixel category — on a 288px meter, five such categories
+ * read about 3 percentage points fuller than the window actually is, and the
+ * exact figures stay in the legend beside the bar.
+ */
+export const SegmentedMeter: React.ForwardRefExoticComponent<
+ SegmentedMeterProps & React.RefAttributes<HTMLDivElement>
+> = React.forwardRef<HTMLDivElement, SegmentedMeterProps>(
+ ({ segments, max, className, ...props }, ref) => {
+ const rendered = segments.filter((segment) => segment.value > 0);
+ const gapBudget = Math.max(rendered.length - 1, 0) * SEGMENT_GAP;
+ const fractions = rendered.map((segment) => Math.min(segment.value / max, 1));
+ const filled = Math.min(
+ fractions.reduce((sum, fraction) => sum + fraction, 0),
+ 1,
+ );
+
+ return (
+ <div
+ ref={ref}
+ className={cn(
+ 'flex h-2 w-full gap-[2px] overflow-hidden rounded-full bg-surface-tertiary',
+ className,
+ )}
+ {...props}
+ >
+ {rendered.map((segment, index) => {
+ const fraction = fractions[index];
+ /** Each segment gives up its share of the gap budget, so the fills and
+ * the gaps between them together span exactly `filled` of the track. */
+ const gapShare = filled > 0 ? (gapBudget * fraction) / filled : 0;
+
+ return (
+ <div
+ key={segment.id}
+ aria-hidden="true"
+ className={cn(
+ 'h-full transition-[width] duration-300 motion-reduce:transition-none',
+ seriesSwatchClass(segment),
+ )}
+ style={{
+ width: `calc(${fraction} * 100% - ${gapShare.toFixed(3)}px)`,
+ minWidth: `${SEGMENT_MIN}px`,
+ ...(segment.hatched ? hatchStyle('2.5px') : undefined),
+ }}
+ />
+ );
+ })}
+ </div>
+ );
+ },
+);
+SegmentedMeter.displayName = 'SegmentedMeter';
diff --git a/packages/client/src/components/index.ts b/packages/client/src/components/index.ts
index 39eb5bd234..58c83c8ef9 100644
--- a/packages/client/src/components/index.ts
+++ b/packages/client/src/components/index.ts
@@ -30,6 +30,8 @@ export * from './Toast';
export * from './Tooltip';
export * from './Pagination';
export * from './Progress';
+export * from './SegmentedMeter';
+export * from './Collapsible';
export * from './InputOTP';
export * from './IconButton';
export * from './MultiSearch';
diff --git a/packages/client/src/theme/registry.ts b/packages/client/src/theme/registry.ts
index c2bd657a17..87d9e2d4e7 100644
--- a/packages/client/src/theme/registry.ts
+++ b/packages/client/src/theme/registry.ts
@@ -1,5 +1,7 @@
import type {
IThemeAppearance,
+ IThemeColors,
+ IThemeVariables,
IThemeRGB,
ResolvedThemeDefinition,
ThemeDefinition,
@@ -10,6 +12,21 @@ import { darkTheme } from './themes/dark';
export const THEME_VERSION = 1 as const;
+/**
+ * Compile-time guard: the categorical series scale is declared across three
+ * hand-maintained token maps, so a slot added to one and missed in another
+ * fails the build rather than surfacing as a broken theme downstream.
+ */
+type SeriesSlot = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+type Assert<Declared extends true> = Declared;
+type DeclaredIn<Keys extends PropertyKey, Tokens> = [Keys] extends [keyof Tokens] ? true : false;
+
+export type SeriesTokensAreDeclared = [
+ Assert<DeclaredIn<`rgb-series-${SeriesSlot}`, IThemeRGB>>,
+ Assert<DeclaredIn<`--series-${SeriesSlot}`, IThemeVariables>>,
+ Assert<DeclaredIn<`series-${SeriesSlot}`, IThemeColors>>,
+];
+
export const themeColorTokens: readonly (keyof IThemeRGB)[] = Object.freeze(
Object.keys(defaultTheme) as Array<keyof IThemeRGB>,
);
diff --git a/packages/client/src/theme/semanticTokens.spec.ts b/packages/client/src/theme/semanticTokens.spec.ts
index fceddba789..66c763a82f 100644
--- a/packages/client/src/theme/semanticTokens.spec.ts
+++ b/packages/client/src/theme/semanticTokens.spec.ts
@@ -1,6 +1,7 @@
import { join } from 'node:path';
import { readFileSync } from 'node:fs';
import type { IThemeRGB } from './types';
+import { createTailwindColors } from './utils/createTailwindColors';
import { defaultTheme } from './themes/default';
import { darkTheme } from './themes/dark';
@@ -9,6 +10,7 @@ const sharedComponents = [
'AlertDialog.tsx',
'Button.tsx',
'Chip.tsx',
+ 'SegmentedMeter.tsx',
'Dialog.tsx',
'DialogTemplate.tsx',
'IconButton.tsx',
@@ -229,3 +231,77 @@ describe.each([
expect(failures).toEqual([]);
});
});
+
+/** The meter paints segments on `surface-tertiary`; the swatch and popover chrome
+ * sit on `surface-secondary`. Both have to clear the 3:1 mark-contrast floor. */
+const seriesTokens = Array.from(
+ { length: 7 },
+ (_, index) => `rgb-series-${index + 1}` as keyof IThemeRGB,
+);
+const seriesSurfaces: Array<keyof IThemeRGB> = ['rgb-surface-tertiary', 'rgb-surface-secondary'];
+const WCAG_MARK_MIN = 3;
+
+describe('categorical series scale', () => {
+ it('defines every slot in both modes as an "R G B" triplet', () => {
+ seriesTokens.forEach((token) => {
+ expect(() => toRgb(defaultTheme, token)).not.toThrow();
+ expect(() => toRgb(darkTheme, token)).not.toThrow();
+ });
+ });
+
+ it('never reuses a reserved status colour for series identity', () => {
+ const reserved = new Set(
+ statusHues.flatMap((hue) => [
+ defaultTheme[`rgb-status-${hue}` as keyof IThemeRGB],
+ darkTheme[`rgb-status-${hue}` as keyof IThemeRGB],
+ ]),
+ );
+
+ seriesTokens.forEach((token) => {
+ expect(reserved.has(defaultTheme[token])).toBe(false);
+ expect(reserved.has(darkTheme[token])).toBe(false);
+ });
+ });
+
+ it('keeps the app CSS defaults in step with the runtime themes', () => {
+ const appStyles = readFileSync(
+ join(__dirname, '..', '..', '..', '..', 'client', 'src', 'style.css'),
+ 'utf8',
+ );
+
+ seriesTokens.forEach((token) => {
+ const property = token.slice(4);
+ const declared = [...appStyles.matchAll(new RegExp(`--${property}:\\s*([^;]+);`, 'g'))].map(
+ (match) => match[1].trim(),
+ );
+
+ /** One declaration for `html`, one for `.dark` — and both must match. */
+ expect(declared).toEqual([defaultTheme[token], darkTheme[token]]);
+ });
+ });
+
+ it('exposes each slot as a Tailwind utility backed by its CSS variable', () => {
+ const colors = createTailwindColors();
+
+ seriesTokens.forEach((token) => {
+ const property = token.slice(4);
+ expect(colors[property]).toBe(`rgb(var(--${property}) / <alpha-value>)`);
+ });
+ });
+});
+
+describe.each([
+ ['default', defaultTheme],
+ ['dark', darkTheme],
+])('%s series contrast', (_name, theme: IThemeRGB) => {
+ it('keeps every series slot at the 3:1 mark floor on the track and the panel', () => {
+ const failures = seriesTokens.flatMap((token) =>
+ seriesSurfaces.flatMap((surface) => {
+ const ratio = contrast(toRgb(theme, token), toRgb(theme, surface));
+ return ratio < WCAG_MARK_MIN ? [`${token} on ${surface}: ${ratio.toFixed(2)}:1`] : [];
+ }),
+ );
+
+ expect(failures).toEqual([]);
+ });
+});
diff --git a/packages/client/src/theme/themes/dark.ts b/packages/client/src/theme/themes/dark.ts
index 3d7a854dff..69cabf4855 100644
--- a/packages/client/src/theme/themes/dark.ts
+++ b/packages/client/src/theme/themes/dark.ts
@@ -88,6 +88,16 @@ export const darkTheme: IThemeRGB = {
// Brand colors
'rgb-brand-purple': '171 104 255', // #ab68ff
+ /** Categorical series scale — the same seven hues stepped for the #212121
+ * surface: worst adjacent CVD ΔE 13.0, normal-vision ΔE 19.0, all ≥ 3:1. */
+ 'rgb-series-1': '9 140 238', // #098cee (cerulean)
+ 'rgb-series-2': '217 87 35', // #d95723 (orange)
+ 'rgb-series-3': '6 158 152', // #069e98 (aqua)
+ 'rgb-series-4': '200 133 12', // #c8850c (amber)
+ 'rgb-series-5': '213 82 130', // #d55282 (magenta)
+ 'rgb-series-6': '171 104 254', // #ab68fe (violet)
+ 'rgb-series-7': '80 167 49', // #50a731 (green)
+
// Presentation
'rgb-presentation': '33 33 33', // #212121 (gray-800)
};
diff --git a/packages/client/src/theme/themes/default.ts b/packages/client/src/theme/themes/default.ts
index ebd693f7fe..503d02ddc4 100644
--- a/packages/client/src/theme/themes/default.ts
+++ b/packages/client/src/theme/themes/default.ts
@@ -88,6 +88,17 @@ export const defaultTheme: IThemeRGB = {
// Brand colors
'rgb-brand-purple': '126 34 206', // #7e22ce (purple-700)
+ /** Categorical series scale. Steps clear 3:1 against BOTH the popover surface
+ * and the #ececec meter track, with worst adjacent CVD ΔE 12.4 and worst
+ * adjacent normal-vision ΔE 19.0. Slot order is the CVD-safety mechanism. */
+ 'rgb-series-1': '5 110 189', // #056ebd (cerulean)
+ 'rgb-series-2': '233 86 13', // #e9560d (orange)
+ 'rgb-series-3': '0 148 142', // #00948e (aqua)
+ 'rgb-series-4': '182 123 5', // #b67b05 (amber)
+ 'rgb-series-5': '216 90 142', // #d85a8e (magenta)
+ 'rgb-series-6': '126 35 205', // #7e23cd (violet)
+ 'rgb-series-7': '1 131 1', // #018301 (green)
+
// Presentation
'rgb-presentation': '255 255 255', // #fff (white)
};
diff --git a/packages/client/src/theme/types/index.ts b/packages/client/src/theme/types/index.ts
index db1e686397..b692da887b 100644
--- a/packages/client/src/theme/types/index.ts
+++ b/packages/client/src/theme/types/index.ts
@@ -86,6 +86,19 @@ export interface IThemeRGB {
// Brand colors
'rgb-brand-purple'?: string;
+ /**
+ * Categorical data-visualisation scale. Slots carry series identity only — the
+ * order is the colour-vision-deficiency safety mechanism and must not be
+ * reshuffled. Reserved status colors never appear here.
+ */
+ 'rgb-series-1'?: string;
+ 'rgb-series-2'?: string;
+ 'rgb-series-3'?: string;
+ 'rgb-series-4'?: string;
+ 'rgb-series-5'?: string;
+ 'rgb-series-6'?: string;
+ 'rgb-series-7'?: string;
+
// Presentation
'rgb-presentation'?: string;
}
@@ -165,6 +178,15 @@ export interface IThemeVariables {
'--status-neutral-border': string;
'--text-on-status': string;
'--brand-purple': string;
+
+ '--series-1': string;
+ '--series-2': string;
+ '--series-3': string;
+ '--series-4': string;
+ '--series-5': string;
+ '--series-6': string;
+ '--series-7': string;
+
'--presentation': string;
}
@@ -239,6 +261,14 @@ export interface IThemeColors {
'status-neutral-border'?: string;
'text-on-status'?: string;
'brand-purple'?: string;
+
+ 'series-1'?: string;
+ 'series-2'?: string;
+ 'series-3'?: string;
+ 'series-4'?: string;
+ 'series-5'?: string;
+ 'series-6'?: string;
+ 'series-7'?: string;
presentation?: string;
// Retained for excluded SidePanel/Agents + SidePanel/Builder (pending migration)
diff --git a/packages/client/src/theme/utils/createTailwindColors.js b/packages/client/src/theme/utils/createTailwindColors.js
index 1ffda1d0b0..fe5408bc8c 100644
--- a/packages/client/src/theme/utils/createTailwindColors.js
+++ b/packages/client/src/theme/utils/createTailwindColors.js
@@ -140,6 +140,14 @@ function createTailwindColors() {
'status-neutral-border': cssVar('--status-neutral-border'),
'text-on-status': cssVar('--text-on-status'),
+ 'series-1': cssVar('--series-1'),
+ 'series-2': cssVar('--series-2'),
+ 'series-3': cssVar('--series-3'),
+ 'series-4': cssVar('--series-4'),
+ 'series-5': cssVar('--series-5'),
+ 'series-6': cssVar('--series-6'),
+ 'series-7': cssVar('--series-7'),
+
'switch-unchecked': hslVar('--switch-unchecked'),
};
}