basalt-ui 2.3.0 → 2.5.0

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,6 +279,16 @@ type NumberHandleExtras<F> = F extends { kind: 'number' }
       readonly step?: undefined
     }
 
+/** A `createLocalStore` field: the shared handle plus `withFallback`. */
+export type LocalFieldHandle<F extends AnyField> = FieldHandle<F> & {
+  /**
+   * 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>
+}
+
 /**
  * The binding every basalt control takes instead of `value`/`onChange` (C2). One field, both lanes,
  * one resolution law. Handed out by `createSearchStore().field.<name>` /
@@ -771,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 = () => 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 }
@@ -798,7 +808,12 @@ export type StoreCore = {
   setLabels(map: Record<string, Record<string, string> | undefined>): void
   optionsFor(entry: StoreEntry): readonly FieldOption[]
   /** The resolution law, once: URL ⊳ localStorage ⊳ fallback. `search: null` skips the URL lane. */
-  resolve(entry: StoreEntry, search: StoreRecord | null, record: StoreRecord): unknown
+  resolve(
+    entry: StoreEntry,
+    search: StoreRecord | null,
+    record: StoreRecord,
+    fallback?: unknown,
+  ): unknown
   writeField(setRecord: (next: StoreRecord) => void, name: string, value: unknown): void
   /**
    * The IN-MEMORY lane's `use()` for one field — a field with neither the URL nor the mirror.
@@ -841,14 +856,19 @@ function assignDefined(into: StoreRecord, from: StoreRecord): void {
  * The resolution law, in one place: URL ⊳ localStorage ⊳ fallback (C4). `search: null` skips the
  * URL lane — what the local lane and `linkSearch` pass.
  */
-function resolveField(entry: StoreEntry, search: StoreRecord | null, record: StoreRecord): unknown {
+function resolveField(
+  entry: StoreEntry,
+  search: StoreRecord | null,
+  record: StoreRecord,
+  fallback?: unknown,
+): unknown {
   const fromUrl = search === null ? null : entry.codec.fromSearch(search)
   if (fromUrl !== null) return fromUrl
   if (entry.codec.lane.persist) {
     const stored = entry.codec.decode(record[entry.name])
     if (stored !== null) return stored
   }
-  return entry.codec.fallback
+  return fallback === undefined ? entry.codec.fallback : fallback
 }
 
 /**
@@ -865,7 +885,7 @@ function resolveField(entry: StoreEntry, search: StoreRecord | null, record: Sto
 function createMemoryLane(): {
   subscribe: (cb: () => void) => () => void
   getVersion: () => number
-  resolve: (entry: StoreEntry) => unknown
+  resolve: (entry: StoreEntry, fallback?: unknown) => unknown
   write: (name: string, value: unknown) => void
   remove: (name: string) => void
   clear: () => void
@@ -889,9 +909,10 @@ function createMemoryLane(): {
     getVersion: () => version,
     // `undefined` is the only "never written" marker the lane needs: no field kind has `undefined`
     // as a legal value, so it can never collide with a written one.
-    resolve: (entry) => {
+    resolve: (entry, fallback) => {
       const stored = values.get(entry.name)
-      return stored === undefined ? entry.codec.fallback : stored
+      if (stored !== undefined) return stored
+      return fallback === undefined ? entry.codec.fallback : fallback
     },
     write: (name, value) => {
       values.set(name, value)
@@ -1036,11 +1057,14 @@ export function createStoreCore(o: StoreCoreOptions): StoreCore {
     },
     readRecord,
     memoryUse(entry) {
-      return () => {
+      return (read) => {
         // Subscribing to the VERSION (never to the value) is what re-renders every other mount of
         // this field when one of them writes, with no snapshot-stability trap.
         useSyncExternalStore(memory.subscribe, memory.getVersion, memory.getVersion)
-        return [memory.resolve(entry), (next: unknown) => memory.write(entry.name, next)] as const
+        return [
+          memory.resolve(entry, read?.fallback),
+          (next: unknown) => memory.write(entry.name, next),
+        ] as const
       }
     },
     readMemoryValue: (entry) => memory.resolve(entry),
@@ -1074,7 +1098,7 @@ export function createStoreCore(o: StoreCoreOptions): StoreCore {
 
 /** `Pick<SearchStore<S>, 'field' | 'readStored' | 'labels'>` — the same handles, no router. */
 export type LocalStore<S extends Record<string, AnyField>> = {
-  readonly field: { [K in keyof S]: FieldHandle<S[K]> }
+  readonly field: { [K in keyof S]: LocalFieldHandle<S[K]> }
   readStored: () => Partial<StoredValues<S>>
   /**
    * Option labels for enum / multi / range fields — the same chainable contract
@@ -1116,22 +1140,56 @@ export function createLocalStore<const S extends Record<string, AnyField>>(o: {
 }): LocalStore<S> {
   const core = createStoreCore({ key: o.key, fields: o.fields, version: o.version })
 
-  const persistedUse = (entry: StoreEntry) => (): readonly [unknown, (next: unknown) => void] => {
-    const [record, setRecord] = core.usePersistedRecord()
-    return [
-      core.resolve(entry, null, record),
-      (next: unknown) => core.writeField(setRecord, entry.name, next),
-    ] as const
-  }
+  const persistedUse =
+    (entry: StoreEntry): FieldUse =>
+    (read) => {
+      const [record, setRecord] = core.usePersistedRecord()
+      return [
+        // The call-site fallback is applied here, in render, after the store read — never inside
+        // the snapshot — so React's out-of-render snapshot reads cannot disagree with it.
+        core.resolve(entry, null, record, read?.fallback),
+        (next: unknown) => core.writeField(setRecord, entry.name, next),
+      ] as const
+    }
 
-  const field = {} as { [K in keyof S]: FieldHandle<S[K]> }
+  const field = {} as { [K in keyof S]: LocalFieldHandle<S[K]> }
   for (const entry of core.entries) {
     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 FieldHandle<
-      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> = {

package/src/telemetry.ts

@@ -65,7 +65,61 @@ export type BasaltEvent =
   | 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 const now = (): number => performance.timeOrigin + performance.now()
 
@@ -73,18 +127,27 @@ export const now = (): number => performance.timeOrigin + performance.now()
 export const errorName = (error: unknown): string => (error instanceof Error ? error.name : 'Error')
 
 /**
- * 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 function createEmitter(sink: Telemetry | undefined): Telemetry {
-  if (sink === undefined) return noop
-  return (event) => {
+export function createLiveEmitter(read: () => Telemetry | undefined): Telemetry {
+  const emit = (event: BasaltEvent): void => {
     try {
-      sink(event)
+      read()?.(event)
     } catch {
       // a throwing sink must never break the app (§ 7 delivery rules)
     }
   }
+  return Object.assign(emit, {
+    startChatTurn(turn: ChatTurnInit): ChatTurnTrace | undefined {
+      try {
+        return read()?.startChatTurn?.(turn)
+      } catch {
+        return undefined
+      }
+    },
+  })
 }
 
 function noop(): void {}