basalt-ui 1.11.0 → 1.12.0

package/src/agent/id.test.ts

@@ -4,6 +4,7 @@
  */
 import { describe, expect, test } from 'bun:test'
 import { withPartIds } from './id'
+import type { AgentPartDraft } from './parts'
 
 async function* gen<T>(values: T[]): AsyncGenerator<T> {
   for (const value of values) yield value
@@ -17,7 +18,10 @@ async function collect<T>(source: AsyncGenerator<T>): Promise<T[]> {
 
 describe('withPartIds', () => {
   test('stamps a sequential id on every draft missing one', async () => {
-    const drafts = [
+    // Annotated: all three literals uniformly omit `id`, so without this TS infers an `id`-less
+    // element type that has no properties in common with withPartIds' `{ id?: string }`
+    // constraint — a weak-type check failure, not a real shape mismatch.
+    const drafts: AgentPartDraft[] = [
       { type: 'text', text: 'a' },
       { type: 'text', text: 'b' },
       { type: 'text', text: 'c' },
@@ -37,7 +41,7 @@ describe('withPartIds', () => {
   })
 
   test('is idempotent: re-running withPartIds over already-identified parts changes nothing', async () => {
-    const drafts = [{ type: 'text', text: 'a' }]
+    const drafts: AgentPartDraft[] = [{ type: 'text', text: 'a' }]
     const once = await collect(withPartIds('run-1', gen(drafts)))
     const twice = await collect(withPartIds('run-1', gen(once)))
     expect(twice).toEqual(once)

package/src/agent/id.ts

@@ -1,3 +1,51 @@
+/**
+ * Id-minting helpers shared by the thread stores: `mintThreadId` (a client-side thread id, used by
+ * both `./thread`'s `createThreadsStore` and `./adapter`'s `createAdapterThreadsStore`) and
+ * `withPartIds` (stamps sequence ids onto streamed parts). Related in theme — both mint an id a
+ * store needs — unrelated in mechanism; grouped here because they're the two id-minting leaves the
+ * two thread stores both sit above.
+ */
+
+/**
+ * Mints a client-side thread id. `crypto.randomUUID()` exists only in SECURE CONTEXTS (HTTPS or
+ * localhost) — a consumer served over plain HTTP on a LAN hostname (a homelab dashboard on a bare
+ * IP, a staging box) would otherwise have `create()`, about the most basic user action a thread
+ * store has, throw a plain TypeError. A store used from a browser must not throw on a user gesture
+ * — the same principle already applied twice this release (`spliceText` clamps rather than throws,
+ * `coalesceParts` degrades rather than throws).
+ *
+ * Fallback chain, each rung reached only when the one above it is unavailable:
+ *   1. `crypto.randomUUID()` — cryptographically random, RFC 4122 UUID. The normal path.
+ *   2. `crypto.getRandomValues()` — still cryptographically random; hand-assembled into a UUIDv4
+ *      (the version/variant bits are set per RFC 4122, since this rung hands back raw bytes, not a
+ *      formatted UUID).
+ *   3. No usable `crypto` at all (missing entirely, or missing both methods above — an old WebView,
+ *      an SSR shim). NOT cryptographically random and NOT collision-resistant in general. This rung
+ *      exists solely so `create()` never throws on such a host. It is acceptable ONLY because this
+ *      id is minted a handful of times per client session and is not the idempotency key any write
+ *      here depends on — `ThreadsStoreAdapter.appendMessage`'s idempotency key is the MESSAGE id,
+ *      not this thread id, so a collision on this rung costs a locally merged/duplicated thread, not
+ *      silent data loss on the append path. Do not reuse this rung for anything with a higher
+ *      collision cost than that.
+ */
+export function mintThreadId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID()
+  }
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    const bytes = crypto.getRandomValues(new Uint8Array(16))
+    const hex = Array.from({ length: 16 }, (_, i) => {
+      const raw = bytes.at(i) ?? 0
+      // Version 4 (bits 12-15 of time_hi_and_version) and variant 10 (bits 6-7 of
+      // clock_seq_hi_and_reserved) — the only structure a UUIDv4 promises over raw random bytes.
+      const byte = i === 6 ? (raw & 0x0f) | 0x40 : i === 8 ? (raw & 0x3f) | 0x80 : raw
+      return byte.toString(16).padStart(2, '0')
+    }).join('')
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+  }
+  return `id-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
+}
+
 /**
  * withPartIds — stamps a stable id onto every draft part arriving without one.
  *

package/src/agent/index.ts

@@ -113,3 +113,11 @@ export type { AgentThread, ThreadStatus, ThreadsStore, ThreadsStoreOptions } fro
 // ── AgentOutcome + heuristicOutcome ────────────────────────────────────────────
 export { heuristicOutcome } from './outcome'
 export type { AgentOutcome, OutcomeResolver } from './outcome'
+
+// ── createAdapterThreadsStore + threadsStoreAdapterContract ──────────────────
+export { createAdapterThreadsStore, threadsStoreAdapterContract } from './adapter'
+export type {
+  AdapterThreadsStoreOptions,
+  ThreadsStoreAdapter,
+  ThreadsStoreAdapterContractCase,
+} from './adapter'

package/src/agent/merge.test.ts

@@ -57,6 +57,93 @@ describe('mergePart', () => {
     expect(replayed).toEqual(firstPassResult.map((p) => ({ ...p, offset: 0 })))
   })
 
+  // ── out-of-range offsets ───────────────────────────────────────────────────
+  // spliceText supports exactly two shapes (append at the end, in-range replace). Everything else
+  // is CLAMPED into [0, existing.text.length] with a dev warning — never thrown on, because a
+  // throw on the render path turns a transient wire anomaly into a permanently dead transcript.
+
+  test('an offset past the end of the existing text clamps to the tail (appends, leaves no hole)', () => {
+    const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hi' }]
+    const [merged] = mergePart(parts, { id: 'p1', type: 'text', text: '!', offset: 10 })
+    expect(merged?.text).toBe('Hi!')
+  })
+
+  test('a negative offset clamps to 0 rather than slicing from the end', () => {
+    const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hello world' }]
+    const [merged] = mergePart(parts, { id: 'p1', type: 'text', text: 'Hey', offset: -3 })
+    expect(merged?.text).toBe('Heylo world')
+  })
+
+  test('an out-of-order (already-covered) offset replaces in place — it never re-appends', () => {
+    // 'Hello world' is fully accumulated; a straggler delta for offset 6 arrives after the tail
+    // has moved past it. In-range, so it is honoured as a replace, not clamped.
+    const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hello world' }]
+    const [merged] = mergePart(parts, { id: 'p1', type: 'text', text: 'WORLD', offset: 6 })
+    expect(merged?.text).toBe('Hello WORLD')
+  })
+
+  test('a non-finite offset clamps to the tail rather than blanking the part', () => {
+    const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hi' }]
+    const [merged] = mergePart(parts, { id: 'p1', type: 'text', text: '!', offset: Number.NaN })
+    expect(merged?.text).toBe('Hi!')
+  })
+
+  test('a FIRST insertion with a nonzero offset clamps and warns like any other out-of-range one', () => {
+    // A first insertion splices against an EMPTY existing text, so the offset is out of range
+    // [0, 0]: mergePart never invents the 2 missing characters, it stores what arrived — but the
+    // anomaly is announced, exactly as it is for an existing part. One contract, one code path.
+    const warnings: string[] = []
+    const original = console.warn
+    console.warn = (...args: unknown[]) => void warnings.push(String(args[0]))
+    let first: TextPart[]
+    try {
+      first = mergePart<TextPart>([], { id: 'p1', type: 'text', text: 'llo', offset: 2 })
+    } finally {
+      console.warn = original
+    }
+    expect(warnings).toHaveLength(1)
+    expect(warnings[0]).toContain('out of range [0, 0]')
+    expect(first).toEqual([{ id: 'p1', type: 'text', text: 'llo', offset: 2 }])
+
+    // The offset rides along inert; the next delta for this id splices relative to the STORED text.
+    const [merged] = mergePart(first, { id: 'p1', type: 'text', text: ' there' })
+    expect(merged?.text).toBe('llo there')
+  })
+
+  test('a FIRST insertion with an in-range (0 or undefined) offset stays silent and stores the text as-is', () => {
+    const warnings: string[] = []
+    const original = console.warn
+    console.warn = (...args: unknown[]) => void warnings.push(String(args[0]))
+    try {
+      expect(mergePart<TextPart>([], { id: 'p1', type: 'text', text: 'Hello', offset: 0 })).toEqual(
+        [{ id: 'p1', type: 'text', text: 'Hello', offset: 0 }],
+      )
+      expect(mergePart<TextPart>([], { id: 'p2', type: 'text', text: 'Hello' })).toEqual([
+        { id: 'p2', type: 'text', text: 'Hello' },
+      ])
+    } finally {
+      console.warn = original
+    }
+    expect(warnings).toHaveLength(0)
+  })
+
+  test('warns in dev on an out-of-range offset, and stays silent on an in-range one', () => {
+    const warnings: string[] = []
+    const original = console.warn
+    console.warn = (...args: unknown[]) => void warnings.push(String(args[0]))
+    try {
+      const parts: TextPart[] = [{ id: 'p1', type: 'text', text: 'Hi' }]
+      mergePart(parts, { id: 'p1', type: 'text', text: '!', offset: 1 })
+      expect(warnings).toHaveLength(0)
+
+      mergePart(parts, { id: 'p1', type: 'text', text: '!', offset: 10 })
+      expect(warnings).toHaveLength(1)
+      expect(warnings[0]).toContain('out of range')
+    } finally {
+      console.warn = original
+    }
+  })
+
   test('non-text/reasoning variants replace wholesale rather than merging fields', () => {
     const parts: ToolCallPart[] = [
       {

package/src/agent/merge.ts

@@ -4,8 +4,11 @@
  * Appending a part whose `id` is already present in `parts` REWRITES that entry in place rather
  * than pushing a duplicate — ordering stays stable (a rewritten part keeps its original position).
  * `text`/`reasoning` splice the incoming delta into the existing text at `next.offset` (an
- * undefined offset means "append at the tail"); every other variant — including any `ForeignPart`,
- * which is never text-like — replaces wholesale.
+ * undefined offset means "append at the tail", and an out-of-range one is clamped rather than
+ * honoured — see `spliceText` for the exact supported shapes); every other variant — including any
+ * `ForeignPart`, which is never text-like — replaces wholesale. A FIRST insertion of a text-like
+ * part goes through the same splice against an empty text, so an offset that claims a prefix this
+ * accumulator never saw is clamped and warned about there too — never honoured, never padded.
  *
  * The invariant this holds, and the reason `offset` exists at all: replaying a whole run from
  * character 0 rebuilds the identical parts array it produced the first time — it cannot double
@@ -41,26 +44,70 @@ function isTextLikeType(type: string): type is TextLike['type'] {
   return type === 'text' || type === 'reasoning'
 }
 
-/** Splices `next`'s text into `existing`'s text at `next.offset` (tail-append when undefined). */
-function spliceText(existing: TextLike, next: TextLike): string {
-  const offset = next.offset ?? existing.text.length
-  return existing.text.slice(0, offset) + next.text + existing.text.slice(offset + next.text.length)
+/**
+ * Splices `next`'s text into `existingText` at `next.offset`. Exactly two shapes are supported,
+ * and they are the only two any basalt transport emits (`diffPart` always sets
+ * `offset = prevText.length`; `diffChunkStream` restarts its accumulator per call):
+ *
+ * 1. **append at the end** — `offset` undefined, or equal to `existingText.length`;
+ * 2. **in-range replace** — `0 <= offset <= existingText.length`, overwriting the span the
+ *    incoming text covers (this is what makes an offset-0 full replay converge instead of double).
+ *
+ * An offset outside that range — negative, past the current length, or non-finite — is **clamped**
+ * into `[0, existingText.length]`, not honoured and not thrown on. A throw here would turn a
+ * transient wire anomaly into a permanently dead transcript; this is stream-reduction code on the
+ * render path. Each clamp is announced in dev.
+ *
+ * A FIRST insertion (no entry with this id yet) runs through here too, against an empty
+ * `existingText`: the stored text is the incoming text either way, but a nonzero offset — the wire
+ * claiming text this accumulator never saw — is clamped to 0 and announced like any other
+ * out-of-range value rather than passing silently. `mergePart` never invents the missing prefix.
+ *
+ * Note what is NOT special-cased: an out-of-order delta whose offset is still in range is an
+ * ordinary in-range replace, so it overwrites whatever already occupies that span. `mergePart`
+ * has no way to tell a stale delta from a deliberate rewrite, and inventing one would break the
+ * offset-0 replay convergence this whole mechanism exists for.
+ */
+function spliceText(existingText: string, next: TextLike): string {
+  const offset = clampOffset(next.offset ?? existingText.length, existingText.length)
+  return existingText.slice(0, offset) + next.text + existingText.slice(offset + next.text.length)
+}
+
+/** Clamps a wire offset into `[0, length]`, warning in dev when the raw value was out of range. */
+function clampOffset(offset: number, length: number): number {
+  // A non-finite offset would make every slice() return '' and blank the part outright — it is
+  // out of range like any other, and appending is the safe reading of "position unknown".
+  const clamped = Number.isFinite(offset) ? Math.min(Math.max(offset, 0), length) : length
+  if (clamped !== offset && process.env['NODE_ENV'] !== 'production') {
+    console.warn(
+      `[basalt] mergePart: text offset ${offset} out of range [0, ${length}] — clamped to ${clamped}`,
+    )
+  }
+  return clamped
 }
 
 export function mergePart<TPart extends PartLike>(parts: readonly TPart[], next: TPart): TPart[] {
   const index = parts.findIndex((part) => part.id === next.id)
-  if (index === -1) return [...parts, next]
+  const existing = index === -1 ? undefined : (parts[index] as TPart)
 
-  const existing = parts[index] as TPart
-  const spliceable = existing.type === next.type && isTextLikeType(next.type)
+  // A first insertion of a text-like part is spliced too — against an empty existing text — so the
+  // offset contract is one path with one set of rules: same clamp, same dev warning, and the same
+  // stored result (`'' + next.text`) an unconditional append would have produced.
+  const spliceable =
+    isTextLikeType(next.type) && (existing === undefined || existing.type === next.type)
 
   const merged: TPart = spliceable
     ? ({
         ...next,
-        text: spliceText(existing as unknown as TextLike, next as unknown as TextLike),
+        text: spliceText(
+          existing === undefined ? '' : (existing as unknown as TextLike).text,
+          next as unknown as TextLike,
+        ),
       } as TPart)
     : next
 
+  if (existing === undefined) return [...parts, merged]
+
   const out = parts.slice()
   out[index] = merged
   return out

package/src/agent/part-list.test.tsx

@@ -5,11 +5,14 @@
  * `output` field, so the old `part.state === 'output-available'`-only body left a failed call
  * rendering as name+input and nothing else — the failure was silently invisible. Same gap for
  * `output-denied`, indistinguishable from a still-pending call.
+ *
+ * Plus the `settled` flag's forwarding contract — the field that lets a text renderer drop out of
+ * streaming mode once the message it belongs to has finished.
  */
 import { cleanup, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, test } from 'bun:test'
 import { PartList } from './part-list'
-import type { ToolCallPart } from './parts'
+import type { AgentPart, ToolCallPart } from './parts'
 
 afterEach(cleanup)
 
@@ -80,3 +83,30 @@ describe('DefaultToolCall — terminal states stay visible', () => {
     expect(screen.queryByText(/Denied/)).toBeNull()
   })
 })
+
+describe('settled — forwarded to every renderer', () => {
+  const TEXT: AgentPart = { id: 't1', type: 'text', text: 'hello' }
+
+  function settledProbe() {
+    const seen: boolean[] = []
+    const components = {
+      text: ({ settled }: { settled: boolean }) => {
+        seen.push(settled)
+        return <div data-testid="probe">{String(settled)}</div>
+      },
+    }
+    return { seen, components }
+  }
+
+  test('defaults to true — a caller that knows nothing about a run renders a finished list', () => {
+    const { seen, components } = settledProbe()
+    render(<PartList parts={[TEXT]} components={components} />)
+    expect(seen).toEqual([true])
+  })
+
+  test('an explicit settled={false} reaches the renderer', () => {
+    const { seen, components } = settledProbe()
+    render(<PartList parts={[TEXT]} components={components} settled={false} />)
+    expect(seen).toEqual([false])
+  })
+})

package/src/agent/part-list.tsx

@@ -19,7 +19,9 @@
  * <PartList
  *   parts={parts}
  *   components={{
- *     text: ({ part }) => <Markdown streaming density="chat">{part.text}</Markdown>,
+ *     text: ({ part, settled }) => (
+ *       <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown>
+ *     ),
  *   }}
  * />
  */
@@ -38,37 +40,48 @@ import type {
 
 // ── Per-type renderer signatures ──────────────────────────────────────────────
 
-export type TextPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-  part: Extract<TPart, { type: 'text' }>
+/**
+ * The per-renderer argument. `settled` is `false` only while the message these parts belong to is
+ * still streaming — it converges this map toward the `PartRenderContext` a foreign renderer
+ * already receives (`./foreign`), rather than adding a third shape. Additive and
+ * source-compatible: an existing `({ part }) => …` renderer simply ignores it.
+ *
+ * Settlement is MONOTONE — a message that has settled never un-settles.
+ */
+type PartRenderArgs<TPart> = {
+  part: TPart
   index: number
-}) => JSX.Element | null
+  settled: boolean
+}
 
-export type ReasoningPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-  part: Extract<TPart, { type: 'reasoning' }>
-  index: number
-}) => JSX.Element | null
+export type TextPartRenderer<TPart extends AgentPart = AgentPart> = (
+  props: PartRenderArgs<Extract<TPart, { type: 'text' }>>,
+) => JSX.Element | null
 
-export type ToolCallPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-  part: Extract<TPart, { type: 'tool' }>
-  index: number
-}) => JSX.Element | null
+export type ReasoningPartRenderer<TPart extends AgentPart = AgentPart> = (
+  props: PartRenderArgs<Extract<TPart, { type: 'reasoning' }>>,
+) => JSX.Element | null
 
-export type SourcePartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-  part: Extract<TPart, { type: 'source' }>
-  index: number
-}) => JSX.Element | null
+export type ToolCallPartRenderer<TPart extends AgentPart = AgentPart> = (
+  props: PartRenderArgs<Extract<TPart, { type: 'tool' }>>,
+) => JSX.Element | null
 
-export type ErrorPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-  part: Extract<TPart, { type: 'error' }>
-  index: number
-}) => JSX.Element | null
+export type SourcePartRenderer<TPart extends AgentPart = AgentPart> = (
+  props: PartRenderArgs<Extract<TPart, { type: 'source' }>>,
+) => JSX.Element | null
+
+export type ErrorPartRenderer<TPart extends AgentPart = AgentPart> = (
+  props: PartRenderArgs<Extract<TPart, { type: 'error' }>>,
+) => JSX.Element | null
 
 /**
  * Partial map of per-type renderers. Any omitted key falls back to the headless default.
  *
  * @example
  * const renderers: Partial<AgentPartRenderers> = {
- *   text: ({ part }) => <Markdown streaming density="chat">{part.text}</Markdown>,
+ *   text: ({ part, settled }) => (
+ *     <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown>
+ *   ),
  * }
  */
 export type AgentPartRenderers<TPart extends AgentPart = AgentPart> = {
@@ -231,10 +244,17 @@ export type PartListProps<TPart extends AgentPart = AgentPart> = {
   readonly parts: TPart[]
   /**
    * Override individual part renderers. Omitted keys fall back to the headless defaults.
-   * Pass `{ text: ({ part }) => <Markdown streaming density="chat">{part.text}</Markdown> }` to
-   * enable rich markdown rendering.
+   * Pass `{ text: ({ part, settled }) => <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown> }`
+   * to enable rich markdown rendering.
    */
   readonly components?: Partial<AgentPartRenderers<TPart>>
+  /**
+   * `false` while the message these parts belong to is still streaming — forwarded to every
+   * renderer so a text renderer can drop out of streaming mode (and a fenced mermaid/diagram can
+   * upgrade) once the turn finishes. Defaults to `true`: a caller that knows nothing about a run
+   * is rendering a finished list, and un-settled must be opted into by the thing that does know.
+   */
+  readonly settled?: boolean
 }
 
 /**
@@ -251,11 +271,19 @@ export type PartListProps<TPart extends AgentPart = AgentPart> = {
  * // With basalt's own Markdown for the text renderer:
  * import { PartList } from 'basalt-ui/agent'
  * import { Markdown } from 'basalt-ui/content'
- * <PartList parts={parts} components={{ text: ({ part }) => <Markdown streaming density="chat">{part.text}</Markdown> }} />
+ * <PartList
+ *   parts={parts}
+ *   components={{
+ *     text: ({ part, settled }) => (
+ *       <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown>
+ *     ),
+ *   }}
+ * />
  */
 export function PartList<TPart extends AgentPart = AgentPart>({
   parts,
   components,
+  settled = true,
 }: PartListProps<TPart>): JSX.Element {
   // Memoised to avoid rebuilding the renderer map on every streaming re-render (hot path).
   // Cast required because DEFAULT_RENDERERS is typed for the base AgentPart, not the generic TPart.
@@ -277,7 +305,11 @@ export function PartList<TPart extends AgentPart = AgentPart>({
             const Render = renderers.text
             return (
               <Fragment key={part.id}>
-                <Render part={part as Extract<TPart, { type: 'text' }>} index={index} />
+                <Render
+                  part={part as Extract<TPart, { type: 'text' }>}
+                  index={index}
+                  settled={settled}
+                />
               </Fragment>
             )
           }
@@ -285,7 +317,11 @@ export function PartList<TPart extends AgentPart = AgentPart>({
             const Render = renderers.reasoning
             return (
               <Fragment key={part.id}>
-                <Render part={part as Extract<TPart, { type: 'reasoning' }>} index={index} />
+                <Render
+                  part={part as Extract<TPart, { type: 'reasoning' }>}
+                  index={index}
+                  settled={settled}
+                />
               </Fragment>
             )
           }
@@ -293,7 +329,11 @@ export function PartList<TPart extends AgentPart = AgentPart>({
             const Render = renderers.tool
             return (
               <Fragment key={part.id}>
-                <Render part={part as Extract<TPart, { type: 'tool' }>} index={index} />
+                <Render
+                  part={part as Extract<TPart, { type: 'tool' }>}
+                  index={index}
+                  settled={settled}
+                />
               </Fragment>
             )
           }
@@ -301,7 +341,11 @@ export function PartList<TPart extends AgentPart = AgentPart>({
             const Render = renderers.source
             return (
               <Fragment key={part.id}>
-                <Render part={part as Extract<TPart, { type: 'source' }>} index={index} />
+                <Render
+                  part={part as Extract<TPart, { type: 'source' }>}
+                  index={index}
+                  settled={settled}
+                />
               </Fragment>
             )
           }
@@ -309,7 +353,11 @@ export function PartList<TPart extends AgentPart = AgentPart>({
             const Render = renderers.error
             return (
               <Fragment key={part.id}>
-                <Render part={part as Extract<TPart, { type: 'error' }>} index={index} />
+                <Render
+                  part={part as Extract<TPart, { type: 'error' }>}
+                  index={index}
+                  settled={settled}
+                />
               </Fragment>
             )
           }