basalt-ui 2.4.0 → 2.6.0

package/dist/telemetry.d.ts

@@ -57,15 +57,69 @@ export type BasaltEvent = Ok<'route.navigate', RouteAttrs> | Err<'route.error',
 }> | Err<'window.error', {
     'basalt.error.source': 'error' | 'unhandledrejection';
 }> | Ok<'chat.turn', ChatAttrs> | Err<'chat.turn', ChatAttrs, Span>;
-export type Telemetry = (event: BasaltEvent) => void;
+/** W3C trace-context request headers a sink contributes to one chat turn's request. */
+export type TraceHeaders = {
+    readonly traceparent: string;
+    readonly tracestate?: string | undefined;
+};
+/**
+ * How a traced chat turn ended: its `chat.turn` event fired (`settled`/`failed`), or `stopped` — a
+ * `stop()`, an unmount or a newer run taking the thread over — which emits no event. The one
+ * lifecycle vocabulary of the run records too.
+ */
+export type ChatTurnEnd = 'settled' | 'failed' | 'stopped';
+/** The turn a sink is asked to trace. */
+type ChatTurnInit = {
+    readonly threadId: string;
+    readonly messageId: string;
+};
+/**
+ * What a sink returns from `startChatTurn`. `settle` runs once, synchronously, right after the
+ * turn's `chat.turn` event (`settled`/`failed`), or when the turn is cut short (`stopped`) — the
+ * point to end a span opened in `startChatTurn`. It runs even when `headers` is absent or
+ * malformed (dropped, the request goes out untraced), so the span never leaks.
+ */
+export type ChatTurnTrace = {
+    readonly headers?: TraceHeaders | undefined;
+    readonly settle?: ((end: ChatTurnEnd) => void) | undefined;
+};
+/**
+ * The event sink. It may carry one optional hook, `startChatTurn`, called when a new chat turn
+ * begins (not on a resume): open your span there and return its `traceparent` (and `tracestate`)
+ * and `aiSdkTransport` sends them with that turn's request to the chat endpoint — never anywhere
+ * else. A sink without the hook, or no sink, changes nothing on the wire. basalt has no OTel
+ * dependency; the hook is where the consumer's SDK does the work.
+ *
+ * @example
+ * export const telemetry: Telemetry = Object.assign(onEvent, {
+ *   startChatTurn({ threadId }) {
+ *     const span = tracer.startSpan('chat.turn', {
+ *       attributes: { 'basalt.chat.thread_id': threadId },
+ *     })
+ *     const carrier: Record<string, string> = {}
+ *     propagation.inject(trace.setSpan(context.active(), span), carrier)
+ *     return {
+ *       headers: { traceparent: carrier.traceparent ?? '', tracestate: carrier.tracestate },
+ *       settle(end) {
+ *         if (end === 'failed') span.setStatus({ code: SpanStatusCode.ERROR })
+ *         span.end()
+ *       },
+ *     }
+ *   },
+ * })
+ */
+export type Telemetry = ((event: BasaltEvent) => void) & {
+    readonly startChatTurn?: ((turn: ChatTurnInit) => ChatTurnTrace | undefined) | undefined;
+};
 export declare const now: () => number;
 /** `error.name`, `'Error'` for a non-`Error` throw. */
 export declare const errorName: (error: unknown) => string;
 /**
- * Wrap a sink so it is called synchronously and a throwing sink never breaks a render. No sink, no
- * events.
+ * The wrapped emitter over a sink read at call time (a ref), so a swapped sink is never stale. It is
+ * called synchronously and a throwing sink never breaks a render; no sink, no events. Its
+ * `startChatTurn` forwards the sink's hook; the hook's consumer validates the headers.
  */
