basalt-ui 2.4.0 → 2.5.0

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.

package/src/charts/panel.tsx

@@ -83,12 +83,15 @@ export const paneY = (opts: {
   format: (v: number) => string
   ticks: number
   cls: ContainerClass
+  /** The whole chart's height ({@link chartHeightOf}). */
+  height: number
 }): StoredChartSpec['scales'][string] => ({
   scale: opts.scale,
   ...yGuide({
     cfg: { ticks: opts.ticks },
     axis: { domain: opts.domain, format: opts.format },
     cls: opts.cls,
+    height: opts.height,
     side: 'left',
     grid: true,
   }),
@@ -102,11 +105,23 @@ export const paneX = <X extends ChartX>(opts: {
   model: XScaleModel<X>
   format: (v: ChartValue) => string
   cls: ContainerClass
+  /** The whole chart's height ({@link chartHeightOf}). */
+  height: number
 }): StoredChartSpec['scales'][string] => ({
   scale: opts.scale,
-  ...xGuide({ model: opts.model, xTicks: undefined, format: opts.format, cls: opts.cls }),
+  ...xGuide({
+    model: opts.model,
+    xTicks: undefined,
+    format: opts.format,
+    cls: opts.cls,
+    height: opts.height,
+  }),
 })
 
+/** The whole chart's height from one pane's: a pane gets `share` of the height less the gap. */
+export const chartHeightOf = (paneHeight: number, share: number, gap: number): number =>
+  paneHeight > 0 && share > 0 ? paneHeight / share + gap : 0
+
 /** One row per datum for a series: a `null` or non-finite value is kept as a gap. */
 export function rowsOf<T, X extends ChartX>(
   data: readonly T[],

package/src/index.ts

@@ -12,7 +12,7 @@ export {
   type BasaltRouter,
   type BasaltRouterContext,
 } from './provider/create-router'
-export type { BasaltEvent } from './telemetry'
+export type { BasaltEvent, ChatTurnEnd, ChatTurnTrace, Telemetry, TraceHeaders } from './telemetry'
 export {
   defineNav,
   navGroup,

package/src/provider/index.tsx

@@ -36,7 +36,13 @@ import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
 import { PageTitle } from '../shell/page-title'
 import { SizeClassHintContext } from '../shell/use-size-class'
 import type { SizeClass } from '../shell/use-size-class'
-import { TelemetryContext, bindRouterTelemetry, createEmitter, errorName, now } from '../telemetry'
+import {
+  TelemetryContext,
+  bindRouterTelemetry,
+  createLiveEmitter,
+  errorName,
+  now,
+} from '../telemetry'
 import type { Telemetry } from '../telemetry'
 import type { BasaltDevDockTool } from '../dev-dock'
 import type { BasaltRouter, BasaltRouterContext } from './create-router'
@@ -426,7 +432,7 @@ export function BasaltProvider({
   useEffect(() => {
     sinkRef.current = telemetry
   })
-  const emit = useMemo(() => createEmitter((event) => sinkRef.current?.(event)), [])
+  const emit = useMemo(() => createLiveEmitter(() => sinkRef.current), [])
   useWindowErrors(emit)
   useRegistryHotkeys()
   // `overlays.confirm` is an imperative call; this tells it a `ModalsProvider` is live.

package/src/state/fields.ts

@@ -279,22 +279,14 @@ type NumberHandleExtras<F> = F extends { kind: 'number' }
       readonly step?: undefined
     }
 
-/**
- * `createLocalStore`'s `use()` read options. `fallback` is a CALL-SITE default for a value that
- * arrives as a prop (a leader, a latest date): it applies only while the field is unset (nothing
- * stored), is applied in render AFTER the store read, and is never persisted — `clear()` unsets
- * back to it. `handle.fallback` and `isDefault` still report the definition's.
- *
- * An object fallback (range, multi) must be memoised by the caller: the value returned while unset
- * IS that object, so a fresh literal per render changes identity every render.
- */
-export type FieldReadOptions<F extends AnyField> = { fallback?: FieldValue<F> }
-
-/** A `createLocalStore` field: the shared handle, plus `use({ fallback })`. */
+/** A `createLocalStore` field: the shared handle plus `withFallback`. */
 export type LocalFieldHandle<F extends AnyField> = FieldHandle<F> & {
-  use(
-    read?: FieldReadOptions<F>,
-  ): readonly [FieldValue<F>, (next: FieldValue<F>, opts?: FieldSetOptions) => void]
+  /**
+   * The same field with a call-site unset value (a prop-derived leader), for `use()` and any
+   * control as `field=`. Rule: `basalt-state`. Stable per fallback: a primitive is cached for the
+   * LAST value only, an object (range, multi) by identity — memoise objects at the caller.
+   */
+  withFallback(fallback: FieldValue<F>): FieldHandle<F>
 }
 
 /**
@@ -789,7 +781,7 @@ type StoreRecord = Record<string, unknown>
 export type FieldWrite = (next: unknown, opts?: FieldSetOptions) => void
 
 /** One field's `use()`, untyped. @internal — see `FieldCodec`. */
-export type FieldUse = (read?: FieldReadOptions<AnyField>) => readonly [unknown, FieldWrite]
+export type FieldUse = (read?: { fallback?: unknown }) => readonly [unknown, FieldWrite]
 
 /** One named field plus its codec, in declaration order. @internal — see `FieldCodec`. */
 export type StoreEntry = { readonly name: string; readonly codec: FieldCodec }
@@ -1165,9 +1157,39 @@ export function createLocalStore<const S extends Record<string, AnyField>>(o: {
     const persisted = entry.codec.lane.persist
     const use = persisted ? persistedUse(entry) : core.memoryUse(entry)
     const clear = persisted ? () => core.clearField(entry.name) : () => core.clearMemory(entry.name)
-    field[entry.name as keyof S] = core.handle(entry, use, clear) as unknown as LocalFieldHandle<
-      S[keyof S]
-    >
+    // Two handles over one field: the public one carries `withFallback`, a derived one is built
+    // on the bare one, so `derived.withFallback` is undefined at runtime as well as in the type.
+    const bare = core.handle(entry, use, clear)
+    // Object.create, never a spread: `options` and `fallback` are live getters, and a spread would
+    // freeze them at derivation. Only what the call-site fallback changes is shadowed.
+    const derive = (fallback: FieldValue<AnyField>): FieldHandle<AnyField> => {
+      const useDerived = () => use({ fallback })
+      return Object.create(bare, {
+        use: { value: useDerived, enumerable: true },
+        fallback: { get: () => fallback, enumerable: true },
+        isDefault: { value: (v: unknown) => entry.codec.equals(v, fallback), enumerable: true },
+      }) as FieldHandle<AnyField>
+    }
+    // Objects by identity (weak); a primitive only for the last value, so a high-cardinality
+    // fallback (a latest date, an id) cannot grow the cache. A function is never cached.
+    const byIdentity = new WeakMap<object, FieldHandle<AnyField>>()
+    let last: { value: FieldValue<AnyField>; handle: FieldHandle<AnyField> } | undefined
+    const withFallback = (fallback: FieldValue<AnyField>): FieldHandle<AnyField> => {
+      if (typeof fallback === 'function') return derive(fallback)
+      if (typeof fallback === 'object') {
+        const cached = byIdentity.get(fallback)
+        if (cached !== undefined) return cached
+        const handle = derive(fallback)
+        byIdentity.set(fallback, handle)
+        return handle
+      }
+      if (last !== undefined && Object.is(last.value, fallback)) return last.handle
+      last = { value: fallback, handle: derive(fallback) }
+      return last.handle
+    }
+    field[entry.name as keyof S] = Object.assign(core.handle(entry, use, clear), {
+      withFallback,
+    }) as unknown as LocalFieldHandle<S[keyof S]>
   }
 
   const store: LocalStore<S> = {