basalt-ui 1.10.0 → 1.11.0

package/src/agent-chat/thread-message.tsx

@@ -30,21 +30,27 @@ import {
   UnstyledButton,
 } from '@mantine/core'
 import { useDisclosure } from '@mantine/hooks'
+import { Fragment, memo, useMemo } from 'react'
 import type { JSX } from 'react'
 import type {
   AgentPart,
   AgentPartRenderers,
   ChatMessage,
   ErrorPart,
+  ForeignPart,
+  PartRenderer,
+  PartRenderers,
   ReasoningPart,
   SourcePart,
   StreamStatus,
   TextPart,
   ToolCallPart,
+  TranscriptPart,
 } from '../agent'
-import { PartList } from '../agent'
+import { coalesceParts, narrowAgentPart, PartList } from '../agent'
 import { Markdown } from '../content/markdown'
-import { alpha, VX } from '../tokens'
+import { VX } from '../tokens'
+import { ToolChip } from './tool-chip'
 
 /** The mono, uppercase, letter-spaced micro-label idiom (docs/DESIGN-SPEC.md §3) — shared by the
  * transcript's role labels and the reasoning/tool-call headers below. */
@@ -76,16 +82,6 @@ const RAIL_STYLE = {
   borderLeft: `2px solid ${VX.divider}`,
   paddingLeft: 'var(--vx-space-agent-rail-inset-x)',
 } as const
-const CODE_BLOCK_STYLE = {
-  margin: 0,
-  marginTop: 'var(--vx-space-agent-part-gap-top)',
-  fontFamily: 'var(--basalt-font-mono)',
-  backgroundColor: alpha(VX.ink, 0.06),
-  borderRadius: 'var(--vx-radius-card)',
-  padding: 'var(--vx-space-agent-code-inset)',
-  whiteSpace: 'pre-wrap',
-  overflowWrap: 'anywhere',
-} as const
 
 /** A dimmed, collapsed-by-default disclosure for reasoning/thinking fragments. */
 function ReasoningRenderer({ part }: { part: ReasoningPart; index: number }): JSX.Element {
@@ -106,22 +102,14 @@ function ReasoningRenderer({ part }: { part: ReasoningPart; index: number }): JS
   )
 }
 