-export declare function createEmitter(sink: Telemetry | undefined): Telemetry;
+export declare function createLiveEmitter(read: () => Telemetry | undefined): Telemetry;
 /**
  * The provider's wrapped emitter, for hooks that emit their own events (`useAgentThreadRuns`'
  * `chat.turn`). `undefined` outside a `BasaltProvider`, where such a hook emits nothing.

package/dist/telemetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAElD,+DAA+D;AAC/D,KAAK,EAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAC3B,qCAAqC;AACrC,KAAK,IAAI,GAAG,EAAE,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAA;AAErC,+DAA+D;AAC/D,KAAK,SAAS,GACV,OAAO,GACP,OAAO,GACP,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,oBAAoB,GACpB,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,SAAS,CAAA;AAEb,KAAK,OAAO,GAAG;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,SAAS,CAAA;CAAE,CAAA;AAC3E,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,IAAI,IAAI,GAAG;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,CAAC,CAAA;CAAE,CAAA;AAChE,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,CAAC,GAAG,OAAO,CAAA;CAAE,CAAA;AAE/E,KAAK,UAAU,GAAG;IAChB,iBAAiB,EAAE,MAAM,CAAA;IACzB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,KAAK,SAAS,GAAG;IACf,uBAAuB,EAAE,MAAM,CAAA;IAC/B,qBAAqB,EAAE,MAAM,CAAA;IAC7B,mBAAmB,EAAE,MAAM,CAAA;IAC3B,oBAAoB,EAAE,YAAY,CAAA;CACnC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GACnB,EAAE,CAAC,gBAAgB,EAAE,UAAU,CAAC,GAChC,GAAG,CAAC,aAAa,EAAE;IAAE,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC,GACjD,GAAG,CAAC,aAAa,EAAE;IAAE,mBAAmB,EAAE,MAAM,CAAC;IAAC,4BAA4B,EAAE,MAAM,CAAA;CAAE,CAAC,GACzF,GAAG,CAAC,gBAAgB,EAAE;IAAE,qBAAqB,EAAE,MAAM,CAAA;CAAE,CAAC,GACxD,GAAG,CAAC,cAAc,EAAE;IAAE,uBAAuB,EAAE,MAAM,CAAA;CAAE,CAAC,GACxD,GAAG,CAAC,cAAc,EAAE;IAAE,qBAAqB,EAAE,OAAO,GAAG,oBAAoB,CAAA;CAAE,CAAC,GAC9E,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC,GAC1B,GAAG,CAAC,WAAW,EAAE,SAAS,EAAE,IAAI,CAAC,CAAA;AAErC,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;AAEpD,eAAO,MAAM,GAAG,QAAO,MAAoD,CAAA;AAE3E,uDAAuD;AACvD,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MAAyD,CAAA;AAEpG;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CASpE;AAID;;;GAGG;AACH,eAAO,MAAM,gBAAgB,gDAAkD,CAAA;AAK/E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,IAAI,CAK/E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAEzD"}
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}

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.4.0
+# basalt-ui v2.6.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.4.0
+Version: 2.6.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "2.4.0",
+  "version": "2.6.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/DualPanel.tsx

@@ -16,7 +16,7 @@ import { VX, alpha } from '../tokens'
 import { resolveContainerClass } from '../tokens/size-classes'
 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'
@@ -269,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 {
@@ -290,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,
             }),
           },
         }

package/src/charts/MirroredBars.tsx

@@ -23,7 +23,7 @@ import { VX, alpha } from '../tokens'
 import { resolveContainerClass } from '../tokens/size-classes'
 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 },
             },

package/src/charts/compile.ts

@@ -23,6 +23,7 @@ import type {
   ResponsiveChartDefinition,
   StoredChartSpec,
 } from '@tanstack/charts/types/core'
+import { SHORT_CHART_HEIGHT } from './box'
 import { fmtCompact } from '../format/number'
 import { VX } from '../tokens'
 import type { ContainerClass } from '../tokens/size-classes'
@@ -97,6 +98,14 @@ const LADDER = {
 const INSIDE_LABEL_DX = 4
 const INSIDE_LABEL_DY = -6
 
+/**
+ * Y labels go inside the plot only for the compact class under `SHORT_CHART_HEIGHT` (the box's own
+ * short signal); otherwise they sit in a left gutter. `height` is the whole chart's, `0` before it
+ * is measured, which keeps the gutter rather than flipping a first paint inside.
+ */
+const labelsInside = (cls: ContainerClass, height: number): boolean =>
+  cls === 'compact' && height > 0 && height < SHORT_CHART_HEIGHT
+
 export function defaultNumberFormat(v: number): string {
   return fmtCompact(v, { digits: Math.abs(v) >= 1000 ? 1 : 2 })
 }
@@ -180,6 +189,22 @@ const REF_KEY_PREFIX = '__ref-'
 /** The legend key of a reference line that names itself (`RefLine.legend`). */
 const refLegendKey = (index: number): string => `${REF_KEY_PREFIX}${index}`
 
