@assistant-ui/react 0.10.23 → 0.10.25

package/src/api/ThreadListRuntime.ts

@@ -21,11 +21,14 @@ export type ThreadListState = {
   readonly newThread: string | undefined;
   readonly threads: readonly string[];
   readonly archivedThreads: readonly string[];
+  readonly isLoading: boolean;
 };
 
 export type ThreadListRuntime = {
   getState(): ThreadListState;
 
+  readonly isLoading: boolean;
+
   subscribe(callback: () => void): Unsubscribe;
 
   readonly main: ThreadRuntime;
@@ -48,6 +51,7 @@ const getThreadListState = (
     newThread: threadList.newThreadId,
     threads: threadList.threadIds,
     archivedThreads: threadList.archivedThreadIds,
+    isLoading: threadList.isLoading,
   };
 };
 
@@ -139,6 +143,10 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
     return this._getState();
   }
 
+  public get isLoading() {
+    return this._core.isLoading;
+  }
+
   public subscribe(callback: () => void): Unsubscribe {
     return this._core.subscribe(callback);
   }

package/src/api/ThreadRuntime.ts

@@ -139,6 +139,11 @@ export type ThreadState = {
    */
   readonly isDisabled: boolean;
 
+  /**
+   * Whether the thread is loading its history.
+   */
+  readonly isLoading: boolean;
+
   /**
    * Whether the thread is running. A thread is considered running when there is an active stream connection to the backend.
    */
@@ -187,6 +192,7 @@ export const getThreadState = (
     metadata: threadListItemState,
     capabilities: runtime.capabilities,
     isDisabled: runtime.isDisabled,
+    isLoading: runtime.isLoading,
     isRunning:
       lastMessage?.role !== "assistant"
         ? false

package/src/api/index.ts

@@ -6,10 +6,18 @@ export type {
   CreateStartRunConfig,
 } from "./ThreadRuntime";
 export type { MessageRuntime, MessageState } from "./MessageRuntime";
+
 export type {
-  ContentPartRuntime,
-  ContentPartState,
-} from "./ContentPartRuntime";
+  MessagePartRuntime,
+  MessagePartState,
+} from "./MessagePartRuntime";
+
+// TODO remove in v0.11
+export type {
+  MessagePartRuntime as MessageContentRuntime,
+  MessagePartState as MessageContentState,
+} from "./MessagePartRuntime";
+
 export type {
   ComposerRuntime,
   ThreadComposerRuntime,

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,12 +1,12 @@
 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";
 
-type AuiV0MessageContentPart =
+type AuiV0MessageMessagePart =
   | {
       readonly type: "text";
       readonly text: string;
@@ -42,7 +42,7 @@ type AuiV0MessageContentPart =
 type AuiV0Message = {
   readonly role: "assistant" | "user" | "system";
   readonly status?: MessageStatus;
-  readonly content: readonly AuiV0MessageContentPart[];
+  readonly content: readonly AuiV0MessageMessagePart[];
   readonly metadata: {
     readonly unstable_state?: ReadonlyJSONValue;
     readonly unstable_annotations: readonly ReadonlyJSONValue[];
@@ -114,7 +114,7 @@ export const auiV0Encode = (message: ThreadMessage): AuiV0Message => {
         default: {
           const unhandledType: "image" | "file" | "audio" = type;
           throw new Error(
-            `Content part type not supported by aui/v0: ${unhandledType}`,
+            `Message part type not supported by aui/v0: ${unhandledType}`,
           );
         }
       }

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/providers/MessagePartRuntimeProvider.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import { type FC, type PropsWithChildren, useEffect, useState } from "react";
+import { create } from "zustand";
+import { MessagePartContext } from "../react/MessagePartContext";
+import type { MessagePartContextValue } from "../react/MessagePartContext";
+import { writableStore } from "../ReadonlyStore";
+import { MessagePartRuntime } from "../../api/MessagePartRuntime";
+import { ensureBinding } from "../react/utils/ensureBinding";
+
+export namespace MessagePartRuntimeProvider {
+  export type Props = PropsWithChildren<{
+    runtime: MessagePartRuntime;
+  }>;
+}
+
+const useMessagePartRuntimeStore = (runtime: MessagePartRuntime) => {
+  const [store] = useState(() => create(() => runtime));
+
+  useEffect(() => {
+    ensureBinding(runtime);
+
+    writableStore(store).setState(runtime, true);
+  }, [runtime, store]);
+
+  return store;
+};
+
+export const MessagePartRuntimeProvider: FC<
+  MessagePartRuntimeProvider.Props
+> = ({ runtime, children }) => {
+  const useMessagePartRuntime = useMessagePartRuntimeStore(runtime);
+  const [context] = useState<MessagePartContextValue>(() => {
+    return { useMessagePartRuntime };
+  });
+
+  return (
+    <MessagePartContext.Provider value={context}>
+      {children}
+    </MessagePartContext.Provider>
+  );
+};

package/src/context/providers/{TextContentPartProvider.tsx → TextMessagePartProvider.tsx}

@@ -3,88 +3,88 @@
 import { FC, PropsWithChildren, useEffect, useState } from "react";
 import { create, StoreApi, UseBoundStore } from "zustand";
 import {
-  ContentPartContext,
-  ContentPartContextValue,
-} from "../react/ContentPartContext";
-import { ContentPartStatus } from "../../types/AssistantTypes";
+  MessagePartContext,
+  MessagePartContextValue,
+} from "../react/MessagePartContext";
+import { MessagePartStatus } from "../../types/AssistantTypes";
 import { writableStore } from "../ReadonlyStore";
 import {
-  ContentPartRuntimeImpl,
-  ContentPartState,
-} from "../../api/ContentPartRuntime";
+  MessagePartRuntimeImpl,
+  MessagePartState,
+} from "../../api/MessagePartRuntime";
 import { ensureBinding } from "../react/utils/ensureBinding";
 
-export namespace TextContentPartProvider {
+export namespace TextMessagePartProvider {
   export type Props = PropsWithChildren<{
     text: string;
     isRunning?: boolean | undefined;
   }>;
 }
 
-const COMPLETE_STATUS: ContentPartStatus = {
+const COMPLETE_STATUS: MessagePartStatus = {
   type: "complete",
 };
 
-const RUNNING_STATUS: ContentPartStatus = {
+const RUNNING_STATUS: MessagePartStatus = {
   type: "running",
 };
 
-export const TextContentPartProvider: FC<TextContentPartProvider.Props> = ({
+export const TextMessagePartProvider: FC<TextMessagePartProvider.Props> = ({
   children,
   text,
   isRunning,
 }) => {
   const [context] = useState<
-    ContentPartContextValue & {
-      useContentPart: UseBoundStore<
-        StoreApi<ContentPartState & { type: "text" }>
+    MessagePartContextValue & {
+      useMessagePart: UseBoundStore<
+        StoreApi<MessagePartState & { type: "text" }>
       >;
     }
   >(() => {
-    const useContentPart = create<ContentPartState & { type: "text" }>(() => ({
+    const useMessagePart = create<MessagePartState & { type: "text" }>(() => ({
       status: isRunning ? RUNNING_STATUS : COMPLETE_STATUS,
       type: "text",
       text,
     }));
 
-    const contentPartRuntime = new ContentPartRuntimeImpl({
+    const MessagePartRuntime = new MessagePartRuntimeImpl({
       path: {
         ref: "text",
         threadSelector: { type: "main" },
         messageSelector: { type: "messageId", messageId: "" },
-        contentPartSelector: { type: "index", index: 0 },
+        messagePartSelector: { type: "index", index: 0 },
       },
-      getState: useContentPart.getState,
-      subscribe: useContentPart.subscribe,
+      getState: useMessagePart.getState,
+      subscribe: useMessagePart.subscribe,
     });
-    ensureBinding(contentPartRuntime);
+    ensureBinding(MessagePartRuntime);
 
-    const useContentPartRuntime = create(() => contentPartRuntime);
+    const useMessagePartRuntime = create(() => MessagePartRuntime);
 
-    return { useContentPartRuntime, useContentPart };
+    return { useMessagePartRuntime, useMessagePart };
   });
 
   useEffect(() => {
-    const state = context.useContentPart.getState();
+    const state = context.useMessagePart.getState();
     const textUpdated = state.text !== text;
     const targetStatus = isRunning ? RUNNING_STATUS : COMPLETE_STATUS;
     const statusUpdated = state.status !== targetStatus;
 
     if (!textUpdated && !statusUpdated) return;
 
-    writableStore(context.useContentPart).setState(
+    writableStore(context.useMessagePart).setState(
       {
         type: "text",
         text,
         status: targetStatus,
-      } satisfies ContentPartState,
+      } satisfies MessagePartState,
       true,
     );
   }, [context, isRunning, text]);
 
   return (
-    <ContentPartContext.Provider value={context}>
+    <MessagePartContext.Provider value={context}>
       {children}
-    </ContentPartContext.Provider>
+    </MessagePartContext.Provider>
   );
 };

package/src/context/providers/index.ts

@@ -1,2 +1,5 @@
 export { AssistantRuntimeProvider } from "./AssistantRuntimeProvider";
-export { TextContentPartProvider } from "./TextContentPartProvider";
+export { TextMessagePartProvider } from "./TextMessagePartProvider";
+
+// TODO remove in v0.11
+export { TextMessagePartProvider as TextContentPartProvider } from "./TextMessagePartProvider";

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/MessagePartContext.ts

@@ -0,0 +1,37 @@
+"use client";
+
+import { createContext } from "react";
+import { ReadonlyStore } from "../ReadonlyStore";
+import { createContextHook } from "./utils/createContextHook";
+import { UseBoundStore } from "zustand";
+import { MessagePartRuntime } from "../../api/MessagePartRuntime";
+import { createStateHookForRuntime } from "./utils/createStateHookForRuntime";
+
+export type MessagePartContextValue = {
+  useMessagePartRuntime: UseBoundStore<ReadonlyStore<MessagePartRuntime>>;
+};
+
+export const MessagePartContext = createContext<MessagePartContextValue | null>(
+  null,
+);
+
+const useMessagePartContext = createContextHook(
+  MessagePartContext,
+  "a component passed to <MessagePrimitive.Parts components={...}>",
+);
+
+export function useMessagePartRuntime(options?: {
+  optional?: false | undefined;
+}): MessagePartRuntime;
+export function useMessagePartRuntime(options?: {
+  optional?: boolean | undefined;
+}): MessagePartRuntime | null;
+export function useMessagePartRuntime(options?: {
+  optional?: boolean | undefined;
+}) {
+  const context = useMessagePartContext(options);
+  if (!context) return null;
+  return context.useMessagePartRuntime();
+}
+
+export const useMessagePart = createStateHookForRuntime(useMessagePartRuntime);

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/context/react/index.ts

@@ -37,7 +37,7 @@ export {
   useMessageUtils,
   useMessageUtilsStore,
 } from "./MessageContext";
-export { useContentPartRuntime, useContentPart } from "./ContentPartContext";
+export { useMessagePartRuntime, useMessagePart } from "./MessagePartContext";
 export { useComposerRuntime, useComposer } from "./ComposerContext";
 
 export {

package/src/context/stores/AssistantToolUIs.ts

@@ -1,25 +1,25 @@
 import { create } from "zustand";
-import type { ToolCallContentPartComponent } from "../../types/ContentPartComponentTypes";
+import type { ToolCallMessagePartComponent } from "../../types/MessagePartComponentTypes";
 import { Unsubscribe } from "../../types";
 
 export type AssistantToolUIsState = {
   /**
    * Get the tool UI configured for a given tool name.
    */
-  getToolUI: (toolName: string) => ToolCallContentPartComponent | null;
+  getToolUI: (toolName: string) => ToolCallMessagePartComponent | null;
 
   /**
    * Registers a tool UI for a given tool name. Returns an unsubscribe function to remove the tool UI.
    */
   setToolUI: (
     toolName: string,
-    render: ToolCallContentPartComponent,
+    render: ToolCallMessagePartComponent,
   ) => Unsubscribe;
 };
 
 export const makeAssistantToolUIsStore = () =>
   create<AssistantToolUIsState>((set) => {
-    const renderers = new Map<string, ToolCallContentPartComponent[]>();
+    const renderers = new Map<string, ToolCallMessagePartComponent[]>();
 
     return Object.freeze({
       getToolUI: (name) => {

package/src/model-context/useAssistantTool.tsx

@@ -5,7 +5,7 @@ import {
   useAssistantRuntime,
   useToolUIsStore,
 } from "../context/react/AssistantContext";
-import type { ToolCallContentPartComponent } from "../types/ContentPartComponentTypes";
+import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
 import type { Tool } from "assistant-stream";
 
 export type AssistantToolProps<
@@ -13,7 +13,7 @@ export type AssistantToolProps<
   TResult,
 > = Tool<TArgs, TResult> & {
   toolName: string;
-  render?: ToolCallContentPartComponent<TArgs, TResult> | undefined;
+  render?: ToolCallMessagePartComponent<TArgs, TResult> | undefined;
 };
 
 export const useAssistantTool = <

package/src/model-context/useAssistantToolUI.tsx

@@ -2,11 +2,11 @@
 
 import { useEffect } from "react";
 import { useToolUIsStore } from "../context/react/AssistantContext";
-import type { ToolCallContentPartComponent } from "../types/ContentPartComponentTypes";
+import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
 
 export type AssistantToolUIProps<TArgs, TResult> = {
   toolName: string;
-  render: ToolCallContentPartComponent<TArgs, TResult>;
+  render: ToolCallMessagePartComponent<TArgs, TResult>;
 };
 
 export const useAssistantToolUI = (

package/src/model-context/useInlineRender.tsx

@@ -1,12 +1,12 @@
 "use client";
 
 import { FC, useCallback, useEffect, useState } from "react";
-import { ToolCallContentPartProps } from "../types";
+import { ToolCallMessagePartProps } from "../types";
 import { create } from "zustand";
 
 export const useInlineRender = <TArgs, TResult>(
-  toolUI: FC<ToolCallContentPartProps<TArgs, TResult>>,
-): FC<ToolCallContentPartProps<TArgs, TResult>> => {
+  toolUI: FC<ToolCallMessagePartProps<TArgs, TResult>>,
+): FC<ToolCallMessagePartProps<TArgs, TResult>> => {
   const [useToolUIStore] = useState(() =>
     create(() => ({
       toolUI,