docs: fix flattenNodes return type and simplify code examples

Update docs to reflect that flattenNodes() returns
ConversationNode<TMessage>[], not TMessage[]. Simplify code examples
to iterate getMessagesWithHeaders() directly instead of constructing
a Map.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mschristensen

docs/features/branching.md

@@ -74,10 +74,11 @@ const tree = useConversationTree(transport);
 // tree.getSelectedIndex(nodeId) - which sibling is currently selected
 // tree.selectSibling(nodeId, index) - switch to a different sibling
 //
-// nodeId is the x-ably-msg-id for each message - resolve it from headers:
-//   const allWithHeaders = transport.getMessagesWithHeaders();
-//   const headers = allWithHeaders.find((entry) => entry.message === msg)?.headers;
-//   const nodeId = headers?.['x-ably-msg-id'] ?? msg.id;
+// nodeId is the x-ably-msg-id for each message - iterate getMessagesWithHeaders()
+// to get messages paired with their headers:
+//   transport.getMessagesWithHeaders().map(({ message: msg, headers }) => {
+//     const nodeId = headers?.['x-ably-msg-id'] ?? msg.id;
+//   });
 ```
 
 Build a sibling navigator (where `nodeId` is the resolved `x-ably-msg-id` for the message):

docs/get-started/vercel-use-client-transport.md

@@ -31,9 +31,7 @@ import { useState } from 'react';
 
 // Resolve the x-ably-msg-id for a message. Tree methods and regenerate/edit
 // use x-ably-msg-id as the key, not UIMessage.id.
-// Build a headers lookup once, then resolve per message.
-function treeMsgId(msg: UIMessage, headersByMessage: Map<UIMessage, Record<string, string> | undefined>): string {
-  const headers = headersByMessage.get(msg);
+function treeMsgId(headers: Record<string, string> | undefined, msg: UIMessage): string {
   return headers?.['x-ably-msg-id'] ?? msg.id;
 }
 
@@ -60,10 +58,7 @@ function ChatInner({ chatId, clientId }: { chatId: string; clientId?: string })
 
   const isStreaming = activeTurns.size > 0;
 
-  // Build a lookup map from message to headers once per render.
-  const headersByMessage = new Map(
-    transport.getMessagesWithHeaders().map((entry) => [entry.message, entry.headers]),
-  );
+  const messagesWithHeaders = transport.getMessagesWithHeaders();
 
   const handleSend = () => {
     const text = input.trim();
@@ -88,9 +83,9 @@ function ChatInner({ chatId, clientId }: { chatId: string; clientId?: string })
         </button>
       )}
 
-      {/* Message list from the conversation tree */}
-      {tree.messages.map((msg) => {
-        const nodeId = treeMsgId(msg, headersByMessage);
+      {/* Message list with headers for tree navigation */}
+      {messagesWithHeaders.map(({ message: msg, headers }) => {
+        const nodeId = treeMsgId(headers, msg);
         return (
           <div key={msg.id}>
             <strong>{msg.role}:</strong>

docs/internals/client-transport.md

@@ -8,7 +8,7 @@ The client never publishes domain messages directly to the channel. Instead, it
 
 ```
 DefaultClientTransport
-├── ConversationTree       - branching message history (flatten → getMessages)
+├── ConversationTree       - branching message history (flattenNodes → getMessages)
 ├── StreamRouter           - maps turn events to per-turn ReadableStreams
 ├── StreamDecoder          - decodes inbound Ably messages to events/messages
 ├── EventEmitter           - typed event bus for message/turn/error/ably-message

docs/internals/glossary.md

@@ -118,7 +118,7 @@ A codec-provided component that assembles [decoder outputs](decoder.md#decoder-o
 
 ### Message materialization
 
-The act of producing a flat `TMessage[]` from the [conversation tree](conversation-tree.md) via [`flattenNodes()`](#flatten). Every call rebuilds from scratch - there is no cached list - because the result depends on branch selection state. All consumers go through `getMessages()`, which delegates to `flattenNodes()`: React hooks, `send()` (for the HTTP POST body), `history()` (for pagination snapshots). See [Message lifecycle](message-lifecycle.md#why-no-cached-message-list).
+The act of producing a flat message list from the [conversation tree](conversation-tree.md) via [`flattenNodes()`](#flatten). `flattenNodes()` returns `ConversationNode<TMessage>[]` - the transport's `getMessages()` extracts `.message` from each node to produce the public `TMessage[]`. Every call rebuilds from scratch - there is no cached list - because the result depends on branch selection state. All consumers go through `getMessages()`, which delegates to `flattenNodes()`: React hooks, `send()` (for the HTTP POST body), `history()` (for pagination snapshots). See [Message lifecycle](message-lifecycle.md#why-no-cached-message-list).
 
 ### Flatten
 

docs/internals/message-lifecycle.md

@@ -88,7 +88,7 @@ When the decoder produces a `{ kind: 'message' }` output (e.g. a user message de
 
 ## How messages reach the UI
 
-The [conversation tree's](conversation-tree.md#flatten-producing-the-linear-path) `flattenNodes()` method is the sole path from tree state to a message array. It walks the sorted node list, checks parent reachability and sibling selection, and returns the linear `TMessage[]` for the currently selected conversation path.
+The [conversation tree's](conversation-tree.md#flatten-producing-the-linear-path) `flattenNodes()` method is the sole path from tree state to a message array. It walks the sorted node list, checks parent reachability and sibling selection, and returns `ConversationNode<TMessage>[]` for the currently selected conversation path. `ClientTransport.getMessages()` extracts the `.message` from each node to produce the public `TMessage[]`.
 
 `ClientTransport.getMessages()` calls `flattenNodes()` and filters out any messages withheld by the history pagination buffer. This is the public API that all downstream consumers call.