@colletdev/docs 0.2.2 → 0.2.3

package/cli.mjs

@@ -85,6 +85,7 @@ Read the reference that matches the user's context:
 | .component.ts / Angular | core.md + angular.md |
 | Custom Elements / @colletdev/core | core.md only |
 | Component API question | components.md |
+| Chat / messages / streaming | messages.md |
 
 Always read core.md first, then the framework-specific reference.
 
@@ -100,14 +101,14 @@ Always read core.md first, then the framework-specific reference.
   writeFileSync(resolve(skillDir, 'SKILL.md'), skillMd);
 
   // Copy all reference docs
-  for (const file of ['core.md', 'components.md', 'react.md', 'vue.md', 'svelte.md', 'angular.md']) {
+  for (const file of ['core.md', 'components.md', 'messages.md', 'react.md', 'vue.md', 'svelte.md', 'angular.md']) {
     const src = docPath(file);
     if (existsSync(src)) {
       writeFileSync(resolve(refDir, file), readDoc(file));
     }
   }
 
-  console.log(`  Claude Code: .claude/skills/collet/ (SKILL.md + 6 references)`);
+  console.log(`  Claude Code: .claude/skills/collet/ (SKILL.md + 7 references)`);
 
   // Add to .claude/CLAUDE.md if it exists and doesn't already mention collet
   const claudeMd = resolve(CWD, '.claude/CLAUDE.md');
@@ -293,7 +294,7 @@ function main() {
 
   console.log('');
   console.log('Done. Your AI agent now has full Collet component knowledge.');
-  console.log('Reference: 7 doc files from @colletdev/docs (108 KB total)');
+  console.log('Reference: 8 doc files from @colletdev/docs');
   console.log('');
 }
 

package/messages.md

@@ -0,0 +1,343 @@
+# Messages — Composition Guide
+
+How to build chat interfaces, AI assistant UIs, and conversational experiences
+with Collet's message component system.
+
+---
+
+## Architecture
+
+Messages are **composed, not monolithic**. There is no single `<Message>` component.
+Instead, four specialized components snap together like building blocks:
+
+```
+MessageBubble          ← outer container (alignment, avatar, timestamp)
+└── MessageGroup       ← groups connected content blocks
+    ├── MessagePart    ← text, code, tool calls, errors, thinking
+    ├── MessagePart    ← another content block
+    └── ActivityGroup  ← tool call/result group with derived status
+```
+
+This design lets you build anything from a simple chat bubble to a full
+AI coding assistant with tool calls, streaming markdown, and code blocks.
+
+---
+
+## The Components
+
+### MessageBubble
+
+The outer container. Controls sender alignment, avatar, name, and timestamp.
+
+```tsx
+import { MessageBubble } from '@colletdev/react';
+
+<MessageBubble role="assistant" senderName="Collet" avatar="/collet.svg">
+  {/* MessageGroup(s) go here */}
+</MessageBubble>
+
+<MessageBubble role="user" senderName="Dan">
+  {/* User message content */}
+</MessageBubble>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `role` | `'user' \| 'assistant'` | `'user'` | Determines alignment and color |
+| `senderName` | `string` | — | Name displayed above the bubble |
+| `avatar` | `string` | — | Avatar image URL |
+| `timestamp` | `string` | — | Timestamp text |
+| `variant` | `'filled' \| 'ghost'` | `'filled'` | Visual style |
+| `shape` | `'sharp' \| 'rounded'` | `'rounded'` | Border radius |
+
+**Alignment:** `role="user"` right-aligns, `role="assistant"` left-aligns.
+
+### MessageGroup
+
+Groups multiple `MessagePart` blocks into a single connected card. Parts within
+a group share edges (no gaps between them).
+
+```tsx
+import { MessageGroup } from '@colletdev/react';
+
+<MessageGroup role="assistant">
+  <MessagePart kind="text">Here is what I found:</MessagePart>
+  <MessagePart kind="code-block" language="rust" filename="main.rs">
+    fn main() { println!("Hello"); }
+  </MessagePart>
+</MessageGroup>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `role` | `'user' \| 'assistant'` | `'user'` | Color scheme |
+| `variant` | `'filled' \| 'ghost'` | `'filled'` | Visual style |
+
+### MessagePart
+
+The individual content block. Each part has a `kind` that determines its rendering:
+
+| Kind | Renders as | Use for |
+|------|-----------|---------|
+| `text` | Plain or markdown text | Chat messages, explanations |
+| `code-block` | Syntax-highlighted code with terminal chrome | Code snippets, file contents |
+| `tool-call` | Collapsible tool invocation row | Function calls, API requests |
+| `tool-result` | Collapsible tool output | Function responses |
+| `thinking` | Shimmer animation or completed indicator | "Thinking..." state |
+| `error` | Danger-styled error message | Error responses |
+
+```tsx
+import { MessagePart } from '@colletdev/react';
+
+{/* Plain text */}
+<MessagePart kind="text">Hello, how can I help?</MessagePart>
+
+{/* Markdown text */}
+<MessagePart kind="text" markdown>
+  Here is a **bold** statement with a [link](https://example.com).
+</MessagePart>
+
+{/* Code block */}
+<MessagePart kind="code-block" language="typescript" filename="setup.ts">
+  import { init } from '@colletdev/core';
+  await init();
+</MessagePart>
+
+{/* Tool call (pending) */}
+<MessagePart
+  kind="tool-call"
+  toolName="search_docs"
+  toolArguments='{"query": "auth"}'
+  status="pending"
+/>
+
+{/* Tool result */}
+<MessagePart
+  kind="tool-result"
+  toolName="search_docs"
+  status="success"
+  collapsible
+>
+  Found 3 results...
+</MessagePart>
+
+{/* Thinking indicator */}
+<MessagePart kind="thinking" thinkingLabel="Analyzing code..." />
+
+{/* Error */}
+<MessagePart kind="error">Connection timed out</MessagePart>
+```
+
+### ActivityGroup
+
+Groups related tool calls and results with a derived status indicator.
+The status is computed from child tool states — you don't set it manually.
+
+```tsx
+import { ActivityGroup } from '@colletdev/react';
+
+<ActivityGroup label="Code analysis" status="running">
+  <MessagePart kind="tool-call" toolName="read_file" status="success" />
+  <MessagePart kind="tool-call" toolName="search_code" status="pending" />
+</ActivityGroup>
+```
+
+| Status | Meaning | Visual |
+|--------|---------|--------|
+| `running` | At least one tool is pending | Shimmer animation |
+| `done` | All tools completed successfully | Checkmark |
+| `error` | At least one tool failed | Error indicator |
+
+---
+
+## Markdown Rendering
+
+MessagePart with `kind="text"` and `markdown` enabled renders GitHub Flavored
+Markdown through Collet's WASM-powered renderer:
+
+```tsx
+<MessagePart kind="text" markdown>
+  ## Features
+
+  - **Tables** with column alignment
+  - `inline code` and fenced code blocks
+  - Task lists: - [x] done - [ ] todo
+  - [Links](https://example.com) with external indicators
+  - Heading anchors for deep linking
+</MessagePart>
+```
+
+**What's supported:** paragraphs, headings (h1-h6) with anchor IDs, bold, italic,
+strikethrough, ordered/unordered/nested lists, task lists, tables, inline code,
+fenced code blocks with language labels, blockquotes, links, images, horizontal rules.
+
+**Security:** XSS-safe at compile time — raw HTML in markdown source is escaped,
+not passed through. No runtime sanitizer needed.
+
+**Programmatic rendering:**
+
+```tsx
+import { renderMarkdown } from '@colletdev/core/markdown';
+
+// Async (lazy-loads WASM)
+const html = await renderMarkdown('**Hello** world');
+
+// Sync (after WASM is loaded)
+import { renderMarkdownSync } from '@colletdev/core/markdown';
+const html = renderMarkdownSync('**Hello** world');
+```
+
+**React hook:**
+
+```tsx
+import { useMarkdown } from '@colletdev/react';
+
+function MyComponent({ content }) {
+  const html = useMarkdown(content);
+  return <div dangerouslySetInnerHTML={{ __html: html }} />;
+}
+```
+
+---
+
+## Streaming Messages
+
+For real-time AI responses, use the streaming API on MessagePart:
+
+```tsx
+import { useRef } from 'react';
+import { MessagePart } from '@colletdev/react';
+import type { MessagePartRef } from '@colletdev/react';
+
+function StreamingMessage() {
+  const ref = useRef<MessagePartRef>(null);
+
+  useEffect(() => {
+    // Start streaming
+    ref.current?.startStream();
+
+    // Append tokens as they arrive
+    eventSource.onmessage = (e) => {
+      ref.current?.appendTokens(e.data);
+    };
+
+    // End stream (triggers WASM re-render for XSS safety)
+    eventSource.onclose = () => {
+      ref.current?.endStream();
+    };
+  }, []);
+
+  return <MessagePart ref={ref} kind="text" stream markdown />;
+}
+```
+
+**How streaming works:**
+1. `startStream()` — switches to DOM-based incremental rendering (fast)
+2. `appendTokens(text)` — appends text tokens with rAF batching
+3. `endStream()` — re-renders accumulated text through WASM markdown pipeline
+   (defense-in-depth XSS sanitization)
+
+---
+
+## MessageTimeline (Rust-side reducer)
+
+For production chat UIs with tool calls, streaming, and complex turn lifecycle,
+Collet provides a Rust-side chronological reducer. This is the recommended way
+to build AI assistant interfaces.
+
+**What it handles:**
+- Chronological ordering of text, thinking, tool calls, code blocks, errors
+- Out-of-order tool result hydration
+- Tool group status derivation (running → done/error) from child state
+- Thinking auto-settlement when the turn advances
+- Duplicate tool result deduplication
+- Terminal turn immutability (completed/aborted turns reject new events)
+
+**Note:** MessageTimeline is currently Rust-side only. It renders directly to HTML
+via the SSR gallery. WASM/npm export is planned — see the project roadmap.
+
+---
+
+## Complete Example
+
+A full AI assistant conversation with tool calls:
+
+```tsx
+import {
+  MessageBubble, MessageGroup, MessagePart, ActivityGroup
+} from '@colletdev/react';
+
+function Conversation() {
+  return (
+    <div style={{ maxWidth: '48rem', margin: '0 auto' }}>
+      {/* User message */}
+      <MessageBubble role="user" senderName="Dan">
+        <MessageGroup role="user">
+          <MessagePart kind="text">
+            How do I set up Collet in my Next.js app?
+          </MessagePart>
+        </MessageGroup>
+      </MessageBubble>
+
+      {/* Assistant response with tool calls */}
+      <MessageBubble role="assistant" senderName="Collet" avatar="/collet.svg">
+        <MessageGroup role="assistant">
+          {/* Thinking */}
+          <MessagePart kind="thinking" completed thinkingLabel="Searched documentation" />
+
+          {/* Tool activity */}
+          <ActivityGroup label="Documentation search" status="done">
+            <MessagePart
+              kind="tool-call"
+              toolName="search_docs"
+              status="success"
+              description="Searched Next.js setup guide"
+            />
+          </ActivityGroup>
+
+          {/* Response text with markdown */}
+          <MessagePart kind="text" markdown>
+            Here's how to set up Collet in Next.js:
+
+            1. Install the packages
+            2. Add the Vite plugin (or configure manually for Next.js)
+            3. Call `init()` in your root layout
+          </MessagePart>
+
+          {/* Code example */}
+          <MessagePart kind="code-block" language="tsx" filename="app/layout.tsx">
+{`import { init } from '@colletdev/core';
+
+init();
+
+export default function RootLayout({ children }) {
+  return <html><body>{children}</body></html>;
+}`}
+          </MessagePart>
+        </MessageGroup>
+      </MessageBubble>
+    </div>
+  );
+}
+```
+
+---
+
+## Standalone Code Blocks
+
+For code display outside of messages, use the dedicated `CodeBlock` component:
+
+```tsx
+import { CodeBlock } from '@colletdev/react';
+
+{/* Full terminal chrome */}
+<CodeBlock content="fn main() {}" language="rust" filename="main.rs" />
+
+{/* Minimal (no chrome, hover copy button) */}
+<CodeBlock content="npm install @colletdev/core" variant="minimal" />
+
+{/* No traffic lights */}
+<CodeBlock content="code" language="js" trafficLights={false} />
+```
+
+See the [CodeBlock component docs](./components.md#codeblock) for full props reference.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colletdev/docs",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Collet component library documentation — API reference, framework guides, and AI agent setup",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "./vue": "./vue.md",
     "./svelte": "./svelte.md",
     "./angular": "./angular.md",
-    "./core": "./core.md"
+    "./core": "./core.md",
+    "./messages": "./messages.md"
   },
   "files": [
     "*.md",