basalt-ui 1.8.0 → 1.10.0

package/src/agent/use-agent-thread-runs.wedge.test.tsx

@@ -0,0 +1,299 @@
+/**
+ * F3 — the mount-reconcile / unmount-cleanup wedge in useAgentThreadRuns.
+ *
+ * The bug: the unmount-cleanup effect (`controllersRef.current.forEach(c => c.abort())`) aborted
+ * every in-flight controller but never CLEARED the map. The mount-reconcile effect treats a thread
+ * as "orphaned" (worth a resume attempt) only when `!controllersRef.current.has(thread.id)`. If
+ * this fiber's effects re-run WITHOUT the fiber itself unmounting — React 19 StrictMode's
+ * dev-only double-invoke, or a `<Activity>` boundary being hidden then shown again — the stale,
+ * now-aborted entry survives into the second reconcile pass, `orphaned` reads `false`, no new
+ * resume is attempted, and the one live consumer that WAS attempted already returned silently on
+ * its AbortError (`consumeAndFinalize`'s guard at the top of its try block). The thread is left in
+ * `'streaming'` forever with nothing left to resolve it.
+ *
+ * Both halves matter equally here:
+ *
+ *   (a) REFUTED — a genuine unmount + remount (a fresh component instance, not a re-run of THIS
+ *       fiber's effects) gets a brand-new `useRef` Map. There is nothing for the fix to protect
+ *       against here; the test exists so nobody "fixes" this non-bug later.
+ *   (b) CONFIRMED — React 19 StrictMode's dev-only double-invoke reuses the SAME fiber (and thus
+ *       the same ref) across a simulated unmount+remount within one commit.
+ *   (c) CONFIRMED — React 19.2's `<Activity>` does the SAME thing in PRODUCTION: hiding an
+ *       Activity boundary destroys the subtree's effects and re-creates them on show, while state,
+ *       DOM, and ref identity survive. This is the reachable-in-prod half of the wedge, not a
+ *       StrictMode-only curiosity — hence testing it directly against `<Activity>` from `react`
+ *       rather than only through Mantine's `Collapse`. At the `@mantine/core` 9.3.0 pinned in THIS
+ *       repo, `Collapse` has no `keepMounted` DEFAULT — with the prop unset it keeps `children`
+ *       permanently mounted (the `else` branch below), so a bare `<Collapse>` cannot wedge and a
+ *       default-Collapse-based test would not reproduce the bug. But a consumer writing
+ *       `<Collapse keepMounted>` on this SAME 9.3.0 does hit the `<Activity>` path — read
+ *       the installed `@mantine/core` 9.3.0 `Collapse.mjs` source directly: it imports
+ *       `Activity` from `react` and, when `keepMounted === true`, renders
+ *       `jsx(Activity, { mode: isExited ? 'hidden' : 'visible', … })` on the ordinary non-zero-
+ *       duration path (only the `duration === 0` fast path carries a `&& env !== 'test'` guard). So
+ *       the Activity hazard is live on THIS pinned version, not only on the 9.4.1 argo resolves —
+ *       testing `<Activity>` directly is still the right call because it is what a `keepMounted`
+ *       consumer actually gets here today, not because 9.3.0 is exempt.
+ *
+ * Verified manually while writing this file (reported alongside the test suite, not re-asserted
+ * here as a runtime check): reverting the one-line `controllersRef.current.clear()` fix makes (b)
+ * and (c) fail — the thread's status stays `'streaming'` instead of settling — while (a) passes
+ * either way, exactly as the "refutation" framing above expects.
+ *
+ * Both (b) and (c) observe `resume()` invoked TWICE post-fix (once for the pass that gets aborted,
+ * once for the pass that survives), not once — React's whole justification for double-invoking a
+ * mount effect with a side effect (a network call here) is to surface exactly this
+ * non-idempotence; a spec that anticipated "resume() attempted exactly once" for this scenario
+ * does not match observed React 19.2.7 behavior. What's invariant, and what these tests assert, is
+ * that the thread SETTLES (leaves `'streaming'`) rather than wedging — the resume() call count is
+ * asserted too, but as an observed constant with the doubling explained, not as evidence of a
+ * single attempt.
+ */
+import { describe, expect, test } from 'bun:test'
+import { Activity, StrictMode, useState } from 'react'
+import { act, render, renderHook, waitFor } from '@testing-library/react'
+import { useAgentThreadRuns } from './use-agent-thread-runs'
+import type { AgentThread, ThreadsStore } from './thread'
+import type { AgentTransport } from './transport'
+import type { AgentPart } from './parts'
+import type { ChatMessage } from './history'
+import type { AgentOutcome } from './outcome'
+
+// ── test-only ThreadsStore double ────────────────────────────────────────────
+//
+// A plain mutable object satisfying the ThreadsStore contract — no React state, no
+// localStorage/useSyncExternalStore. useAgentThreadRuns only ever reads `store.threads` and calls
+// its action methods synchronously (via `storeRef.current`), so a hand-rolled mutable double gives
+// the test full, synchronous, non-persisted control over what a "reload mid-stream" looked like —
+// exactly what these mount-reconcile tests need to seed.
+function createTestThreadsStore(initial: AgentThread<AgentPart>[] = []): ThreadsStore<AgentPart> {
+  let threads = initial
+  let activeId: string | null = null
+  return {
+    get threads() {
+      return threads
+    },
+    get activeId() {
+      return activeId
+    },
+    select(id) {
+      activeId = id
+    },
+    create(opts) {
+      const id = crypto.randomUUID()
+      const now = Date.now()
+      const thread: AgentThread<AgentPart> = {
+        id,
+        messages: [],
+        outcome: null,
+        status: 'pending',
+        read: false,
+        createdAt: now,
+        updatedAt: now,
+        ...(opts?.meta !== undefined ? { meta: opts.meta } : {}),
+      }
+      threads = [thread, ...threads]
+      return id
+    },
+    appendMessage(id, message) {
+      threads = threads.map((thread) =>
+        thread.id === id
+          ? { ...thread, messages: [...thread.messages, message], updatedAt: Date.now() }
+          : thread,
+      )
+    },
+    setOutcome(id, outcome) {
+      threads = threads.map((thread) =>
+        thread.id === id ? { ...thread, outcome, updatedAt: Date.now() } : thread,
+      )
+    },
+    setStatus(id, status) {
+      threads = threads.map((thread) =>
+        thread.id === id ? { ...thread, status, updatedAt: Date.now() } : thread,
+      )
+    },
+    setResumeToken(id, token) {
+      threads = threads.map((thread) => {
+        if (thread.id !== id) return thread
+        const { resumeToken: _resumeToken, ...rest } = thread
+        return {
+          ...rest,
+          ...(token !== undefined ? { resumeToken: token } : {}),
+          updatedAt: Date.now(),
+        }
+      })
+    },
+    markRead(id) {
+      threads = threads.map((thread) => (thread.id === id ? { ...thread, read: true } : thread))
+    },
+    remove(id) {
+      threads = threads.filter((thread) => thread.id !== id)
+      if (activeId === id) activeId = null
+    },
+    clear() {
+      threads = []
+      activeId = null
+    },
+  }
+}
+
+function makeThread(overrides: Partial<AgentThread<AgentPart>> = {}): AgentThread<AgentPart> {
+  const now = Date.now()
+  return {
+    id: crypto.randomUUID(),
+    messages: [],
+    outcome: null,
+    status: 'pending',
+    read: false,
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  }
+}
+
+function deferred<T>(): { promise: Promise<T>; resolve: (value: T) => void } {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((r) => {
+    resolve = r
+  })
+  return { promise, resolve }
+}
+
+const resolveOutcome = (): AgentOutcome => ({ title: 'title', summary: 'summary', status: 'done' })
+
+describe('useAgentThreadRuns — F3 mount-reconcile / unmount-cleanup wedge', () => {
+  test('(a) REFUTED: a genuine unmount + remount gets a fresh controllers map — resolves to interrupted, never re-enters streaming', () => {
+    const store = createTestThreadsStore()
+    const threadId = store.create()
+
+    // No `resume` on this transport: on remount, the orphaned thread must fall straight to
+    // 'interrupted' with no async wait involved.
+    const transport: AgentTransport<AgentPart, string> = {
+      // oxlint-disable-next-line require-yield -- hangs until aborted; never has anything to yield
+      async *stream(_input, signal) {
+        await new Promise((resolve) => {
+          signal?.addEventListener('abort', () => resolve(undefined))
+        })
+      },
+    }
+
+    const { result, unmount } = renderHook(() =>
+      useAgentThreadRuns({ transport, store, resolveOutcome }),
+    )
+
+    act(() => {
+      result.current.start(threadId, 'hello')
+    })
+    expect(store.threads.find((thread) => thread.id === threadId)?.status).toBe('streaming')
+
+    unmount()
+
+    // A brand-new component instance against the SAME store object — a fresh fiber, fresh
+    // `useRef` Map. This must hold both before AND after the F3 fix.
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }))
+
+    expect(store.threads.find((thread) => thread.id === threadId)?.status).toBe('interrupted')
+  })
+
+  test('(b) CONFIRMED: React 19 StrictMode double-invoke resumes the orphaned thread instead of wedging it in streaming', async () => {
+    const userMessage: ChatMessage<AgentPart> = {
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text: 'hello' }],
+      createdAt: Date.now(),
+    }
+    const thread = makeThread({
+      status: 'streaming',
+      resumeToken: 'resume-token-1',
+      messages: [userMessage],
+    })
+    const store = createTestThreadsStore([thread])
+
+    let resumeCalls = 0
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+      async *resume() {
+        resumeCalls++
+        yield { type: 'text', text: 'resumed' }
+      },
+    }
+
+    renderHook(() => useAgentThreadRuns({ transport, store, resolveOutcome }), {
+      wrapper: StrictMode,
+    })
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === thread.id)?.status).toBe('done')
+    })
+    // Observed constant for this scenario (see file doc): the aborted first pass plus the
+    // surviving second pass, not "exactly once".
+    expect(resumeCalls).toBe(2)
+  })
+
+  test('(c) CONFIRMED: an <Activity> hide/show cycle resumes the orphaned thread instead of wedging it in streaming', async () => {
+    const userMessage: ChatMessage<AgentPart> = {
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text: 'hello' }],
+      createdAt: Date.now(),
+    }
+    const thread = makeThread({
+      status: 'streaming',
+      resumeToken: 'resume-token-2',
+      messages: [userMessage],
+    })
+    const store = createTestThreadsStore([thread])
+
+    // Gates the first resume() attempt so the hide happens strictly before it settles — an
+    // explicit happens-before, not a scheduler coincidence a `setTimeout(…, 0)` would only
+    // usually win.
+    const gate = deferred<void>()
+
+    let resumeCalls = 0
+    const transport: AgentTransport<AgentPart, string> = {
+      async *stream() {},
+      async *resume() {
+        resumeCalls++
+        await gate.promise
+        yield { type: 'text', text: 'resumed' }
+      },
+    }
+
+    let externalSetMode: ((mode: 'visible' | 'hidden') => void) | undefined
+
+    function Probe(): null {
+      useAgentThreadRuns({ transport, store, resolveOutcome })
+      return null
+    }
+
+    function Harness(): JSX.Element {
+      const [mode, setMode] = useState<'visible' | 'hidden'>('visible')
+      externalSetMode = setMode
+      return (
+        <Activity mode={mode}>
+          <Probe />
+        </Activity>
+      )
+    }
+
+    await act(async () => {
+      render(<Harness />)
+    })
+
+    // First resume attempt is in flight (its gate hasn't been released yet) — hide now to abort
+    // it via the F3-fixed cleanup effect. `gate.resolve()` only runs after this completes, so the
+    // hide is guaranteed to land before the first attempt could ever settle.
+    await act(async () => {
+      externalSetMode?.('hidden')
+    })
+    gate.resolve()
+    await act(async () => {
+      externalSetMode?.('visible')
+    })
+
+    await waitFor(() => {
+      expect(store.threads.find((t) => t.id === thread.id)?.status).toBe('done')
+    })
+    expect(resumeCalls).toBe(2)
+  })
+})

