@assistant-ui/react 0.10.23 → 0.10.24

package/package.json

@@ -28,7 +28,7 @@
     "conversational-ui",
     "conversational-ai"
   ],
-  "version": "0.10.23",
+  "version": "0.10.24",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -57,12 +57,13 @@
     "@radix-ui/react-use-callback-ref": "^1.1.1",
     "@radix-ui/react-use-escape-keydown": "^1.1.1",
     "@standard-schema/spec": "^1.0.0",
-    "assistant-stream": "^0.2.15",
+    "assistant-stream": "^0.2.17",
     "json-schema": "^0.4.0",
     "nanoid": "5.1.5",
     "react-textarea-autosize": "^8.5.9",
-    "zod": "^3.25.49",
-    "zustand": "^5.0.5"
+    "zod": "^3.25.64",
+    "zustand": "^5.0.5",
+    "assistant-cloud": "0.0.2"
   },
   "peerDependencies": {
     "@types/react": "*",
@@ -82,11 +83,11 @@
     "@stryker-mutator/core": "^9.0.1",
     "@stryker-mutator/vitest-runner": "^9.0.1",
     "@types/json-schema": "^7.0.15",
-    "@types/node": "^22.15.29",
+    "@types/node": "^24.0.1",
     "eslint": "^9",
     "eslint-config-next": "15.3.3",
-    "tsx": "^4.19.4",
-    "vitest": "^3.2.0",
+    "tsx": "^4.20.3",
+    "vitest": "^3.2.3",
     "@assistant-ui/x-buildutils": "0.0.1"
   },
   "publishConfig": {

package/src/cloud/AssistantCloudThreadHistoryAdapter.tsx

@@ -2,7 +2,7 @@ import { RefObject, useState } from "react";
 import { useThreadListItemRuntime } from "../context";
 import { ThreadHistoryAdapter } from "../runtimes/adapters/thread-history/ThreadHistoryAdapter";
 import { ExportedMessageRepositoryItem } from "../runtimes/utils/MessageRepository";
-import { AssistantCloud } from "./AssistantCloud";
+import { AssistantCloud } from "assistant-cloud";
 import { auiV0Decode, auiV0Encode } from "./auiV0";
 import { ThreadListItemRuntime } from "../api";
 

package/src/cloud/auiV0.ts

@@ -1,7 +1,7 @@
 import { ThreadMessage } from "../types";
 import { MessageStatus } from "../types/AssistantTypes";
 import { fromThreadMessageLike } from "../runtimes/external-store/ThreadMessageLike";
-import { CloudMessage } from "./AssistantCloudThreadMessages";
+import { CloudMessage } from "assistant-cloud";
 import { isJSONValue } from "../utils/json/is-json";
 import { ReadonlyJSONObject, ReadonlyJSONValue } from "assistant-stream/utils";
 import { ExportedMessageRepositoryItem } from "../runtimes/utils/MessageRepository";

package/src/cloud/index.ts

@@ -1,2 +1,2 @@
 export { useCloudThreadListRuntime } from "./useCloudThreadListRuntime";
-export { AssistantCloud } from "./AssistantCloud";
+export { AssistantCloud } from "assistant-cloud";

package/src/cloud/useCloudThreadListRuntime.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { AssistantCloud } from "./AssistantCloud";
+import { AssistantCloud } from "assistant-cloud";
 import { AssistantRuntime } from "../api";
 import { useRemoteThreadListRuntime } from "../runtimes/remote-thread-list/useRemoteThreadListRuntime";
 import { useCloudThreadListAdapter } from "../runtimes/remote-thread-list/adapter/cloud";

package/src/context/react/AssistantContext.ts

@@ -24,6 +24,29 @@ export const useAssistantContext = createContextHook(
   "AssistantRuntimeProvider",
 );
 
+/**
+ * Hook to access the AssistantRuntime from the current context.
+ *
+ * The AssistantRuntime provides access to the top-level assistant state and actions,
+ * including thread management, tool registration, and configuration.
+ *
+ * @param options Configuration options
+ * @param options.optional Whether the hook should return null if no context is found
+ * @returns The AssistantRuntime instance, or null if optional is true and no context exists
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const runtime = useAssistantRuntime();
+ *
+ *   const handleNewThread = () => {
+ *     runtime.switchToNewThread();
+ *   };
+ *
+ *   return <button onClick={handleNewThread}>New Thread</button>;
+ * }
+ * ```
+ */
 export function useAssistantRuntime(options?: {
   optional?: false | undefined;
 }): AssistantRuntime;

package/src/context/react/ComposerContext.ts

@@ -5,6 +5,44 @@ import { useThreadRuntime } from "./ThreadContext";
 import { ComposerRuntime } from "../../api/ComposerRuntime";
 import { createStateHookForRuntime } from "./utils/createStateHookForRuntime";
 
+/**
+ * Hook to access the ComposerRuntime from the current context.
+ *
+ * The ComposerRuntime provides access to composer state and actions for message
+ * composition, including text input, attachments, and sending functionality.
+ * This hook automatically resolves to either the message's edit composer or
+ * the thread's main composer depending on the context.
+ *
+ * @param options Configuration options
+ * @param options.optional Whether the hook should return null if no context is found
+ * @returns The ComposerRuntime instance, or null if optional is true and no context exists
+ *
+ * @example
+ * ```tsx
+ * function ComposerActions() {
+ *   const runtime = useComposerRuntime();
+ *
+ *   const handleSend = () => {
+ *     if (runtime.getState().canSend) {
+ *       runtime.send();
+ *     }
+ *   };
+ *
+ *   const handleCancel = () => {
+ *     if (runtime.getState().canCancel) {
+ *       runtime.cancel();
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleSend}>Send</button>
+ *       <button onClick={handleCancel}>Cancel</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export function useComposerRuntime(options?: {
   optional?: false | undefined;
 }): ComposerRuntime;
@@ -21,4 +59,30 @@ export function useComposerRuntime(options?: {
     : (threadRuntime?.composer ?? null);
 }
 
+/**
+ * Hook to access the current composer state.
+ *
+ * This hook provides reactive access to the composer's state, including text content,
+ * attachments, editing status, and send/cancel capabilities.
+ *
+ * @param selector Optional selector function to pick specific state properties
+ * @returns The selected composer state or the entire composer state if no selector provided
+ *
+ * @example
+ * ```tsx
+ * function ComposerStatus() {
+ *   const text = useComposer((state) => state.text);
+ *   const canSend = useComposer((state) => state.canSend);
+ *   const attachmentCount = useComposer((state) => state.attachments.length);
+ *
+ *   return (
+ *     <div>
+ *       Text: {text.length} chars,
+ *       Attachments: {attachmentCount},
+ *       Can send: {canSend}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export const useComposer = createStateHookForRuntime(useComposerRuntime);

package/src/context/react/MessageContext.ts

@@ -22,6 +22,38 @@ const useMessageContext = createContextHook(
   "a component passed to <ThreadPrimitive.Messages components={...} />",
 );
 
+/**
+ * Hook to access the MessageRuntime from the current context.
+ *
+ * The MessageRuntime provides access to message-level state and actions,
+ * including message content, status, editing capabilities, and branching.
+ *
+ * @param options Configuration options
+ * @param options.optional Whether the hook should return null if no context is found
+ * @returns The MessageRuntime instance, or null if optional is true and no context exists
+ *
+ * @example
+ * ```tsx
+ * function MessageActions() {
+ *   const runtime = useMessageRuntime();
+ *
+ *   const handleReload = () => {
+ *     runtime.reload();
+ *   };
+ *
+ *   const handleEdit = () => {
+ *     runtime.startEdit();
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleReload}>Reload</button>
+ *       <button onClick={handleEdit}>Edit</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export function useMessageRuntime(options?: {
   optional?: false | undefined;
 }): MessageRuntime;
@@ -36,6 +68,30 @@ export function useMessageRuntime(options?: {
   return context.useMessageRuntime();
 }
 
+/**
+ * Hook to access the current message state.
+ *
+ * This hook provides reactive access to the message's state, including content,
+ * role, status, and other message-level properties.
+ *
+ * @param selector Optional selector function to pick specific state properties
+ * @returns The selected message state or the entire message state if no selector provided
+ *
+ * @example
+ * ```tsx
+ * function MessageContent() {
+ *   const role = useMessage((state) => state.role);
+ *   const content = useMessage((state) => state.content);
+ *   const isLoading = useMessage((state) => state.status.type === "running");
+ *
+ *   return (
+ *     <div className={`message-${role}`}>
+ *       {isLoading ? "Loading..." : content.map(part => part.text).join("")}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export const useMessage = createStateHookForRuntime(useMessageRuntime);
 
 const useEditComposerRuntime = (opt: {

package/src/context/react/ThreadContext.ts

@@ -20,6 +20,29 @@ const useThreadContext = createContextHook(
   "AssistantRuntimeProvider",
 );
 
+/**
+ * Hook to access the ThreadRuntime from the current context.
+ *
+ * The ThreadRuntime provides access to thread-level state and actions,
+ * including message management, thread state, and composer functionality.
+ *
+ * @param options Configuration options
+ * @param options.optional Whether the hook should return null if no context is found
+ * @returns The ThreadRuntime instance, or null if optional is true and no context exists
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const runtime = useThreadRuntime();
+ *
+ *   const handleSendMessage = (text: string) => {
+ *     runtime.append({ role: "user", content: [{ type: "text", text }] });
+ *   };
+ *
+ *   return <button onClick={() => handleSendMessage("Hello!")}>Send</button>;
+ * }
+ * ```
+ */
 export function useThreadRuntime(options?: {
   optional?: false | undefined;
 }): ThreadRuntime;
@@ -32,6 +55,25 @@ export function useThreadRuntime(options?: { optional?: boolean | undefined }) {
   return context.useThreadRuntime();
 }
 
+/**
+ * Hook to access the current thread state.
+ *
+ * This hook provides reactive access to the thread's state, including messages,
+ * running status, capabilities, and other thread-level properties.
+ *
+ * @param selector Optional selector function to pick specific state properties
+ * @returns The selected thread state or the entire thread state if no selector provided
+ *
+ * @example
+ * ```tsx
+ * function ThreadStatus() {
+ *   const isRunning = useThread((state) => state.isRunning);
+ *   const messageCount = useThread((state) => state.messages.length);
+ *
+ *   return <div>Running: {isRunning}, Messages: {messageCount}</div>;
+ * }
+ * ```
+ */
 export const useThread = createStateHookForRuntime(useThreadRuntime);
 
 const useThreadComposerRuntime = (opt: {

package/src/primitives/actionBar/ActionBarCopy.tsx

@@ -12,6 +12,30 @@ import {
 } from "../../context/react/MessageContext";
 import { useComposerRuntime } from "../../context";
 
+/**
+ * Hook that provides copy functionality for action bar buttons.
+ *
+ * This hook returns a callback function that copies message content to the clipboard,
+ * or null if copying is not available. It handles both regular message content and
+ * composer text when in editing mode.
+ *
+ * @param options Configuration options
+ * @param options.copiedDuration Duration in milliseconds to show the copied state
+ * @returns A copy callback function, or null if copying is disabled
+ *
+ * @example
+ * ```tsx
+ * function CustomCopyButton() {
+ *   const copy = useActionBarPrimitiveCopy({ copiedDuration: 2000 });
+ *
+ *   return (
+ *     <button onClick={copy} disabled={!copy}>
+ *       {copy ? "Copy" : "Cannot Copy"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 const useActionBarPrimitiveCopy = ({
   copiedDuration = 3000,
 }: { copiedDuration?: number | undefined } = {}) => {
@@ -44,9 +68,27 @@ const useActionBarPrimitiveCopy = ({
 
 export namespace ActionBarPrimitiveCopy {
   export type Element = HTMLButtonElement;
+  /**
+   * Props for the ActionBarPrimitive.Copy component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useActionBarPrimitiveCopy>;
 }
 
+/**
+ * A button component that copies message content to the clipboard.
+ *
+ * This component automatically handles copying message text to the clipboard
+ * and provides visual feedback through the data-copied attribute. It's disabled
+ * when there's no copyable content available.
+ *
+ * @example
+ * ```tsx
+ * <ActionBarPrimitive.Copy copiedDuration={2000}>
+ *   Copy Message
+ * </ActionBarPrimitive.Copy>
+ * ```
+ */
 export const ActionBarPrimitiveCopy = forwardRef<
   ActionBarPrimitiveCopy.Element,
   ActionBarPrimitiveCopy.Props

package/src/primitives/actionBar/ActionBarEdit.tsx

@@ -8,6 +8,27 @@ import {
 import { useCallback } from "react";
 import { useEditComposer, useMessageRuntime } from "../../context";
 
+/**
+ * Hook that provides edit functionality for action bar buttons.
+ *
+ * This hook returns a callback function that starts editing the current message,
+ * or null if editing is not available (e.g., already in editing mode).
+ *
+ * @returns An edit callback function, or null if editing is disabled
+ *
+ * @example
+ * ```tsx
+ * function CustomEditButton() {
+ *   const edit = useActionBarEdit();
+ *
+ *   return (
+ *     <button onClick={edit} disabled={!edit}>
+ *       {edit ? "Edit Message" : "Cannot Edit"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 const useActionBarEdit = () => {
   const messageRuntime = useMessageRuntime();
   const disabled = useEditComposer((c) => c.isEditing);
@@ -22,9 +43,26 @@ const useActionBarEdit = () => {
 
 export namespace ActionBarPrimitiveEdit {
   export type Element = ActionButtonElement;
+  /**
+   * Props for the ActionBarPrimitive.Edit component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useActionBarEdit>;
 }
 
+/**
+ * A button component that starts editing the current message.
+ *
+ * This component automatically handles starting the edit mode for the current message
+ * and is disabled when editing is not available (e.g., already in editing mode).
+ *
+ * @example
+ * ```tsx
+ * <ActionBarPrimitive.Edit>
+ *   Edit Message
+ * </ActionBarPrimitive.Edit>
+ * ```
+ */
 export const ActionBarPrimitiveEdit = createActionButton(
   "ActionBarPrimitive.Edit",
   useActionBarEdit,

package/src/primitives/actionBar/ActionBarReload.tsx

@@ -10,6 +10,27 @@ import { useMessageRuntime } from "../../context";
 import { useThreadRuntime } from "../../context/react/ThreadContext";
 import { useCombinedStore } from "../../utils/combined/useCombinedStore";
 
+/**
+ * Hook that provides reload functionality for action bar buttons.
+ *
+ * This hook returns a callback function that reloads/regenerates the current assistant message,
+ * or null if reloading is not available (e.g., thread is running, disabled, or message is not from assistant).
+ *
+ * @returns A reload callback function, or null if reloading is disabled
+ *
+ * @example
+ * ```tsx
+ * function CustomReloadButton() {
+ *   const reload = useActionBarReload();
+ *
+ *   return (
+ *     <button onClick={reload} disabled={!reload}>
+ *       {reload ? "Reload Message" : "Cannot Reload"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 const useActionBarReload = () => {
   const messageRuntime = useMessageRuntime();
   const threadRuntime = useThreadRuntime();
@@ -29,9 +50,27 @@ const useActionBarReload = () => {
 
 export namespace ActionBarPrimitiveReload {
   export type Element = ActionButtonElement;
+  /**
+   * Props for the ActionBarPrimitive.Reload component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useActionBarReload>;
 }
 
+/**
+ * A button component that reloads/regenerates the current assistant message.
+ *
+ * This component automatically handles reloading the current assistant message
+ * and is disabled when reloading is not available (e.g., thread is running,
+ * disabled, or message is not from assistant).
+ *
+ * @example
+ * ```tsx
+ * <ActionBarPrimitive.Reload>
+ *   Reload Message
+ * </ActionBarPrimitive.Reload>
+ * ```
+ */
 export const ActionBarPrimitiveReload = createActionButton(
   "ActionBarPrimitive.Reload",
   useActionBarReload,

package/src/primitives/actionBar/ActionBarRoot.tsx

@@ -12,12 +12,50 @@ type PrimitiveDivProps = ComponentPropsWithoutRef<typeof Primitive.div>;
 export namespace ActionBarPrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
   export type Props = PrimitiveDivProps & {
+    /**
+     * Whether to hide the action bar when the thread is running.
+     * @default false
+     */
     hideWhenRunning?: boolean | undefined;
+    /**
+     * Controls when the action bar should automatically hide.
+     * - "always": Always hide unless hovered
+     * - "not-last": Hide unless this is the last message
+     * - "never": Never auto-hide
+     * @default "never"
+     */
     autohide?: "always" | "not-last" | "never" | undefined;
+    /**
+     * Controls floating behavior when auto-hidden.
+     * - "always": Always float when hidden
+     * - "single-branch": Float only for single-branch messages
+     * - "never": Never float
+     * @default "never"
+     */
     autohideFloat?: "always" | "single-branch" | "never" | undefined;
   };
 }
 
+/**
+ * The root container for action bar components.
+ *
+ * This component provides intelligent visibility and floating behavior for action bars,
+ * automatically hiding and showing based on message state, hover status, and configuration.
+ * It supports floating mode for better UX when space is limited.
+ *
+ * @example
+ * ```tsx
+ * <ActionBarPrimitive.Root
+ *   hideWhenRunning={true}
+ *   autohide="not-last"
+ *   autohideFloat="single-branch"
+ * >
+ *   <ActionBarPrimitive.Copy />
+ *   <ActionBarPrimitive.Edit />
+ *   <ActionBarPrimitive.Reload />
+ * </ActionBarPrimitive.Root>
+ * ```
+ */
 export const ActionBarPrimitiveRoot = forwardRef<
   ActionBarPrimitiveRoot.Element,
   ActionBarPrimitiveRoot.Props

package/src/primitives/attachment/AttachmentRoot.tsx

@@ -7,9 +7,27 @@ type PrimitiveDivProps = ComponentPropsWithoutRef<typeof Primitive.div>;
 
 export namespace AttachmentPrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
+  /**
+   * Props for the AttachmentPrimitive.Root component.
+   * Accepts all standard div element props.
+   */
   export type Props = PrimitiveDivProps;
 }
 
+/**
+ * The root container component for an attachment.
+ *
+ * This component provides the foundational wrapper for attachment-related components
+ * and content. It serves as the context provider for attachment state and actions.
+ *
+ * @example
+ * ```tsx
+ * <AttachmentPrimitive.Root>
+ *   <AttachmentPrimitive.Name />
+ *   <AttachmentPrimitive.Remove />
+ * </AttachmentPrimitive.Root>
+ * ```
+ */
 export const AttachmentPrimitiveRoot = forwardRef<
   AttachmentPrimitiveRoot.Element,
   AttachmentPrimitiveRoot.Props

package/src/primitives/branchPicker/BranchPickerCount.tsx

@@ -9,9 +9,26 @@ const useBranchPickerCount = () => {
 };
 
 export namespace BranchPickerPrimitiveCount {
+  /**
+   * Props for the BranchPickerPrimitive.Count component.
+   * This component takes no props.
+   */
   export type Props = Record<string, never>;
 }
 
+/**
+ * A component that displays the total number of branches for the current message.
+ *
+ * This component renders the branch count as plain text, useful for showing
+ * users how many alternative responses are available.
+ *
+ * @example
+ * ```tsx
+ * <div>
+ *   Branch <BranchPickerPrimitive.Count /> of {totalBranches}
+ * </div>
+ * ```
+ */
 export const BranchPickerPrimitiveCount: FC<
   BranchPickerPrimitiveCount.Props
 > = () => {

package/src/primitives/branchPicker/BranchPickerNext.tsx

@@ -25,9 +25,26 @@ const useBranchPickerNext = () => {
 
 export namespace BranchPickerPrimitiveNext {
   export type Element = ActionButtonElement;
+  /**
+   * Props for the BranchPickerPrimitive.Next component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useBranchPickerNext>;
 }
 
+/**
+ * A button component that navigates to the next branch in the message tree.
+ *
+ * This component automatically handles switching to the next available branch
+ * and is disabled when there are no more branches to navigate to.
+ *
+ * @example
+ * ```tsx
+ * <BranchPickerPrimitive.Next>
+ *   Next →
+ * </BranchPickerPrimitive.Next>
+ * ```
+ */
 export const BranchPickerPrimitiveNext = createActionButton(
   "BranchPickerPrimitive.Next",
   useBranchPickerNext,

package/src/primitives/branchPicker/BranchPickerPrevious.tsx

@@ -11,6 +11,27 @@ import {
   useMessageRuntime,
 } from "../../context/react/MessageContext";
 
+/**
+ * Hook that provides navigation to the previous branch functionality.
+ *
+ * This hook returns a callback function that switches to the previous branch
+ * in the message branch tree, or null if there is no previous branch available.
+ *
+ * @returns A previous branch callback function, or null if navigation is disabled
+ *
+ * @example
+ * ```tsx
+ * function CustomPreviousButton() {
+ *   const previous = useBranchPickerPrevious();
+ *
+ *   return (
+ *     <button onClick={previous} disabled={!previous}>
+ *       {previous ? "Previous Branch" : "No Previous Branch"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 const useBranchPickerPrevious = () => {
   const messageRuntime = useMessageRuntime();
   const disabled = useMessage((m) => m.branchNumber <= 1);
@@ -25,9 +46,26 @@ const useBranchPickerPrevious = () => {
 
 export namespace BranchPickerPrimitivePrevious {
   export type Element = ActionButtonElement;
+  /**
+   * Props for the BranchPickerPrimitive.Previous component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useBranchPickerPrevious>;
 }
 
+/**
+ * A button component that navigates to the previous branch in the message tree.
+ *
+ * This component automatically handles switching to the previous available branch
+ * and is disabled when there are no previous branches to navigate to.
+ *
+ * @example
+ * ```tsx
+ * <BranchPickerPrimitive.Previous>
+ *   ← Previous
+ * </BranchPickerPrimitive.Previous>
+ * ```
+ */
 export const BranchPickerPrimitivePrevious = createActionButton(
   "BranchPickerPrimitive.Previous",
   useBranchPickerPrevious,