+/**
+ * A reference line is drawn translucent (`*-ref`, 20-30% alpha) so it recedes behind the data, but
+ * a 16x8 swatch at that alpha vanishes on the dark surface. The legend takes the status solid,
+ * which the color gate holds to 3:1 on the panel in both schemes, like a series swatch.
+ */
+const SWATCH_SOLID: ReadonlyMap<string, string> = new Map([
+  [VX.goodRef, VX.goodSolid],
+  [VX.badRef, VX.badSolid],
+  [VX.warnRef, VX.warnSolid],
+  // The tinted status fills are as translucent, and a consumer may pass either as a line color.
+  [VX.good, VX.goodSolid],
+  [VX.goodSoft, VX.goodSolid],
+  [VX.bad, VX.badSolid],
+  [VX.warn, VX.warnSolid],
+])
+
 /** Legend-only entries for the reference lines that name themselves, in line order. */
 export function refLegendSeries<T>(refLines: readonly RefLine[] | undefined): ChartSeries<T>[] {
   return (refLines ?? []).flatMap((r, i) =>
@@ -189,7 +214,7 @@ export function refLegendSeries<T>(refLines: readonly RefLine[] | undefined): Ch
           {
             key: refLegendKey(i),
             label: r.legend.label,
-            color: r.color,
+            color: SWATCH_SOLID.get(r.color) ?? r.color,
             role: 'reference' as const,
             tooltip: false,
             getValue: () => null,
@@ -218,8 +243,10 @@ export function yGuide<T>(opts: {
   cls: ContainerClass
   side: 'left' | 'right'
   grid: boolean
+  /** The whole chart's height: decides inside or gutter labels. */
+  height: number
 }): Omit<ChartPositionScaleOptions<number>, 'scale'> {
-  const { cfg, axis, cls, side, grid } = opts
+  const { cfg, axis, cls, side, grid, height } = opts
   const ladder = LADDER[cls]
   const ticks =
     typeof cfg?.ticks === 'object'
@@ -227,8 +254,8 @@ export function yGuide<T>(opts: {
       : { count: typeof cfg?.ticks === 'number' ? cfg.ticks : ladder.yTicks }
   const gridLine = grid ? { grid: GRID_LINE } : {}
   if (cls === 'micro') return { ...gridLine, axis: false }
-  // Compact: labels sit INSIDE the plot, above their grid line, so the plot keeps the full width.
-  const inside = cls === 'compact'
+  // Labels sit INSIDE the plot, above their grid line, so the plot keeps the full width.
+  const inside = labelsInside(cls, height)
   return {
     ...gridLine,
     ...(side === 'right' && { side: 'right' as const }),
@@ -276,9 +303,12 @@ export function xGuide<X extends ChartX>(opts: {
   xTicks: number | readonly X[] | undefined
   format: (v: ChartValue) => string
   cls: ContainerClass
+  /** The whole chart's height: decides whether the left margin is locked to zero. */
+  height: number
 }): Omit<ChartPositionScaleOptions<ChartValue>, 'scale'> {
-  const { model, xTicks, format, cls } = opts
+  const { model, xTicks, format, cls, height } = opts
   const ladder = LADDER[cls]
+  const inside = labelsInside(cls, height)
   const ticks = xTickPolicy(model, xTicks ?? ladder.xTicks)
   return {
     axis: {
@@ -288,8 +318,8 @@ export function xGuide<X extends ChartX>(opts: {
         fontSize: ladder.font,
         opacity: 1,
         thin: true,
-        // A locked-zero left margin (compact) must not clip the first label.
-        ...(cls === 'compact' && {
+        // A locked-zero left margin (inside labels) must not clip the first label.
+        ...(inside && {
           anchor: ({ index }: { index: number }) => (index === 0 ? ('start' as const) : undefined),
         }),
       },
@@ -634,18 +664,26 @@ function buildScales<T, X extends ChartX>(opts: {
   axes: Axes<T>
   formatX: (v: ChartValue) => string
   cls: ContainerClass
+  height: number
   zoneScale: boolean
 }): StoredChartSpec['scales'] {
-  const { input, model, axes, formatX, cls, zoneScale } = opts
+  const { input, model, axes, formatX, cls, height, zoneScale } = opts
   const { left, right } = axes
   return {
     x: {
       scale: model.scale,
-      ...xGuide({ model, xTicks: input.xTicks, format: formatX, cls }),
+      ...xGuide({ model, xTicks: input.xTicks, format: formatX, cls, height }),
     },
     y: {
       scale: yScaleFor(input.y, left.domain),
-      ...yGuide({ cfg: input.y, axis: left, cls, side: 'left', grid: input.y?.grid ?? true }),
+      ...yGuide({
+        cfg: input.y,
+        axis: left,
+        cls,
+        height,
+        side: 'left',
+        grid: input.y?.grid ?? true,
+      }),
     },
     ...(right && {
       y2: {
@@ -655,6 +693,7 @@ function buildScales<T, X extends ChartX>(opts: {
           cfg: input.y2,
           axis: right,
           cls,
+          height,
           side: 'right',
           grid: input.y2?.grid ?? false,
         }),
@@ -816,11 +855,19 @@ export function compileCartesian<T, X extends ChartX>(
       })
       return {
         marks: [...under, ...kindMarks, ...dots, ...over, crosshair({ x: CROSSHAIR, y: false })],
-        scales: buildScales({ input, model, axes, formatX, cls, zoneScale: under.length > 0 }),
+        scales: buildScales({
+          input,
+          model,
+          axes,
+          formatX,
+          cls,
+          height,
+          zoneScale: under.length > 0,
+        }),
         theme: CHART_THEME,
         ...(gradients.length > 0 && { gradients }),
         clip: true,
-        ...(cls === 'compact' && { margin: { left: 0, ...(axes.right && { right: 0 }) } }),
+        ...(labelsInside(cls, height) && { margin: { left: 0, ...(axes.right && { right: 0 }) } }),
       }
     },
     // Followers paint the crosshair only, unless the chart opts into following tooltips.