@kitn.ai/ui 0.20.1 → 0.22.0

package/src/state/stream.ts

@@ -1,73 +1,72 @@
 // src/state/stream.ts
-import type { ChatMessage } from '../elements/chat-types';
+import type { ChatMessage, MessagePart, Source } from '../elements/chat-types';
 import type { ToolPart } from '../components/tool-types';
+import type { CardEnvelope } from '../primitives/card-contract';
+import type { AttachmentData } from '../components/attachment-types';
+import { appendReasoningPart, appendTextPart, upsertCardPart, upsertToolPart, type ReasoningOpts } from './parts';
 
 /** The one universal contract: a functional-updater setter (React setState shape). */
 export type SetMessages = (updater: (prev: ChatMessage[]) => ChatMessage[]) => void;
 
+function newId(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID();
+  return 'kai-' + Math.random().toString(36).slice(2);
+}
+
 /** A fluent builder for one in-flight assistant message. Owns no state. */
 export interface AssistantStream {
   readonly id: string;
   appendText(delta: string): AssistantStream;
-  setText(content: string): AssistantStream;
-  appendReasoning(delta: string, label?: string): AssistantStream;
-  setReasoning(text: string, label?: string): AssistantStream;
-  upsertTool(tool: ToolPart): AssistantStream;
-  updateTool(toolCallId: string, patch: Partial<ToolPart>): AssistantStream;
-  patch(patch: Partial<ChatMessage>): AssistantStream;
-  done(final?: Partial<ChatMessage>): void;
+  appendReasoning(delta: string, opts?: ReasoningOpts): AssistantStream;
+  upsertTool(toolCallId: string, patch: Partial<ToolPart>): AssistantStream;
+  /** Adds a card, or REPLACES the existing one with the same `envelope.id`. A
+   *  model that revises a card mid-turn re-sends the whole envelope, so a second
+   *  call with a known id revises that card in place rather than rendering a
+   *  second copy of it. See `upsertCardPart`. */
+  addCard(envelope: CardEnvelope): AssistantStream;
+  addSource(source: Source): AssistantStream;
+  addFile(attachment: AttachmentData): AssistantStream;
+  done(): void;
   abort(reason?: string): void;
 }
 
-function newId(): string {
-  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') return crypto.randomUUID();
-  return 'kai-' + Math.random().toString(36).slice(2);
-}
-
 /** Start an assistant message and drive it through `set`. New refs on every mutation. */
