@assistant-ui/react 0.14.15 → 0.14.18

package/dist/utils/smooth/useSmooth.js

@@ -5,12 +5,17 @@ import { useAui, useAuiState } from "@assistant-ui/store";
 import { useEffect, useMemo, useRef, useState } from "@assistant-ui/tap/react-shim";
 import { useCallbackRef } from "@radix-ui/react-use-callback-ref";
 //#region src/utils/smooth/useSmooth.ts
+const DEFAULT_DRAIN_MS = 250;
+const DEFAULT_MAX_CHAR_INTERVAL_MS = 5;
 var TextStreamAnimator = class {
 	currentText;
 	setText;
 	animationFrameId = null;
 	lastUpdateTime = Date.now();
 	targetText = "";
+	drainMs = DEFAULT_DRAIN_MS;
+	maxCharIntervalMs = DEFAULT_MAX_CHAR_INTERVAL_MS;
+	maxCharsPerFrame = Infinity;
 	constructor(currentText, setText) {
 		this.currentText = currentText;
 		this.setText = setText;
@@ -30,12 +35,14 @@ var TextStreamAnimator = class {
 		const currentTime = Date.now();
 		let timeToConsume = currentTime - this.lastUpdateTime;
 		const remainingChars = this.targetText.length - this.currentText.length;
-		const baseTimePerChar = Math.min(5, 250 / remainingChars);
+		const baseTimePerChar = Math.min(this.maxCharIntervalMs, this.drainMs / remainingChars);
+		const frameLimit = Math.min(remainingChars, this.maxCharsPerFrame);
 		let charsToAdd = 0;
-		while (timeToConsume >= baseTimePerChar && charsToAdd < remainingChars) {
+		while (timeToConsume >= baseTimePerChar && charsToAdd < frameLimit) {
 			charsToAdd++;
 			timeToConsume -= baseTimePerChar;
 		}
+		if (charsToAdd === frameLimit && frameLimit === this.maxCharsPerFrame) timeToConsume = 0;
 		if (charsToAdd !== remainingChars) this.animationFrameId = requestAnimationFrame(this.animate);
 		else this.animationFrameId = null;
 		if (charsToAdd === 0) return;
@@ -45,8 +52,30 @@ var TextStreamAnimator = class {
 	};
 };
 const SMOOTH_STATUS = Object.freeze({ type: "running" });
+const positiveOr = (value, fallback) => value !== void 0 && value > 0 ? value : fallback;
+/**
+* Animates streamed message part text with a typewriter-style reveal.
+*
+* Takes the current part state and a `smooth` argument: `false` disables,
+* `true` uses the default rate, and a {@link SmoothOptions} object tunes
+* the reveal. Returns the part state with `text` replaced by the revealed
+* prefix and `status` reporting `running` until the reveal catches up.
+*
+* @example
+* ```tsx
+* const { text, status } = useSmooth(useMessagePartText(), {
+*   drainMs: 500,
+*   maxCharsPerFrame: 30,
+* });
+* ```
+*/
 const useSmooth = (state, smooth = false) => {
 	const { text } = state;
+	const options = typeof smooth === "object" && smooth !== null ? smooth : void 0;
+	const enabled = smooth !== false && smooth !== null;
+	const drainMs = positiveOr(options?.drainMs, DEFAULT_DRAIN_MS);
+	const maxCharIntervalMs = positiveOr(options?.maxCharIntervalMs, DEFAULT_MAX_CHAR_INTERVAL_MS);
+	const maxCharsPerFrame = positiveOr(options?.maxCharsPerFrame, Infinity);
 	const [displayedText, setDisplayedText] = useState(state.status.type === "running" ? "" : text);
 	const aui = useAui();
 	const part = useAuiState(() => aui.part());
@@ -65,20 +94,30 @@ const useSmooth = (state, smooth = false) => {
 	});
 	useEffect(() => {
 		if (smoothStatusStore) {
-			const target = smooth && (displayedText !== text || state.status.type === "running") ? SMOOTH_STATUS : state.status;
+			const target = enabled && (displayedText !== text || state.status.type === "running") ? SMOOTH_STATUS : state.status;
 			writableStore(smoothStatusStore).setState(target, true);
 		}
 	}, [
 		smoothStatusStore,
-		smooth,
+		enabled,
 		text,
 		displayedText,
 		state.status
 	]);
 	const [animatorRef] = useState(new TextStreamAnimator(displayedText, setText));
+	useEffect(() => {
+		animatorRef.drainMs = drainMs;
+		animatorRef.maxCharIntervalMs = maxCharIntervalMs;
+		animatorRef.maxCharsPerFrame = maxCharsPerFrame;
+	}, [
+		animatorRef,
+		drainMs,
+		maxCharIntervalMs,
+		maxCharsPerFrame
+	]);
 	const animatorPartRef = useRef(part);
 	useEffect(() => {
-		if (!smooth) {
+		if (!enabled) {
 			animatorRef.stop();
 			return;
 		}
@@ -100,7 +139,7 @@ const useSmooth = (state, smooth = false) => {
 		animatorRef.start();
 	}, [
 		animatorRef,
-		smooth,
+		enabled,
 		text,
 		state.status.type,
 		part
@@ -110,12 +149,12 @@ const useSmooth = (state, smooth = false) => {
 			animatorRef.stop();
 		};
 	}, [animatorRef]);
-	return useMemo(() => smooth ? {
-		type: "text",
+	return useMemo(() => enabled ? {
+		...state,
 		text: displayedText,
 		status: text === displayedText ? state.status : SMOOTH_STATUS
 	} : state, [
-		smooth,
+		enabled,
 		displayedText,
 		state,
 		text

package/dist/utils/smooth/useSmooth.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSmooth.js","names":[],"sources":["../../../src/utils/smooth/useSmooth.ts"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useMemo, useRef, useState } from \"react\";\nimport { useAui, useAuiState } from \"@assistant-ui/store\";\nimport type {\n  MessagePartStatus,\n  ReasoningMessagePart,\n  TextMessagePart,\n  MessagePartState,\n} from \"@assistant-ui/core\";\nimport { useCallbackRef } from \"@radix-ui/react-use-callback-ref\";\nimport { useSmoothStatusStore } from \"./SmoothContext\";\nimport { writableStore } from \"../../context/ReadonlyStore\";\n\nclass TextStreamAnimator {\n  private animationFrameId: number | null = null;\n  private lastUpdateTime: number = Date.now();\n\n  public targetText: string = \"\";\n\n  constructor(\n    public currentText: string,\n    private setText: (newText: string) => void,\n  ) {}\n\n  start() {\n    if (this.animationFrameId !== null) return;\n    this.lastUpdateTime = Date.now();\n    this.animate();\n  }\n\n  stop() {\n    if (this.animationFrameId !== null) {\n      cancelAnimationFrame(this.animationFrameId);\n      this.animationFrameId = null;\n    }\n  }\n\n  private animate = () => {\n    const currentTime = Date.now();\n    const deltaTime = currentTime - this.lastUpdateTime;\n    let timeToConsume = deltaTime;\n\n    const remainingChars = this.targetText.length - this.currentText.length;\n    const baseTimePerChar = Math.min(5, 250 / remainingChars);\n\n    let charsToAdd = 0;\n    while (timeToConsume >= baseTimePerChar && charsToAdd < remainingChars) {\n      charsToAdd++;\n      timeToConsume -= baseTimePerChar;\n    }\n\n    if (charsToAdd !== remainingChars) {\n      this.animationFrameId = requestAnimationFrame(this.animate);\n    } else {\n      this.animationFrameId = null;\n    }\n    if (charsToAdd === 0) return;\n\n    this.currentText = this.targetText.slice(\n      0,\n      this.currentText.length + charsToAdd,\n    );\n    this.lastUpdateTime = currentTime - timeToConsume;\n    this.setText(this.currentText);\n  };\n}\n\nconst SMOOTH_STATUS: MessagePartStatus = Object.freeze({\n  type: \"running\",\n});\n\nexport const useSmooth = (\n  state: MessagePartState & (TextMessagePart | ReasoningMessagePart),\n  smooth: boolean = false,\n): MessagePartState & (TextMessagePart | ReasoningMessagePart) => {\n  const { text } = state;\n\n  const [displayedText, setDisplayedText] = useState(\n    state.status.type === \"running\" ? \"\" : text,\n  );\n\n  // Render-phase resync on part flip or text discontinuity, so the\n  // first paint after a thread switch never shows the previous\n  // part's text (#4051). `displayedText` is already a prefix of\n  // `text` during normal streaming, so use it as the previous-text\n  // reference instead of carrying separate state — avoids the\n  // double render per streaming token. Read part identity through\n  // `useAuiState` so we actually subscribe to its changes instead\n  // of relying on a render-time proxy reference that may be stable\n  // across thread swaps.\n  const aui = useAui();\n  const part = useAuiState(() => aui.part());\n  const [prevPart, setPrevPart] = useState(part);\n  if (part !== prevPart || !text.startsWith(displayedText)) {\n    setPrevPart(part);\n    setDisplayedText(state.status.type === \"running\" ? \"\" : text);\n  }\n\n  const smoothStatusStore = useSmoothStatusStore({ optional: true });\n  const setText = useCallbackRef((text: string) => {\n    setDisplayedText(text);\n    if (smoothStatusStore) {\n      const target =\n        displayedText !== text || state.status.type === \"running\"\n          ? SMOOTH_STATUS\n          : state.status;\n      writableStore(smoothStatusStore).setState(target, true);\n    }\n  });\n\n  // TODO this is hacky\n  useEffect(() => {\n    if (smoothStatusStore) {\n      const target =\n        smooth && (displayedText !== text || state.status.type === \"running\")\n          ? SMOOTH_STATUS\n          : state.status;\n      writableStore(smoothStatusStore).setState(target, true);\n    }\n  }, [smoothStatusStore, smooth, text, displayedText, state.status]);\n\n  const [animatorRef] = useState<TextStreamAnimator>(\n    new TextStreamAnimator(displayedText, setText),\n  );\n\n  const animatorPartRef = useRef(part);\n  useEffect(() => {\n    if (!smooth) {\n      animatorRef.stop();\n      return;\n    }\n\n    // Discontinuity: part flipped, or new text breaks continuation\n    // of the animator's current target. Either case requires\n    // resetting the cursor — without the part check, a new part\n    // whose text happens to share a prefix with the previous target\n    // would keep the stale cursor and flicker.\n    const partChanged = animatorPartRef.current !== part;\n    animatorPartRef.current = part;\n    if (partChanged || !text.startsWith(animatorRef.targetText)) {\n      if (state.status.type === \"running\") {\n        animatorRef.currentText = \"\";\n        animatorRef.targetText = text;\n        animatorRef.start();\n      } else {\n        animatorRef.currentText = text;\n        animatorRef.targetText = text;\n        animatorRef.stop();\n      }\n      return;\n    }\n\n    animatorRef.targetText = text;\n    animatorRef.start();\n  }, [animatorRef, smooth, text, state.status.type, part]);\n\n  useEffect(() => {\n    return () => {\n      animatorRef.stop();\n    };\n  }, [animatorRef]);\n\n  return useMemo(\n    () =>\n      smooth\n        ? {\n            type: \"text\",\n            text: displayedText,\n            status: text === displayedText ? state.status : SMOOTH_STATUS,\n          }\n        : state,\n    [smooth, displayedText, state, text],\n  );\n};\n"],"mappings":"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"}
+{"version":3,"file":"useSmooth.js","names":[],"sources":["../../../src/utils/smooth/useSmooth.ts"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useMemo, useRef, useState } from \"react\";\nimport { useAui, useAuiState } from \"@assistant-ui/store\";\nimport type {\n  MessagePartStatus,\n  ReasoningMessagePart,\n  TextMessagePart,\n  MessagePartState,\n} from \"@assistant-ui/core\";\nimport { useCallbackRef } from \"@radix-ui/react-use-callback-ref\";\nimport { useSmoothStatusStore } from \"./SmoothContext\";\nimport { writableStore } from \"../../context/ReadonlyStore\";\n\n/**\n * Tuning options for the smooth text streaming animation.\n */\nexport type SmoothOptions = {\n  /**\n   * Target time in milliseconds to drain the backlog of unrevealed\n   * characters. Larger values reveal long backlogs more gradually.\n   * @default 250\n   */\n  drainMs?: number | undefined;\n  /**\n   * Maximum time in milliseconds between revealed characters, i.e. the\n   * slowest reveal rate when the backlog is short.\n   * @default 5\n   */\n  maxCharIntervalMs?: number | undefined;\n  /**\n   * Maximum number of characters revealed per animation frame.\n   * @default Infinity\n   */\n  maxCharsPerFrame?: number | undefined;\n};\n\nconst DEFAULT_DRAIN_MS = 250;\nconst DEFAULT_MAX_CHAR_INTERVAL_MS = 5;\n\nclass TextStreamAnimator {\n  private animationFrameId: number | null = null;\n  private lastUpdateTime: number = Date.now();\n\n  public targetText: string = \"\";\n  public drainMs: number = DEFAULT_DRAIN_MS;\n  public maxCharIntervalMs: number = DEFAULT_MAX_CHAR_INTERVAL_MS;\n  public maxCharsPerFrame: number = Infinity;\n\n  constructor(\n    public currentText: string,\n    private setText: (newText: string) => void,\n  ) {}\n\n  start() {\n    if (this.animationFrameId !== null) return;\n    this.lastUpdateTime = Date.now();\n    this.animate();\n  }\n\n  stop() {\n    if (this.animationFrameId !== null) {\n      cancelAnimationFrame(this.animationFrameId);\n      this.animationFrameId = null;\n    }\n  }\n\n  private animate = () => {\n    const currentTime = Date.now();\n    const deltaTime = currentTime - this.lastUpdateTime;\n    let timeToConsume = deltaTime;\n\n    const remainingChars = this.targetText.length - this.currentText.length;\n    const baseTimePerChar = Math.min(\n      this.maxCharIntervalMs,\n      this.drainMs / remainingChars,\n    );\n\n    const frameLimit = Math.min(remainingChars, this.maxCharsPerFrame);\n    let charsToAdd = 0;\n    while (timeToConsume >= baseTimePerChar && charsToAdd < frameLimit) {\n      charsToAdd++;\n      timeToConsume -= baseTimePerChar;\n    }\n    // A cap-limited frame must not bank its surplus time, or the next\n    // frame would burst past the cap.\n    if (charsToAdd === frameLimit && frameLimit === this.maxCharsPerFrame) {\n      timeToConsume = 0;\n    }\n\n    if (charsToAdd !== remainingChars) {\n      this.animationFrameId = requestAnimationFrame(this.animate);\n    } else {\n      this.animationFrameId = null;\n    }\n    if (charsToAdd === 0) return;\n\n    this.currentText = this.targetText.slice(\n      0,\n      this.currentText.length + charsToAdd,\n    );\n    this.lastUpdateTime = currentTime - timeToConsume;\n    this.setText(this.currentText);\n  };\n}\n\nconst SMOOTH_STATUS: MessagePartStatus = Object.freeze({\n  type: \"running\",\n});\n\nconst positiveOr = (value: number | undefined, fallback: number): number =>\n  value !== undefined && value > 0 ? value : fallback;\n\n/**\n * Animates streamed message part text with a typewriter-style reveal.\n *\n * Takes the current part state and a `smooth` argument: `false` disables,\n * `true` uses the default rate, and a {@link SmoothOptions} object tunes\n * the reveal. Returns the part state with `text` replaced by the revealed\n * prefix and `status` reporting `running` until the reveal catches up.\n *\n * @example\n * ```tsx\n * const { text, status } = useSmooth(useMessagePartText(), {\n *   drainMs: 500,\n *   maxCharsPerFrame: 30,\n * });\n * ```\n */\nexport const useSmooth = (\n  state: MessagePartState & (TextMessagePart | ReasoningMessagePart),\n  smooth: boolean | SmoothOptions = false,\n): MessagePartState & (TextMessagePart | ReasoningMessagePart) => {\n  const { text } = state;\n  const options =\n    typeof smooth === \"object\" && smooth !== null ? smooth : undefined;\n  const enabled = smooth !== false && smooth !== null;\n  const drainMs = positiveOr(options?.drainMs, DEFAULT_DRAIN_MS);\n  const maxCharIntervalMs = positiveOr(\n    options?.maxCharIntervalMs,\n    DEFAULT_MAX_CHAR_INTERVAL_MS,\n  );\n  const maxCharsPerFrame = positiveOr(options?.maxCharsPerFrame, Infinity);\n\n  const [displayedText, setDisplayedText] = useState(\n    state.status.type === \"running\" ? \"\" : text,\n  );\n\n  // Render-phase resync on part flip or text discontinuity, so the\n  // first paint after a thread switch never shows the previous\n  // part's text (#4051). `displayedText` is already a prefix of\n  // `text` during normal streaming, so use it as the previous-text\n  // reference instead of carrying separate state — avoids the\n  // double render per streaming token. Read part identity through\n  // `useAuiState` so we actually subscribe to its changes instead\n  // of relying on a render-time proxy reference that may be stable\n  // across thread swaps.\n  const aui = useAui();\n  const part = useAuiState(() => aui.part());\n  const [prevPart, setPrevPart] = useState(part);\n  if (part !== prevPart || !text.startsWith(displayedText)) {\n    setPrevPart(part);\n    setDisplayedText(state.status.type === \"running\" ? \"\" : text);\n  }\n\n  const smoothStatusStore = useSmoothStatusStore({ optional: true });\n  const setText = useCallbackRef((text: string) => {\n    setDisplayedText(text);\n    if (smoothStatusStore) {\n      const target =\n        displayedText !== text || state.status.type === \"running\"\n          ? SMOOTH_STATUS\n          : state.status;\n      writableStore(smoothStatusStore).setState(target, true);\n    }\n  });\n\n  // TODO this is hacky\n  useEffect(() => {\n    if (smoothStatusStore) {\n      const target =\n        enabled && (displayedText !== text || state.status.type === \"running\")\n          ? SMOOTH_STATUS\n          : state.status;\n      writableStore(smoothStatusStore).setState(target, true);\n    }\n  }, [smoothStatusStore, enabled, text, displayedText, state.status]);\n\n  const [animatorRef] = useState<TextStreamAnimator>(\n    new TextStreamAnimator(displayedText, setText),\n  );\n\n  useEffect(() => {\n    animatorRef.drainMs = drainMs;\n    animatorRef.maxCharIntervalMs = maxCharIntervalMs;\n    animatorRef.maxCharsPerFrame = maxCharsPerFrame;\n  }, [animatorRef, drainMs, maxCharIntervalMs, maxCharsPerFrame]);\n\n  const animatorPartRef = useRef(part);\n  useEffect(() => {\n    if (!enabled) {\n      animatorRef.stop();\n      return;\n    }\n\n    // Discontinuity: part flipped, or new text breaks continuation\n    // of the animator's current target. Either case requires\n    // resetting the cursor — without the part check, a new part\n    // whose text happens to share a prefix with the previous target\n    // would keep the stale cursor and flicker.\n    const partChanged = animatorPartRef.current !== part;\n    animatorPartRef.current = part;\n    if (partChanged || !text.startsWith(animatorRef.targetText)) {\n      if (state.status.type === \"running\") {\n        animatorRef.currentText = \"\";\n        animatorRef.targetText = text;\n        animatorRef.start();\n      } else {\n        animatorRef.currentText = text;\n        animatorRef.targetText = text;\n        animatorRef.stop();\n      }\n      return;\n    }\n\n    animatorRef.targetText = text;\n    animatorRef.start();\n  }, [animatorRef, enabled, text, state.status.type, part]);\n\n  useEffect(() => {\n    return () => {\n      animatorRef.stop();\n    };\n  }, [animatorRef]);\n\n  return useMemo(\n    () =>\n      enabled\n        ? {\n            ...state,\n            text: displayedText,\n            status: text === displayedText ? state.status : SMOOTH_STATUS,\n          }\n        : state,\n    [enabled, displayedText, state, text],\n  );\n};\n"],"mappings":"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"}

package/package.json

@@ -1,33 +1,40 @@
 {
   "name": "@assistant-ui/react",
-  "version": "0.14.15",
+  "version": "0.14.18",
   "description": "Open-source TypeScript/React library for building production-grade AI chat experiences",
   "keywords": [
-    "radix-ui",
-    "nextjs",
-    "vercel",
-    "ai-sdk",
-    "react",
-    "components",
+    "ai",
     "ui",
-    "frontend",
-    "tailwind",
-    "shadcn",
+    "sdk",
+    "mcp",
+    "agent",
+    "agentic",
+    "generative",
+    "components",
     "assistant",
-    "openai",
-    "ai",
     "chat",
     "chatbot",
-    "copilot",
-    "ai-chat",
-    "ai-chatbot",
-    "ai-assistant",
-    "ai-copilot",
+    "shadcn",
+    "radix-ui",
+    "tailwind",
+    "javascript",
+    "openai",
+    "anthropic",
+    "claude",
+    "xai",
     "chatgpt",
-    "gpt4",
-    "gpt-4",
-    "conversational-ui",
-    "conversational-ai"
+    "gemini",
+    "grok",
+    "react",
+    "framework",
+    "nextjs",
+    "web",
+    "server",
+    "node",
+    "front-end",
+    "backend",
+    "cli",
+    "vercel"
   ],
   "author": "AgentbaseAI Inc.",
   "license": "MIT",
@@ -48,9 +55,9 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@assistant-ui/core": "^0.2.11",
-    "@assistant-ui/store": "^0.2.14",
-    "@assistant-ui/tap": "^0.6.0",
+    "@assistant-ui/core": "^0.2.14",
+    "@assistant-ui/store": "^0.2.16",
+    "@assistant-ui/tap": "^0.7.1",
     "@radix-ui/primitive": "^1.1.4",
     "@radix-ui/react-compose-refs": "^1.1.3",
     "@radix-ui/react-context": "^1.1.4",

package/src/client/ExternalThread.ts

@@ -17,14 +17,17 @@ import type {
   ThreadUserMessagePart,
   ThreadMessage,
   ExternalThreadQueueAdapter,
+  ExternalThreadBranchAdapter,
 } from "@assistant-ui/core";
 import type { QueueItemState } from "@assistant-ui/core/store";
 import type { ComposerSendOptions } from "@assistant-ui/core/store";
+import { getThreadMessageText } from "@assistant-ui/core/internal";
 import { ModelContext, Suggestions } from "@assistant-ui/core/store";
 import { Tools, DataRenderers } from "@assistant-ui/core/react";
 import { SingleThreadList } from "./SingleThreadList";
 
 const EMPTY_QUEUE_ITEMS: readonly QueueItemState[] = [];
+const EMPTY_BRANCH_IDS: readonly string[] = [];
 
 export type ExternalThreadMessage = ThreadMessage & {
   id: string;
@@ -51,6 +54,8 @@ export type ExternalThreadProps = {
   onCancel?: () => void;
   /** Queue adapter for runtimes that support message queuing and steering. */
   queue?: ExternalThreadQueueAdapter;
+  /** Branch adapter for runtimes that track sibling variants of messages. */
+  branches?: ExternalThreadBranchAdapter;
 };
 
 type MessageClientProps = {
@@ -59,16 +64,18 @@ type MessageClientProps = {
   onEdit?: (message: AppendMessage) => void;
   onReload?: () => void;
   queue?: ExternalThreadQueueAdapter | undefined;
+  branches?: ExternalThreadBranchAdapter | undefined;
 };
 
 // Message Client - minimal implementation
-const MessageClient = resource(function MessageClient({
+const useMessageClient = ({
   message,
   index,
   onEdit,
   onReload,
   queue,
-}: MessageClientProps): ClientOutput<"message"> {
+  branches,
+}: MessageClientProps): ClientOutput<"message"> => {
   const [isCopied, setIsCopied] = useState(false);
   const [isHovering, setIsHovering] = useState(false);
   const [isEditing, setIsEditing] = useState(false);
@@ -124,14 +131,19 @@ const MessageClient = resource(function MessageClient({
     }),
   );
 
+  const branchIds = branches?.getBranches(message.id) ?? EMPTY_BRANCH_IDS;
+  const branchIndex = branchIds.indexOf(message.id);
+  const branchNumber = branchIndex === -1 ? 1 : branchIndex + 1;
+  const branchCount = branchIndex === -1 ? 1 : branchIds.length;
+
   const state = useMemo(() => {
     return {
       ...message,
       attachments: message.attachments ?? [],
       parentId: null,
       isLast: false, // Will be set by thread
-      branchNumber: 1,
-      branchCount: 1,
+      branchNumber,
+      branchCount,
       speech: undefined,
       parts: partClients.state,
       isCopied,
@@ -146,20 +158,35 @@ const MessageClient = resource(function MessageClient({
     index,
     composerClient.state,
     partClients.state,
+    branchNumber,
+    branchCount,
   ]);
 
   return {
     getState: () => state,
     composer: () => composerClient.methods,
+    delete: () => {},
     reload: () => {
       onReload?.();
     },
     speak: () => {},
     stopSpeaking: () => {},
     submitFeedback: () => {},
-    switchToBranch: () => {},
-    getCopyText: () =>
-      message.content.map((c) => ("text" in c ? c.text : "")).join(""),
+    switchToBranch: ({ position, branchId }) => {
+      if (!branches) return;
+      const target =
+        branchId ??
+        (branchIndex === -1
+          ? undefined
+          : position === "previous"
+            ? branchIds[branchIndex - 1]
+            : position === "next"
+              ? branchIds[branchIndex + 1]
+              : undefined);
+      if (target !== undefined && target !== message.id)
+        branches.switchToBranch(target);
+    },
+    getCopyText: () => getThreadMessageText(message),
     part: (selector) => {
       if ("index" in selector) {
         return partClients.get(selector);
@@ -178,16 +205,16 @@ const MessageClient = resource(function MessageClient({
     setIsCopied,
     setIsHovering,
   };
-});
+};
+
+const MessageClient = resource(useMessageClient);
 
 type PartResourceProps = {
   part: ThreadAssistantMessagePart | ThreadUserMessagePart;
 };
 
 // Part Client - minimal implementation
-const PartResource = resource(function PartResource({
-  part,
-}: PartResourceProps): ClientOutput<"part"> {
+const usePartResource = ({ part }: PartResourceProps): ClientOutput<"part"> => {
   const state = useMemo(
     () => ({
       ...part,
@@ -202,7 +229,9 @@ const PartResource = resource(function PartResource({
     resumeToolCall: () => {},
     respondToToolApproval: () => {},
   };
-});
+};
+
+const PartResource = resource(usePartResource);
 
 type AttachmentResourceProps = {
   attachment: Attachment;
@@ -210,17 +239,19 @@ type AttachmentResourceProps = {
 };
 
 // Attachment Client - minimal implementation
-const AttachmentResource = resource(function AttachmentResource({
+const useAttachmentResource = ({
   attachment,
   onRemove,
-}: AttachmentResourceProps): ClientOutput<"attachment"> {
+}: AttachmentResourceProps): ClientOutput<"attachment"> => {
   return {
     getState: () => attachment,
     remove: async () => {
       onRemove?.();
     },
   };
-});
+};
+
+const AttachmentResource = resource(useAttachmentResource);
 
 type ComposerClientResourceProps = {
   type: "thread" | "edit";
@@ -234,7 +265,7 @@ type ComposerClientResourceProps = {
   queue?: ExternalThreadQueueAdapter | undefined;
 };
 
-const QueueItemClient = resource(function QueueItemClient({
+const useQueueItemClient = ({
   item,
   onSteer,
   onRemove,
@@ -242,16 +273,18 @@ const QueueItemClient = resource(function QueueItemClient({
   item: QueueItemState;
   onSteer: () => void;
   onRemove: () => void;
-}): ClientOutput<"queueItem"> {
+}): ClientOutput<"queueItem"> => {
   return {
     getState: () => item,
     steer: onSteer,
     remove: onRemove,
   };
-});
+};
+
+const QueueItemClient = resource(useQueueItemClient);
 
 // Composer Client - minimal implementation
-const ComposerClientResource = resource(function ComposerClientResource({
+const useComposerClientResource = ({
   type,
   isEditing,
   canCancel,
@@ -261,7 +294,7 @@ const ComposerClientResource = resource(function ComposerClientResource({
   onSend,
   message,
   queue,
-}: ComposerClientResourceProps): ClientOutput<"composer"> {
+}: ComposerClientResourceProps): ClientOutput<"composer"> => {
   const [text, setText] = useState("");
   const [role, setRole] = useState<"user" | "assistant" | "system">("user");
   const [runConfig, setRunConfig] = useState<Record<string, unknown>>({});
@@ -436,10 +469,12 @@ const ComposerClientResource = resource(function ComposerClientResource({
       return queueItemClients.get(selector);
     },
   };
-});
+};
+
+const ComposerClientResource = resource(useComposerClientResource);
 
 // External Thread Client
-export const ExternalThread = resource(function ExternalThread({
+const useExternalThread = ({
   messages,
   isRunning = false,
   isSendDisabled = false,
@@ -449,7 +484,8 @@ export const ExternalThread = resource(function ExternalThread({
   onStartRun,
   onCancel,
   queue,
-}: ExternalThreadProps): ClientOutput<"thread"> {
+  branches,
+}: ExternalThreadProps): ClientOutput<"thread"> => {
   const handleReload = (messageId: string) => {
     const messageIndex = messages.findIndex((m) => m.id === messageId);
     if (messageIndex === -1) return;
@@ -467,11 +503,12 @@ export const ExternalThread = resource(function ExternalThread({
           index,
           onReload: () => handleReload(msg.id),
           queue,
+          branches,
         };
         if (onEdit) props.onEdit = onEdit;
         return withKey(msg.id, MessageClient(props));
       }),
-    [messages, onEdit, queue],
+    [messages, onEdit, queue, branches],
   );
 
   const handleCancelRun = () => {
@@ -496,6 +533,7 @@ export const ExternalThread = resource(function ExternalThread({
   );
 
   const hasQueue = !!queue;
+  const hasBranches = !!branches;
   const state = useMemo(() => {
     const messageStates = messageClients.state.map((s, idx, arr) => ({
       ...s,
@@ -509,13 +547,14 @@ export const ExternalThread = resource(function ExternalThread({
       isRunning,
       capabilities: {
         edit: false,
+        delete: false,
         reload: false,
         cancel: isRunning,
         speech: false,
         attachments: false,
         feedback: false,
         voice: false,
-        switchToBranch: false,
+        switchToBranch: hasBranches,
         switchBranchDuringRun: false,
         unstable_copy: false,
         dictation: false,
@@ -533,6 +572,7 @@ export const ExternalThread = resource(function ExternalThread({
     messages,
     isRunning,
     hasQueue,
+    hasBranches,
     messageClients.state,
     composerClient.state,
   ]);
@@ -570,6 +610,7 @@ export const ExternalThread = resource(function ExternalThread({
         onNew?.(appendMessage);
       }
     },
+    deleteMessage: () => {},
     startRun: () => {
       onStartRun?.();
     },
@@ -593,9 +634,11 @@ export const ExternalThread = resource(function ExternalThread({
     muteVoice: () => {},
     unmuteVoice: () => {},
   };
-});
+};
+
+export const ExternalThread = resource(useExternalThread);
 
-attachTransformScopes(ExternalThread, (scopes, parent) => {
+attachTransformScopes(useExternalThread, (scopes, parent) => {
   if (!scopes.threads && parent.threads.source === null) {
     const threadElement = scopes.thread as ClientElement<"thread">;
     scopes.threads = SingleThreadList({ thread: threadElement });

package/src/client/InMemoryThreadList.ts

@@ -27,14 +27,14 @@ type ThreadData = {
 };
 
 // ThreadListItem Client
-const ThreadListItemClient = resource(function ThreadListItemClient(props: {
+const useThreadListItemClient = (props: {
   data: ThreadData;
   onSwitchTo: () => void;
   onUpdateCustom: (custom: Record<string, unknown> | undefined) => void;
   onArchive: () => void;
   onUnarchive: () => void;
   onDelete: () => void;
-}): ClientOutput<"threadListItem"> {
+}): ClientOutput<"threadListItem"> => {
   const { data, onSwitchTo, onUpdateCustom, onArchive, onUnarchive, onDelete } =
     props;
   const state = useMemo(
@@ -61,12 +61,14 @@ const ThreadListItemClient = resource(function ThreadListItemClient(props: {
     initialize: async () => ({ remoteId: data.id, externalId: undefined }),
     detach: () => {},
   };
-});
+};
+
+const ThreadListItemClient = resource(useThreadListItemClient);
 
 // InMemoryThreadList Client
-export const InMemoryThreadList = resource(function InMemoryThreadList(
+const useInMemoryThreadList = (
   props: InMemoryThreadListProps,
-): ClientOutput<"threads"> {
+): ClientOutput<"threads"> => {
   const {
     thread: threadFactory,
     onSwitchToThread,
@@ -184,9 +186,11 @@ export const InMemoryThreadList = resource(function InMemoryThreadList(
     },
     thread: () => mainThreadClient.methods,
   };
-});
+};
+
+export const InMemoryThreadList = resource(useInMemoryThreadList);
 
-attachTransformScopes(InMemoryThreadList, (scopes, parent) => {
+attachTransformScopes(useInMemoryThreadList, (scopes, parent) => {
   scopes.thread ??= Derived({
     source: "threads",
     query: { type: "main" },

package/src/client/SingleThreadList.ts

@@ -9,31 +9,31 @@ import {
 const RESOLVED_PROMISE = Promise.resolve();
 const THREAD_ID = "default";
 
-const SingleThreadListItem = resource(
-  function SingleThreadListItem(): ClientOutput<"threadListItem"> {
-    const [custom, setCustom] = useState<Record<string, unknown> | undefined>();
+const useSingleThreadListItem = (): ClientOutput<"threadListItem"> => {
+  const [custom, setCustom] = useState<Record<string, unknown> | undefined>();
 
-    return {
-      getState: () => ({
-        id: THREAD_ID,
-        remoteId: undefined,
-        externalId: undefined,
-        title: undefined,
-        status: "regular",
-        custom,
-      }),
-      switchTo: () => {},
-      rename: () => {},
-      updateCustom: setCustom,
-      archive: () => {},
-      unarchive: () => {},
-      delete: () => {},
-      generateTitle: () => {},
-      initialize: async () => ({ remoteId: THREAD_ID, externalId: undefined }),
-      detach: () => {},
-    };
-  },
-);
+  return {
+    getState: () => ({
+      id: THREAD_ID,
+      remoteId: undefined,
+      externalId: undefined,
+      title: undefined,
+      status: "regular",
+      custom,
+    }),
+    switchTo: () => {},
+    rename: () => {},
+    updateCustom: setCustom,
+    archive: () => {},
+    unarchive: () => {},
+    delete: () => {},
+    generateTitle: () => {},
+    initialize: async () => ({ remoteId: THREAD_ID, externalId: undefined }),
+    detach: () => {},
+  };
+};
+
+const SingleThreadListItem = resource(useSingleThreadListItem);
 
 type SingleThreadListProps = {
   thread: ClientElement<"thread">;
@@ -44,9 +44,9 @@ type SingleThreadListProps = {
  * Automatically provided by ExternalThread when no threads scope exists.
  * Mounts the provided thread resource element.
  */
-export const SingleThreadList = resource(function SingleThreadList({
+const useSingleThreadList = ({
   thread,
-}: SingleThreadListProps): ClientOutput<"threads"> {
+}: SingleThreadListProps): ClientOutput<"threads"> => {
   const itemClient = useClientResource(SingleThreadListItem());
   const threadClient = useClientResource(thread);
 
@@ -105,4 +105,6 @@ export const SingleThreadList = resource(function SingleThreadList({
       return threadClient.methods;
     },
   };
-});
+};
+
+export const SingleThreadList = resource(useSingleThreadList);