cursedbelt 5.82.0 → 5.85.0

package/scripts/attributesForwarded.ts

@@ -0,0 +1,172 @@
+/**
+ * `bun run attributes:forwarded [--prune]` — a `data-testid` written on a component reaches the DOM.
+ *
+ * ## The trap this exists for
+ *
+ * Forge task 3451 (2026-10-20): `<Alert tone="error" data-testid="ship-stopped">` in station type-
+ * checked, rendered its text, and its test's `findByTestId("ship-stopped")` hung until it timed out.
+ * `Alert` destructured a fixed list of props and spread nothing onto its root, so the id was
+ * dropped — and TypeScript accepts ANY hyphenated attribute (`data-*`, `aria-*`) on any component, so
+ * no type error could ever say so. 358 exported components were built the same way.
+ *
+ * ## What counts
+ *
+ * A COMPONENT is a capitalised export of a `src/react` `.tsx` file that is a function (a
+ * declaration, or a `const` arrow/function, through `memo`/`forwardRef`) taking a props parameter.
+ * It FORWARDS when the props it does not name reach a JSX element: its parameter's destructuring
+ * (or a `const { … } = props` inside it) ends in a rest element that is spread onto an element
+ * (`{...rest}`), or the props object itself is spread. A component with no parameter has nothing to
+ * drop and is not judged.
+ *
+ * A component that renders no element of its own — a provider, a portal host, a hook wrapper —
+ * says so on the line above its export: `// no-attribute-forward: <why>`, which the check reads.
+ *
+ * `attributesForwarded.baseline` lists the components that dropped them when this was written, as
+ * `<file>#<Component>`. It is a CEILING: a non-forwarding component missing from it fails, and an
+ * entry that now forwards (or is gone) fails too, so the list only shrinks — `--prune` removes
+ * those and refuses to add anything.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as ts from "typescript";
+
+const ROOT = join(import.meta.dir, "..");
+export const BASELINE = join(ROOT, "attributesForwarded.baseline");
+export const OPT_OUT = "no-attribute-forward:";
+
+export interface Judged {
+	/** `<file relative to the repo>#<Component>`. */
+	id: string;
+	forwards: boolean;
+}
+
+type Fn = ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression;
+
+/** The function a `const X = memo(forwardRef((props) => …))` finally wraps. */
+function unwrap(node: ts.Expression | undefined): Fn | undefined {
+	let current = node;
+	while (current && (ts.isCallExpression(current) || ts.isParenthesizedExpression(current) || ts.isAsExpression(current))) {
+		current = ts.isCallExpression(current) ? current.arguments[0] : current.expression;
+	}
+	return current && (ts.isArrowFunction(current) || ts.isFunctionExpression(current)) ? current : undefined;
+}
+
+/** Every identifier spread onto a JSX element anywhere in `node`. */
+function spreadNames(node: ts.Node): Set<string> {
+	const names = new Set<string>();
+	const visit = (n: ts.Node): void => {
+		if (ts.isJsxSpreadAttribute(n) && ts.isIdentifier(n.expression)) names.add(n.expression.text);
+		n.forEachChild(visit);
+	};
+	visit(node);
+	return names;
+}
+
+/** The rest element's name in a destructuring, if it has one. */
+function restName(pattern: ts.ObjectBindingPattern): string | undefined {
+	const rest = pattern.elements.find((e) => e.dotDotDotToken);
+	return rest && ts.isIdentifier(rest.name) ? rest.name.text : undefined;
+}
+
+/** Does this component's unnamed props reach an element? `undefined` ⇒ not judged (no props). */
+export function forwardsAttributes(fn: Fn): boolean | undefined {
+	const param = fn.parameters[0];
+	if (!param) return undefined;
+	const spread = spreadNames(fn);
+	if (ts.isObjectBindingPattern(param.name)) {
+		const rest = restName(param.name);
+		return rest !== undefined && spread.has(rest);
+	}
+	if (!ts.isIdentifier(param.name)) return false;
+	const props = param.name.text;
+	if (spread.has(props)) return true;
+	let forwards = false;
+	const visit = (n: ts.Node): void => {
+		if (
+			ts.isVariableDeclaration(n) &&
+			ts.isObjectBindingPattern(n.name) &&
+			n.initializer &&
+			ts.isIdentifier(n.initializer) &&
+			n.initializer.text === props
+		) {
+			const rest = restName(n.name);
+			if (rest !== undefined && spread.has(rest)) forwards = true;
+		}
+		n.forEachChild(visit);
+	};
+	visit(fn);
+	return forwards;
+}
+
+function optedOut(statement: ts.Statement, source: ts.SourceFile): boolean {
+	const ranges = ts.getLeadingCommentRanges(source.text, statement.getFullStart()) ?? [];
+	return ranges.some((r) => source.text.slice(r.pos, r.end).includes(OPT_OUT));
+}
+
+/** Every judged component in one source file. */
+export function judgeSource(id: string, text: string): Judged[] {
+	const source = ts.createSourceFile(id, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+	const judged: Judged[] = [];
+	const judge = (name: string, fn: Fn | undefined, statement: ts.Statement): void => {
+		if (!fn || !/^[A-Z]/.test(name) || optedOut(statement, source)) return;
+		const forwards = forwardsAttributes(fn);
+		if (forwards !== undefined) judged.push({ id: `${id}#${name}`, forwards });
+	};
+	for (const statement of source.statements) {
+		const exported = ts.canHaveModifiers(statement) && ts.getModifiers(statement)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+		if (!exported) continue;
+		if (ts.isFunctionDeclaration(statement) && statement.name && statement.body) judge(statement.name.text, statement, statement);
+		if (ts.isVariableStatement(statement)) {
+			for (const d of statement.declarationList.declarations) {
+				if (ts.isIdentifier(d.name)) judge(d.name.text, unwrap(d.initializer), statement);
+			}
+		}
+	}
+	return judged;
+}
+
+/** Every `src/react` component that drops what it does not name, sorted. */
+export function dropping(root: string = ROOT): string[] {
+	const files = [...new Bun.Glob("src/react/**/*.tsx").scanSync(root)].filter((f) => !/\.(spec|test)\.tsx$/.test(f));
+	return files
+		.flatMap((f) => judgeSource(f, readFileSync(join(root, f), "utf8")))
+		.filter((j) => !j.forwards)
+		.map((j) => j.id)
+		.sort();
+}
+
+export function readBaseline(file: string = BASELINE): string[] {
+	return readFileSync(file, "utf8")
+		.split("\n")
+		.map((l) => l.trim())
+		.filter((l) => l && !l.startsWith("#"));
+}
+
+/** The new gaps (a fault), and the entries that have outlived their gap (also a fault). */
+export function compare(now: readonly string[], baseline: readonly string[]): { added: string[]; stale: string[] } {
+	const current = new Set(now);
+	const allowed = new Set(baseline);
+	return { added: now.filter((n) => !allowed.has(n)), stale: baseline.filter((n) => !current.has(n)) };
+}
+
+if (import.meta.main) {
+	const now = dropping();
+	const baseline = readBaseline();
+	const { added, stale } = compare(now, baseline);
+	const prune = process.argv.includes("--prune");
+	if (prune && stale.length > 0) {
+		const gone = new Set(stale);
+		const text = readFileSync(BASELINE, "utf8");
+		writeFileSync(BASELINE, text.split("\n").filter((l) => !gone.has(l.trim())).join("\n"));
+		console.log(`pruned ${stale.length}: ${stale.join(", ")}`);
+	}
+	for (const id of added) {
+		console.error(
+			`✗ ${id} drops the attributes it does not name — end its props destructuring with \`...rest\` and spread it on its root element, or say \`// ${OPT_OUT} <why>\` above it.`,
+		);
+	}
+	if (!prune) for (const id of stale) console.error(`✗ ${id} is in attributesForwarded.baseline but forwards now — \`bun run attributes:forwarded --prune\`.`);
+	const faults = added.length + (prune ? 0 : stale.length);
+	console.log(`${now.length} component(s) drop unnamed attributes (baseline ${baseline.length - (prune ? stale.length : 0)})`);
+	process.exit(faults > 0 ? 1 : 0);
+}

package/scripts/guardrailsEnforce.spec.ts

@@ -1713,6 +1713,34 @@ describe('no-raw-kbd', () => {
   });
 });
 
