@dremio/js-sdk 0.45.3 → 0.45.4

package/README.md

@@ -510,6 +510,63 @@ type ChatEventWithChunkType<T extends ChatEvent["content"]["chunkType"]> =
   Extract<ChatEvent, { content: { chunkType: T } }>;
 ```
 
+#### UI Rendering and React Reconciliation
+
+The conversation snapshot produced by the reducer (and automatically managed by the `AgentConversationMachine`) is designed specifically for modern declarative UIs like React, Vue, Svelte, or Ink.
+
+**You do not need to manually track message IDs, buffer stream chunks, or manage parallel tool call states.**
+
+The reducer performs highly optimized, **immutable updates** as new events arrive. Because the top-level references change only when the underlying data changes, you can directly map over the snapshot in your render function. It is safe to pass these objects into memoized components (e.g., `React.memo`) without writing complex deep-equality checks or manual diffing logic.
+
+**React Example:**
+
+```typescript
+import { createActor } from "xstate";
+import { UserChatMessage } from "@dremio/js-sdk/enterprise/ai";
+
+const actor = createActor(conversationMachine, {
+  input: { conversationId: null },
+});
+
+// Subscribe to state changes and update React state
+actor.subscribe((snapshot) => {
+  setExchanges(snapshot.context.conversationSnapshot ?? []);
+});
+
+actor.start();
+
+// In your render function - direct mapping, no manual diffing needed
+return (
+  <div>
+    {exchanges.map((exchange) => (
+      <Exchange key={exchange.id} exchange={exchange} />
+    ))}
+  </div>
+);
+```
+
+**Why this works:**
+
+- The reducer uses **structural sharing** via the `mutative` library, creating new object references only for changed data
+- Unchanged exchanges and messages retain their original references, enabling efficient React reconciliation
+- Maps preserve insertion order and provide O(1) lookups by ID
+- Tool calls are automatically paired and their state is derived, eliminating manual tracking logic
+
+**Vue/Svelte Example:**
+
+```typescript
+// The same principle applies - just bind to the snapshot
+actor.subscribe((snapshot) => {
+  conversationSnapshot = snapshot.context.conversationSnapshot ?? [];
+});
+```
+
+```svelte
+{#each conversationSnapshot as exchange (exchange.id)}
+  <Exchange {exchange} />
+{/each}
+```
+
 #### Incremental Updates
 
 The reducer is a pure function with signature `(snapshot, events) => newSnapshot`. You can incrementally update a snapshot as new events arrive:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dremio/js-sdk",
-  "version": "0.45.3",
+  "version": "0.45.4",
   "description": "JavaScript library for the Dremio API",
   "keywords": [
     "dremio",