@assistant-ui/react 0.14.4 → 0.14.6

package/src/legacy-runtime/AssistantRuntimeProvider.tsx

@@ -10,12 +10,18 @@ import { DevToolsProviderApi } from "../devtools/DevToolsHooks";
 export namespace AssistantRuntimeProvider {
   export type Props = PropsWithChildren<{
     /**
-     * The runtime to provide to the rest of your app.
+     * The assistant runtime to expose to descendants. Build one with
+     * `useLocalRuntime`, `useExternalStoreRuntime`, or
+     * `useAssistantTransportRuntime`.
      */
     runtime: AssistantRuntime;
 
     /**
-     * The aui instance to extend. If not provided, a new aui instance will be created.
+     * Optional parent `AssistantClient` whose scopes are inherited by the
+     * client created for this runtime. Use this when nesting an
+     * `AssistantRuntimeProvider` inside another assistant context. Omit this
+     * prop when there is no parent client.
+     * @defaultValue undefined
      */
     aui?: AssistantClient;
   }>;

package/src/legacy-runtime/hooks/AssistantContext.ts

@@ -6,7 +6,7 @@ import type { ThreadListRuntime } from "../runtime/ThreadListRuntime";
 import { createStateHookForRuntime } from "../../context/react/utils/createStateHookForRuntime";
 
 /**
- * @deprecated Use `useAui()` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAui} instead. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  *
  * Hook to access the AssistantRuntime from the current context.
  *
@@ -62,6 +62,6 @@ const useThreadListRuntime = (opt: {
 }): ThreadListRuntime | null => useAssistantRuntime(opt)?.threads ?? null;
 
 /**
- * @deprecated Use `useAuiState((s) => s.threads)` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAuiState}: `useAuiState((s) => s.threads)`. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useThreadList = createStateHookForRuntime(useThreadListRuntime);

package/src/legacy-runtime/hooks/AttachmentContext.ts

@@ -5,7 +5,7 @@ import { createStateHookForRuntime } from "../../context/react/utils/createState
 import { useAui, useAuiState } from "@assistant-ui/store";
 
 /**
- * @deprecated Use `useAui()` with `aui.attachment()` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAui} with `aui.attachment()` instead. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export function useAttachmentRuntime(options?: {
   optional?: false | undefined;
@@ -84,7 +84,7 @@ export function useMessageAttachmentRuntime(options?: {
 }
 
 /**
- * @deprecated Use `useAuiState((s) => s.attachment)` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAuiState}: `useAuiState((s) => s.attachment)`. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useAttachment = createStateHookForRuntime(useAttachmentRuntime);
 

package/src/legacy-runtime/hooks/ComposerContext.ts

@@ -5,7 +5,7 @@ import type { ComposerRuntime } from "../runtime/ComposerRuntime";
 import { createStateHookForRuntime } from "../../context/react/utils/createStateHookForRuntime";
 
 /**
- * @deprecated Use `useAui()` with `aui.composer()` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAui} with `aui.composer()` instead. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  *
  * Hook to access the ComposerRuntime from the current context.
  *
@@ -87,7 +87,7 @@ export function useComposerRuntime(options?: {
 }
 
 /**
- * @deprecated Use `useAuiState((s) => s.composer)` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAuiState}: `useAuiState((s) => s.composer)`. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  *
  * Hook to access the current composer state.
  *

package/src/legacy-runtime/hooks/MessageContext.ts

@@ -6,7 +6,7 @@ import { createStateHookForRuntime } from "../../context/react/utils/createState
 import type { EditComposerRuntime } from "@assistant-ui/core";
 
 /**
- * @deprecated Use `useAui()` with `aui.message()` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAui} with `aui.message()` instead. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  *
  * Hook to access the MessageRuntime from the current context.
  *
@@ -76,7 +76,7 @@ export function useMessageRuntime(options?: {
 }
 
 /**
- * @deprecated Use `useAuiState((s) => s.message)` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAuiState}: `useAuiState((s) => s.message)`. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  *
  * Hook to access the current message state.
  *
@@ -120,7 +120,7 @@ const useEditComposerRuntime = (opt: {
 }): EditComposerRuntime | null => useMessageRuntime(opt)?.composer ?? null;
 
 /**
- * @deprecated Use `useAuiState((s) => s.message.composer)` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAuiState}: `useAuiState((s) => s.message.composer)`. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useEditComposer = createStateHookForRuntime(
   useEditComposerRuntime,

package/src/legacy-runtime/hooks/MessagePartContext.ts

@@ -5,7 +5,7 @@ import { createStateHookForRuntime } from "../../context/react/utils/createState
 import { useAui, useAuiState } from "@assistant-ui/store";
 
 /**
- * @deprecated Use `useAui()` with `aui.part()` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAui} with `aui.part()` instead. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export function useMessagePartRuntime(options?: {
   optional?: false | undefined;
@@ -27,6 +27,6 @@ export function useMessagePartRuntime(options?: {
 }
 
 /**
- * @deprecated Use `useAuiState((s) => s.part)` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAuiState}: `useAuiState((s) => s.part)`. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useMessagePart = createStateHookForRuntime(useMessagePartRuntime);

package/src/legacy-runtime/hooks/ThreadContext.ts

@@ -8,7 +8,7 @@ import type { ThreadComposerRuntime } from "@assistant-ui/core";
 import { useAui, useAuiEvent, useAuiState } from "@assistant-ui/store";
 
 /**
- * @deprecated Use `useAui()` with `aui.thread()` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAui} with `aui.thread()` instead. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  *
  * Hook to access the ThreadRuntime from the current context.
  *
@@ -58,7 +58,7 @@ export function useThreadRuntime(options?: { optional?: boolean | undefined }) {
 }
 
 /**
- * @deprecated Use `useAuiState((s) => s.thread)` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAuiState}: `useAuiState((s) => s.thread)`. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  *
  * Hook to access the current thread state.
  *
@@ -92,14 +92,14 @@ const useThreadComposerRuntime = (opt: {
 }): ThreadComposerRuntime | null => useThreadRuntime(opt)?.composer ?? null;
 
 /**
- * @deprecated Use `useAuiState((s) => s.thread.composer)` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAuiState}: `useAuiState((s) => s.thread.composer)`. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useThreadComposer = createStateHookForRuntime(
   useThreadComposerRuntime,
 );
 
 /**
- * @deprecated Use `useAuiState((s) => s.thread.modelContext)` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAuiState}: `useAuiState((s) => s.thread.modelContext)`. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export function useThreadModelContext(options?: {
   optional?: false | undefined;

package/src/legacy-runtime/hooks/ThreadListItemContext.ts

@@ -5,7 +5,7 @@ import { createStateHookForRuntime } from "../../context/react/utils/createState
 import { useAui, useAuiState } from "@assistant-ui/store";
 
 /**
- * @deprecated Use `useAui()` with `aui.threadListItem()` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAui} with `aui.threadListItem()` instead. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export function useThreadListItemRuntime(options?: {
   optional?: false | undefined;
@@ -29,7 +29,7 @@ export function useThreadListItemRuntime(options?: {
 }
 
 /**
- * @deprecated Use `useAuiState((s) => s.threadListItem)` instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12
+ * @deprecated Use {@link useAuiState}: `useAuiState((s) => s.threadListItem)`. See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useThreadListItem = createStateHookForRuntime(
   useThreadListItemRuntime,

package/src/legacy-runtime/runtime-cores/assistant-transport/useToolInvocations.test.ts

@@ -635,4 +635,258 @@ describe("useToolInvocations", () => {
       expect(onResult).not.toHaveBeenCalled();
     });
   });
+
+  it("fires streamCall for already-resolved tool calls loaded after the initial snapshot", async () => {
+    const execute = vi.fn(async () => ({ forecast: "ok" }));
+    const streamCall = vi.fn();
+    const getTools = () => ({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        execute,
+        streamCall,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const setToolStatuses = vi.fn();
+
+    const { rerender } = renderHook(
+      ({ state }: { state: AssistantTransportState }) =>
+        useToolInvocations({
+          state,
+          getTools,
+          onResult,
+          setToolStatuses,
+        }),
+      {
+        initialProps: {
+          state: createState([]),
+        },
+      },
+    );
+
+    act(() => {
+      rerender({
+        state: createState([
+          createAssistantMessage(
+            '{"query":"London"}',
+            { query: "London" },
+            { result: { source: "history" } },
+          ),
+        ]),
+      });
+    });
+
+    await waitFor(() => {
+      expect(streamCall).toHaveBeenCalledTimes(1);
+    });
+
+    const [reader] = streamCall.mock.calls[0]!;
+    await expect(reader.args.get("query")).resolves.toBe("London");
+    const response = await reader.response.get();
+    expect(response.result).toEqual({ source: "history" });
+
+    expect(execute).not.toHaveBeenCalled();
+    expect(onResult).not.toHaveBeenCalled();
+    expect(setToolStatuses).not.toHaveBeenCalled();
+  });
+
+  it("does not fire streamCall for tool calls present in the initial snapshot", async () => {
+    const streamCall = vi.fn();
+    const getTools = () => ({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        streamCall,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const setToolStatuses = vi.fn();
+
+    renderHook(
+      ({ state }: { state: AssistantTransportState }) =>
+        useToolInvocations({
+          state,
+          getTools,
+          onResult,
+          setToolStatuses,
+        }),
+      {
+        initialProps: {
+          state: createState([
+            createAssistantMessage(
+              '{"query":"London"}',
+              { query: "London" },
+              { result: { source: "history" } },
+            ),
+          ]),
+        },
+      },
+    );
+
+    await act(async () => {});
+    expect(streamCall).not.toHaveBeenCalled();
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("promotes an in-progress tool call from the initial snapshot when it changes", async () => {
+    const execute = vi.fn(async () => ({ forecast: "ok" }));
+    const streamCall = vi.fn();
+    const getTools = () => ({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        execute,
+        streamCall,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const setToolStatuses = vi.fn();
+
+    const { rerender } = renderHook(
+      ({ state }: { state: AssistantTransportState }) =>
+        useToolInvocations({
+          state,
+          getTools,
+          onResult,
+          setToolStatuses,
+        }),
+      {
+        initialProps: {
+          state: createState([
+            createAssistantMessage('{"query":"Lon', { query: "Lon" }),
+          ]),
+        },
+      },
+    );
+
+    await act(async () => {});
+    expect(streamCall).not.toHaveBeenCalled();
+
+    act(() => {
+      rerender({
+        state: createState([
+          createAssistantMessage(
+            '{"query":"London"}',
+            { query: "London" },
+            { result: { source: "history" } },
+          ),
+        ]),
+      });
+    });
+
+    await waitFor(() => {
+      expect(streamCall).toHaveBeenCalledTimes(1);
+    });
+
+    const [reader] = streamCall.mock.calls[0]!;
+    await expect(reader.args.get("query")).resolves.toBe("London");
+    const response = await reader.response.get();
+    expect(response.result).toEqual({ source: "history" });
+
+    expect(execute).not.toHaveBeenCalled();
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("does not re-fire streamCall when an initial-snapshot tool call is unchanged in later snapshots", async () => {
+    const streamCall = vi.fn();
+    const getTools = () => ({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        streamCall,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const setToolStatuses = vi.fn();
+
+    const { rerender } = renderHook(
+      ({ state }: { state: AssistantTransportState }) =>
+        useToolInvocations({
+          state,
+          getTools,
+          onResult,
+          setToolStatuses,
+        }),
+      {
+        initialProps: {
+          state: createState([
+            createAssistantMessage(
+              '{"query":"London"}',
+              { query: "London" },
+              { result: { source: "history" } },
+            ),
+          ]),
+        },
+      },
+    );
+
+    act(() => {
+      rerender({
+        state: createState([
+          createAssistantMessage(
+            '{"query":"London"}',
+            { query: "London" },
+            { result: { source: "history" } },
+          ),
+        ]),
+      });
+    });
+
+    await act(async () => {});
+    expect(streamCall).not.toHaveBeenCalled();
+  });
+
+  it("does not emit a cancellation onResult for pre-resolved tool calls aborted by reset", async () => {
+    const streamCall = vi.fn();
+    const getTools = () => ({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        execute: vi.fn(async () => ({ forecast: "ok" })),
+        streamCall,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const setToolStatuses = vi.fn();
+
+    const { result, rerender } = renderHook(
+      ({ state }: { state: AssistantTransportState }) =>
+        useToolInvocations({
+          state,
+          getTools,
+          onResult,
+          setToolStatuses,
+        }),
+      {
+        initialProps: {
+          state: createState([]),
+        },
+      },
+    );
+
+    act(() => {
+      rerender({
+        state: createState([
+          createAssistantMessage(
+            '{"query":"London"}',
+            { query: "London" },
+            { result: { source: "history" } },
+          ),
+        ]),
+      });
+    });
+
+    await waitFor(() => {
+      expect(streamCall).toHaveBeenCalledTimes(1);
+    });
+
+    act(() => {
+      result.current.reset();
+    });
+
+    // Flush microtasks through the executor's abort race + the stream
+    // pipeline so any cancellation `result` chunk has a chance to land
+    // before we assert it didn't.
+    for (let i = 0; i < 5; i++) {
+      await act(async () => {});
+    }
+
+    expect(onResult).not.toHaveBeenCalled();
+  });
 });

package/src/mcp-apps/McpAppRenderer.tsx

@@ -192,6 +192,14 @@ function InlineRenderer({
   );
 }
 
+/**
+ * Creates a tool-call renderer for MCP Apps embedded in assistant messages.
+ *
+ * Compose this into the `Tools` resource through its `mcpApp` option. When a
+ * tool-call part carries `mcp.app` metadata for a `ui://` resource, the
+ * renderer loads that resource from the configured host and displays it in a
+ * sandboxed frame.
+ */
 export const McpAppRenderer = resource(
   (
     options: McpAppRendererOptions,

package/src/mcp-apps/McpAppsRemoteHost.ts

@@ -26,6 +26,13 @@ async function postToHost(
   return res.json();
 }
 
+/**
+ * Creates the default HTTP host for MCP App widgets.
+ *
+ * The host POSTs widget requests to the configured route as `{ method,
+ * params }`, using the method names expected by the assistant-ui MCP Apps
+ * guide.
+ */
 export const McpAppsRemoteHost = resource(
   (options: McpAppsRemoteHostOptions): McpAppsHost => {
     const optionsRef = tapRef(options);

package/src/mcp-apps/bridge.ts

@@ -42,6 +42,22 @@ const DEFAULT_HOST_INFO: McpAppHostInfo = {
   version: "0.1",
 };
 
+// Accept both the legacy method names and the MCP-UI 2026-01-26 names that
+// `ui/*` capable widgets (e.g. xmcp's host-bridge) emit. Normalize on input
+// so downstream switch statements only need to know the legacy names.
+const METHOD_ALIASES: Record<string, string> = {
+  "ui/notifications/initialized": "notifications/initialized",
+  "ui/notifications/size-changed": "notifications/size_changed",
+  "ui/request-display-mode": "requestDisplayMode",
+  "ui/open-link": "openLink",
+  "ui/update-model-context": "updateModelContext",
+  "ui/message": "sendMessage",
+  "notifications/message": "notifications/log",
+};
+
+const normalizeMethod = (method: string): string =>
+  METHOD_ALIASES[method] ?? method;
+
 const JSONRPC_ERROR = {
   parseError: -32700,
   invalidRequest: -32600,
@@ -118,7 +134,7 @@ export function createMcpAppBridge(
     try {
       const params = req.params;
 
-      switch (req.method) {
+      switch (normalizeMethod(req.method)) {
         case "ui/initialize": {
           respond(req.id, {
             result: {
@@ -356,7 +372,7 @@ export function createMcpAppBridge(
   };
 
   const handleNotification = (note: McpAppJsonRpcNotification) => {
-    switch (note.method) {
+    switch (normalizeMethod(note.method)) {
       case "notifications/initialized": {
         handlers.onInitialized?.();
         return;

package/src/mcp-apps/utils.ts

@@ -6,6 +6,13 @@ import {
 
 type ToolPartLike = Pick<ToolCallMessagePart, "mcp">;
 
+/**
+ * Returns MCP app metadata for a tool-call part that points at a `ui://`
+ * resource.
+ *
+ * Returns `undefined` when the part has no MCP app metadata or the metadata
+ * does not reference an assistant-ui MCP app resource.
+ */
 export function getMcpAppFromToolPart(
   part: ToolPartLike,
 ): McpAppMetadata | undefined {

package/src/primitives/actionBar/ActionBarCopy.tsx

@@ -38,7 +38,12 @@ const useActionBarPrimitiveCopy = ({
 } = {}) => {
   const { copy, disabled } = useActionBarCopy({
     copiedDuration,
-    copyToClipboard: (text) => navigator.clipboard.writeText(text),
+    copyToClipboard: (text) => {
+      if (typeof navigator === "undefined" || !navigator.clipboard) {
+        return Promise.reject(new Error("Clipboard API is unavailable"));
+      }
+      return navigator.clipboard.writeText(text);
+    },
   });
   if (disabled) return null;
   return copy;

package/src/primitives/messagePart/MessagePartInProgress.ts

@@ -1,19 +1,3 @@
 "use client";
 
-import type { FC, PropsWithChildren } from "react";
-import { useAuiState } from "@assistant-ui/store";
-
-export namespace MessagePartPrimitiveInProgress {
-  export type Props = PropsWithChildren;
-}
-
-// TODO should this be renamed to IsRunning?
-export const MessagePartPrimitiveInProgress: FC<
-  MessagePartPrimitiveInProgress.Props
-> = ({ children }) => {
-  const isInProgress = useAuiState((s) => s.part.status.type === "running");
-
-  return isInProgress ? children : null;
-};
-
-MessagePartPrimitiveInProgress.displayName = "MessagePartPrimitive.InProgress";
+export { MessagePartPrimitiveInProgress } from "@assistant-ui/core/react";

package/src/primitives/messagePart/useMessagePartData.ts

@@ -3,6 +3,22 @@
 import type { DataMessagePart } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering, or throw inside the selector to
+ * preserve the old hook's strict behavior.
+ *
+ * @example
+ * ```tsx
+ * const part = useAuiState((s) =>
+ *   s.part.type === "data" && (!name || s.part.name === name)
+ *     ? s.part
+ *     : null,
+ * );
+ * ```
+ *
+ * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
+ */
 export const useMessagePartData = <T = any>(name?: string) => {
   const part = useAuiState((s) => {
     if (s.part.type !== "data") {

package/src/primitives/messagePart/useMessagePartFile.ts

@@ -3,6 +3,21 @@
 import type { FileMessagePart, MessagePartState } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering, or throw inside the selector to
+ * preserve the old hook's strict behavior.
+ *
+ * @example
+ * ```tsx
+ * const file = useAuiState((s) => {
+ *   if (s.part.type !== "file") return null;
+ *   return s.part;
+ * });
+ * ```
+ *
+ * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
+ */
 export const useMessagePartFile = () => {
   const file = useAuiState((s) => {
     if (s.part.type !== "file")

package/src/primitives/messagePart/useMessagePartImage.ts

@@ -3,6 +3,21 @@
 import type { ImageMessagePart, MessagePartState } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering, or throw inside the selector to
+ * preserve the old hook's strict behavior.
+ *
+ * @example
+ * ```tsx
+ * const image = useAuiState((s) => {
+ *   if (s.part.type !== "image") return null;
+ *   return s.part;
+ * });
+ * ```
+ *
+ * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
+ */
 export const useMessagePartImage = () => {
   const image = useAuiState((s) => {
     if (s.part.type !== "image")

package/src/primitives/messagePart/useMessagePartReasoning.ts

@@ -6,6 +6,21 @@ import type {
 } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering, or throw inside the selector to
+ * preserve the old hook's strict behavior.
+ *
+ * @example
+ * ```tsx
+ * const reasoning = useAuiState((s) => {
+ *   if (s.part.type !== "reasoning") return null;
+ *   return s.part;
+ * });
+ * ```
+ *
+ * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
+ */
 export const useMessagePartReasoning = () => {
   const text = useAuiState((s) => {
     if (s.part.type !== "reasoning")

package/src/primitives/messagePart/useMessagePartSource.ts

@@ -3,6 +3,21 @@
 import type { SourceMessagePart, MessagePartState } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering, or throw inside the selector to
+ * preserve the old hook's strict behavior.
+ *
+ * @example
+ * ```tsx
+ * const source = useAuiState((s) => {
+ *   if (s.part.type !== "source") return null;
+ *   return s.part;
+ * });
+ * ```
+ *
+ * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
+ */
 export const useMessagePartSource = () => {
   const source = useAuiState((s) => {
     if (s.part.type !== "source")