convo-tree 0.1.0 → 0.1.1

package/README.md

@@ -2,130 +2,730 @@
 
 Tree-structured conversation state manager for branching chats.
 
-Manages a tree of conversation nodes where each node holds a message (role + content). You can branch at any point, navigate branches, undo/redo, prune subtrees, and serialize the full state.
+[![npm version](https://img.shields.io/npm/v/convo-tree.svg)](https://www.npmjs.com/package/convo-tree)
+[![npm downloads](https://img.shields.io/npm/dt/convo-tree.svg)](https://www.npmjs.com/package/convo-tree)
+[![license](https://img.shields.io/npm/l/convo-tree.svg)](https://github.com/SiluPanda/convo-tree/blob/master/LICENSE)
+[![node](https://img.shields.io/node/v/convo-tree.svg)](https://www.npmjs.com/package/convo-tree)
 
-## Install
+`convo-tree` models a conversation as a rooted tree where each node holds a message (system, user, assistant, or tool), children represent alternative continuations from the same point, and any root-to-leaf path is one complete linear conversation. The core metaphor is git: `fork()` is `git branch`, `switchTo()` is `git checkout`, `getActivePath()` is `git log --first-parent`, and `prune()` is `git branch -D`.
+
+The package is a pure data structure with zero runtime dependencies and no network I/O. It manages the tree; the caller manages LLM interactions. Extract the active path with `getActivePath()`, send it to any LLM provider, and add the response back with `addMessage()`.
+
+## Installation
 
 ```bash
 npm install convo-tree
 ```
 
+Requires Node.js 18 or later.
+
 ## Quick Start
 
 ```typescript
-import { createConversationTree } from 'convo-tree'
+import { createConversationTree } from 'convo-tree';
+
+// Create a tree with an automatic system prompt root node
+const tree = createConversationTree({
+  systemPrompt: 'You are a helpful assistant.',
+});
+
+// Build a conversation by appending messages
+tree.addMessage('user', 'Hello!');
+tree.addMessage('assistant', 'Hi there! How can I help?');
+tree.addMessage('user', 'Tell me a joke.');
+tree.addMessage('assistant', 'Why did the chicken cross the road?');
+
+// Extract the active path as a flat message array for any LLM API
+const messages = tree.getActivePath();
+// [
+//   { role: 'system', content: 'You are a helpful assistant.' },
+//   { role: 'user', content: 'Hello!' },
+//   { role: 'assistant', content: 'Hi there! How can I help?' },
+//   { role: 'user', content: 'Tell me a joke.' },
+//   { role: 'assistant', content: 'Why did the chicken cross the road?' }
+// ]
+```
 
-const tree = createConversationTree({ systemPrompt: 'You are a helpful assistant.' })
+## Features
+
+- **Branching conversations** -- Fork at any point to explore alternative continuations. Multiple branches coexist in a single tree structure.
+- **HEAD tracking** -- A HEAD pointer tracks the current position. New messages append as children of HEAD, and HEAD advances automatically.
+- **Active path extraction** -- `getActivePath()` returns a flat `Message[]` from root to HEAD, ready to send to any LLM API.
+- **Undo/redo** -- Navigate backward and forward along the active path without losing history. Adding a new message after undo implicitly creates a new branch.
+- **Subtree pruning** -- Remove a node and all its descendants in one operation. HEAD relocates automatically if it falls within the pruned subtree.
+- **Branch labels** -- Assign human-readable labels to branches for organization (e.g., "creative approach", "model: GPT-4o").
+- **Node metadata** -- Attach arbitrary key-value data to any node (model name, temperature, latency, token count).
+- **Event system** -- Subscribe to `message`, `fork`, `switch`, and `prune` events for reactive UI updates and logging.
+- **Serialization** -- Export the full tree state as a JSON-serializable object for persistence and restoration.
+- **Zero dependencies** -- Pure data structure using only built-in Node.js APIs (`crypto.randomUUID`, `Date.now`).
+- **Full TypeScript support** -- Written in TypeScript with exported type declarations.
+
+## API Reference
+
+### `createConversationTree(options?)`
 
-tree.addMessage('user', 'Hello!')
-tree.addMessage('assistant', 'Hi there! How can I help?')
-tree.addMessage('user', 'Tell me a joke.')
-tree.addMessage('assistant', 'Why did the chicken cross the road?...')
+Factory function that creates and returns a `ConversationTree` instance.
 
-// Get the full active conversation as an array of messages
-const messages = tree.getActivePath()
-// [{ role: 'system', content: '...' }, { role: 'user', ... }, ...]
+```typescript
+import { createConversationTree } from 'convo-tree';
+
+const tree = createConversationTree({
+  systemPrompt: 'You are a helpful assistant.',
+  now: () => Date.now(),
+  generateId: () => crypto.randomUUID(),
+});
 ```
 
-## Branching
+#### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `systemPrompt` | `string` | `undefined` | If provided, a system-role node is created automatically as the root. |
+| `treeMeta` | `Record<string, unknown>` | `undefined` | Arbitrary metadata to associate with the tree itself. |
+| `now` | `() => number` | `Date.now` | Custom timestamp function used for `createdAt` on every new node. |
+| `generateId` | `() => string` | `crypto.randomUUID` | Custom ID generator for node IDs. |
+
+---
+
+### `tree.addMessage(role, content, metadata?)`
+
+Appends a new message node as a child of the current HEAD and advances HEAD to the new node. Clears the redo stack.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `role` | `'system' \| 'user' \| 'assistant' \| 'tool'` | The message role. |
+| `content` | `string` | The message content. |
+| `metadata` | `Record<string, unknown>` | Optional metadata to attach to the node. Defaults to `{}`. |
+
+**Returns:** `ConversationNode` -- the newly created node.
 
 ```typescript
-const tree = createConversationTree()
-const root = tree.addMessage('user', 'What is the capital of France?')
-const responseA = tree.addMessage('assistant', 'Paris.')
+const node = tree.addMessage('user', 'Hello!', { tokens: 3 });
+// node.id        -> unique UUID
+// node.role      -> 'user'
+// node.content   -> 'Hello!'
+// node.parentId  -> ID of the previous HEAD node (or null if first node)
+// node.children  -> []
+// node.metadata  -> { tokens: 3 }
+// node.createdAt -> timestamp from now()
+```
+
+When called on a node that already has children, the new message becomes a sibling, creating an implicit fork without requiring an explicit `fork()` call.
+
+---
+
+### `tree.fork(nodeId?, label?)`
 
-// Fork back to the user question and try a different assistant response
-tree.fork(root.id, 'alternate-response')
-tree.switchTo(root.id)
-const responseB = tree.addMessage('assistant', 'Paris is the capital of France.')
+Marks a fork point in the tree. Does not create a new node. If `nodeId` is provided, that node becomes the fork point; otherwise the current HEAD is used. Optionally assigns a branch label to the fork point node.
 
-// path A: root → responseA
-const pathA = tree.getPathTo(responseA.id)
-// path B: root → responseB
-const pathB = tree.getPathTo(responseB.id)
+**Parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `nodeId` | `string` | Optional. The node ID to fork from. Defaults to the current HEAD. |
+| `label` | `string` | Optional. A human-readable label to assign to the fork point node. |
+
+**Returns:** `Branch` -- an object with `forkPointId` and optional `label`.
+
+**Throws:** `InvalidOperationError` if the tree is empty. `NodeNotFoundError` if `nodeId` does not exist.
+
+```typescript
+const branch = tree.fork(someNode.id, 'alternate-response');
+// branch.forkPointId -> someNode.id
+// branch.label       -> 'alternate-response'
 ```
 
-## Undo / Redo
+After calling `fork()`, use `switchTo()` to move HEAD to the fork point, then call `addMessage()` to diverge from the original path.
+
+---
+
+### `tree.switchTo(nodeId)`
+
+Moves HEAD to any existing node in the tree, changing the active path to the root-to-node path.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `nodeId` | `string` | The ID of the node to switch to. |
+
+**Returns:** `void`
+
+**Throws:** `NodeNotFoundError` if the node does not exist.
+
+```typescript
+tree.switchTo(earlierNode.id);
+// HEAD is now at earlierNode
+// getActivePath() returns root -> ... -> earlierNode
+```
+
+---
+
+### `tree.getActivePath()`
+
+Returns the linear message array from root to the current HEAD. The returned array is suitable for direct use with any LLM chat completion API.
+
+**Returns:** `Message[]` -- an array of `{ role, content, ...metadata }` objects. Returns an empty array if the tree is empty.
 
 ```typescript
-const tree = createConversationTree()
-tree.addMessage('user', 'First message')
-tree.addMessage('assistant', 'Second message')
+const messages = tree.getActivePath();
+// messages[0].role    -> 'system' (if systemPrompt was set)
+// messages[0].content -> 'You are a helpful assistant.'
+```
+
+Metadata fields are spread into the message object. For example, if a node has `metadata: { tokens: 5 }`, the corresponding message will include `tokens: 5` alongside `role` and `content`.
+
+---
+
+### `tree.getPathTo(nodeId)`
+
+Returns the linear message array from root to the specified node, without changing HEAD.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `nodeId` | `string` | The ID of the target node. |
+
+**Returns:** `Message[]`
 
-tree.undo()  // head moves back to 'First message'
-tree.redo()  // head moves forward to 'Second message'
+**Throws:** `NodeNotFoundError` if the node does not exist.
+
+```typescript
+const pathA = tree.getPathTo(responseA.id);
+const pathB = tree.getPathTo(responseB.id);
+// Compare two branch paths without switching HEAD
 ```
 
-Adding a new message after an undo clears the redo stack.
+---
 
-## Prune
+### `tree.undo()`
+
+Moves HEAD to its parent node, pushing the current HEAD onto the redo stack. Returns the new HEAD node, or `null` if HEAD is already at the root or the tree is empty.
+
+**Returns:** `ConversationNode | null`
 
 ```typescript
-const tree = createConversationTree()
-const n1 = tree.addMessage('user', 'Root')
-const n2 = tree.addMessage('assistant', 'Child')
-tree.addMessage('user', 'Grandchild')
+tree.addMessage('user', 'First');
+tree.addMessage('assistant', 'Second');
+
+const previous = tree.undo();
+// previous.content -> 'First'
+// tree.getHead().content -> 'First'
+```
+
+---
+
+### `tree.redo()`
+
+Restores the most recently undone node by popping the redo stack and advancing HEAD. Returns the restored node, or `null` if the redo stack is empty or invalid.
 
-// Remove n2 and all its descendants (2 nodes total)
-const removed = tree.prune(n2.id) // returns 2
+The redo stack is validated: the node to redo must be a child of the current HEAD. If the tree structure has changed (e.g., via `addMessage()` or `prune()`), the redo stack is cleared.
+
+**Returns:** `ConversationNode | null`
+
+```typescript
+tree.undo();
+const restored = tree.redo();
+// HEAD is back at the node that was undone
 ```
 
-## Events
+Adding a new message after `undo()` clears the redo stack, creating an implicit new branch from the undo point.
+
+---
+
+### `tree.getHead()`
+
+Returns the current HEAD node, or `null` if the tree is empty.
+
+**Returns:** `ConversationNode | null`
 
 ```typescript
-const tree = createConversationTree()
+const head = tree.getHead();
+if (head) {
+  console.log(head.role, head.content);
+}
+```
 
-const unsub = tree.on('message', (node) => {
-  console.log('New message:', node.role, node.content)
-})
+---
+
+### `tree.getNode(nodeId)`
+
+Retrieves any node in the tree by its ID.
 
-tree.addMessage('user', 'Hello') // triggers the handler
+**Parameters:**
 
-unsub() // stop listening
+| Parameter | Type | Description |
+|---|---|---|
+| `nodeId` | `string` | The ID of the node to retrieve. |
+
+**Returns:** `ConversationNode | undefined`
+
+```typescript
+const node = tree.getNode('some-uuid');
+if (node) {
+  console.log(node.children.length, 'children');
+}
 ```
 
-Available events: `message`, `fork`, `switch`, `prune`.
+---
+
+### `tree.prune(nodeId)`
+
+Removes the specified node and all of its descendants from the tree. Updates the parent's `children` array. If HEAD falls within the pruned subtree, HEAD is moved to the pruned node's parent. If the root is pruned, the tree is fully cleared.
+
+**Parameters:**
 
-## Serialize / Restore
+| Parameter | Type | Description |
+|---|---|---|
+| `nodeId` | `string` | The ID of the node to prune. |
+
+**Returns:** `number` -- the count of nodes removed (including the target node and all descendants).
+
+**Throws:** `NodeNotFoundError` if the node does not exist.
 
 ```typescript
-const state = tree.serialize()
-// { version: 1, nodes: {...}, rootId: '...', headId: '...', redoStack: [...] }
+const n1 = tree.addMessage('user', 'Root');
+const n2 = tree.addMessage('assistant', 'Child');
+tree.addMessage('user', 'Grandchild');
 
-// Store or transmit `state`, then reconstruct:
-const newTree = createConversationTree()
-// Replay messages from state.nodes in createdAt order to restore
+const removed = tree.prune(n2.id);
+// removed -> 2 (Child + Grandchild)
+// HEAD automatically moves to n1
 ```
 
-## API
+Entries in the redo stack that reference pruned nodes are also removed.
 
-### `createConversationTree(options?)`
+---
+
+### `tree.setLabel(nodeId, label)`
+
+Sets or updates the branch label on a node.
+
+**Parameters:**
 
-| Option | Type | Description |
+| Parameter | Type | Description |
 |---|---|---|
-| `systemPrompt` | `string` | Optional system message added as the root node |
-| `now` | `() => number` | Custom timestamp function (default: `Date.now`) |
-| `generateId` | `() => string` | Custom ID generator (default: `randomUUID`) |
+| `nodeId` | `string` | The ID of the node to label. |
+| `label` | `string` | The label to assign. |
+
+**Returns:** `void`
+
+**Throws:** `NodeNotFoundError` if the node does not exist.
+
+```typescript
+tree.setLabel(node.id, 'creative-approach');
+// tree.getNode(node.id).branchLabel -> 'creative-approach'
+```
+
+---
+
+### `tree.clear()`
+
+Resets the tree to an empty state. All nodes, the root, HEAD, and the redo stack are cleared.
+
+**Returns:** `void`
+
+```typescript
+tree.clear();
+// tree.nodeCount -> 0
+// tree.getHead() -> null
+// tree.getActivePath() -> []
+```
+
+---
+
+### `tree.serialize()`
+
+Exports the full tree state as a plain JSON-serializable object.
+
+**Returns:** `TreeState`
+
+```typescript
+const state = tree.serialize();
+// {
+//   version: 1,
+//   nodes: { 'uuid-1': { ... }, 'uuid-2': { ... } },
+//   rootId: 'uuid-1',
+//   headId: 'uuid-2',
+//   redoStack: []
+// }
+
+// Persist to disk, database, or transmit over the network
+const json = JSON.stringify(state);
+```
+
+---
+
+### `tree.nodeCount`
+
+A readonly property returning the total number of nodes in the tree.
+
+**Type:** `number`
+
+```typescript
+console.log(tree.nodeCount); // 5
+```
+
+---
+
+### `tree.on(event, handler)`
 
-### Methods
+Subscribes to tree events. Returns an unsubscribe function.
 
-| Method | Returns | Description |
+**Parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `event` | `string` | The event name: `'message'`, `'fork'`, `'switch'`, or `'prune'`. |
+| `handler` | `Function` | The callback invoked when the event fires. |
+
+**Returns:** `() => void` -- call this function to unsubscribe.
+
+#### Events
+
+| Event | Payload | Fires when |
 |---|---|---|
-| `addMessage(role, content, metadata?)` | `ConversationNode` | Append a message to the current head |
-| `fork(nodeId?, label?)` | `Branch` | Mark a fork point (defaults to current head) |
-| `switchTo(nodeId)` | `void` | Move head to any existing node |
-| `getActivePath()` | `Message[]` | Messages from root to current head |
-| `getPathTo(nodeId)` | `Message[]` | Messages from root to the specified node |
-| `undo()` | `ConversationNode \| null` | Move head to parent |
-| `redo()` | `ConversationNode \| null` | Re-apply the last undone message |
-| `getHead()` | `ConversationNode \| null` | Current head node |
-| `getNode(nodeId)` | `ConversationNode \| undefined` | Retrieve any node by ID |
-| `prune(nodeId)` | `number` | Remove a node and all descendants; returns count |
-| `setLabel(nodeId, label)` | `void` | Set a branch label on a node |
-| `clear()` | `void` | Reset the tree to empty state |
-| `serialize()` | `TreeState` | Export full tree state |
-| `on(event, handler)` | `() => void` | Subscribe to events; returns unsubscribe fn |
-| `nodeCount` | `number` | Total number of nodes in the tree |
+| `message` | `ConversationNode` | `addMessage()` creates a new node. |
+| `fork` | `Branch` | `fork()` is called. |
+| `switch` | `string` (nodeId) | `switchTo()` moves HEAD. |
+| `prune` | `{ nodeId: string, count: number }` | `prune()` removes nodes. |
+
+```typescript
+const unsub = tree.on('message', (node) => {
+  console.log('New message:', node.role, node.content);
+});
+
+tree.addMessage('user', 'Hello'); // triggers handler
+
+unsub(); // stop listening
+tree.addMessage('user', 'World'); // handler is NOT called
+```
+
+## Types
+
+All types are exported from the package entry point.
+
+```typescript
+import type {
+  ConversationNode,
+  ConversationTree,
+  ConversationTreeOptions,
+  Branch,
+  Message,
+  TreeState,
+} from 'convo-tree';
+```
+
+### `ConversationNode`
+
+```typescript
+interface ConversationNode {
+  id: string;
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  parentId: string | null;
+  children: string[];
+  createdAt: number;
+  metadata: Record<string, unknown>;
+  branchLabel?: string;
+}
+```
+
+### `Branch`
+
+```typescript
+interface Branch {
+  forkPointId: string;
+  label?: string;
+}
+```
+
+### `Message`
+
+```typescript
+interface Message {
+  role: string;
+  content: string;
+  [k: string]: unknown;
+}
+```
+
+### `TreeState`
+
+```typescript
+interface TreeState {
+  nodes: Record<string, ConversationNode>;
+  rootId: string | null;
+  headId: string | null;
+  redoStack: string[];
+  version: 1;
+}
+```
+
+### `ConversationTreeOptions`
+
+```typescript
+interface ConversationTreeOptions {
+  systemPrompt?: string;
+  treeMeta?: Record<string, unknown>;
+  now?: () => number;
+  generateId?: () => string;
+}
+```
+
+## Configuration
+
+### Custom ID Generator
+
+Supply a deterministic ID generator for reproducible tests or when UUIDs are not desired.
+
+```typescript
+let counter = 0;
+const tree = createConversationTree({
+  generateId: () => `msg-${++counter}`,
+});
+
+const n1 = tree.addMessage('user', 'Hello');
+// n1.id -> 'msg-1'
+```
+
+### Custom Timestamp
+
+Supply a custom clock for deterministic timestamps in tests or when using a different time source.
+
+```typescript
+const tree = createConversationTree({
+  now: () => 1700000000000,
+});
+
+const node = tree.addMessage('user', 'Hello');
+// node.createdAt -> 1700000000000
+```
+
+## Error Handling
+
+`convo-tree` exports three error classes, all extending from `ConvoTreeError`.
+
+```typescript
+import {
+  ConvoTreeError,
+  NodeNotFoundError,
+  InvalidOperationError,
+} from 'convo-tree';
+```
+
+### `ConvoTreeError`
+
+Base error class. Has a `code` property (string) for programmatic error handling.
+
+```typescript
+try {
+  tree.switchTo('nonexistent');
+} catch (err) {
+  if (err instanceof ConvoTreeError) {
+    console.log(err.code); // 'NODE_NOT_FOUND'
+  }
+}
+```
+
+### `NodeNotFoundError`
+
+Thrown when an operation references a node ID that does not exist in the tree. Has a `nodeId` property indicating which ID was not found.
+
+- **Code:** `'NODE_NOT_FOUND'`
+- **Thrown by:** `switchTo()`, `getPathTo()`, `prune()`, `setLabel()`, `fork()` (when `nodeId` is provided)
+
+```typescript
+try {
+  tree.getPathTo('does-not-exist');
+} catch (err) {
+  if (err instanceof NodeNotFoundError) {
+    console.log(err.nodeId); // 'does-not-exist'
+  }
+}
+```
+
+### `InvalidOperationError`
+
+Thrown when an operation is structurally invalid given the current tree state.
+
+- **Code:** `'INVALID_OPERATION'`
+- **Thrown by:** `fork()` when called on an empty tree
+
+```typescript
+const emptyTree = createConversationTree();
+try {
+  emptyTree.fork();
+} catch (err) {
+  if (err instanceof InvalidOperationError) {
+    console.log(err.message); // 'Cannot fork an empty tree'
+  }
+}
+```
+
+## Advanced Usage
+
+### Branching Conversations
+
+Fork at any point to explore alternative continuations, then switch between branches.
+
+```typescript
+const tree = createConversationTree();
+const question = tree.addMessage('user', 'What is the capital of France?');
+const responseA = tree.addMessage('assistant', 'Paris.');
+
+// Fork back to the question and try a different response
+tree.fork(question.id, 'detailed-response');
+tree.switchTo(question.id);
+const responseB = tree.addMessage('assistant', 'The capital of France is Paris.');
+
+// Extract each branch independently
+const pathA = tree.getPathTo(responseA.id);
+// [{ role: 'user', content: 'What is the capital of France?' },
+//  { role: 'assistant', content: 'Paris.' }]
+
+const pathB = tree.getPathTo(responseB.id);
+// [{ role: 'user', content: 'What is the capital of France?' },
+//  { role: 'assistant', content: 'The capital of France is Paris.' }]
+```
+
+### Undo/Redo with Implicit Branching
+
+Calling `addMessage()` after `undo()` creates a new branch from the undo point and clears the redo stack.
+
+```typescript
+const tree = createConversationTree();
+tree.addMessage('user', 'First');
+tree.addMessage('assistant', 'Second');
+tree.addMessage('user', 'Third');
+
+tree.undo(); // HEAD at 'Second'
+tree.undo(); // HEAD at 'First'
+
+// New message creates a branch from 'First'
+tree.addMessage('assistant', 'Alternative second');
+// redo() now returns null -- redo stack was cleared
+```
+
+### Serialization and Persistence
+
+Serialize the tree for storage and reconstruct later.
+
+```typescript
+// Save
+const state = tree.serialize();
+const json = JSON.stringify(state);
+fs.writeFileSync('conversation.json', json);
+
+// Load
+const loaded = JSON.parse(fs.readFileSync('conversation.json', 'utf-8'));
+// Reconstruct by creating a new tree and replaying messages
+// from loaded.nodes in createdAt order
+```
+
+### Event-Driven Updates
+
+Use the event system for reactive UI updates, logging, or analytics.
+
+```typescript
+const tree = createConversationTree();
+
+// Log all new messages
+tree.on('message', (node) => {
+  console.log(`[${node.role}] ${node.content}`);
+});
+
+// Track branch creation
+tree.on('fork', (branch) => {
+  console.log(`Forked at ${branch.forkPointId}: ${branch.label ?? 'unlabeled'}`);
+});
+
+// Monitor pruning
+tree.on('prune', ({ nodeId, count }) => {
+  console.log(`Pruned ${count} nodes starting from ${nodeId}`);
+});
+
+// React to navigation
+tree.on('switch', (nodeId) => {
+  console.log(`Switched HEAD to ${nodeId}`);
+});
+```
+
+### Attaching Metadata
+
+Store per-message provenance data such as model, latency, and token counts.
+
+```typescript
+const node = tree.addMessage('assistant', 'Hello!', {
+  model: 'gpt-4o',
+  temperature: 0.7,
+  latencyMs: 450,
+  promptTokens: 128,
+  completionTokens: 12,
+});
+
+// Metadata is included in getActivePath() output
+const messages = tree.getActivePath();
+// Last message: { role: 'assistant', content: 'Hello!',
+//   model: 'gpt-4o', temperature: 0.7, latencyMs: 450, ... }
+```
+
+### Prompt A/B Testing
+
+Fork at the same point to compare responses from different models or prompt configurations.
+
+```typescript
+const tree = createConversationTree({
+  systemPrompt: 'You are a writing assistant.',
+});
+
+const prompt = tree.addMessage('user', 'Write a haiku about rain.');
+const responseA = tree.addMessage('assistant', 'Gentle drops descend...');
+
+// Fork for a second attempt
+tree.fork(prompt.id, 'attempt-2');
+tree.switchTo(prompt.id);
+const responseB = tree.addMessage('assistant', 'Silver threads of rain...');
+
+// Fork for a third attempt
+tree.fork(prompt.id, 'attempt-3');
+tree.switchTo(prompt.id);
+const responseC = tree.addMessage('assistant', 'Clouds weep softly now...');
+
+// Compare all three paths
+const paths = [responseA, responseB, responseC].map((r) =>
+  tree.getPathTo(r.id)
+);
+```
+
+## TypeScript
+
+`convo-tree` is written in TypeScript and ships type declarations alongside the compiled JavaScript. All public types are exported from the package entry point.
+
+```typescript
+import { createConversationTree } from 'convo-tree';
+import type {
+  ConversationNode,
+  ConversationTree,
+  ConversationTreeOptions,
+  Branch,
+  Message,
+  TreeState,
+} from 'convo-tree';
+```
+
+The `ConversationTree` interface defines the full shape of the tree object returned by `createConversationTree()`. Use it for explicit typing when passing tree instances between functions.
+
+```typescript
+function analyzeTree(tree: ConversationTree): void {
+  const path = tree.getActivePath();
+  const head = tree.getHead();
+  console.log(`${tree.nodeCount} nodes, head at ${head?.id ?? 'empty'}`);
+}
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convo-tree",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Tree-structured conversation state manager for branching chats",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",