conversationalist 0.0.2 → 0.0.4

package/README.md

@@ -1,14 +1,52 @@
 # Conversationalist
 
-A TypeScript-first library for managing LLM conversation state with immutable updates, type-safe APIs, and provider adapters.
+A TypeScript-first library for managing LLM conversation state with **immutable updates**, **type-safe APIs**, and **provider-agnostic adapters**.
 
-The high-level value proposition:
+[![Tests](https://github.com/stevekinney/conversationalist/actions/workflows/test.yml/badge.svg)](https://github.com/stevekinney/conversationalist/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-- keep a single, model-agnostic conversation shape across UI, storage, and providers
-- append messages without mutation (safe for React, concurrent updates, replay)
-- handle tool calls, streaming responses, and hidden or internal messages
-- trim context windows and estimate token budgets
-- validate input with Zod schemas and typed errors
+## What is Conversationalist?
+
+**Conversationalist** is a state engine for LLM-driven applications. While most libraries focus on making the API calls themselves, Conversationalist focuses on the **state** that lives between those calls. It provides a unified, model-agnostic representation of a conversation that can be easily stored, serialized, and adapted for any major LLM provider (OpenAI, Anthropic, Gemini).
+
+In a modern AI application, a conversation is more than just a list of strings. It involves:
+
+- **Tool Use**: Pairing function calls with their results and ensuring they stay in sync.
+- **Hidden Logic**: Internal "thought" messages or snapshots that should be saved but never sent to the provider.
+- **Metadata**: Tracking tags, custom IDs, and tokens across different steps.
+- **Streaming**: Gracefully handling partial messages in a UI without messy state transitions.
+
+Conversationalist handles these complexities through a robust, type-safe API that treats your conversation as the "Single Source of Truth."
+
+## Why Use It?
+
+Managing LLM conversations manually often leads to "provider lock-in" or fragile glue code. Conversationalist solves this by:
+
+- **Decoupling Logic from Providers**: Write your business logic once using Conversationalist's message model, and use adapters to talk to OpenAI, Anthropic, or Gemini.
+- **Built-in Context Management**: Automatically handle context window limits by truncating history while preserving critical system instructions or recent messages.
+- **Type Safety Out-of-the-Box**: Built with Zod and TypeScript, ensuring that your conversation data is valid at runtime and compile-time.
+- **Unified Serialization**: One standard format (`ConversationJSON`) for your database, your frontend, and your backend.
+
+## The Immutable Advantage
+
+At its core, Conversationalist is **strictly immutable**. Every change to a conversation—whether appending a message, updating a stream, or redacting sensitive data—returns a _new_ conversation object.
+
+This approach offers several critical advantages for modern application development:
+
+1.  **React/Redux Friendly**: Because updates return new references, they trigger re-renders naturally and work seamlessly with state management libraries.
+2.  **Concurrency Safe**: You can safely pass a conversation to multiple functions or async tasks without worrying about one part of your app mutating it out from under another.
+3.  **Easy Branching & Replay**: Want to let a user "undo" an AI response or branch a conversation into two different paths? Simply keep a reference to the previous immutable state. No complex cloning required.
+4.  **Auditability**: Timestamps and message positions are automatically managed and preserved, making it easy to reconstruct the exact state of a chat at any point in time.
+
+## Real-World Use Cases
+
+- **Multi-Model Chatbots**: Build a UI where users can switch between GPT-4o and Claude 3.5 Sonnet mid-conversation without losing history.
+- **Chain-of-Thought Workflows**: Use `hidden` messages to store internal reasoning or intermediate steps that the AI uses to reach a final answer, without cluttering the user's view.
+- **Agentic Workflows**: Track complex tool-use loops where multiple functions are called in sequence, ensuring every result is correctly paired with its corresponding call ID.
+- **Token Budgeting**: Automatically trim old messages when a conversation gets too long, ensuring your API costs stay predictable and you never hit provider limits.
+- **Deterministic Testing**: Use the custom `environment` parameter to mock IDs and timestamps, allowing you to write 100% deterministic tests for your chat logic.
+
+---
 
 ## Installation
 
@@ -18,8 +56,7 @@ npm add conversationalist zod
 pnpm add conversationalist zod
 ```
 
-This package is ESM-only. Use `import` syntax.
-Zod is a peer dependency and must be installed by your app.
+This package is ESM-only. Use `import` syntax. Zod is a peer dependency and must be installed by your application.
 
 ## Quick Start
 
@@ -28,68 +65,29 @@ import {
   appendAssistantMessage,
   appendUserMessage,
   createConversation,
-  deserializeConversation,
   serializeConversation,
 } from 'conversationalist';
 import { toOpenAIMessages } from 'conversationalist/openai';
 
+// 1. Create a conversation
 let conversation = createConversation({
-  title: 'Support chat',
-  tags: ['support'],
+  title: 'Order Support',
+  metadata: { userId: 'user_123' },
 });
 
+// 2. Add messages (returns a new conversation object)
 conversation = appendUserMessage(conversation, 'Where is my order?');
 conversation = appendAssistantMessage(conversation, 'Let me check that for you.');
 
-const messages = toOpenAIMessages(conversation);
-// send messages to your provider...
-
-const stored = serializeConversation(conversation);
-const restored = deserializeConversation(stored);
-```
-
-## End-to-End Example (Store + Resume)
-
-```ts
-import {
-  appendAssistantMessage,
-  appendSystemMessage,
-  appendUserMessage,
-  createConversation,
-  deserializeConversation,
-  serializeConversation,
-} from 'conversationalist';
-import { toOpenAIMessages } from 'conversationalist/openai';
-
-let conversation = createConversation({ title: 'Order lookup' });
-conversation = appendSystemMessage(conversation, 'You are a support agent.');
-conversation = appendUserMessage(conversation, 'Where is order 123?');
-
-const response = await openai.chat.completions.create({
-  model: 'gpt-4.1-mini',
-  messages: toOpenAIMessages(conversation),
-});
-
-conversation = appendAssistantMessage(
-  conversation,
-  response.choices[0]?.message?.content ?? '',
-);
+// 3. Adapt for a provider
+const openAIMessages = toOpenAIMessages(conversation);
+// [{ role: 'user', content: 'Where is my order?' }, ...]
 
-const stored = serializeConversation(conversation);
-// await db.save(stored);
-
-let restored = deserializeConversation(stored);
-restored = appendUserMessage(restored, 'Can you email me the tracking link?');
+// 4. Save to your database
+const data = serializeConversation(conversation);
+// db.save(data.id, JSON.stringify(data));
 ```
 
-## When to Use
-
-- Build multi-provider chat apps with a consistent message model.
-- Store and replay conversation history safely.
-- Drive streaming UIs without ad-hoc state machines.
-- Enforce tool call correctness and pair calls with results.
-- Manage context windows and token limits in one place.
-
 ## Core Concepts
 
 ### Conversations
@@ -112,7 +110,7 @@ const conversation = createConversation({
 Messages have roles and can contain text or multi-modal content. Optional fields include
 `metadata`, `hidden`, `tokenUsage`, `toolCall`, `toolResult`, and `goalCompleted`.
 
-Roles: `user`, `assistant`, `system`, `developer`, `tool-use`, `tool-result`, `snapshot`.
+**Roles**: `user`, `assistant`, `system`, `developer`, `tool-use`, `tool-result`, `snapshot`.
 The `snapshot` role is for internal state and is skipped by adapters.
 
 ```ts
@@ -127,8 +125,8 @@ conversation = appendMessages(conversation, {
 });
 ```
 
-Hidden messages remain in history but are skipped by default when querying or adapting to
-providers.
+**Hidden messages** remain in history but are skipped by default when querying or adapting to
+providers. This is perfect for internal logging or "thinking" steps.
 
 ### Tool Calls
 
@@ -155,8 +153,6 @@ conversation = appendMessages(
 );
 ```
 
-Use `pairToolCallsWithResults` to render tool calls alongside their results.
-
 ### Streaming
 
 Streaming helpers let you append a placeholder, update it as chunks arrive, and finalize
@@ -182,62 +178,218 @@ conversation = finalizeStreamingMessage(conversation, messageId, {
 });
 ```
 
-### Context Window
+### Context Window Management
 
-Trim history to fit token budgets or to keep only recent messages.
+Automatically trim history to fit token budgets or to keep only recent messages.
 
 ```ts
 import { simpleTokenEstimator, truncateToTokenLimit } from 'conversationalist';
 
-conversation = truncateToTokenLimit(conversation, 4000, simpleTokenEstimator, {
+conversation = truncateToTokenLimit(conversation, 4000, {
   preserveSystemMessages: true,
   preserveLastN: 2,
 });
 ```
 
-### Provider Adapters
+#### Custom Token Counters
 
-Convert the same conversation into provider-specific formats.
+You can provide a custom token estimator (e.g. using `tiktoken` or `anthropic-tokenizer`) by passing it in the options or by binding it to your environment.
+
+```ts
+import { truncateToTokenLimit } from 'conversationalist';
+// import { get_encoding } from 'tiktoken';
 
-Adapters skip hidden and snapshot messages and map system or developer roles as needed.
+const tiktokenEstimator = (message) => {
+  // Your logic here...
+  return 100;
+};
+
+// 1. Pass directly in options
+conversation = truncateToTokenLimit(conversation, 4000, {
+  estimateTokens: tiktokenEstimator,
+});
+
+// 2. Or bind to a history instance/environment
+const history = new ConversationHistory(conversation, {
+  estimateTokens: tiktokenEstimator,
+});
+
+const boundTruncate = history.bind(truncateToTokenLimit);
+boundTruncate(4000); // Uses tiktokenEstimator automatically
+```
+
+### Markdown Conversion
+
+Convert conversations to human-readable Markdown format, or parse Markdown back into a conversation object.
+
+#### Basic Usage (Clean Markdown)
+
+By default, `toMarkdown` produces clean, readable Markdown without metadata:
 
 ```ts
-import { toOpenAIMessages, toOpenAIMessagesGrouped } from 'conversationalist/openai';
+import {
+  toMarkdown,
+  fromMarkdown,
+  createConversation,
+  appendMessages,
+} from 'conversationalist';
+
+let conversation = createConversation({ id: 'conv-1' });
+conversation = appendMessages(
+  conversation,
+  { role: 'user', content: 'What is 2 + 2?' },
+  { role: 'assistant', content: 'The answer is 4.' },
+);
+
+const markdown = toMarkdown(conversation);
+// Output:
+// ### User
+//
+// What is 2 + 2?
+//
+// ### Assistant
+//
+// The answer is 4.
+```
+
+When parsing simple Markdown without metadata, `fromMarkdown` generates new IDs and uses sensible defaults:
+
+```ts
+const parsed = fromMarkdown(markdown);
+// parsed.id is a new generated ID
+// parsed.status is 'active'
+// Message IDs are generated, positions are assigned sequentially
+```
+
+#### Lossless Round-Trip (with Metadata)
+
+For archiving or backup scenarios where you need to preserve all data, use `{ includeMetadata: true }`:
+
+```ts
+const markdown = toMarkdown(conversation, { includeMetadata: true });
+// Output includes YAML frontmatter with all metadata keyed by message ID:
+// ---
+// id: conv-1
+// status: active
+// metadata: {}
+// tags: []
+// createdAt: '2024-01-15T10:00:00.000Z'
+// updatedAt: '2024-01-15T10:01:00.000Z'
+// messages:
+//   msg-1:
+//     position: 0
+//     createdAt: '2024-01-15T10:00:00.000Z'
+//     metadata: {}
+//     hidden: false
+//   msg-2:
+//     position: 1
+//     createdAt: '2024-01-15T10:01:00.000Z'
+//     metadata: {}
+//     hidden: false
+// ---
+// ### User (msg-1)
+//
+// What is 2 + 2?
+//
+// ### Assistant (msg-2)
+//
+// The answer is 4.
+
+// Parse back with all metadata preserved
+const restored = fromMarkdown(markdown);
+// restored.id === 'conv-1'
+// restored.messages[0].id === 'msg-1'
+```
+
+#### Multi-Modal Content
+
+Both functions handle multi-modal content. Images render as Markdown images, and with metadata enabled, additional properties like `mimeType` are preserved in the YAML frontmatter:
+
+```ts
+conversation = appendMessages(conversation, {
+  role: 'user',
+  content: [
+    { type: 'text', text: 'Describe this:' },
+    { type: 'image', url: 'https://example.com/photo.png', mimeType: 'image/png' },
+  ],
+});
+
+const md = toMarkdown(conversation);
+// Describe this:
+//
+// ![image](https://example.com/photo.png)
+```
+
+## Plugins
+
+**Conversationalist** supports a plugin system that allows you to transform messages as they are appended to a conversation. Plugins are functions that take a `MessageInput` and return a modified `MessageInput`.
+
+### PII Redaction Plugin
+
+The library includes a built-in `piiRedactionPlugin` that can automatically redact emails, phone numbers, and common API key patterns.
+
+```ts
+import {
+  appendUserMessage,
+  createConversation,
+  piiRedactionPlugin,
+} from 'conversationalist';
+
+// 1. Enable by adding to your environment
+const env = {
+  plugins: [piiRedactionPlugin],
+};
+
+// 2. Use the environment when appending messages
+let conversation = createConversation({}, env);
+conversation = appendUserMessage(
+  conversation,
+  'Contact me at test@example.com',
+  undefined,
+  env,
+);
+
+console.log(conversation.messages[0].content);
+// "Contact me at [EMAIL_REDACTED]"
+```
+
+When using `ConversationHistory`, you only need to provide the plugin once during initialization:
+
+```ts
+const history = new ConversationHistory(createConversation(), {
+  plugins: [piiRedactionPlugin],
+});
+
+const appendUser = history.bind(appendUserMessage);
+appendUser('My key is sk-12345...'); // Automatically redacted
+```
+
+## Provider Adapters
+
+Convert the same conversation into provider-specific formats. Adapters automatically skip hidden/snapshot messages and map roles correctly.
+
+```ts
+import { toOpenAIMessages } from 'conversationalist/openai';
 import { toAnthropicMessages } from 'conversationalist/anthropic';
 import { toGeminiMessages } from 'conversationalist/gemini';
 ```
 
-- OpenAI: `toOpenAIMessages` and `toOpenAIMessagesGrouped` (groups consecutive tool calls)
-- Anthropic: `toAnthropicMessages`
-- Gemini: `toGeminiMessages`
+- **OpenAI**: Supports `toOpenAIMessages` and `toOpenAIMessagesGrouped` (which groups consecutive tool calls).
+- **Anthropic**: Maps system messages and tool blocks to Anthropic's specific format.
+- **Gemini**: Handles Gemini's unique content/part structure.
 
-### Tool Call Wiring Examples
+### Provider-Specific Examples
 
-#### OpenAI
+#### OpenAI (with Tool Calls)
 
 ```ts
 import { appendAssistantMessage, appendMessages } from 'conversationalist';
 import { toOpenAIMessages } from 'conversationalist/openai';
 
-const tools = [
-  {
-    type: 'function',
-    function: {
-      name: 'getWeather',
-      description: 'Get current weather by city.',
-      parameters: {
-        type: 'object',
-        properties: { city: { type: 'string' } },
-        required: ['city'],
-      },
-    },
-  },
-];
-
 const response = await openai.chat.completions.create({
-  model: 'gpt-4.1-mini',
+  model: 'gpt-4o',
   messages: toOpenAIMessages(conversation),
-  tools,
+  tools: [{ type: 'function', function: { name: 'getWeather', ... } }],
 });
 
 const toolCalls = response.choices[0]?.message?.tool_calls ?? [];
@@ -245,11 +397,7 @@ for (const call of toolCalls) {
   conversation = appendMessages(conversation, {
     role: 'tool-use',
     content: '',
-    toolCall: {
-      id: call.id,
-      name: call.function.name,
-      arguments: call.function.arguments,
-    },
+    toolCall: { id: call.id, name: call.function.name, arguments: call.function.arguments },
   });
 
   const result = await getWeather(JSON.parse(call.function.arguments));
@@ -259,43 +407,20 @@ for (const call of toolCalls) {
     toolResult: { callId: call.id, outcome: 'success', content: result },
   });
 }
-
-const followUp = await openai.chat.completions.create({
-  model: 'gpt-4.1-mini',
-  messages: toOpenAIMessages(conversation),
-  tools,
-});
-
-conversation = appendAssistantMessage(
-  conversation,
-  followUp.choices[0]?.message?.content ?? '',
-);
 ```
 
-#### Anthropic
+#### Anthropic (with Tool Calls)
 
 ```ts
 import { appendAssistantMessage, appendMessages } from 'conversationalist';
 import { toAnthropicMessages } from 'conversationalist/anthropic';
 
-const tools = [
-  {
-    name: 'getWeather',
-    description: 'Get current weather by city.',
-    input_schema: {
-      type: 'object',
-      properties: { city: { type: 'string' } },
-      required: ['city'],
-    },
-  },
-];
-
 const { system, messages } = toAnthropicMessages(conversation);
 const response = await anthropic.messages.create({
   model: 'claude-3-5-sonnet-20240620',
   system,
   messages,
-  tools,
+  tools: [{ name: 'getWeather', ... }],
 });
 
 for (const block of response.content) {
@@ -306,64 +431,33 @@ for (const block of response.content) {
     toolCall: { id: block.id, name: block.name, arguments: block.input },
   });
 
-  const result = await getWeather(block.input as { city: string });
+  const result = await getWeather(block.input);
   conversation = appendMessages(conversation, {
     role: 'tool-result',
     content: '',
     toolResult: { callId: block.id, outcome: 'success', content: result },
   });
 }
-
-const followUp = await anthropic.messages.create({
-  model: 'claude-3-5-sonnet-20240620',
-  ...toAnthropicMessages(conversation),
-  tools,
-});
-
-const assistantText = followUp.content
-  .filter((block) => block.type === 'text')
-  .map((block) => block.text)
-  .join('\n');
-
-conversation = appendAssistantMessage(conversation, assistantText);
 ```
 
-#### Gemini
-
-Gemini does not include tool call IDs, so generate one to pair the tool result.
+#### Gemini (with Tool Calls)
 
 ```ts
 import { appendMessages } from 'conversationalist';
 import { toGeminiMessages } from 'conversationalist/gemini';
 
-const tools = [
-  {
-    functionDeclarations: [
-      {
-        name: 'getWeather',
-        description: 'Get current weather by city.',
-        parameters: {
-          type: 'object',
-          properties: { city: { type: 'string' } },
-          required: ['city'],
-        },
-      },
-    ],
-  },
-];
-
 const { systemInstruction, contents } = toGeminiMessages(conversation);
 const response = await model.generateContent({
   systemInstruction,
   contents,
-  tools,
+  tools: [{ functionDeclarations: [{ name: 'getWeather', ... }] }],
 });
 
 const parts = response.response.candidates?.[0]?.content?.parts ?? [];
 for (const part of parts) {
   if (!('functionCall' in part)) continue;
-  const callId = crypto.randomUUID();
-  const args = part.functionCall.args as { city: string };
+  const callId = crypto.randomUUID(); // Gemini doesn't provide IDs, so we generate one
+  const args = part.functionCall.args;
 
   conversation = appendMessages(conversation, {
     role: 'tool-use',
@@ -378,26 +472,14 @@ for (const part of parts) {
     toolResult: { callId, outcome: 'success', content: result },
   });
 }
-
-const followUp = await model.generateContent({
-  ...toGeminiMessages(conversation),
-  tools,
-});
 ```
 
-## Builder Pattern
+## Builder Pattern (Fluent API)
 
-Use the draft pattern for fluent, mutable-style updates that still return immutable
-conversations.
+If you prefer a more fluent style, use `withConversation` or `pipeConversation`. These allow you to "mutate" a draft within a scope while still resulting in an immutable object.
 
 ```ts
-import {
-  appendSystemMessage,
-  appendUserMessage,
-  createConversation,
-  pipeConversation,
-  withConversation,
-} from 'conversationalist';
+import { withConversation, createConversation } from 'conversationalist';
 
 const conversation = withConversation(createConversation(), (draft) => {
   draft
@@ -405,166 +487,323 @@ const conversation = withConversation(createConversation(), (draft) => {
     .appendUserMessage('Hello!')
     .appendAssistantMessage('Hi there!');
 });
+```
 
-const piped = pipeConversation(
+`pipeConversation` allows you to chain multiple transformation functions together:
+
+```ts
+import {
+  createConversation,
+  pipeConversation,
+  appendSystemMessage,
+  appendUserMessage,
+} from 'conversationalist';
+
+const conversation = pipeConversation(
   createConversation(),
-  (c) => appendSystemMessage(c, 'You are helpful.'),
+  (c) => appendSystemMessage(c, 'You are a helpful assistant.'),
   (c) => appendUserMessage(c, 'Hello!'),
+  (c) => appendAssistantMessage(c, 'Hi there!'),
 );
 ```
 
-`ConversationDraft` includes appending, system message helpers, streaming, redaction, and
-context window utilities.
+## Conversation History (Undo/Redo)
 
-## API Overview
+Use the `ConversationHistory` class to manage a stack of conversation states. Because every change returns a new immutable object, supporting undo/redo is built into the architecture.
+
+````ts
+import {
+  ConversationHistory,
+  createConversation,
+  appendUserMessage,
+} from 'conversationalist';
 
-### Conversation Creation and Serialization
+const history = new ConversationHistory(createConversation());
 
-```ts
-createConversation(options?, environment?)
-serializeConversation(conversation)
-deserializeConversation(json)
-toChatMessages(conversation)
+// You can use convenience methods that automatically track state
+history.appendUserMessage('Hello!');
+history.appendAssistantMessage('How are you?');
+
+history.undo(); // State reverts to just "Hello!"
+history.redo(); // State advances back to "How are you?"
+
+// Convenience methods for all library utilities are built-in
+history.appendUserMessage('Another message');
+history.redactMessageAtPosition(0);
+history.truncateToTokenLimit(4000);
+
+// Query methods work on the current state
+const messages = history.getMessages();
+const stats = history.getStatistics();
+const tokens = history.estimateTokens();
 ```
 
-### Message Appending
+### Event Subscription
+
+`ConversationHistory` implements `EventTarget` and follows the Svelte store contract. You can listen for changes using standard DOM events or the `subscribe` method.
+
+#### Using DOM Events
 
 ```ts
-appendMessages(conversation, ...inputs, environment?)
-appendUserMessage(conversation, content, metadata?, environment?)
-appendAssistantMessage(conversation, content, metadata?, environment?)
-appendSystemMessage(conversation, content, metadata?, environment?)
+const history = new ConversationHistory(createConversation());
+
+// addEventListener returns a convenient unsubscribe function
+const unsubscribe = history.addEventListener('change', (event) => {
+  const { type, conversation } = event.detail;
+  console.log(`History updated via ${type}`);
+});
+
+history.appendUserMessage('Hello!'); // Fires 'push' and 'change' events
+
+unsubscribe(); // Clean up when done
 ```
 
-### System Message Utilities
+#### Using the Store Contract
 
 ```ts
-prependSystemMessage(conversation, content, metadata?, environment?)
-replaceSystemMessage(conversation, content, metadata?, environment?)
-collapseSystemMessages(conversation, environment?)
-hasSystemMessage(conversation)
-getFirstSystemMessage(conversation)
-getSystemMessages(conversation)
+// Subscribe returns an unsubscribe function and calls the callback immediately
+const unsubscribe = history.subscribe((conversation) => {
+  console.log('Current conversation state:', conversation);
+});
 ```
 
-### Querying and Stats
+You can also use an `AbortSignal` for automatic cleanup:
 
 ```ts
-getConversationMessages(conversation, { includeHidden? })
-getMessageAtPosition(conversation, position)
-getMessageByIdentifier(conversation, id)
-searchConversationMessages(conversation, predicate)
-computeConversationStatistics(conversation)
+const controller = new AbortController();
+history.addEventListener('change', (e) => { ... }, { signal: controller.signal });
+
+// Later...
+controller.abort();
 ```
 
-### Modification
+### Conversation Branching
+
+The `ConversationHistory` class supports branching. When you undo to a previous state and push a new update, it creates an alternate path instead of deleting the old history.
 
 ```ts
-redactMessageAtPosition(conversation, position, placeholder?)
+const history = new ConversationHistory(createConversation());
+
+history.push(appendUserMessage(history.current, 'Path A'));
+history.undo();
+
+history.push(appendUserMessage(history.current, 'Path B'));
+
+console.log(history.branchCount); // 2
+console.log(history.current.messages[0].content); // "Path B"
+
+history.switchToBranch(0);
+console.log(history.current.messages[0].content); // "Path A"
 ```
 
-### Streaming
+### Serialization
+
+You can serialize the entire history tree (including all branches) to JSON and reconstruct it later.
 
 ```ts
-appendStreamingMessage(conversation, role, metadata?, environment?)
-updateStreamingMessage(conversation, messageId, content, environment?)
-finalizeStreamingMessage(conversation, messageId, { tokenUsage?, metadata? }, environment?)
-cancelStreamingMessage(conversation, messageId, environment?)
-isStreamingMessage(message)
-getStreamingMessage(conversation)
+// 1. Save to JSON
+const json = history.toJSON();
+// localStorage.setItem('chat_history', JSON.stringify(json));
+
+// 2. Restore from JSON
+const restored = ConversationHistory.from(json);
+
+// You can also provide a new environment (e.g. with fresh token counters)
+const restoredWithEnv = ConversationHistory.from(json, {
+  estimateTokens: myNewEstimator,
+});
 ```
 
-### Context Window
+## Integration
 
-```ts
-getRecentMessages(conversation, count, { includeHidden?, includeSystem? })
-truncateFromPosition(conversation, position, { preserveSystemMessages? }, environment?)
-truncateToTokenLimit(
-  conversation,
-  maxTokens,
-  estimateTokens,
-  { preserveSystemMessages?, preserveLastN? },
-  environment?,
-)
-estimateConversationTokens(conversation, estimateTokens)
-simpleTokenEstimator(message)
+### Using with React
+
+Because **Conversationalist** is immutable, it works perfectly with React's `useState` or `useReducer`. Every update returns a new reference, which automatically triggers a re-render.
+
+```tsx
+import { useState } from 'react';
+import { createConversation, appendUserMessage } from 'conversationalist';
+
+export function ChatApp() {
+  const [conversation, setConversation] = useState(() => createConversation());
+
+  const handleSend = (text: string) => {
+    // The new conversation object is set into state
+    setConversation((prev) => appendUserMessage(prev, text));
+  };
+
+  return (
+    <div>
+      {conversation.messages.map((m) => (
+        <div key={m.id}>{String(m.content)}</div>
+      ))}
+      <button onClick={() => handleSend('Hello!')}>Send</button>
+    </div>
+  );
+}
 ```
 
-### Utilities
+#### Custom React Hook Example
 
-```ts
-pairToolCallsWithResults(messages);
-normalizeContent(content);
-toMultiModalArray(content);
-createMessage(messageJSON);
-copyContent(content);
-copyMultiModalContent(item);
+For more complex applications, you can wrap the logic into a custom hook. This example uses `addEventListener` to sync the history with local React state and returns the unsubscribe function for easy cleanup in `useEffect`.
+
+```tsx
+import { useState, useCallback, useEffect } from 'react';
+import {
+  createConversation,
+  ConversationHistory,
+  toChatMessages,
+} from 'conversationalist';
+
+export function useChat(initialTitle?: string) {
+  // 1. Initialize history (this could also come from context or props)
+  const [history] = useState(
+    () => new ConversationHistory(createConversation({ title: initialTitle })),
+  );
+
+  // 2. Sync history with local state for reactivity
+  const [conversation, setConversation] = useState(history.current);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    // addEventListener returns a cleanup function!
+    return history.addEventListener('change', (e) => {
+      setConversation(e.detail.conversation);
+    });
+  }, [history]);
+
+  const sendMessage = useCallback(
+    async (text: string) => {
+      history.appendUserMessage(text);
+      setLoading(true);
+
+      try {
+        const response = await fetch('/api/chat', {
+          method: 'POST',
+          body: JSON.stringify({
+            messages: history.toChatMessages(),
+          }),
+        });
+        const data = await response.json();
+        history.appendAssistantMessage(data.answer);
+      } finally {
+        setLoading(false);
+      }
+    },
+    [history],
+  );
+
+  return {
+    conversation,
+    messages: conversation.messages,
+    loading,
+    sendMessage,
+    undo: () => history.undo(),
+    redo: () => history.redo(),
+  };
+}
 ```
 
-### Schemas
+> **Note**: `ConversationHistory.addEventListener()` returns an unsubscribe function, which is ideal for cleaning up effects in React (`useEffect`) or Svelte.
+
+### Using with Redux
+
+Redux requires immutable state updates, making **Conversationalist** an ideal companion. You can store the conversation object directly in your store.
 
 ```ts
-conversationSchema;
-conversationShape;
-messageInputSchema;
-messageJSONSchema;
-messageRoleSchema;
-multiModalContentSchema;
-tokenUsageSchema;
-toolCallSchema;
-toolResultSchema;
+import { createSlice, PayloadAction } from '@reduxjs/toolkit';
+import { createConversation, appendUserMessage, Conversation } from 'conversationalist';
+
+interface ChatState {
+  conversation: Conversation;
+}
+
+const chatSlice = createSlice({
+  name: 'chat',
+  initialState: {
+    conversation: createConversation(),
+  } as ChatState,
+  reducers: {
+    userMessageReceived: (state, action: PayloadAction<string>) => {
+      // Redux Toolkit's createSlice uses Immer, but since appendUserMessage
+      // returns a new object, we can just replace the property.
+      state.conversation = appendUserMessage(state.conversation, action.payload);
+    },
+  },
+});
 ```
 
-### Errors
+### Using with Svelte (Runes)
 
-```ts
-ConversationalistError;
-createDuplicateIdError;
-createInvalidInputError;
-createInvalidPositionError;
-createInvalidToolReferenceError;
-createLockedError;
-createNotFoundError;
-createSerializationError;
-createValidationError;
+In Svelte 5, you can manage conversation state using the `$state` rune. Since **Conversationalist** is immutable, you update the state by re-assigning the variable with a new conversation object.
+
+```svelte
+<script lang="ts">
+  import { createConversation, appendUserMessage } from 'conversationalist';
+
+  let conversation = $state(createConversation());
+
+  function handleSend(text: string) {
+    conversation = appendUserMessage(conversation, text);
+  }
+</script>
+
+<div>
+  {#each conversation.messages as m (m.id)}
+    <div>{String(m.content)}</div>
+  {/each}
+  <button onclick={() => handleSend('Hello!')}>Send</button>
+</div>
 ```
 
-## Deterministic Environments (Testing)
+#### Custom Svelte Rune Example
 
-Pass a custom environment to control timestamps and IDs.
+Svelte 5's runes pair perfectly with **Conversationalist**. You can use the `ConversationHistory` class directly as a store, or wrap it in a class with runes.
 
-```ts
-import { appendUserMessage, createConversation } from 'conversationalist';
+```svelte
+<script lang="ts">
+  import { ConversationHistory, createConversation } from 'conversationalist';
 
-const env = {
-  now: () => '2024-01-01T00:00:00.000Z',
-  randomId: () => 'fixed-id',
-};
+  // history implements the Svelte store contract
+  const history = new ConversationHistory(createConversation());
+</script>
 
-let conversation = createConversation({ title: 'Test' }, env);
-conversation = appendUserMessage(conversation, 'Hello', undefined, env);
+<div>
+  {#each $history.messages as m (m.id)}
+    <div>{String(m.content)}</div>
+  {/each}
+  <button onclick={() => history.appendUserMessage('Hello!')}>
+    Send
+  </button>
+</div>
 ```
 
-## Types
+> **Note**: `ConversationHistory.addEventListener()` returns an unsubscribe function, which is ideal for cleaning up reactive effects in Svelte 5 or React hooks.
+
+## API Overview
+
+| Category         | Key Functions                                                                                            |
+| :--------------- | :------------------------------------------------------------------------------------------------------- |
+| **Creation**     | `createConversation`, `serializeConversation`, `deserializeConversation`                                 |
+| **Appending**    | `appendUserMessage`, `appendAssistantMessage`, `appendSystemMessage`, `appendMessages`                   |
+| **Streaming**    | `appendStreamingMessage`, `updateStreamingMessage`, `finalizeStreamingMessage`, `cancelStreamingMessage` |
+| **Modification** | `redactMessageAtPosition`, `replaceSystemMessage`, `collapseSystemMessages`                              |
+| **Context**      | `truncateToTokenLimit`, `getRecentMessages`, `estimateConversationTokens`                                |
+| **Querying**     | `getConversationMessages`, `getMessageByIdentifier`, `computeConversationStatistics`                     |
+| **Conversion**   | `toMarkdown`, `fromMarkdown`, `toChatMessages`, `pairToolCallsWithResults`                               |
+| **History**      | `ConversationHistory`, `bindToConversationHistory`                                                       |
+
+## Deterministic Environments (Testing)
+
+Pass a custom environment to control timestamps and IDs, making your tests 100% predictable.
 
 ```ts
-import type {
-  Conversation,
-  ConversationEnvironment,
-  ConversationJSON,
-  ConversationStatus,
-  ExternalMessage,
-  ImageContent,
-  Message,
-  MessageInput,
-  MessageJSON,
-  MessageRole,
-  MultiModalContent,
-  TextContent,
-  TokenUsage,
-  ToolCall,
-  ToolResult,
-} from 'conversationalist';
+const testEnv = {
+  now: () => '2024-01-01T00:00:00.000Z',
+  randomId: () => 'fixed-id',
+};
+
+let conversation = createConversation({ title: 'Test' }, testEnv);
 ```
 
 ## Development
@@ -572,11 +811,6 @@ import type {
 ```bash
 bun install
 bun test
-bun run typecheck
-bun run lint
 bun run build
 ```
-
-## License
-
-MIT
+````