@assistant-ui/react 0.14.5 → 0.14.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/react",
-  "version": "0.14.5",
+  "version": "0.14.7",
   "description": "Open-source TypeScript/React library for building production-grade AI chat experiences",
   "keywords": [
     "radix-ui",
@@ -47,16 +47,9 @@
     "README.md"
   ],
   "sideEffects": false,
-  "scripts": {
-    "prepack": "cp ../../README.md /tmp/aui-readme-pack.md && mv /tmp/aui-readme-pack.md ./README.md",
-    "postpack": "rm -f ./README.md && ln -s ../../README.md ./README.md",
-    "build": "aui-build",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {
-    "@assistant-ui/core": "^0.2.2",
-    "@assistant-ui/store": "^0.2.10",
+    "@assistant-ui/core": "^0.2.4",
+    "@assistant-ui/store": "^0.2.11",
     "@assistant-ui/tap": "^0.5.11",
     "@radix-ui/primitive": "^1.1.3",
     "@radix-ui/react-compose-refs": "^1.1.2",
@@ -64,8 +57,8 @@
     "@radix-ui/react-primitive": "^2.1.4",
     "@radix-ui/react-use-callback-ref": "^1.1.1",
     "@radix-ui/react-use-escape-keydown": "^1.1.1",
-    "assistant-cloud": "^0.1.27",
-    "assistant-stream": "^0.3.14",
+    "assistant-cloud": "^0.1.28",
+    "assistant-stream": "^0.3.15",
     "nanoid": "^5.1.11",
     "radix-ui": "^1.4.3",
     "react-textarea-autosize": "^8.5.9",
@@ -88,7 +81,6 @@
     }
   },
   "devDependencies": {
-    "@assistant-ui/x-buildutils": "workspace:*",
     "@testing-library/react": "^16.3.2",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^25.6.0",
@@ -97,11 +89,12 @@
     "jsdom": "^29.1.1",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.5",
+    "@assistant-ui/x-buildutils": "0.0.8"
   },
   "publishConfig": {
     "access": "public",
-    "provenance": false
+    "provenance": true
   },
   "homepage": "https://www.assistant-ui.com/",
   "repository": {
@@ -111,5 +104,10 @@
   },
   "bugs": {
     "url": "https://github.com/assistant-ui/assistant-ui/issues"
+  },
+  "scripts": {
+    "build": "aui-build",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}

package/src/index.ts

@@ -378,6 +378,12 @@ export {
   type RegisteredTrigger as Unstable_RegisteredTrigger,
   type TriggerBehavior as Unstable_TriggerBehavior,
 } from "./primitives/composer/trigger";
+export type {
+  Unstable_DirectiveFormatter,
+  Unstable_DirectiveSegment,
+  Unstable_TriggerItem,
+} from "@assistant-ui/core";
+export { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
 
 export type { Assistant } from "./augmentations";
 

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/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")