basalt-ui 2.3.0 → 2.5.0

package/dist/telemetry.js

@@ -1,14 +1,22 @@
 import { createContext } from "react";
 const now = () => performance.timeOrigin + performance.now();
 const errorName = (error) => error instanceof Error ? error.name : "Error";
-function createEmitter(sink) {
-  if (sink === void 0) return noop;
-  return (event) => {
+function createLiveEmitter(read) {
+  const emit = (event) => {
     try {
-      sink(event);
+      read()?.(event);
     } catch {
     }
   };
+  return Object.assign(emit, {
+    startChatTurn(turn) {
+      try {
+        return read()?.startChatTurn?.(turn);
+      } catch {
+        return void 0;
+      }
+    }
+  });
 }
 function noop() {
 }
@@ -26,7 +34,7 @@ function routerTelemetry(router) {
 export {
   TelemetryContext,
   bindRouterTelemetry,
-  createEmitter,
+  createLiveEmitter,
   errorName,
   now,
   routerTelemetry

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v2.3.0
+# basalt-ui v2.5.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, TanStack Charts, toolchain presets
 #
 # Entry points: use the exact import specifier below; do not guess.
@@ -13,7 +13,7 @@
 # A subpath's `Install:` line is its required peers; `OptionalPeers:` are import()-only, install on use.
 
 Package: basalt-ui
-Version: 2.3.0
+Version: 2.5.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, TanStack Charts, toolchain presets",
   "keywords": [
     "charts",

package/src/agent/ai-sdk-transport.ts

@@ -49,7 +49,7 @@ import { assertNever } from '../register'
 import { mintMessageId, mintThreadId } from './id'
 import { TERMINAL_TOOL_STATES } from './parts'
 import type { AgentPart, AgentPartDraft } from './parts'
-import type { ResumableAgentTransport } from './transport'
+import type { AgentStreamContext, ResumableAgentTransport } from './transport'
 
 // ── ai (optional peer) — TYPE-ONLY imports, erased at runtime ────────────────
 // verbatimModuleSyntax-safe: these never trigger a runtime resolution of 'ai'. The actual runtime
@@ -415,7 +415,7 @@ export function aiSdkTransport<TPart = AgentPart>(
       async *stream(
         input: string,
         signal?: AbortSignal,
-        ctx?: { readonly messageId: string },
+        ctx?: AgentStreamContext,
       ): AsyncGenerator<TPart> {
         // Synthesized locally, first — we already know the chat id client-side, so there is no
         // need to wait on the server to hand us a run id (unlike a river-style protocol).
@@ -439,6 +439,9 @@ export function aiSdkTransport<TPart = AgentPart>(
           trigger: 'submit-message',
           messageId: undefined,
           abortSignal: signal,
+          // Per-turn trace context goes to the chat endpoint only (merged over the static headers by
+          // AI SDK's HTTP transport); absent, the request is exactly what it was.
+          ...(ctx?.headers !== undefined ? { headers: ctx.headers } : {}),
         })
         yield* diffChunkStream<TPart>(chatId, chunkStream, readStream, signal)
       },

package/src/agent/index.ts

@@ -24,7 +24,7 @@ export { toAgentError } from './error'
 export type { ChatMessage } from './history'
 export type { AgentThread, ThreadStatus, ThreadsStore } from './thread'
 export type { AgentOutcome, OutcomeResolver } from './outcome'
-export type { AgentTransport, ResumableAgentTransport } from './transport'
+export type { AgentStreamContext, AgentTransport, ResumableAgentTransport } from './transport'
 
 // ── Chat UI ───────────────────────────────────────────────────────────────────
 export { ThreadFeed } from './chat/thread-feed'

package/src/agent/run-records.ts

@@ -12,10 +12,12 @@
  * covers: it outlives the run only until a render shows the outcome (`sweepFlushed`).
  */
 
+import type { ChatTurnEnd, ChatTurnTrace } from '../telemetry'
+
 /** The part of a rendered `runs` entry this module reads. */
 type RenderedRun<TPart> = { readonly status: string; readonly parts: TPart[] }
 
-export type RunEnd = 'settled' | 'failed' | 'stopped'
+export type RunEnd = ChatTurnEnd
 
 export type RunRecord<TPart> = {
   readonly controller: AbortController
@@ -28,15 +30,22 @@ export type RunRecord<TPart> = {
   ended: RunEnd | undefined
   /** A newer run began on the same thread (set by `beginRun` on the record it replaces). */
   superseded: boolean
+  /** The turn's telemetry `settle`, run once by `settleTrace`. */
+  settle: ChatTurnTrace['settle']
 }
 
 export type RunRecords<TPart> = Map<string, RunRecord<TPart>>
 
-/** Registers a live run for `threadId`, replacing whatever record the previous run left. */
+/**
+ * Registers a live run for `threadId`, replacing whatever record the previous run left. A previous
+ * run still being driven is cut short: its trace settles as `stopped`. `settle` is the new turn's
+ * telemetry hook (absent for a resume).
+ */
 export function beginRun<TPart>(
   records: RunRecords<TPart>,
   threadId: string,
   controller: AbortController,
+  settle?: ChatTurnTrace['settle'],
 ): RunRecord<TPart> {
   const record: RunRecord<TPart> = {
     controller,
@@ -45,13 +54,28 @@ export function beginRun<TPart>(
     resolving: false,
     ended: undefined,
     superseded: false,
+    settle,
   }
   const previous = records.get(threadId)
-  if (previous !== undefined) previous.superseded = true
+  if (previous !== undefined) {
+    previous.superseded = true
+    settleTrace(previous, 'stopped')
+  }
   records.set(threadId, record)
   return record
 }
 
+/** Runs the turn's telemetry `settle` once; a throwing consumer hook never breaks the run. */
+export function settleTrace<TPart>(record: RunRecord<TPart>, end: RunEnd): void {
+  const { settle } = record
+  record.settle = undefined
+  try {
+    settle?.(end)
+  } catch {
+    // a throwing sink must never break the app (§ 7 delivery rules)
+  }
+}
+
 /** Marks a run as no longer driven and drops the content it held. */
 export function endRun<TPart>(record: RunRecord<TPart>, reason: RunEnd): void {
   record.ended = reason

package/src/agent/transport.ts

@@ -16,6 +16,16 @@ import type { AgentPartDraft } from './parts'
 
 // ── AgentTransport ────────────────────────────────────────────────────────────
 
+/**
+ * The third `stream` argument. `headers` are extra request headers for THIS turn's request to the
+ * transport's own endpoint — today the W3C trace context a telemetry sink's `startChatTurn`
+ * returned. Absent unless a sink contributed; a transport that ignores them keeps working.
+ */
+export type AgentStreamContext = {
+  readonly messageId: string
+  readonly headers?: Readonly<Record<string, string>> | undefined
+}
+
 /**
  * The injected transport seam. `stream(input, signal, ctx)` returns an async generator of parts.
  * Implement this interface for any backend — fetch-based SSE, AI SDK, or a mock.
@@ -43,11 +53,7 @@ import type { AgentPartDraft } from './parts'
  * }
  */
 export type AgentTransport<TPart = AgentPartDraft, TInput = string> = {
-  stream: (
-    input: TInput,
-    signal?: AbortSignal,
-    ctx?: { readonly messageId: string },
-  ) => AsyncGenerator<TPart>
+  stream: (input: TInput, signal?: AbortSignal, ctx?: AgentStreamContext) => AsyncGenerator<TPart>
   /** Optional: resume a previously-started run from its resumeToken (see StartPart). Transports that don't support resumption simply omit this. */
   resume?: ((resumeToken: string, signal?: AbortSignal) => AsyncGenerator<TPart>) | undefined
 }

package/src/agent/use-agent-thread-runs.ts

@@ -50,6 +50,7 @@ import { createRunCommitter, isContentPart } from './run-committer'
 import {
   beginRun,
   endRun,
+  settleTrace,
   failedThreadIds,
   dismissRun,
   hasLiveRun,
@@ -62,8 +63,8 @@ import type { RunRecord, RunRecords } from './run-records'
 import type { AgentThread, LiveRunStatus, ThreadStatus, ThreadsStore } from './thread'
 import { isResumable } from './transport'
 import type { AgentTransport } from './transport'
-import { TelemetryContext, createEmitter, errorName, now } from '../telemetry'
-import type { BasaltEvent, Telemetry } from '../telemetry'
+import { TelemetryContext, createLiveEmitter, errorName, now } from '../telemetry'
+import type { BasaltEvent, Telemetry, TraceHeaders } from '../telemetry'
 
 // ── ThreadRunState ────────────────────────────────────────────────────────────
 
@@ -388,6 +389,7 @@ async function consumeAndFinalize<TPart extends PartLike>(args: {
         status: outcome.status,
       }),
     )
+    settleTrace(record, 'settled')
   } catch (err) {
     // Guard: the run ended (stop(), unmount — which abort the controller, so their AbortError lands
     // here) or a newer stream took the thread over. Only an abort from somewhere else gets past.
@@ -421,6 +423,7 @@ async function consumeAndFinalize<TPart extends PartLike>(args: {
         failure: { error: err, agentError },
       }),
     )
+    settleTrace(record, 'failed')
     onError?.({ threadId, error: err })
   } finally {
     committer.cancel()
@@ -555,6 +558,24 @@ async function finalizeStop<TPart extends PartLike>(args: {
   }
 }
 
+const TRACEPARENT = /^[\da-f]{2}-[\da-f]{32}-[\da-f]{16}-[\da-f]{2}$/
+const TRACESTATE_MEMBER = /^[\da-z][\w*/@-]{0,255}=[^\s,=]([^,=]{0,254}[^\s,=])?$/
+
+/**
+ * The wire form of a turn's trace context: a well-formed `traceparent` (else none — the request
+ * goes out untraced, the sink's `settle` still runs) and a `tracestate` only if valid.
+ */
+function traceRequestHeaders(headers: TraceHeaders): Record<string, string> | undefined {
+  const { traceparent, tracestate } = headers
+  if (typeof traceparent !== 'string' || !TRACEPARENT.test(traceparent)) return undefined
+  const members = typeof tracestate === 'string' ? tracestate.split(',') : []
+  const valid =
+    members.length > 0 &&
+    members.length <= 32 &&
+    members.every((member) => TRACESTATE_MEMBER.test(member.trim()))
+  return valid ? { traceparent, tracestate: tracestate as string } : { traceparent }
+}
+
 /** The `chat.turn` event for a turn that completed (`failure` absent) or failed. */
 function buildTurnEvent(args: {
   threadId: string
@@ -654,10 +675,7 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
   toUserPartsRef.current = resolvedToUserParts
 
   // Stable over the sink ref, so an inline `telemetry` function never changes what `start` closes over.
-  const emitTelemetry = useMemo<Telemetry>(
-    () => createEmitter((event) => telemetryRef.current?.(event)),
-    [],
-  )
+  const emitTelemetry = useMemo<Telemetry>(() => createLiveEmitter(() => telemetryRef.current), [])
 
   // Resolves the transport for `threadId`: the shared object as-is for the plain-object form
   // (unchanged behavior), or the factory's result — resolved once per thread id and cached in
@@ -707,6 +725,7 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
         if (record.ended !== undefined) continue
         abortedThreadIds.push(threadId)
         record.controller.abort()
+        settleTrace(record, 'stopped')
       }
       recordsRef.current.clear()
       if (abortedThreadIds.length === 0) return
@@ -841,8 +860,12 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
       })
 
       const controller = new AbortController()
-      const record = beginRun(recordsRef.current, threadId, controller)
+      // Opened before the request so its context rides on it; closed by `settleTrace` (a resume is
+      // the same turn's reconnect, not a new one, and carries none).
+      const trace = emitTelemetry.startChatTurn?.({ threadId, messageId: userMessage.id })
+      const record = beginRun(recordsRef.current, threadId, controller, trace?.settle)
       const resolvedTransport = resolveTransport(threadId)
+      const headers = trace?.headers === undefined ? undefined : traceRequestHeaders(trace.headers)
 
       // Non-awaited: this consumer runs in the background so start() returns immediately and
       // multiple threads can stream at once.
@@ -855,7 +878,10 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
         // id instead of a second, unrelated one (R1 — see AgentTransport.stream's doc).
         generator: withPartIds(
           threadId,
-          resolvedTransport.stream(input, controller.signal, { messageId: userMessage.id }),
+          resolvedTransport.stream(input, controller.signal, {
+            messageId: userMessage.id,
+            ...(headers !== undefined ? { headers } : {}),
+          }),
         ),
         userMessage,
         recordsRef,
@@ -913,6 +939,7 @@ export function useAgentThreadRuns<TPart extends PartLike = AgentPart>({
       const { appended, resolving } = record
       endRun(record, 'stopped')
       record.controller.abort()
+      settleTrace(record, 'stopped')
       void finalizeStop({
         threadId,
         parts,

package/src/charts/CartesianChart.tsx

@@ -9,7 +9,7 @@
 import { useCallback, useId, useMemo, useState } from 'react'
 import type { CSSProperties, ReactElement, ReactNode } from 'react'
 import { useInChartCard } from './card-context'
-import { compileCartesian } from './compile'
+import { compileCartesian, refLegendSeries } from './compile'
 import type { CartesianDefinition } from './compile'
 import { ChartEngine, idPrefixOf } from './host'
 import { ChartLegend, legendEntries } from './legend'
@@ -170,9 +170,14 @@ export function CartesianRung<T, X extends ChartX>(
     (ctx: ShellContext) => compileCartesian({ ...stable, ...ctx }),
     [stable],
   )
+  // Reference lines that name themselves join the legend after the series (role `reference`).
+  const legendSeries = useMemo(
+    () => [...stable.series, ...refLegendSeries<T>(stable.refLines)],
+    [stable.series, stable.refLines],
+  )
   return (
     <ChartShell
-      series={series}
+      series={legendSeries}
       compile={compile}
       ariaLabel={ariaLabel}
       {...(legend !== undefined && { legend })}

package/src/charts/DualPanel.tsx

@@ -14,9 +14,9 @@ import { useCallback, useMemo } from 'react'
 import type { ReactElement } from 'react'
 import { VX, alpha } from '../tokens'
 import { resolveContainerClass } from '../tokens/size-classes'
-import { defaultFormatX, defaultNumberFormat, visibleSeries } from './compile'
+import { defaultFormatX, defaultNumberFormat, engineRow, seriesRow, visibleSeries } from './compile'
 import { barMark, emphasis, lineMark, markersOf, thinFill } from './marks'
-import { PanelRung, paneX, paneY, rowsOf } from './panel'
+import { PanelRung, chartHeightOf, paneX, paneY, rowsOf } from './panel'
 import type { PaneBuilder, PanelInput, PanelPlan } from './panel'
 import { xScaleFor } from './scales'
 import { rowX } from './types'
@@ -61,8 +61,10 @@ export type DualPanelBar<T> = {
   positive: string
   /** The fill below zero. */
   negative: string
-  /** Tick and tooltip formatter. */
+  /** Tick formatter, and the tooltip's too unless `tooltipFormat` is given. */
   format: (v: number) => string
+  /** The tooltip row's formatter. Default: `format`. */
+  tooltipFormat?: ((v: number) => string) | undefined
   /** The tooltip row's value, for a unit or a decimal `format` cannot carry. */
   formatValue?: ((v: number, d: T) => string) | undefined
   /** Default `'auto'`: a symmetric `[-maxAbs, maxAbs]` from the data, rounded to nice ticks. A tuple
@@ -95,6 +97,8 @@ export type DualPanelProps<T, X extends Date | number = Date | number> = Pick<
     | {
         domain?: readonly [number, number] | 'auto' | undefined
         format?: ((v: number) => string) | undefined
+        /** The lines' tooltip formatter. Default: `format`. */
+        tooltipFormat?: ((v: number) => string) | undefined
       }
     | undefined
   /**
@@ -157,6 +161,8 @@ export function DualPanel<T, X extends Date | number = Date | number>(
   )
   const all = useMemo(() => [...lines, barSeries], [lines, barSeries])
   const topFormat = top?.format ?? defaultNumberFormat
+  const topTooltipFormat = top?.tooltipFormat ?? topFormat
+  const barTooltipFormat = bar.tooltipFormat ?? bar.format
 
   const plan = useCallback(
     ({ hidden, highlighted }: PanelInput): PanelPlan<T> => {
@@ -263,13 +269,21 @@ export function DualPanel<T, X extends Date | number = Date | number>(
           ],
           scales: {
             x: { scale: xScale(), axis: false },
-            y: paneY({ scale: topY, domain: topDomain, format: topFormat, ticks: TOP_TICKS, cls }),
+            y: paneY({
+              scale: topY,
+              domain: topDomain,
+              format: topFormat,
+              ticks: TOP_TICKS,
+              cls,
+              height: chartHeightOf(h, topFraction, PANE_GAP),
+            }),
           },
         }
       }
 
-      const barPane: PaneBuilder = ({ width }) => {
+      const barPane: PaneBuilder = ({ width, height: h }) => {
         const cls = resolveContainerClass(width)
+        const whole = chartHeightOf(h, 1 - topFraction, PANE_GAP)
         const barRows = barOn ? rowsOf(data, x, barSeries) : []
         const dim = emphasis(highlighted, { key: BAR_KEY })
         return {
@@ -284,13 +298,14 @@ export function DualPanel<T, X extends Date | number = Date | number>(
             }),
           ],
           scales: {
-            x: paneX({ scale: xScale(), model, format, cls }),
+            x: paneX({ scale: xScale(), model, format, cls, height: whole }),
             y: paneY({
               scale: barScale,
               domain: barDomain,
               format: bar.format,
               ticks: BAR_TICKS,
               cls,
+              height: whole,
             }),
           },
         }
@@ -307,26 +322,42 @@ export function DualPanel<T, X extends Date | number = Date | number>(
           for (const s of visible) {
             const v = s.getValue(d)
             if (s.tooltip === false || v === null || !Number.isFinite(v)) continue
-            out.push({
-              label: s.note === undefined ? s.label : `${s.label} · ${s.note}`,
-              value: s.formatValue ? s.formatValue(v, d) : topFormat(v),
-              color: s.color,
-              ...(highlighted === s.key && { active: true }),
-            })
+            out.push(
+              seriesRow(
+                s,
+                s.formatValue ? s.formatValue(v, d) : topTooltipFormat(v),
+                highlighted === s.key,
+              ),
+            )
           }
           const v = barOn ? bar.getValue(d) : null
           if (v !== null && Number.isFinite(v))
-            out.push({
-              label: bar.label,
-              value: bar.formatValue ? bar.formatValue(v, d) : bar.format(v),
-              color: v >= 0 ? bar.positive : bar.negative,
-              ...(highlighted === BAR_KEY && { active: true }),
-            })
+            out.push(
+              engineRow({
+                label: bar.label,
+                value: bar.formatValue ? bar.formatValue(v, d) : barTooltipFormat(v),
+                color: v >= 0 ? bar.positive : bar.negative,
+                active: highlighted === BAR_KEY,
+              }),
+            )
           return out
         },
       }
     },
-    [data, x, lines, barSeries, top, fillBetween, bar, topFraction, topFormat, formatX],
+    [
+      data,
+      x,
+      lines,
+      barSeries,
+      top,
+      fillBetween,
+      bar,
+      topFraction,
+      topFormat,
+      topTooltipFormat,
+      barTooltipFormat,
+      formatX,
+    ],
   )
 
   return <PanelRung {...rung} series={all} plan={plan} />

package/src/charts/Heatmap.tsx

@@ -18,7 +18,7 @@ import type { CSSProperties, ReactElement } from 'react'
 import type { BasaltProps } from '../common/props'
 import { alpha, VX } from '../tokens'
 import { resolveContainerClass } from '../tokens/size-classes'
-import { strideTicks } from './compile'
+import { engineRow, strideTicks } from './compile'
 import type { CartesianDefinition } from './compile'
 import { ChartEngine, idPrefixOf } from './host'
 import { useCoarsePointer } from '../common/use-media-query'
@@ -244,7 +244,7 @@ export function Heatmap<T>(props: HeatmapProps<T>): ReactElement {
                         ...(point.color && { color: point.color }),
                       },
                     ]
-              return { title: header(c), rows: [...value, ...extra] }
+              return { title: header(c), rows: [...value, ...extra].map(engineRow) }
             },
           }
         : false,

package/src/charts/Lines.tsx

@@ -17,7 +17,7 @@ import { VX } from '../tokens'
 import { CartesianRung } from './CartesianChart'
 import { areaGradientId } from './compile'
 import { chartCurve } from './curves'
-import { lineMark, markersOf, yScaleOf } from './marks'
+import { drawnRows, lineMark, markersOf, yScaleOf } from './marks'
 import { rowX } from './types'
 import type {
   CartesianChartProps,
@@ -120,7 +120,7 @@ export function Lines<T, X extends ChartX = ChartX>(props: LinesProps<T, X>): Re
         if (!s.area) continue
         out.push(
           decorative(
-            areaY(plot.rows(s.key), {
+            areaY(drawnRows(plot, s), {
               id: `${s.key}-area`,
               x: rowX,
               y2: 'y',

package/src/charts/MirroredBars.tsx

@@ -21,9 +21,9 @@ import { useCallback, useMemo } from 'react'
 import type { ReactElement } from 'react'
 import { VX, alpha } from '../tokens'
 import { resolveContainerClass } from '../tokens/size-classes'
-import { defaultFormatX, defaultNumberFormat, visibleSeries } from './compile'
+import { defaultFormatX, defaultNumberFormat, seriesRow, visibleSeries } from './compile'
 import { barMark, emphasis } from './marks'
-import { PanelRung, paneX, paneY, rowsOf } from './panel'
+import { PanelRung, chartHeightOf, paneX, paneY, rowsOf } from './panel'
 import type { PaneBuilder, PanelInput, PanelPlan } from './panel'
 import { xScaleFor } from './scales'
 import { rowX } from './types'
@@ -174,8 +174,9 @@ export function MirroredBars<T, X extends ChartX = ChartX>(
           on: boolean,
           max: number,
         ): PaneBuilder =>
-        ({ width: w }) => {
+        ({ width: w, height: h }) => {
           const cls = resolveContainerClass(w)
+          const whole = chartHeightOf(h, side === 'up' ? upFraction : 1 - upFraction, 0)
           // The down pane's zero is at its top.
           const domain: [number, number] = side === 'up' ? [0, max] : [max, 0]
           const rows: PlotRow<T, X>[] = on ? rowsOf(drawn, x, s) : []
@@ -249,7 +250,7 @@ export function MirroredBars<T, X extends ChartX = ChartX>(
             scales: {
               x:
                 side === 'down'
-                  ? paneX({ scale: bandScale(), model, format, cls })
+                  ? paneX({ scale: bandScale(), model, format, cls, height: whole })
                   : { scale: bandScale(), axis: false },
               y: paneY({
                 scale: scaleLinear().domain(domain),
@@ -257,6 +258,7 @@ export function MirroredBars<T, X extends ChartX = ChartX>(
                 format: cfg.format,
                 ticks: cfg.ticks ?? DEFAULT_PANE_TICKS,
                 cls,
+                height: whole,
               }),
               zx: { channel: 'x', scale: scaleLinear().domain([0, 1]), axis: false },
             },
@@ -277,12 +279,13 @@ export function MirroredBars<T, X extends ChartX = ChartX>(
             // Each pane's row falls back to ITS OWN formatter: the panes are in different units.
             const fallback =
               s.key === up.key ? up.format : s.key === down.key ? down.format : defaultNumberFormat
-            out.push({
-              label: s.note === undefined ? s.label : `${s.label} · ${s.note}`,
-              value: s.formatValue ? s.formatValue(v, d) : fallback(v),
-              color: s.color,
-              ...(highlighted === s.key && { active: true }),
-            })
+            out.push(
+              seriesRow(
+                s,
+                s.formatValue ? s.formatValue(v, d) : fallback(v),
+                highlighted === s.key,
+              ),
+            )
           }
           return out
         },