-function ToolRenderer({ part }: { part: ToolCallPart; index: number }): JSX.Element {
-  return (
-    <Box style={RAIL_STYLE}>
-      <Stack gap={4}>
-        <Text style={MICRO_LABEL_STYLE}>{part.toolName}</Text>
-        <Text component="pre" size="xs" style={CODE_BLOCK_STYLE}>
-          {JSON.stringify(part.input, null, 2)}
-        </Text>
-        {part.output !== undefined && (
-          <Text component="pre" size="xs" style={CODE_BLOCK_STYLE}>
-            {JSON.stringify(part.output, null, 2)}
-          </Text>
-        )}
-      </Stack>
-    </Box>
-  )
+// Thin adapter: PartList's per-type renderer signature is `{ part, index }`, ToolChip's is a
+// richer `ToolChipProps` (defaultExpanded/onApprove/onDeny) that the built-in AgentPart union has
+// no slot for — a 'tool' part reaching this path is always basalt's own six-variant union, never a
+// consumer-registered one, so there is nowhere upstream to source approve/deny handlers from at
+// this call site. A consumer that needs approve/deny wiring renders `ToolChip` directly instead of
+// going through `PartList`/`threadPartRenderers`.
+function ToolChipRenderer({ part }: { part: ToolCallPart; index: number }): JSX.Element {
+  return <ToolChip part={part} />
 }
 
 function SourceRenderer({ part }: { part: SourcePart; index: number }): JSX.Element {
@@ -152,78 +140,246 @@ function ErrorRenderer({ part }: { part: ErrorPart; index: number }): JSX.Elemen
 export const threadPartRenderers: Partial<AgentPartRenderers> = {
   text: TextRenderer,
   reasoning: ReasoningRenderer,
-  tool: ToolRenderer,
+  tool: ToolChipRenderer,
   source: SourceRenderer,
   error: ErrorRenderer,
 }
 
-// ── ThreadTranscript ──────────────────────────────────────────────────────────
+// ── UnknownPartChip — the dev-visible default fallback ────────────────────────
+
+/** A visible marker for a part `ThreadTranscript` could not resolve — neither a registered
+ * consumer renderer nor a built-in `AgentPart` variant claimed it. Dev-only by default (see
+ * `DEFAULT_FALLBACK_RENDERER` below): a server emitting a new part type must not blank the
+ * transcript, but it also shouldn't silently vanish while the app is being built against it. */
+function UnknownPartChip({ part }: { part: ForeignPart }): JSX.Element {
+  return (
+    <Box style={RAIL_STYLE}>
+      <Text style={MICRO_LABEL_STYLE}>{`Unknown part: ${part.type}`}</Text>
+    </Box>
+  )
+}
+
+/** Consulted only when `ThreadTranscript` gets no `fallbackRenderer` prop. `process.env.NODE_ENV`
+ * (not `import.meta.env` — basalt-ui bans it) is read INSIDE the render so tests can flip it. */
+const DEFAULT_FALLBACK_RENDERER: PartRenderer<ForeignPart> = ({ part }) =>
+  process.env['NODE_ENV'] !== 'production' ? <UnknownPartChip part={part} /> : null
+
+// ── Part resolution — the three-step order that is the whole design ───────────
+//
+// 1. `renderers[part.type]` — a registered consumer renderer, if present. Consumer wins, always.
+// 2. `narrowAgentPart(part)` non-null — one of basalt's own six variants, routed to `PartList`'s
+//    UNCHANGED, closed-union, exhaustive switch (`part-list.tsx:291-293`).
+// 3. `fallbackRenderer` — anything left over. Never throws.
+//
+// `PartList` keeps its own `AgentPartRenderers` map and `assertNever` gate untouched — two
+// registries, two jobs: `PartList` renders what basalt knows, exhaustively; `ThreadTranscript`
+// renders what the app knows, openly. A `TPart` generic threaded through `AgentThread` →
+// `ThreadsStore` → `useAgentThreadRuns` → every component would be the alternative, and it's the
+// exact ripple `thread.ts:79-93` already cites as the reason `meta` stayed untyped.
+
+type ResolvedSegment =
+  | { readonly kind: 'agent'; readonly key: string; readonly parts: AgentPart[] }
+  | {
+      readonly kind: 'foreign'
+      readonly key: string
+      readonly part: ForeignPart
+      readonly render: PartRenderer<ForeignPart>
+    }
+
+/**
+ * Splits a message's parts into ordered, render-ready segments per the resolution order above.
+ * Consecutive built-in-resolved parts are batched into one 'agent' segment — coalesced, then
+ * handed to `PartList` as a unit — so the existing adjacent-merge behaviour (text+text, tool-by-id
+ * regardless of adjacency) survives a foreign part interleaving the stream. A foreign-resolved
+ * part always stands alone; there is nothing in the closed union for it to merge with.
+ */
+function resolveSegments(
+  parts: readonly TranscriptPart[],
+  renderers: PartRenderers,
+  fallbackRenderer: PartRenderer<ForeignPart>,
+): ResolvedSegment[] {
+  const segments: ResolvedSegment[] = []
+  let buffer: AgentPart[] = []
+
+  const flushBuffer = (): void => {
+    const first = buffer[0]
+    if (first === undefined) return
+    segments.push({ kind: 'agent', key: first.id, parts: coalesceParts(buffer) })
+    buffer = []
+  }
 
-// Streamed answers arrive as many small text parts; merge consecutive same-type text/reasoning
-// parts so a streaming reply renders as one flowing block instead of a stack of fragments.
-function coalesceParts(parts: AgentPart[]): AgentPart[] {
-  const out: AgentPart[] = []
   for (const part of parts) {
-    const last = out[out.length - 1]
-    if (part.type === 'text' && last?.type === 'text') {
-      out[out.length - 1] = { type: 'text', text: last.text + part.text }
-    } else if (part.type === 'reasoning' && last?.type === 'reasoning') {
-      out[out.length - 1] = { type: 'reasoning', text: last.text + part.text }
-    } else {
-      out.push(part)
+    // `PartRenderers` resolves to `Record<string, PartRenderer<ForeignPart>>` in basalt-ui's own
+    // (un-augmented) compilation — a plain runtime string-keyed lookup, `noUncheckedIndexedAccess`
+    // giving the `| undefined` this relies on.
+    const consumerRenderer = renderers[part.type]
+    if (consumerRenderer !== undefined) {
+      flushBuffer()
+      // Not narrowed to ForeignPart by the `renderers[part.type]` lookup above — asserted, not
+      // proven, by the registry contract (a registered key belongs to the consumer's foreign-part
+      // union).
+      segments.push({
+        kind: 'foreign',
+        key: part.id,
+        part: part as ForeignPart,
+        render: consumerRenderer,
+      })
+      continue
     }
+
+    const agentPart = narrowAgentPart(part)
+    if (agentPart !== null) {
+      buffer.push(agentPart)
+      continue
+    }
+
+    flushBuffer()
+    segments.push({
+      kind: 'foreign',
+      key: part.id,
+      part: part as ForeignPart,
+      render: fallbackRenderer,
+    })
   }
-  return out
+
+  flushBuffer()
+  return segments
 }
 
+// ── MessageBlock (memoized) ────────────────────────────────────────────────────
+
 const ROLE_LABEL: Record<ChatMessage['role'], string> = {
   user: 'You',
   assistant: 'Assistant',
 }
 
-function MessageBlock({
-  author,
-  parts,
+// Terminal-state indicator (docs/AGENT-CHAT-SPEC.md §10) — `message.finish` is optional (absent on
+// every user message and on pre-1.11 persisted assistant messages) and carries the distinction
+// `ThreadStatus` deliberately does not: a stopped turn's thread status is `'done'`, same as a
+// completed one. `'complete'` is the unremarkable case and has no entry here, so a lookup miss
+// renders nothing — no badge on every ordinary message. Only 'stopped'/'error' earn a mark, in the
+// same mono micro-label register as ROLE_LABEL, not a new decorative element.
+const FINISH_INDICATOR: Partial<
+  Record<
+    NonNullable<ChatMessage['finish']>,
+    { readonly label: string; readonly statusToken: string }
+  >
+> = {
+  stopped: { label: 'Stopped', statusToken: VX.status.warn },
+  error: { label: 'Error', statusToken: VX.status.bad },
+}
+
+type MessageBlockProps = {
+  readonly message: ChatMessage<TranscriptPart>
+  readonly streaming?: boolean
+  readonly renderers: PartRenderers
+  readonly fallbackRenderer: PartRenderer<ForeignPart>
+}
+
+/**
+ * Render-execution counter for `MessageBlockImpl` — increments only when React actually calls the
+ * function body (a `memo` bail-out never reaches it). NOT part of the public surface —
+ * `agent-chat/index.ts` does not re-export it. The memoization test imports this module directly
+ * (bypassing the barrel) to prove the memo boundary in a controlled render-count harness.
+ */
+export const messageBlockRenderCounter = { count: 0 }
+
+function MessageBlockImpl({
+  message,
   streaming = false,
-}: {
-  author: ChatMessage['role']
-  parts: AgentPart[]
-  streaming?: boolean
-}): JSX.Element {
+  renderers,
+  fallbackRenderer,
+}: MessageBlockProps): JSX.Element {
+  messageBlockRenderCounter.count += 1
+  const settled = !streaming
+  const segments = useMemo(
+    () => resolveSegments(message.parts, renderers, fallbackRenderer),
+    [message.parts, renderers, fallbackRenderer],
+  )
+  const finishIndicator =
+    message.finish === undefined ? undefined : FINISH_INDICATOR[message.finish]
+
   // Assistant/user surfaces are differentiated by subtle vs panel tokens, radius 7
   // (VX.radiusCard, docs/DESIGN-SPEC.md §5) — the user's own turn sits a shade quieter than the reply.
   return (
     <Box
       style={{
         padding: 'var(--vx-space-agent-message-inset-y) var(--vx-space-agent-message-inset-x)',
-        backgroundColor: author === 'user' ? VX.surface.subtle : VX.surface.panel,
+        backgroundColor: message.role === 'user' ? VX.surface.subtle : VX.surface.panel,
         borderRadius: VX.radiusCard,
         boxShadow: VX.shadowCard,
       }}
     >
       <Stack gap={6}>
         <Group gap={6} align="center">
-          <Text style={MICRO_LABEL_STYLE}>{ROLE_LABEL[author]}</Text>
+          <Text style={MICRO_LABEL_STYLE}>{ROLE_LABEL[message.role]}</Text>
           {streaming && <Loader size="xs" />}
+          {finishIndicator !== undefined && (
+            <Text style={{ ...MICRO_LABEL_STYLE, color: finishIndicator.statusToken }}>
+              {finishIndicator.label}
+            </Text>
+          )}
         </Group>
-        <PartList parts={coalesceParts(parts)} components={threadPartRenderers} />
+        {segments.map((segment) =>
+          segment.kind === 'agent' ? (
+            <PartList key={segment.key} parts={segment.parts} components={threadPartRenderers} />
+          ) : (
+            <Fragment key={segment.key}>
+              {segment.render({
+                part: segment.part,
+                messageId: message.id,
+                partId: segment.part.id,
+                settled,
+                role: message.role,
+              })}
+            </Fragment>
+          ),
+        )}
       </Stack>
     </Box>
   )
 }
 
-export type ThreadTranscriptProps = {
+/** Compares `message` BY REFERENCE plus the `streaming` flag — the props a per-token streaming
+ * re-render must not force through every settled message's `MessageBlock`. `renderers`/
+ * `fallbackRenderer` are included too: both are memoized once at the `ThreadTranscript` level (see
+ * below), so in practice they're stable across renders, but a genuine change to either (a consumer
+ * swapping its renderer map) must still invalidate the memo. */
+function areMessageBlockPropsEqual(prev: MessageBlockProps, next: MessageBlockProps): boolean {
+  return (
+    prev.message === next.message &&
+    prev.streaming === next.streaming &&
+    prev.renderers === next.renderers &&
+    prev.fallbackRenderer === next.fallbackRenderer
+  )
+}
+
+const MessageBlock = memo(MessageBlockImpl, areMessageBlockPropsEqual)
+
+// ── ThreadTranscript ──────────────────────────────────────────────────────────
+
+const EMPTY_RENDERERS: PartRenderers = {}
+
+type ThreadTranscriptBase = {
   /** Settled messages for the thread, oldest first. */
-  readonly messages: ChatMessage[]
+  readonly messages: readonly ChatMessage<TranscriptPart>[]
   /** The live (in-flight) assistant turn's parts, when a run is streaming for this thread. */
-  readonly liveParts?: AgentPart[]
+  readonly liveParts?: readonly TranscriptPart[]
   /** The live run's status — drives the in-progress indicator on the live block. */
   readonly liveStatus?: StreamStatus
+  /** Consumer renderers keyed by part.type. Consulted BEFORE the built-in union. */
+  readonly renderers?: PartRenderers
+  /** Called for a part whose type is neither an AgentPart variant nor a registered key. Defaults
+   * to a visible `UnknownPartChip` outside production, `null` in production — never throws. */
+  readonly fallbackRenderer?: PartRenderer<ForeignPart>
 }
 
+export type ThreadTranscriptProps = ThreadTranscriptBase
+
 /**
- * Renders a thread's settled messages, each role-labelled ("You" / "Assistant") and rendered via
- * `PartList` + `threadPartRenderers`. When `liveParts` is non-empty, an extra in-progress
+ * Renders a thread's settled messages, each role-labelled ("You" / "Assistant"). Each part
+ * resolves in order: a registered `renderers[part.type]` first, then basalt's own `PartList` for
+ * the built-in six, then `fallbackRenderer`. When `liveParts` is non-empty, an extra in-progress
  * assistant block is appended at the tail.
  *
  * @example
@@ -234,18 +390,35 @@ export function ThreadTranscript({
   messages,
   liveParts,
   liveStatus,
+  renderers: renderersProp,
+  fallbackRenderer = DEFAULT_FALLBACK_RENDERER,
 }: ThreadTranscriptProps): JSX.Element {
+  // Mirrors PartList's own `useMemo` (part-list.tsx:237-240) — avoids rebuilding the renderer
+  // lookup on every streaming re-render.
+  const renderers = useMemo(() => renderersProp ?? EMPTY_RENDERERS, [renderersProp])
+
+  const liveMessage = useMemo<ChatMessage<TranscriptPart> | null>(() => {
+    if (liveParts === undefined || liveParts.length === 0) return null
+    return { id: '__live__', role: 'assistant', parts: liveParts as TranscriptPart[], createdAt: 0 }
+  }, [liveParts])
+
   return (
     <Stack gap="sm">
       {messages.map((message) => (
-        <MessageBlock key={message.id} author={message.role} parts={message.parts} />
+        <MessageBlock
+          key={message.id}
+          message={message}
+          renderers={renderers}
+          fallbackRenderer={fallbackRenderer}
+        />
       ))}
-      {liveParts !== undefined && liveParts.length > 0 && (
+      {liveMessage !== null && (
         <div aria-live="polite" aria-atomic="false" aria-relevant="additions">
           <MessageBlock
-            author="assistant"
-            parts={liveParts}
+            message={liveMessage}
             streaming={liveStatus === 'streaming'}
+            renderers={renderers}
+            fallbackRenderer={fallbackRenderer}
           />
         </div>
       )}

package/src/agent-chat/tool-chip.test.tsx

@@ -0,0 +1,139 @@
+/**
+ * ToolChip — one test per wire state proving it renders without throwing, plus the
+ * approve/deny-visibility contract: rendered ONLY in 'approval-requested', and only for whichever
+ * of onApprove/onDeny is actually supplied.
+ */
+import { MantineProvider } from '@mantine/core'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, test } from 'bun:test'
+import { ToolChip } from './tool-chip'
+import type { ToolCallPart } from '../agent'
+
+afterEach(cleanup)
+
+function renderChip(part: ToolCallPart, extra: Partial<Parameters<typeof ToolChip>[0]> = {}) {
+  return render(
+    <MantineProvider>
+      <ToolChip part={part} defaultExpanded {...extra} />
+    </MantineProvider>,
+  )
+}
+
+const BASE = { id: 'p1', type: 'tool' as const, toolCallId: 'c1', toolName: 'search' }
+
+describe('every wire state renders without throwing', () => {
+  const CASES: { name: string; part: ToolCallPart }[] = [
+    { name: 'input-streaming', part: { ...BASE, state: 'input-streaming' } },
+    { name: 'input-available', part: { ...BASE, state: 'input-available', input: { q: 'x' } } },
+    {
+      name: 'approval-requested',
+      part: { ...BASE, state: 'approval-requested', input: { q: 'x' }, approval: { id: 'a1' } },
+    },
+    {
+      name: 'approval-responded (approved)',
+      part: {
+        ...BASE,
+        state: 'approval-responded',
+        input: { q: 'x' },
+        approval: { id: 'a1', approved: true },
+      },
+    },
+    {
+      name: 'approval-responded (declined)',
+      part: {
+        ...BASE,
+        state: 'approval-responded',
+        input: { q: 'x' },
+        approval: { id: 'a1', approved: false },
+      },
+    },
+    {
+      name: 'output-available',
+      part: { ...BASE, state: 'output-available', input: { q: 'x' }, output: { hits: 3 } },
+    },
+    {
+      name: 'output-available (preliminary)',
+      part: {
+        ...BASE,
+        state: 'output-available',
+        input: { q: 'x' },
+        output: { hits: 1 },
+        preliminary: true,
+      },
+    },
+    {
+      name: 'output-error (with rawInput)',
+      part: { ...BASE, state: 'output-error', errorText: 'boom', rawInput: { q: 'x' } },
+    },
+    {
+      name: 'output-denied (with reason)',
+      part: {
+        ...BASE,
+        state: 'output-denied',
+        input: { q: 'x' },
+        approval: { id: 'a1', approved: false, reason: 'not now' },
+      },
+    },
+  ]
+
+  for (const { name, part } of CASES) {
+    test(name, () => {
+      expect(() => renderChip(part)).not.toThrow()
+    })
+  }
+})
+
+describe('approve/deny affordances', () => {
+  const REQUESTED: ToolCallPart = {
+    ...BASE,
+    state: 'approval-requested',
+    input: { q: 'x' },
+    approval: { id: 'a1' },
+  }
+
+  test('read-only when both handlers are omitted', () => {
+    renderChip(REQUESTED)
+    expect(screen.queryByText('Approve')).toBeNull()
+    expect(screen.queryByText('Deny')).toBeNull()
+  })
+
+  test('renders only the supplied handler', () => {
+    renderChip(REQUESTED, { onApprove: () => {} })
+    expect(screen.queryByText('Approve')).not.toBeNull()
+    expect(screen.queryByText('Deny')).toBeNull()
+  })
+
+  test('calls onApprove with the approval id', () => {
+    let approvedId: string | undefined
+    renderChip(REQUESTED, { onApprove: (id) => (approvedId = id) })
+    fireEvent.click(screen.getByText('Approve'))
+    expect(approvedId).toBe('a1')
+  })
+
+  test('never renders for a non-approval-requested state even with both handlers supplied', () => {
+    renderChip(
+      { ...BASE, state: 'output-available', input: { q: 'x' }, output: {} },
+      { onApprove: () => {}, onDeny: () => {} },
+    )
+    expect(screen.queryByText('Approve')).toBeNull()
+    expect(screen.queryByText('Deny')).toBeNull()
+  })
+})
+
+// F3: a runtime value the type system believes is exhaustively handled — but isn't, once
+// persisted (localStorage, zero shape validation) or wire (edenTransport, zero validation) data
+// is involved — must render an inert 'unknown' chip, never throw via assertNever and blank the
+// transcript.
+describe('a malformed/unrecognized state never throws (F3)', () => {
+  test('state undefined (the pre-1.11.0 flat persisted shape) renders "unknown" instead of throwing', () => {
+    const malformed = { ...BASE, output: { hits: 1 } } as unknown as ToolCallPart
+    expect(() => renderChip(malformed)).not.toThrow()
+    expect(screen.getByText('unknown')).not.toBeNull()
+  })
+
+  test('an unrecognized state string renders "unknown" instead of throwing', () => {
+    const malformed = { ...BASE, state: 'bogus-future-state' } as unknown as ToolCallPart
+    expect(() => renderChip(malformed)).not.toThrow()
+    expect(screen.getByText('unknown')).not.toBeNull()
+  })
+})