package/src/agent-chat/index.ts

@@ -2,11 +2,12 @@
  * Mantine-styled thread-chat components over the headless `basalt-ui/agent` layer, capped by the
  * flagship `ThreadWorkspace` composite.
  *
- * This module is Mantine-coupled by design and lives under the root entry (unlike `basalt-ui/agent`,
- * which stays headless so it can be styled by any consumer).
+ * This module is Mantine-coupled by design and ships its own `basalt-ui/agent-chat` subpath
+ * (also re-exported from the root entry, unchanged for existing consumers) — unlike
+ * `basalt-ui/agent`, which stays headless so it can be styled by any consumer.
  *
  * @example
- * import { ThreadWorkspace } from 'basalt-ui'
+ * import { ThreadWorkspace } from 'basalt-ui/agent-chat'
  * import { createThreadsStore, edenTransport, heuristicOutcome } from 'basalt-ui/agent'
  */
 

package/src/charts/hooks/useHoverSync.ts

@@ -24,12 +24,29 @@ export function useHoverSync<T>({
   getKey,
   xScale,
   marginLeft,
+  resolveKey,
 }: {
   data: T[]
   chartId: string
   getKey: (d: T) => string
   xScale: XScale
   marginLeft: number
+  /**
+   * Overrides how a SIBLING's broadcast key resolves to one of THIS chart's own points. Only
+   * affects reading another chart's hover — this chart's own hover (via `getKey`/`xScale`) is
+   * untouched.
+   *
+   * Cross-chart sync is exact string match by default (`pointByKey.get(ctx.key)`), so two charts
+   * share a cursor only if they emit identical key strings. A chart that downsamples/folds its
+   * domain to fit a narrow viewport (e.g. ~288 buckets folded into ~97 columns at 390px) no longer
+   * owns most of the keys its unfolded siblings broadcast — the shared crosshair then appears on
+   * roughly one hover in three, with no rule a reader can infer, which is worse than no shared
+   * cursor at all. Pass `resolveKey` to map a foreign key onto whichever of this chart's own points
+   * swallowed it (e.g. the folded bucket the key falls into).
+   *
+   * Omit it and behaviour is byte-identical to today.
+   */
+  resolveKey?: (key: string) => T | null
 }) {
   const ctx = useContext(HoverContext)
   // Latest context in a ref so the mouse callbacks stay referentially stable: the provider's value
@@ -53,13 +70,26 @@ export function useHoverSync<T>({
 
   const { tip, show, hide, tooltipRef, lastDateRef } = useChartTooltip<T>()
 
+  // Latest accessors in refs, same reasoning as `ctxRef` above: the natural call style is an
+  // inline arrow for `getKey`/`xScale`, which is fresh on every render, and this file already
+  // pays for that hazard once (see the comment above `ctxRef`) without applying the fix here — a
+  // several-hundred-entry `pointByKey` Map was rebuilding on every render of a page that
+  // re-renders on a heartbeat. Trade-off: because `getKey` is read through a ref, changing key
+  // SEMANTICS without changing `data` will NOT rebuild the map. That's the intended trade — a
+  // `getKey` that changes meaning for the same data is pathological; a `getKey` that changes
+  // identity every render is the normal case.
+  const getKeyRef = useRef(getKey)
+  getKeyRef.current = getKey
+  const xScaleRef = useRef(xScale)
+  xScaleRef.current = xScale
+
   // O(1) lookup of a point by its key. Under a provider every sibling resolves the broadcast
   // key each frame; an O(n) `data.find` per sibling per move is N×O(M). This makes it N×O(1).
   const pointByKey = useMemo(() => {
     const m = new Map<string, T>()
-    for (const d of data) m.set(getKey(d), d)
+    for (const d of data) m.set(getKeyRef.current(d), d)
     return m
-  }, [data, getKey])
+  }, [data])
 
   const handleMouse = useCallback(
     (event: React.MouseEvent<SVGRectElement>) => {
@@ -69,7 +99,7 @@ export function useHoverSync<T>({
       let closest: T = data[0] as T
       let minDist = Infinity
       for (const d of data) {
-        const sx = xScale(getKey(d)) ?? 0
+        const sx = xScaleRef.current(getKeyRef.current(d)) ?? 0
         const dist = Math.abs(sx - px)
         if (dist < minDist) {
           minDist = dist
@@ -77,13 +107,13 @@ export function useHoverSync<T>({
         }
       }
       show(closest, event)
-      const key = getKey(closest)
+      const key = getKeyRef.current(closest)
       if (lastDateRef.current !== key) {
         lastDateRef.current = key
         ctxRef.current.setHover(key, chartId)
       }
     },
-    [data, xScale, getKey, chartId, marginLeft, show, lastDateRef],
+    [data, chartId, marginLeft, show, lastDateRef],
   )
 
   const handleLeave = useCallback(() => {
@@ -97,8 +127,14 @@ export function useHoverSync<T>({
   // The point the crosshair + synced dots track. Inside a <ChartHoverSync> this follows the
   // broadcast key (so every sibling paints a ghost crosshair at the same x). WITHOUT a provider the
   // chart is standalone, so it falls back to THIS chart's own hovered point (`tip.data`) — otherwise
-  // a chart outside a provider would never draw a crosshair/dots at all.
-  const syncedPoint = ctx.key ? (pointByKey.get(ctx.key) ?? null) : (tip?.data ?? null)
+  // a chart outside a provider would never draw a crosshair/dots at all. When `resolveKey` is
+  // supplied it replaces the default exact-match lookup for reading a SIBLING's broadcast key (see
+  // its doc comment above) — this chart's own hover is unaffected either way.
+  const syncedPoint = ctx.key
+    ? resolveKey
+      ? resolveKey(ctx.key)
+      : (pointByKey.get(ctx.key) ?? null)
+    : (tip?.data ?? null)
   // Which chart owns the floating tooltip. Inside a provider the hovered chart is the one whose id
   // matches the broadcast source (siblings show a ghost crosshair only). Standalone, its own local
   // hover (`tip`) drives the tooltip.

package/src/charts/index.ts

@@ -46,6 +46,12 @@ export {
 // ── Primitives ───────────────────────────────────────────────────────────
 export { ResponsiveChart, type ResponsiveChartProps } from './primitives/ResponsiveChart'
 export { ChartFrame, type ChartFrameProps, type ChartFrameLegend } from './primitives/ChartFrame'
+export {
+  ChartCenter,
+  type ChartCenterProps,
+  ChartPending,
+  type ChartPendingProps,
+} from './primitives/ChartPending'
 export { Crosshair, SeriesDot } from './primitives/Crosshair'
 export { ChartCard } from './primitives/ChartCard'
 export { ChartLegend, type LegendEntry } from './primitives/ChartLegend'

package/src/charts/kinds/Bars.tsx

@@ -139,6 +139,8 @@ export type BarsProps<T> = {
   legend?: ChartLegendConfig | false
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 /**
@@ -164,6 +166,7 @@ function BarsInner<T>(props: BarsProps<T>) {
     height,
     legend,
     ariaLabel,
+    isPending,
   } = props
   const [highlightedKey, setHighlightedKey] = useState<string | null>(null)
 
@@ -207,6 +210,7 @@ function BarsInner<T>(props: BarsProps<T>) {
       chartId={chartId}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
       legend={resolveLegend(legend, {
         highlighted: highlightedKey,
         onHighlight: setHighlightedKey,

package/src/charts/kinds/Donut.tsx

@@ -53,6 +53,8 @@ export type DonutProps<K extends string = SeriesKey> = {
   padAngle?: number
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 /**
@@ -64,7 +66,7 @@ export type DonutProps<K extends string = SeriesKey> = {
  * (donut ↔ bar, via the generalized key) is a distinct, deliberately deferred feature.
  */
 function DonutInner<K extends string = SeriesKey>(props: DonutProps<K>) {
-  const { data, height, colorForKey, seriesLabel = (k) => k, ariaLabel } = props
+  const { data, height, colorForKey, seriesLabel = (k) => k, ariaLabel, isPending } = props
 
   const series: SeriesStyle[] = data.map((d) => ({
     key: d.key,
@@ -78,6 +80,7 @@ function DonutInner<K extends string = SeriesKey>(props: DonutProps<K>) {
       series={series}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
     >
       {(plot) => <DonutPlot {...props} plot={plot} />}
     </ChartFrame>
@@ -136,13 +139,16 @@ function DonutPlot<K extends string = SeriesKey>(props: DonutPlotProps<K>) {
                 return (
                   <g
                     key={key}
-                    onMouseEnter={(event) => {
+                    onPointerEnter={(event) => {
                       show(arc.data, event)
                     }}
-                    onMouseMove={(event) => {
+                    onPointerMove={(event) => {
                       show(arc.data, event)
                     }}
-                    onMouseLeave={() => {
+                    onPointerLeave={() => {
+                      hide()
+                    }}
+                    onPointerCancel={() => {
                       hide()
                     }}
                     style={{ cursor: 'pointer' }}

package/src/charts/kinds/DualPanel.tsx

@@ -57,6 +57,8 @@ export type DualPanelProps<T> = {
   legend?: ChartLegendConfig | false
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 const PANE_GAP = 12
@@ -74,7 +76,8 @@ const PANE_GAP = 12
  * when a series has nulls; lines/bars skip null points (visual gaps).
  */
 function DualPanelInner<T>(props: DualPanelProps<T>) {
-  const { series, chartId, height, barLabel, barColorPositive, legend, ariaLabel } = props
+  const { series, chartId, height, barLabel, barColorPositive, legend, ariaLabel, isPending } =
+    props
 
   // Default the top-pane line overlays to the redesign's 1.9px stroke (docs/DESIGN-SPEC.md §5) —
   // applied once here so the plotted line, the derived legend swatch, and the derived tooltip row
@@ -101,6 +104,7 @@ function DualPanelInner<T>(props: DualPanelProps<T>) {
       chartId={chartId}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
       legend={resolveLegend(legend)}
     >
       {(plot) => <DualPanelPlot {...props} series={styledSeries} plot={plot} />}

package/src/charts/kinds/Heatmap.tsx

@@ -8,6 +8,7 @@ import {
   TooltipRow,
   useTooltipStyles,
 } from '../primitives/ChartTooltip'
+import { ChartPending } from '../primitives/ChartPending'
 import { useChartTooltip } from '../hooks/useChartTooltip'
 import { VX, alpha } from '../../tokens'
 
@@ -47,6 +48,14 @@ export type HeatmapProps<T> = {
   renderTooltip?: (cell: HeatmapCell) => ReactNode
   /** Optional gradient legend strip below the grid (faint → solid color). */
   legend?: { min: string; max: string }
+  /**
+   * The query behind this chart hasn't resolved yet. Renders `ChartPending` (see its JSDoc for the
+   * three-state rationale) over the full `width` × `height` box in place of the grid, suppressing
+   * the legend strip and every cell/label/tooltip along with it. Unlike the other six kinds,
+   * `Heatmap` doesn't compose `ChartFrame` (it takes `width`/`height` directly rather than
+   * measuring), so this is handled locally instead of forwarded.
+   */
+  isPending?: boolean
 }
 
 /** Build a first-seen-ordered list of unique keys from data via an accessor. */
@@ -106,6 +115,7 @@ function HeatmapInner<T>(props: HeatmapProps<T>) {
     colLabel = (c) => c,
     renderTooltip,
     legend,
+    isPending,
   } = props
 
   const tooltipStyles = useTooltipStyles()
@@ -126,6 +136,12 @@ function HeatmapInner<T>(props: HeatmapProps<T>) {
     return { lookup: map, max: m }
   }, [data, getRow, getCol, getValue])
 
+  // Every hook above must still run on a pending render (Rules of Hooks) — the early return comes
+  // after them. No `ChartFrame` to forward to here (Heatmap measures via required `width`/`height`
+  // props, not `useChartSize`), so the placeholder is rendered directly in its place, same footprint,
+  // legend strip and all other content omitted along with it.
+  if (isPending) return <ChartPending width={width} height={height} />
+
   const legendH = legend ? LEGEND_H + LEGEND_LABEL_H : 0
   const gridW = Math.max(0, width - PAD_LEFT)
   const gridH = Math.max(0, height - PAD_TOP - PAD_BOTTOM - legendH)
@@ -152,8 +168,9 @@ function HeatmapInner<T>(props: HeatmapProps<T>) {
                   rx={cellRadius}
                   fill={fill}
                   style={{ cursor: has ? 'pointer' : 'default' }}
-                  onMouseMove={(e) => has && show({ row, col, value }, e)}
-                  onMouseLeave={hide}
+                  onPointerMove={(e) => has && show({ row, col, value }, e)}
+                  onPointerLeave={hide}
+                  onPointerCancel={hide}
                 />
               )
             }),

package/src/charts/kinds/MultiLine.tsx

@@ -67,6 +67,8 @@ export type MultiLineProps<T> = {
   legend?: ChartLegendConfig | false
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 const STAR_R = 6
@@ -96,7 +98,7 @@ function starPath(cx: number, cy: number, r: number): string {
  * has nulls; each series line skips null points (creating visual gaps).
  */
 function MultiLineInner<T>(props: MultiLineProps<T>) {
-  const { series, chartId, height, legend, ariaLabel } = props
+  const { series, chartId, height, legend, ariaLabel, isPending } = props
   const [highlightedKey, setHighlightedKey] = useState<string | null>(null)
 
   // Default line overlays to the redesign's 1.9px stroke (docs/DESIGN-SPEC.md §5) — applied once
@@ -112,6 +114,7 @@ function MultiLineInner<T>(props: MultiLineProps<T>) {
       chartId={chartId}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
       legend={resolveLegend(legend, {
         highlighted: highlightedKey,
         onHighlight: setHighlightedKey,

package/src/charts/kinds/StackedArea.tsx

@@ -40,6 +40,8 @@ export type StackedAreaProps<T> = {
   legend?: ChartLegendConfig | false
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 /**
@@ -48,7 +50,7 @@ export type StackedAreaProps<T> = {
  * The tooltip renders rows in reversed (top-to-bottom) stack order so it matches the visual stack.
  */
 function StackedAreaInner<T>(props: StackedAreaProps<T>) {
-  const { series, chartId, height, legend, ariaLabel } = props
+  const { series, chartId, height, legend, ariaLabel, isPending } = props
   const [highlightedKey, setHighlightedKey] = useState<string | null>(null)
 
   return (
@@ -57,6 +59,7 @@ function StackedAreaInner<T>(props: StackedAreaProps<T>) {
       chartId={chartId}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
       legend={resolveLegend(legend, {
         highlighted: highlightedKey,
         onHighlight: setHighlightedKey,

package/src/charts/kinds/ZonedLine.tsx

@@ -101,6 +101,8 @@ export type ZonedLineProps<T> = {
   legend?: ChartLegendConfig | false
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 /**
@@ -116,7 +118,7 @@ export type ZonedLineProps<T> = {
  * visual gaps).
  */
 function ZonedLineInner<T>(props: ZonedLineProps<T>) {
-  const { series, chartId, height, legend, ariaLabel } = props
+  const { series, chartId, height, legend, ariaLabel, isPending } = props
 
   // Default the line overlay to the redesign's 1.9px stroke (docs/DESIGN-SPEC.md §5) — applied
   // once here so the plotted line, the derived legend swatch, and the derived tooltip row agree.
@@ -131,6 +133,7 @@ function ZonedLineInner<T>(props: ZonedLineProps<T>) {
       chartId={chartId}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
       legend={resolveLegend(legend)}
     >
       {(plot) => <ZonedLinePlot {...props} series={styledSeries} plot={plot} />}