-export function createAssistantStream(set: SetMessages, init: Partial<ChatMessage> = {}): AssistantStream {
+export function createAssistantStream(
+  set: SetMessages,
+  init: Partial<ChatMessage> = {},
+): AssistantStream {
   const id = init.id ?? newId();
-  const seed: ChatMessage = { id, role: 'assistant', content: '', ...init };
-  set((prev) => [...prev, seed]);
+  let settled = false;
+
+  set((prev) => [...prev, { id, role: 'assistant', parts: [], ...init }]);
 
-  const mutate = (fn: (m: ChatMessage) => ChatMessage) =>
-    set((prev) => prev.map((m) => (m.id === id ? fn(m) : m)));
+  const mutate = (fn: (parts: MessagePart[]) => MessagePart[]) => {
+    if (settled) return;
+    set((prev) => {
+      const i = prev.findIndex((m) => m.id === id);
+      if (i < 0) return prev;
+      const next = fn(prev[i].parts);
+      if (next === prev[i].parts) return prev;
+      return [...prev.slice(0, i), { ...prev[i], parts: next }, ...prev.slice(i + 1)];
+    });
+  };
 
   const stream: AssistantStream = {
     id,
-    appendText(delta) { mutate((m) => ({ ...m, content: m.content + delta })); return stream; },
-    setText(content) { mutate((m) => ({ ...m, content })); return stream; },
-    appendReasoning(delta, label) {
-      mutate((m) => ({ ...m, reasoning: { text: (m.reasoning?.text ?? '') + delta, label: label ?? m.reasoning?.label } }));
-      return stream;
-    },
-    setReasoning(text, label) {
-      mutate((m) => ({ ...m, reasoning: { text, label: label ?? m.reasoning?.label } }));
-      return stream;
-    },
-    upsertTool(tool) {
-      mutate((m) => {
-        const tools = m.tools ? m.tools.slice() : [];
-        const i = tool.toolCallId != null
-          ? tools.findIndex((t) => t.toolCallId === tool.toolCallId)
-          : tools.findIndex((t) => t.type === tool.type);
-        if (i === -1) tools.push(tool); else tools[i] = tool;
-        return { ...m, tools };
-      });
-      return stream;
-    },
-    updateTool(toolCallId, patch) {
-      mutate((m) => ({ ...m, tools: (m.tools ?? []).map((t) => (t.toolCallId === toolCallId ? { ...t, ...patch } : t)) }));
-      return stream;
-    },
-    patch(patch) { mutate((m) => ({ ...m, ...patch })); return stream; },
-    done(final) { if (final) mutate((m) => ({ ...m, ...final })); },
+    appendText(delta) { mutate((p) => appendTextPart(p, delta)); return stream; },
+    appendReasoning(delta, opts) { mutate((p) => appendReasoningPart(p, delta, opts)); return stream; },
+    upsertTool(toolCallId, patch) { mutate((p) => upsertToolPart(p, toolCallId, patch)); return stream; },
+    // Upsert, not append: keyed on envelope.id so a revised card replaces itself.
+    addCard(envelope) { mutate((p) => upsertCardPart(p, envelope)); return stream; },
+    addSource(source) { mutate((p) => [...p, { type: 'source', source }]); return stream; },
+    addFile(attachment) { mutate((p) => [...p, { type: 'file', attachment }]); return stream; },
+    done() { settled = true; },
     abort(reason) {
-      if (reason) {
-        mutate((m) => ({ ...m, tools: (m.tools ?? []).map((t) => ({ ...t, state: 'output-error' as const, errorText: reason })) }));
-      } else {
-        set((prev) => prev.filter((m) => m.id !== id));
-      }
+      mutate((p) => p.map((part) =>
+        part.type === 'tool' && part.tool.state !== 'output-available'
+          ? { ...part, tool: { ...part.tool, state: 'output-error' as const, errorText: reason } }
+          : part));
+      settled = true;
     },
   };
   return stream;
@@ -78,14 +77,13 @@ export function createAssistantStream(set: SetMessages, init: Partial<ChatMessag
 export function onStreamSettled(inner: AssistantStream, onSettle: () => void): AssistantStream {
   const wrapper: AssistantStream = {
     id: inner.id,
-    appendText(d) { inner.appendText(d); return wrapper; },
-    setText(c) { inner.setText(c); return wrapper; },
-    appendReasoning(d, l) { inner.appendReasoning(d, l); return wrapper; },
-    setReasoning(t, l) { inner.setReasoning(t, l); return wrapper; },
-    upsertTool(t) { inner.upsertTool(t); return wrapper; },
-    updateTool(tcId, p) { inner.updateTool(tcId, p); return wrapper; },
-    patch(p) { inner.patch(p); return wrapper; },
-    done(final) { inner.done(final); onSettle(); },
+    appendText(delta) { inner.appendText(delta); return wrapper; },
+    appendReasoning(delta, opts) { inner.appendReasoning(delta, opts); return wrapper; },
+    upsertTool(toolCallId, patch) { inner.upsertTool(toolCallId, patch); return wrapper; },
+    addCard(envelope) { inner.addCard(envelope); return wrapper; },
+    addSource(source) { inner.addSource(source); return wrapper; },
+    addFile(attachment) { inner.addFile(attachment); return wrapper; },
+    done() { inner.done(); onSettle(); },
     abort(reason) { inner.abort(reason); onSettle(); },
   };
   return wrapper;

package/src/ui/collapsible.tsx

@@ -39,7 +39,7 @@ const useCollapsible = () => {
  *  (no `open` prop); in controlled mode the parent already owns the state. */
 export interface CollapsibleController { open: Accessor<boolean>; setOpen: (v: boolean) => void; }
 
-export function Collapsible(props: {
+export interface CollapsibleProps {
   open?: boolean;
   defaultOpen?: boolean;
   onOpenChange?: (open: boolean) => void;
@@ -51,7 +51,9 @@ export function Collapsible(props: {
   controllerRef?: (api: CollapsibleController) => void;
   children: JSX.Element;
   class?: string;
-}) {
+}
+
+export function Collapsible(props: CollapsibleProps) {
   const [local, rest] = splitProps(props, ['open', 'defaultOpen', 'onOpenChange', 'disabled', 'controllerRef', 'children', 'class']);
   const [uncontrolled, setUncontrolled] = createSignal(local.defaultOpen ?? false);
   const isControlled = () => local.open !== undefined;
@@ -88,13 +90,16 @@ export function Collapsible(props: {
   );
 }
 
-export function CollapsibleTrigger(props: {
+export interface CollapsibleTriggerProps {
   children?: JSX.Element;
   class?: string;
   as?: (props: Record<string, any>) => JSX.Element;
   onClick?: JSX.EventHandlerUnion<HTMLButtonElement, MouseEvent>;
+  /** Remaining attributes are spread onto the rendered trigger. */
   [k: string]: any;
-}) {
+}
+
+export function CollapsibleTrigger(props: CollapsibleTriggerProps) {
   const ctx = useCollapsible();
   const [local, rest] = splitProps(props, ['children', 'class', 'as', 'onClick']);
 
@@ -130,7 +135,14 @@ export function CollapsibleTrigger(props: {
   );
 }
 
-export function CollapsibleContent(props: { children?: JSX.Element; class?: string; [k: string]: any }) {
+export interface CollapsibleContentProps {
+  children?: JSX.Element;
+  class?: string;
+  /** Remaining attributes are spread onto the rendered panel. */
+  [k: string]: any;
+}
+
+export function CollapsibleContent(props: CollapsibleContentProps) {
   const ctx = useCollapsible();
   const [local, rest] = splitProps(props, ['children', 'class']);
   return (

package/src/ui/dropdown.tsx

@@ -41,7 +41,7 @@ const ITEM_SELECTOR = '[role="menuitem"]:not([aria-disabled="true"]), [role="men
  *  `controllerRef` so it can drive/observe the Dropdown's open state. */
 export interface DropdownController { open: Accessor<boolean>; setOpen: (v: boolean) => void; }
 
-export function Dropdown(props: {
+export interface DropdownProps {
   children: JSX.Element;
   /** Initial open state (uncontrolled seed). */
   defaultOpen?: boolean;
@@ -49,7 +49,41 @@ export function Dropdown(props: {
   disabled?: boolean;
   /** Receive the open controller (open accessor + setOpen) once mounted. */
   controllerRef?: (api: DropdownController) => void;
-}) {
+}
+
+export interface DropdownTriggerProps {
+  /** Render as a different tag/component; defaults to a button. */
+  as?: AsTag;
+  children?: JSX.Element;
+  class?: string;
+  /** Remaining attributes are spread onto the rendered trigger. */
+  [k: string]: unknown;
+}
+
+export interface DropdownContentProps { children: JSX.Element; class?: string }
+
+export interface DropdownItemProps {
+  children: JSX.Element;
+  class?: string;
+  onSelect?: () => void;
+  disabled?: boolean;
+}
+
+export interface DropdownSeparatorProps { class?: string }
+
+export interface DropdownLabelProps { children: JSX.Element; class?: string }
+
+export interface DropdownCheckboxItemProps extends DropdownItemProps { checked?: boolean }
+
+export interface DropdownRadioItemProps extends DropdownItemProps { checked?: boolean }
+
+export interface DropdownSubProps { children: JSX.Element }
+
+export interface DropdownSubTriggerProps { children: JSX.Element; class?: string }
+
+export interface DropdownSubContentProps { children: JSX.Element; class?: string }
+
+export function Dropdown(props: DropdownProps) {
   const [open, setOpenSig] = createSignal(props.defaultOpen ?? false);
   const [viaKb, setViaKb] = createSignal(false);
   const [trigger, setTrigger] = createSignal<HTMLElement>();
@@ -95,7 +129,7 @@ export function Dropdown(props: {
   );
 }
 
-export function DropdownTrigger(props: { as?: AsTag; children?: JSX.Element; class?: string; [k: string]: any }) {
+export function DropdownTrigger(props: DropdownTriggerProps) {
   const ctx = useDropdown();
   // Forward extra attributes (e.g. aria-label for an icon-only trigger). The
   // controlled wiring below (id/aria-*/onClick/onKeyDown/class/type) is applied
@@ -126,7 +160,7 @@ export function DropdownTrigger(props: { as?: AsTag; children?: JSX.Element; cla
   );
 }
 
-export function DropdownContent(props: { children: JSX.Element; class?: string }) {
+export function DropdownContent(props: DropdownContentProps) {
   const ctx = useDropdown();
   const config = useChatConfig();
   const presence = createPresence(ctx.open);
@@ -221,7 +255,7 @@ export function DropdownContent(props: { children: JSX.Element; class?: string }
   );
 }
 
-export function DropdownItem(props: { children: JSX.Element; class?: string; onSelect?: () => void; disabled?: boolean }) {
+export function DropdownItem(props: DropdownItemProps) {
   const ctx = useDropdown();
   const activate = () => {
     if (props.disabled) return;
@@ -253,7 +287,7 @@ export function DropdownItem(props: { children: JSX.Element; class?: string; onS
  * a11y: `role="separator"` — exposed to AT as a group boundary; not in the
  * roving-focus tab order (the `[role="menuitem"]` query skips it).
  */
-export function DropdownSeparator(props: { class?: string }) {
+export function DropdownSeparator(props: DropdownSeparatorProps) {
   return <div role="separator" class={cn('-mx-1 my-1 h-px bg-border', props.class)} />;
 }
 
@@ -262,7 +296,7 @@ export function DropdownSeparator(props: { class?: string }) {
  * a11y: a plain muted label — NOT a menuitem and NOT focusable, so roving focus
  * skips it; it labels the items that follow visually only (`select-none`).
  */
-export function DropdownLabel(props: { children: JSX.Element; class?: string }) {
+export function DropdownLabel(props: DropdownLabelProps) {
   return (
     <div class={cn('select-none px-2 py-1.5 text-xs font-medium text-muted-foreground', props.class)}>
       {props.children}
@@ -278,7 +312,7 @@ export function DropdownLabel(props: { children: JSX.Element; class?: string })
  * present — aligns with the plain items above it instead of being pushed in by a
  * reserved leading check column.
  */
-export function DropdownCheckboxItem(props: { children: JSX.Element; class?: string; checked?: boolean; onSelect?: () => void; disabled?: boolean }) {
+export function DropdownCheckboxItem(props: DropdownCheckboxItemProps) {
   const activate = () => {
     if (props.disabled) return;
     props.onSelect?.(); /* stay open — consumer owns `checked` */
@@ -315,7 +349,7 @@ export function DropdownCheckboxItem(props: { children: JSX.Element; class?: str
  * content aligns with plain items. Group membership is the consumer's concern;
  * this primitive just renders the selected state and reports the click.
  */
-export function DropdownRadioItem(props: { children: JSX.Element; class?: string; checked?: boolean; onSelect?: () => void; disabled?: boolean }) {
+export function DropdownRadioItem(props: DropdownRadioItemProps) {
   const activate = () => {
     if (props.disabled) return;
     props.onSelect?.(); /* stay open — consumer owns the group selection */
@@ -377,7 +411,7 @@ const useDropdownSub = () => {
  * (Escape/outside-click/select), `useDismiss` on the parent unmounts the whole
  * content tree, which tears this provider down and drops the sub with it.
  */
-export function DropdownSub(props: { children: JSX.Element }) {
+export function DropdownSub(props: DropdownSubProps) {
   const [open, setOpenSig] = createSignal(false);
   const [viaKb, setViaKb] = createSignal(false);
   const [trigger, setTrigger] = createSignal<HTMLElement>();
@@ -422,7 +456,7 @@ export function DropdownSub(props: { children: JSX.Element }) {
  * keyboard-open also moves focus into the sub's first item. ArrowRight/Enter are
  * swallowed so the parent menu doesn't also act on them.
  */
-export function DropdownSubTrigger(props: { children: JSX.Element; class?: string }) {
+export function DropdownSubTrigger(props: DropdownSubTriggerProps) {
   const sub = useDropdownSub();
   const onKeyDown = (e: KeyboardEvent) => {
     if (e.key === 'ArrowRight' || e.key === 'Enter' || e.key === ' ') {
@@ -465,7 +499,7 @@ export function DropdownSubTrigger(props: { children: JSX.Element; class?: strin
  * ArrowUp/Down/Home/End rove within; typeahead included (matches DropdownContent).
  * Keyboard-open focuses the first item.
  */
-export function DropdownSubContent(props: { children: JSX.Element; class?: string }) {
+export function DropdownSubContent(props: DropdownSubContentProps) {
   const sub = useDropdownSub();
   const parent = useDropdown();
   const config = useChatConfig();

package/src/ui/overlay.tsx

@@ -261,11 +261,17 @@ export function useDismiss(opts: UseDismissOptions) {
       const inside = opts.refs().some((el) => el && el.contains(target));
       if (!inside) opts.onDismiss('outside');
     };
-    document.addEventListener('keydown', onKey);
-    document.addEventListener('pointerdown', onPointer, true);
+    // Captured at SETUP and closed over, never re-resolved as a global inside
+    // `onCleanup`: cleanup can run after the host removed the DOM globals (a
+    // `kai-*` release is deferred one microtask past detachment, so an
+    // environment teardown gets in between), and a bare `document` there throws.
+    // See tests/components/teardown-without-dom-globals.test.tsx.
+    const doc = document;
+    doc.addEventListener('keydown', onKey);
+    doc.addEventListener('pointerdown', onPointer, true);
     onCleanup(() => {
-      document.removeEventListener('keydown', onKey);
-      document.removeEventListener('pointerdown', onPointer, true);
+      doc.removeEventListener('keydown', onKey);
+      doc.removeEventListener('pointerdown', onPointer, true);
     });
   });
 }

package/src/wire/chunk.ts

@@ -0,0 +1,201 @@
+// The provider-neutral chunk surface. Everything the adapter needs out of one
+// streaming chunk, and nothing else. A WireFormat maps a decoded provider frame
+// onto these; nothing below this line knows a provider exists.
+import type { RawOrigin, ToolPart } from '../components/tool-types';
+import type { MessagePart, MessageSource } from '../elements/chat-types';
+import type { ReasoningOpts } from '../state/parts';
+
+/** One fragment of a tool call. */
+export interface ModelToolCallDelta {
+  /**
+   * The ONLY thing correlating fragments, and its NAMESPACE IS FORMAT-DEFINED.
+   * `openaiChatFormat` uses the position in `delta.tool_calls`;
+   * `anthropicMessagesFormat` uses the content-block index. Both are correct and
+   * both are stable within one stream, but they are not the same number, so a
+   * third-party format must pick one and stay consistent with itself.
+   */
+  index: number;
+  id?: string;
+  /** Usually whole on the first fragment; a few providers split it. */
+  name?: string;
+  /** A FRAGMENT of the JSON arguments string, not valid JSON on its own. */
+  arguments?: string;
+  /** A result the PROVIDER executed (Anthropic web_search_tool_result, an OpenAI
+   *  built-in). Completes the panel with no host work. */
+  output?: Record<string, unknown>;
+  /** A provider-executed tool that failed. */
+  outputError?: string;
+}
+
+/** Field names are deliberately provider-neutral. OpenAI says prompt/completion,
+ *  Anthropic says input/output; input/output is the one that reads correctly for
+ *  both. */
+export interface ModelUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  /** Non-zero proves the model reasoned even when no reasoning text streamed. */
+  reasoningTokens?: number;
+  cachedInputTokens?: number;
+  costUsd?: number;
+}
+
+export interface ModelStreamChunk {
+  text?: string;
+  /**
+   * Reasoning delta. `''` is MEANINGFUL, not a no-op: a redacted block has no
+   * readable text but still carries a payload that must round-trip, and a format
+   * uses an empty delta to OPEN a reasoning part at the right position in the
+   * stream so block order survives into `parts`.
+   */
+  reasoning?: string;
+  /** The provider's BLOCK index. Keeps parallel reasoning blocks distinct.
+   *  Omitted means block 0, the single-block case every provider degrades to. */
+  reasoningIndex?: number;
+  /**
+   * The UNTRANSLATED provider payload for this reasoning block. Valid on a chunk
+   * with NO reasoning text at all, which is the whole point: Anthropic returns
+   * 400 if a `thinking` block is modified, reordered or RECONSTRUCTED, so an
+   * encoder has to echo the original block rather than rebuild one from `text`
+   * plus `signature`.
+   */
+  reasoningRaw?: RawOrigin;
+  /** Informational. `reasoningRaw` is the round-trip channel, not this. */
+  reasoningSignature?: string;
+  toolCalls?: ModelToolCallDelta[];
+  /** Citations the model produced. A run of consecutive `source` parts renders
+   *  as one citation row (`part="citations"`), outside the message bubble. */
+  sources?: MessageSource[];
+  /** Provider VERBATIM: 'stop' | 'tool_calls' | 'end_turn' | 'max_tokens' | ...
+   *  Normalizing in place would destroy information consumers branch on. */
+  finishReason?: string | null;
+  usage?: ModelUsage;
+  /** An in-band provider error (the HTTP response was already 200). */
+  error?: { code?: string | number; message: string };
+}
+
+/** One vocabulary across formats, for code that has to BRANCH. `finishReason`
+ *  stays beside it, verbatim, for code that has to REPORT. */
+export type StopReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'other';
+
+const STOP_REASONS: Record<string, StopReason> = {
+  // OpenAI chat completions
+  stop: 'stop',
+  length: 'length',
+  tool_calls: 'tool-calls',
+  function_call: 'tool-calls',
+  content_filter: 'content-filter',
+  error: 'error',
+  // Anthropic Messages
+  end_turn: 'stop',
+  stop_sequence: 'stop',
+  max_tokens: 'length',
+  tool_use: 'tool-calls',
+  refusal: 'content-filter',
+  pause_turn: 'other',
+};
+
+/** Unknown reasons degrade to 'other' rather than throwing: providers add stop
+ *  reasons without warning and a new one must not take a turn down. */
+export function normalizeStopReason(
+  finishReason: string | null | undefined,
+): StopReason | undefined {
+  if (!finishReason) return undefined;
+  return STOP_REASONS[finishReason] ?? 'other';
+}
+
+/**
+ * The subset of the kit's `AssistantStream` the adapter drives. Declared
+ * STRUCTURALLY so the adapter has no runtime dependency on a stream
+ * implementation and can be tested against a recorder. The kit's real
+ * `AssistantStream` satisfies it as-is: same method names, same arities, and its
+ * `AssistantStream` returns are assignable to `unknown`.
+ *
+ * `addSource` is optional so a hand-rolled three-method sink still compiles.
+ */
+export interface AssistantStreamSink {
+  appendText(delta: string): unknown;
+  appendReasoning(delta: string, opts?: ReasoningOpts): unknown;
+  /** Create-or-merge. There is no separate "announce" call: handing a patch for
+   *  an unknown `toolCallId` creates the ToolPart, and every later patch merges. */
+  upsertTool(toolCallId: string, patch: Partial<ToolPart>): unknown;
+  addSource?(source: MessageSource): unknown;
+}
+
+/** One tool call reassembled out of the stream's fragments. */
+export interface ModelToolCall {
+  /** The delta index that correlated this call's fragments. */
+  index: number;
+  /** Provider call id (synthesised as `call_<index>` if the provider omits it). */
+  id: string;
+  name: string;
+  /** The RAW accumulated argument fragments. Echo THIS back on the next turn,
+   *  not a re-stringified parse. */
+  argumentsText: string;
+  /** Parsed arguments: present only when `argumentsText` was a valid JSON object. */
+  input?: Record<string, unknown>;
+  /** Present only for a call the PROVIDER executed. */
+  output?: Record<string, unknown>;
+  /** True when the provider ran the tool and returned its result in-stream. The
+   *  host must NOT execute these. */
+  providerExecuted?: boolean;
+  /** Why this call is unusable (malformed or truncated args, missing name). */
+  error?: string;
+}
+
+/** Everything one assistant turn produced. */
+export interface ModelTurn {
+  /** The turn as ORDERED MESSAGE PARTS, built with the kit's own part builders,
+   *  so it is exactly what the sink was driven with. Covers this turn only. */
+  parts: MessagePart[];
+  /** Flat concatenation of the text deltas. The provider wire format is a flat
+   *  string, so this is kept for encoders. Not the content model. */
+  text: string;
+  /** Flat concatenation of the reasoning deltas, for the same reason. */
+  reasoning: string;
+  toolCalls: ModelToolCall[];
+  sources: MessageSource[];
+  /** The provider's own word for why it stopped. Never normalized. */
+  finishReason: string | null;
+  /** The same fact in one vocabulary. Branch on this. */
+  stopReason?: StopReason;
+  error?: { code?: string | number; message: string };
+  usage?: ModelUsage;
+  /** How many chunks carried a NON-EMPTY reasoning delta. Zero with a non-zero
+   *  `usage.reasoningTokens` means the provider hid the thinking text. */
+  reasoningChunks: number;
+  chunks: number;
+}
+
+export interface ConsumeOptions {
+  /** Label for the reasoning disclosure. Defaults to 'Thinking'. */
+  reasoningLabel?: string;
+  /** Fires once per tool call the moment its arguments parse cleanly. This is
+   *  the hook a host's tool loop waits on. There is deliberately no
+   *  per-fragment callback: `ToolPart.rawInput` is written on every fragment,
+   *  so the streaming text is already on the part. */
+  onToolCallReady?: (call: ModelToolCall) => void;
+}
+
+/** Per-stream state for one format. */
+export interface WireFormatReader {
+  /**
+   * Map one decoded frame onto zero or more neutral chunks. Returns an ARRAY
+   * because the mapping is not one-to-one: an Anthropic `message_start` yields
+   * usage, a `content_block_start` for `tool_use` yields an id-plus-name delta,
+   * a `ping` yields nothing.
+   *
+   * MUST NOT throw on an unrecognized frame. Return `[]` instead: providers add
+   * event types without warning.
+   */
+  push(frame: unknown): ModelStreamChunk[];
+}
+
+/** A pluggable wire format. Values, not a flag, so a third party can add one
+ *  without a PR to this repo. */
+export interface WireFormat {
+  readonly id: string;
+  /** Called once per stream so a format can hold per-stream state. Two calls
+   *  must share NOTHING. */
+  open(): WireFormatReader;
+}