+describe('no-raw-search', () => {
+  test('🔴 flags the hand-made box vault shipped — the browser ✕ only shows under a pointer', () => {
+    expect(check('no-raw-search', `<Input ref={searchRef} type="search" value={filter.query} />`)).toHaveLength(1);
+    expect(check('no-raw-search', `<input type='search' />`)).toHaveLength(1);
+    expect(check('no-raw-search', `const field = { name: 'q', type: 'search' };`)).toHaveLength(1);
+  });
+
+  test('passes SearchInput, and an attribute SELECTOR is not a field', () => {
+    expect(check('no-raw-search', `<SearchInput value={q} onChange={setQ} />`)).toHaveLength(0);
+    expect(check('no-raw-search', `root.querySelector('input[type="search"], [data-game]')`)).toHaveLength(0);
+  });
+
+  test('passes an ignore-commented line, same line or the block above', () => {
+    expect(
+      check(
+        'no-raw-search',
+        `{/* guardrails-ignore no-raw-search: the find bar's own Close clears it */}
+<input type="search" />`,
+      ),
+    ).toHaveLength(0);
+  });
+
+  test('a stylesheet is not scanned, nor the belt\'s own boxes that draw their ✕', () => {
+    expect(RULES['no-raw-search']!.check('src/styles.css', 'input[type="search"] { font-size: 16px }')).toHaveLength(0);
+    expect(RULES['no-raw-search']!.check('src/react/components/SearchInput.tsx', `<Input type='search' />`)).toHaveLength(0);
+  });
+});
+
 describe('no-raw-nav', () => {
   test('🔴 flags a hand-rolled <nav> — the header music shipped on 2026-09-25', () => {
     expect(

package/scripts/guardrailsEnforce.ts

@@ -2408,6 +2408,45 @@ const noRawPassword: Rule = {
 	},
 };
 
+// ── no-raw-search (owner, 2026-10-20: "a small x … standardized so all apps have it") ──
+// A search box with no ✕ a phone can reach. Vault's had one only because Chrome paints
+// `type="search"`'s own cancel button — under the pointer, and never on an iPhone, which is where
+// the owner found it missing. cursedbelt's `SearchInput` draws its ✕ whenever there is text (the
+// default since 5.84.0), so a search field is that component, never a hand-made
+// `<Input type="search">`.
+//
+// Same shape as `no-raw-password`: on the ATTRIBUTE, any tag or props object. An attribute
+// SELECTOR (`input[type="search"]` in a querySelector or a stylesheet) is not a field and does not
+// match. The belt's own boxes that draw their own ✕ (`SearchInput`, `HeaderSearch`, the canvas
+// HUD's field) are exempt by path; a field that genuinely cannot be a `SearchInput` takes the
+// per-line opt-out naming its own way to clear.
+const SEARCH_TYPE_RE =
+	/(?<![[\w-])type\s*=\s*(?:\{\s*)?["'`]search["'`]|\btype\s*:\s*["'`]search["'`]/;
+const SEARCH_IGNORE_RE = /guardrails-ignore\s+no-raw-search\s*:/;
+const SEARCH_OWNERS_RE = /(^|\/)src\/react\/(components\/SearchInput|nav\/HeaderSearch|canvas-hud\/CanvasSearchField)\.tsx$/;
+
+const noRawSearch: Rule = {
+	name: "no-raw-search",
+	description:
+		"Owner, 2026-10-20: every search box has a ✕ that clears it, on every device. A `type=\"search\"` field — on any tag, component or props object — must be cursedbelt's `SearchInput` (`cursedbelt/react/search-input`), which draws the ✕ whenever there is text; the browser's own shows only on hover, and never on an iPhone. A field that cannot be one takes the per-line opt-out naming how it clears.",
+	check(filePath, source) {
+		const normalized = filePath.replace(/\\/g, "/");
+		if (isTestSource(normalized)) return [];
+		if (!/\.[jt]sx?$/.test(normalized) || SEARCH_OWNERS_RE.test(normalized)) return [];
+		const raws = source.split("\n");
+		const scan = blankComments(source).split("\n");
+		const out: Violation[] = [];
+		for (const [i, line] of scan.entries()) {
+			if (!SEARCH_TYPE_RE.test(line)) continue;
+			const raw = raws[i] ?? "";
+			if (SEARCH_IGNORE_RE.test(raw)) continue;
+			if (SEARCH_IGNORE_RE.test(raws.slice(Math.max(0, i - 3), i).join("\n"))) continue;
+			out.push({ file: filePath, line: i + 1, snippet: raw.trim() });
+		}
+		return out;
+	},
+};
+
 // ── no-raw-nav ──────────────────────────────────────────────────────────────
 // The owner, 2026-09-25: *"the music app header on iphone goes off the right side of the
 // screen. … cb should enforce this via a top bar component so each app cannot do it wrong
@@ -3085,6 +3124,7 @@ export const RULES: Record<string, Rule> = {
 	[typedFieldOutsideAForm.name]: typedFieldOutsideAForm,
 	[noFastTooltip.name]: noFastTooltip,
 	[noRawPassword.name]: noRawPassword,
+	[noRawSearch.name]: noRawSearch,
 	[noRawNav.name]: noRawNav,
 	[noRawLazy.name]: noRawLazy,
 	[noRawPopover.name]: noRawPopover,

package/scripts/styleAreas.ts

@@ -378,6 +378,7 @@ export const AREAS: readonly Area[] = [
 			'components/StatTile.tsx',
 			'components/StatTileGrid.tsx',
 			'components/ThresholdMeter.tsx',
+			'components/Heat.tsx',
 			'components/BuildFreshness.tsx',
 		],
 	},

package/src/react/AuthGate.tsx

@@ -43,6 +43,7 @@ function dropSearchParam(name: string): void {
  * accepts any bearer token), so mounting this unconditionally around every
  * generated app is a safe no-op until `notifyUnauthorized` is ever called.
  */
+// no-attribute-forward: renders its children, or a redirect, with no element of its own.
 export function AuthGate({ loginPath, registerPath = '/auth/register', children }: AuthGateProps) {
   const [unauthorized, setUnauthorized] = useState(false);
   const [invite, setInvite] = useState(

package/src/react/activity-bar/ActivityBar.tsx

@@ -420,6 +420,7 @@ export function ActivityBar({
   expandable = true,
   locked = false,
   onLockedChange,
+  ...rest
 }: ActivityBarProps): JSX.Element {
   const wide = useMediaQuery(`(min-width: ${LOCK_MIN_WIDTH}px)`);
   const lockable = expandable && onLockedChange !== undefined && wide;
@@ -434,6 +435,7 @@ export function ActivityBar({
      * buttons, and seven separate tab stops is both honest and better here.
      */
     <fieldset
+      {...rest}
       ref={root}
       className={className ? `cbab ${className}` : 'cbab'}
       aria-label={ariaLabel}

package/src/react/analytics/MetricDrilldown.tsx

@@ -72,9 +72,11 @@ export function MetricDrilldown<TRow extends Record<string, unknown>>({
   downloadName,
   emptyState,
   children,
+  ...rest
 }: MetricDrilldownProps<TRow>) {
   return (
     <Modal
+      {...rest}
       open={open}
       onClose={onClose}
       size='lg'

package/src/react/analytics/RangeTabs.tsx

@@ -88,6 +88,7 @@ export function RangeTabs({
   onCustomChange,
   className,
   'aria-label': ariaLabel = 'Time range',
+  ...rest
 }: RangeTabsProps) {
   const offered = keys ?? (onCustomChange ? RANGE_PRESETS.map((p) => p.key) : FIXED_RANGE_KEYS);
   const presets = RANGE_PRESETS.filter(
@@ -104,7 +105,7 @@ export function RangeTabs({
     // `min-w-0 max-w-full`: as a flex item (a toolbar, a header row) this wrapper otherwise
     // takes the strip's whole width as its minimum, and the segment row's own sideways scroll
     // never engages — at 390px the six presets pushed the page 31px wide (forge task 2589).
-    <div className={cn('min-w-0 max-w-full', className)}>
+    <div {...rest} className={cn('min-w-0 max-w-full', className)}>
       <div className='flex flex-wrap items-center gap-2'>
         <SegmentedControl
           aria-label={ariaLabel}

package/src/react/canvas-hud/AlignmentGuides.tsx

@@ -17,11 +17,12 @@ export interface AlignmentGuidesProps {
  * `aria-hidden` and `pointer-events: none`: the lines are a hint about where the item will land,
  * which the item itself already shows; they must never take a pointer from the item underneath.
  */
-export function AlignmentGuides({ guides, scale }: AlignmentGuidesProps) {
+export function AlignmentGuides({ guides, scale, ...rest }: AlignmentGuidesProps) {
   if (guides.length === 0 || !(scale > 0)) return null;
   const width = 1 / scale;
   return (
     <svg
+      {...rest}
       data-testid='canvas-alignment-guides'
       aria-hidden='true'
       width={1}

package/src/react/canvas-hud/CanvasMinimap.tsx

@@ -37,6 +37,7 @@ export function CanvasMinimap({
   children,
   hint,
   className,
+  ...rest
 }: CanvasMinimapProps) {
   if (bounds.width <= 0 || bounds.height <= 0 || viewport.width <= 0 || view.scale <= 0) return null;
   const ratio = Math.min(size / bounds.width, (size * 0.62) / bounds.height);
@@ -54,6 +55,7 @@ export function CanvasMinimap({
   const caption = hint === undefined ? (onJump ? 'Tap to jump' : null) : hint;
   return (
     <div
+      {...rest}
       data-testid='canvas-minimap'
       className={cn(
         'pointer-events-auto flex flex-col items-center gap-1 rounded-lg border border-border/60 bg-background/70 p-2 shadow-raised backdrop-blur-md',

package/src/react/canvas-hud/CanvasNodeMenu.tsx

@@ -45,10 +45,12 @@ export function CanvasNodeMenu({
   align = 'start',
   side = 'bottom',
   className,
+  ...rest
 }: CanvasNodeMenuProps) {
   const stop = (event: PointerEvent) => event.stopPropagation();
   return (
     <Popover
+      {...rest}
       open={open}
       onOpenChange={onOpenChange}
       align={align}

package/src/react/canvas-hud/CanvasSearchField.tsx

@@ -40,6 +40,7 @@ export function CanvasSearchField({
   placeholder = 'Find…',
   'aria-label': ariaLabel,
   className,
+  ...rest
 }: CanvasSearchFieldProps) {
   const searching = value.trim().length > 0;
   const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
@@ -54,7 +55,7 @@ export function CanvasSearchField({
     event.stopPropagation();
   };
   return (
-    <HudPill className={cn('gap-0.5 rounded-lg py-0.5 pr-1 pl-0', className)}>
+    <HudPill {...rest} className={cn('gap-0.5 rounded-lg py-0.5 pr-1 pl-0', className)}>
       <IconSearch size={16} className='ml-2 shrink-0 text-muted-foreground' />
       <Input
         type='search'

package/src/react/canvas-hud/HudControls.tsx

@@ -31,9 +31,10 @@ export interface HudButtonProps {
 }
 
 /** One HUD control — an icon-sized belt `IconButton`, with a pressed state for a toggle. */
-export function HudButton({ label, onClick, children, pressed, unavailableReason, className }: HudButtonProps) {
+export function HudButton({ label, onClick, children, pressed, unavailableReason, className, ...rest }: HudButtonProps) {
   return (
     <IconButton
+      {...rest}
       label={label}
       size='sm'
       aria-pressed={pressed}
@@ -81,6 +82,7 @@ export function HudZoomControls({
   children,
   orientation = 'horizontal',
   className,
+  ...rest
 }: HudZoomControlsProps) {
   const vertical = orientation === 'vertical';
   const zoomOut = (
@@ -95,6 +97,7 @@ export function HudZoomControls({
   );
   return (
     <HudPill
+      {...rest}
       role='group'
       aria-label='View'
       aria-orientation={orientation}
@@ -133,10 +136,11 @@ export interface CanvasZoomHintProps {
  * CNV-1's "Hold ⌘ to zoom" — what an embedded canvas says when a plain wheel scrolled the page
  * instead of zooming it, the way an embedded Google Map does. Says Ctrl off a Mac.
  */
-export function CanvasZoomHint({ show, className }: CanvasZoomHintProps) {
+export function CanvasZoomHint({ show, className, ...rest }: CanvasZoomHintProps) {
   const mac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);
   return (
     <div
+      {...rest}
       aria-hidden={!show}
       data-testid='canvas-zoom-hint'
       className={cn(

package/src/react/charts/AreaChart.tsx

@@ -52,11 +52,12 @@ export function AreaChart({
   xTickFormatter,
   valueFormatter,
   labelFormatter,
+  ...rest
 }: AreaChartProps) {
   const gradId = useGradientId();
   const showLegend = (box: ChartBox) => legend ?? (!box.legendInHeader && series.length > 1);
   return (
-    <ChartFrame ariaLabel={ariaLabel} height={height}>
+    <ChartFrame {...rest} ariaLabel={ariaLabel} height={height}>
       {(t, box) => (
         <RAreaChart data={data} margin={{ top: 8, right: 12, bottom: 0, left: 0 }}>
           <defs>

package/src/react/charts/BarChart.tsx

@@ -1,9 +1,10 @@
-import { Bar, CartesianGrid, Legend, BarChart as RBarChart, Tooltip, XAxis, YAxis } from 'recharts';
+import { Bar, CartesianGrid, Cell, Legend, BarChart as RBarChart, Tooltip, XAxis, YAxis } from 'recharts';
 import type { ChartBox } from './chartBox.js';
 import { ChartFrame } from './ChartFrame.js';
 import { legendContent } from './ChartLegend.js';
 import { tooltipContent } from './ChartTooltip.js';
 import { axisProps, valueAxisProps, type ChartDatum, type ChartSeries, seriesColor } from './shared.js';
+import { type ChartTone, toneColor } from './tokens.js';
 
 type Corners = [number, number, number, number];
 
@@ -32,6 +33,13 @@ export type BarChartProps = {
   valueFormatter?: (value: number) => string;
   /** Format the tooltip header. */
   labelFormatter?: (label: string | number) => string;
+  /**
+   * Colour each BAR by its datum rather than its series — the heat of a cost against the fleet's
+   * median (`heatChartTone(heatBandOf(…))`), a budget's bar turning at its thresholds. Return
+   * `undefined` to keep the series colour. CHT-7: colour is meaning, so the tones are the status
+   * tones, never a free hex.
+   */
+  colorBy?: (datum: ChartDatum, index: number) => ChartTone | undefined;
 };
 
 /** Vertical/horizontal, grouped/stacked bar chart with rounded corners. */
@@ -49,6 +57,8 @@ export function BarChart({
   categoryTickFormatter,
   valueFormatter,
   labelFormatter,
+  colorBy,
+  ...rest
 }: BarChartProps) {
   const horizontal = orientation === 'horizontal';
   const showLegend = (box: ChartBox) => legend ?? (!box.legendInHeader && series.length > 1);
@@ -59,7 +69,7 @@ export function BarChart({
     return horizontal ? [0, 4, 4, 0] : [4, 4, 0, 0];
   };
   return (
-    <ChartFrame ariaLabel={ariaLabel} height={height}>
+    <ChartFrame {...rest} ariaLabel={ariaLabel} height={height}>
       {(t, box) => (
         <RBarChart
           data={data}
@@ -121,7 +131,15 @@ export function BarChart({
               fill={seriesColor(t, s, i)}
               radius={cornersFor(i)}
               isAnimationActive={false}
-            />
+            >
+              {colorBy
+                ? data.map((d, j) => {
+                    const tone = colorBy(d, j);
+                    // Keyed on the category value: a bar IS its datum, and recharts matches cells to bars by position.
+                    return <Cell key={`${s.dataKey}-${String(d[xKey] ?? j)}`} fill={tone ? toneColor(t, tone) : seriesColor(t, s, i)} />;
+                  })
+                : null}
+            </Bar>
           ))}
         </RBarChart>
       )}

package/src/react/charts/ChartCard.tsx

@@ -91,6 +91,7 @@ export function ChartCard({
   height,
   children,
   className,
+  ...rest
 }: ChartCardProps) {
   const bodyRef = useRef<HTMLDivElement>(null);
   const tokens = useChartTokens(bodyRef);
@@ -103,7 +104,7 @@ export function ChartCard({
   const emptyContent = empty === true ? { title: 'No data for this range' } : empty || null;
 
   return (
-    <Surface level='flat' pad='md' radius='lg' className={cn('flex min-w-0 flex-col gap-3', className)} data-cb-chart-card=''>
+    <Surface {...rest} level='flat' pad='md' radius='lg' className={cn('flex min-w-0 flex-col gap-3', className)} data-cb-chart-card=''>
       <div className='flex min-w-0 flex-wrap items-start justify-between gap-x-4 gap-y-2'>
         <div className='flex min-w-0 flex-col gap-0.5'>
           <h3 className='truncate text-sm font-semibold text-foreground'>{title}</h3>

package/src/react/charts/ChartFrame.tsx

@@ -27,7 +27,7 @@ export type ChartFrameProps = {
  * (a sidebar folding re-measures it) and derives the plot's shape and its marks' weight
  * from it — see `chartBox`. All wrappers below build on it.
  */
-export function ChartFrame({ ariaLabel, height, className, children }: ChartFrameProps) {
+export function ChartFrame({ ariaLabel, height, className, children, ...rest }: ChartFrameProps) {
   const ref = useRef<HTMLDivElement>(null);
   const tokens = useChartTokens(ref);
   const { width } = useElementSize(ref, { layout: true });
@@ -35,6 +35,7 @@ export function ChartFrame({ ariaLabel, height, className, children }: ChartFram
   const box = chartBox(width, { height: height ?? card?.height, legendInHeader: card?.legendInHeader ?? false });
   return (
     <div
+      {...rest}
       ref={ref}
       role='img'
       aria-label={ariaLabel}

package/src/react/charts/ChartLegend.tsx

@@ -9,7 +9,7 @@ export type ChartLegendProps = {
 };
 
 /** A themed recharts legend: horizontal color chips that wrap on narrow widths. */
-export function ChartLegend({ payload, tokens = FALLBACK_TOKENS }: ChartLegendProps) {
+export function ChartLegend({ payload, tokens = FALLBACK_TOKENS, ...rest }: ChartLegendProps) {
   // A series drawn with `legendType='none'` (a band, a helper area) still arrives in recharts'
   // payload, marked `type: 'none'`; the default legend drops it and so must this one — the
   // time series listed its band's "hi" and a swatchless "lo" as series (forge task 2593).
@@ -17,6 +17,7 @@ export function ChartLegend({ payload, tokens = FALLBACK_TOKENS }: ChartLegendPr
   if (!items.length) return null;
   return (
     <ul
+      {...rest}
       className='m-0 flex list-none flex-wrap items-center justify-center gap-x-4 gap-y-1 p-0 pt-2 text-xs'
       style={{ color: tokens.foreground }}
     >

package/src/react/charts/ChartTooltip.tsx

@@ -31,10 +31,12 @@ export function ChartTooltip({
   tokens = FALLBACK_TOKENS,
   labelFormatter,
   valueFormatter,
+  ...rest
 }: ChartTooltipProps) {
   if (!active || !payload?.length) return null;
   return (
     <div
+      {...rest}
       className='rounded-lg px-3 py-2 text-xs shadow-[var(--shadow-popover)]'
       style={{
         backgroundColor: tokens.surface,

package/src/react/charts/HeatmapChart.tsx

@@ -97,6 +97,7 @@ export function HeatmapChart({
   footnote,
   onCellClick,
   className,
+  ...rest
 }: HeatmapChartProps) {
   const ref = useRef<HTMLDivElement>(null);
   const tokens: ChartTokens = useChartTokens(ref);
@@ -114,7 +115,7 @@ export function HeatmapChart({
     }`;
 
   return (
-    <div ref={ref} data-cb-chart='' className={cn('flex w-full min-w-0 flex-col gap-2', className)}>
+    <div {...rest} ref={ref} data-cb-chart='' className={cn('flex w-full min-w-0 flex-col gap-2', className)}>
       <div
         role='img'
         aria-label={ariaLabel}

package/src/react/charts/IntervalTimeline.tsx

@@ -101,6 +101,7 @@ export function IntervalTimeline({
   formatDuration = defaultDuration,
   onSelect,
   className,
+  ...rest
 }: IntervalTimelineProps) {
   const ref = useId();
   const rootRef = useRef<HTMLDivElement>(null);
@@ -127,6 +128,7 @@ export function IntervalTimeline({
   if (view.usable.length === 0) {
     return (
       <div
+        {...rest}
         ref={rootRef}
         className={cn('flex h-24 items-center justify-center text-muted-foreground text-xs', className)}
       >
@@ -136,7 +138,7 @@ export function IntervalTimeline({
   }
 
   return (
-    <div ref={rootRef} className={cn('flex min-w-0 flex-col gap-1.5', className)}>
+    <div {...rest} ref={rootRef} className={cn('flex min-w-0 flex-col gap-1.5', className)}>
       <div
         // guardrails-ignore no-hand-rolled-surface: a chart's plot well (sunken, fixed height, drawn into) — an instrument surface, not a card
         role='img'

package/src/react/charts/LineChart.tsx

@@ -49,10 +49,11 @@ export function LineChart({
   xTickFormatter,
   valueFormatter,
   labelFormatter,
+  ...rest
 }: LineChartProps) {
   const showLegend = (box: ChartBox) => legend ?? (!box.legendInHeader && series.length > 1);
   return (
-    <ChartFrame ariaLabel={ariaLabel} height={height}>
+    <ChartFrame {...rest} ariaLabel={ariaLabel} height={height}>
       {(t, box) => (
         <RLineChart data={data} margin={{ top: 8, right: 12, bottom: 0, left: 0 }}>
           {grid && (

package/src/react/charts/PieChart.tsx

@@ -51,9 +51,10 @@ export function PieChart({
   legend = true,
   labels = false,
   valueFormatter,
+  ...rest
 }: PieChartProps) {
   return (
-    <ChartFrame ariaLabel={ariaLabel} height={height}>
+    <ChartFrame {...rest} ariaLabel={ariaLabel} height={height}>
       {(t) => (
         <RPieChart margin={{ top: 8, right: 8, bottom: 8, left: 8 }}>
           <Pie

package/src/react/charts/RadialBarChart.tsx

@@ -37,13 +37,14 @@ export function RadialBarChart({
   max,
   legend = true,
   valueFormatter,
+  ...rest
 }: RadialBarChartProps) {
   const ref = useRef<HTMLDivElement>(null);
   const tokens = useChartTokens(ref);
   const rings = data.map((d, i) => ({ ...d, fill: seriesColor(tokens, d, i) }));
   const domainMax = max ?? Math.max(1, ...data.map((d) => d.value));
   return (
-    <div ref={ref} role='img' aria-label={ariaLabel} data-cb-chart='' className='w-full'>
+    <div {...rest} ref={ref} role='img' aria-label={ariaLabel} data-cb-chart='' className='w-full'>
       <ResponsiveContainer width='100%' height={height}>
         <RRadialBarChart
           data={rings}