learning_ai_common_plat/packages/ai-ui/README.md

@bytelyst/ai-ui

AI-native UI primitives for ByteLyst products. The flagship deliverable of Wave 2 in learning_ai_uxui_web/docs/ROADMAP_2026.md.

Status: 0.1.0 MVP — 3 components + 1 hook + 1 utility. Subsequent 0.x bumps add <ToolCallCard>, <CitationChip>, <AgentTimeline>, <ModelPicker>, <ToolPalette>, and the useToolCalls / usePromptHistory / useTokenCount hooks.

Quick start

import { ChatStream } from '@bytelyst/ai-ui';

export function ChatPage() {
  return (
    <div style={{ height: '70vh' }}>
      <ChatStream
        endpoint="/api/chat"
        placeholder="Ask anything…"
        emptyState={<EmptyHint />}
      />
    </div>
  );
}

Architectural decisions

Per learning_ai_common_plat/docs/ROADMAP_2026_DECISIONS.md:

• §10 hook shape — useChat() returns the same shape as Vercel AI SDK's useChat. Drop-in compatible for any engineer who has already written a chat UI with the AI SDK.
• Transport is pluggable — products inject endpoint, streamProtocol, fetcher, or headers. We are not locked to Vercel's SSE wire format.

Components

<ChatStream>

Opinionated composition of useChat + <MessageBubble> + <PromptComposer>. Auto-scrolls (sticky-bottom), shows Stop while streaming, surfaces transport errors inline.

<MessageBubble>

Single chat message atom. Variants by role (user / assistant / system / tool). Built-in "thinking" indicator while streaming with no content yet. Honors --bl-* design tokens.

<PromptComposer>

Multi-line input. Enter submits, Shift+Enter newlines, Cmd/Ctrl+Enter alternates submit. Auto-grows up to maxLines. Slot for leading actions (slash-commands etc.).

Hooks

useChat(options?)

Vercel-AI-SDK-shaped:

const {
  messages, input, setInput, handleInputChange, handleSubmit,
  append, isLoading, error, stop, reload, setMessages
} = useChat({
  endpoint: '/api/chat',
  streamProtocol: 'text',   // 'text' | 'sse' | 'data'
  initialMessages: [],
  onFinish: (msg) => console.log('done', msg),
  onError:  (err) => console.error(err),
});

streamText(response, protocol?, signal?)

Low-level async generator that yields text deltas from a streaming HTTP response. Supports 'text', 'sse', and 'data' protocols.

Wire protocols

Protocol	Body format	Use when
'text' (default)	Plain text, streamed chunk-by-chunk	Any backend that pipes an LLM stream directly
'sse'	Server-Sent Events with data: ... frames	OpenAI-compatible, Anthropic, most HF inference
'data'	Vercel AI SDK "data stream" prefix protocol	Backends using streamText() from ai/server

For tool calls / citations / images, use 'sse' or 'data' once the matching components ship in 0.2.x.

Tests

pnpm --filter @bytelyst/ai-ui test

Roadmap

• 0.2.0 — <ToolCallCard>, <CitationChip>, useToolCalls()
• 0.3.0 — <AgentTimeline>, <ModelPicker>
• 0.4.0 — <ToolPalette> with MCP discovery
• 0.5.0 — <Markdown> + <CodeDiff> (Wave 2 stretch)
• 1.0.0 — API freeze when 3+ products consume in production