@assistant-ui/mcp-docs-server 0.1.31 → 0.1.33

package/.docs/raw/docs/(reference)/api-reference/hooks/primitives.mdx

@@ -0,0 +1,640 @@
+---
+title: Primitive Hooks
+description: Primitive hooks for reading scoped assistant-ui runtime state, viewport behavior, timing, and message part data inside React components.
+---
+
+import { useAssistantRuntime, useAttachmentRuntime, useCloudThreadListAdapter, useComposerRuntime, useEditComposerAttachmentRuntime, useMessageAttachmentRuntime, useMessagePartData, useMessagePartRuntime, useMessageRuntime, useScrollLock, useThreadComposerAttachmentRuntime, useThreadListItemRuntime, useThreadRuntime, useThreadViewportAutoScroll } from "@/generated/typeDocs";
+
+{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
+{/* Do not edit manually. */}
+
+{/* api-reference:start */}
+{/* AUTO-GENERATED by scripts/generate-api-reference.mts */}
+{/* Do not edit this block manually. */}
+
+## API Reference
+
+### useAssistantRuntime
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAui](/docs/api-reference/hooks/state#useaui) instead. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+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.
+
+```tsx
+// Before:
+function MyComponent() {
+  const runtime = useAssistantRuntime();
+  const handleNewThread = () => {
+    runtime.switchToNewThread();
+  };
+  return <button onClick={handleNewThread}>New Thread</button>;
+}
+
+// After:
+function MyComponent() {
+  const aui = useAui();
+  const handleNewThread = () => {
+    aui.threads().switchToNewThread();
+  };
+  return <button onClick={handleNewThread}>New Thread</button>;
+}
+```
+
+<ParametersTable {...useAssistantRuntime} />
+
+### useAttachment
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#useauistate): `useAuiState((s) => s.attachment)`. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+```ts
+const useAttachment: { (): AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }; <TSelected>(selector: (state: AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }) => TSelected): TSelected; <TSelected>(selector: ((state: AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }) => TSelected) | undefined): (AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }) | TSelected; (options: { optional?: false | undefined; }): AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }; (options: { optional?: boolean | undefined; }): (AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }) | null; <TSelected>(options: { optional?: false | undefined; selector: (state: AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }) => TSelected) | undefined; }): (AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }) | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }) => TSelected) | undefined; }): (AttachmentState & { source: "message" | "thread-composer" | "edit-composer"; }) | TSelected | null; };
+```
+
+### useAttachmentRuntime
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAui](/docs/api-reference/hooks/state#useaui) with `aui.attachment()` instead. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+<ParametersTable {...useAttachmentRuntime} />
+
+### useCloudThreadListAdapter
+
+<ParametersTable {...useCloudThreadListAdapter} />
+
+### useComposer
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#useauistate): `useAuiState((s) => s.composer)`. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+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.
+
+```tsx
+// Before:
+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>
+  );
+}
+
+// After:
+function ComposerStatus() {
+  const text = useAuiState((s) => s.composer.text);
+  const canSend = useAuiState((s) => s.composer.canSend);
+  const attachmentCount = useAuiState((s) => s.composer.attachments.length);
+  return (
+    <div>
+      Text: {text.length} chars,
+      Attachments: {attachmentCount},
+      Can send: {canSend}
+    </div>
+  );
+}
+```
+
+```ts
+const useComposer: { (): ComposerState; <TSelected>(selector: (state: ComposerState) => TSelected): TSelected; <TSelected>(selector: ((state: ComposerState) => TSelected) | undefined): ComposerState | TSelected; (options: { optional?: false | undefined; }): ComposerState; (options: { optional?: boolean | undefined; }): ComposerState | null; <TSelected>(options: { optional?: false | undefined; selector: (state: ComposerState) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: ComposerState) => TSelected) | undefined; }): ComposerState | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: ComposerState) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: ComposerState) => TSelected) | undefined; }): ComposerState | TSelected | null; };
+```
+
+### useComposerRuntime
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAui](/docs/api-reference/hooks/state#useaui) with `aui.composer()` instead. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+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.
+
+```tsx
+// Before:
+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>
+  );
+}
+
+// After:
+function ComposerActions() {
+  const aui = useAui();
+  const canSend = useAuiState((s) => s.composer.canSend);
+  const canCancel = useAuiState((s) => s.composer.canCancel);
+  const handleSend = () => {
+    if (canSend) {
+      aui.composer().send();
+    }
+  };
+  const handleCancel = () => {
+    if (canCancel) {
+      aui.composer().cancel();
+    }
+  };
+  return (
+    <div>
+      <button onClick={handleSend}>Send</button>
+      <button onClick={handleCancel}>Cancel</button>
+    </div>
+  );
+}
+```
+
+<ParametersTable {...useComposerRuntime} />
+
+### useEditComposer
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#useauistate): `useAuiState((s) => s.message.composer)`. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+```ts
+const useEditComposer: { (): EditComposerState; <TSelected>(selector: (state: EditComposerState) => TSelected): TSelected; <TSelected>(selector: ((state: EditComposerState) => TSelected) | undefined): EditComposerState | TSelected; (options: { optional?: false | undefined; }): EditComposerState; (options: { optional?: boolean | undefined; }): EditComposerState | null; <TSelected>(options: { optional?: false | undefined; selector: (state: EditComposerState) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: EditComposerState) => TSelected) | undefined; }): EditComposerState | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: EditComposerState) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: EditComposerState) => TSelected) | undefined; }): EditComposerState | TSelected | null; };
+```
+
+### useEditComposerAttachment
+
+```ts
+const useEditComposerAttachment: { (): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }); <TSelected>(selector: (state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; })) => TSelected): TSelected; <TSelected>(selector: ((state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; })) => TSelected) | undefined): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | TSelected; (options: { optional?: false | undefined; }): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }); (options: { optional?: boolean | undefined; }): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | null; <TSelected>(options: { optional?: false | undefined; selector: (state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; })) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; })) => TSelected) | undefined; }): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; })) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; })) => TSelected) | undefined; }): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "edit-composer"; } & { source: "edit-composer"; }) | TSelected | null; };
+```
+
+### useEditComposerAttachmentRuntime
+
+<ParametersTable {...useEditComposerAttachmentRuntime} />
+
+### useMessage
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#useauistate): `useAuiState((s) => s.message)`. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+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.
+
+```tsx
+// Before:
+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>
+  );
+}
+
+// After:
+function MessageContent() {
+  const role = useAuiState((s) => s.message.role);
+  const content = useAuiState((s) => s.message.content);
+  const isLoading = useAuiState((s) => s.message.status.type === "running");
+  return (
+    <div className={`message-${role}`}>
+      {isLoading ? "Loading..." : content.map(part => part.text).join("")}
+    </div>
+  );
+}
+```
+
+```ts
+const useMessage: { (): MessageState; <TSelected>(selector: (state: MessageState) => TSelected): TSelected; <TSelected>(selector: ((state: MessageState) => TSelected) | undefined): MessageState | TSelected; (options: { optional?: false | undefined; }): MessageState; (options: { optional?: boolean | undefined; }): MessageState | null; <TSelected>(options: { optional?: false | undefined; selector: (state: MessageState) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: MessageState) => TSelected) | undefined; }): MessageState | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: MessageState) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: MessageState) => TSelected) | undefined; }): MessageState | TSelected | null; };
+```
+
+### useMessageAttachment
+
+```ts
+const useMessageAttachment: { (): { id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }; <TSelected>(selector: (state: { id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }) => TSelected): TSelected; <TSelected>(selector: ((state: { id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }) => TSelected) | undefined): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }) | TSelected; (options: { optional?: false | undefined; }): { id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }; (options: { optional?: boolean | undefined; }): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }) | null; <TSelected>(options: { optional?: false | undefined; selector: (state: { id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: { id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }) => TSelected) | undefined; }): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }) | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: { id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: { id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }) => TSelected) | undefined; }): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "message"; } & { source: "message"; }) | TSelected | null; };
+```
+
+### useMessageAttachmentRuntime
+
+<ParametersTable {...useMessageAttachmentRuntime} />
+
+### useMessagePart
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#useauistate): `useAuiState((s) => s.part)`. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+```ts
+const useMessagePart: { (): MessagePartState; <TSelected>(selector: (state: MessagePartState) => TSelected): TSelected; <TSelected>(selector: ((state: MessagePartState) => TSelected) | undefined): MessagePartState | TSelected; (options: { optional?: false | undefined; }): MessagePartState; (options: { optional?: boolean | undefined; }): MessagePartState | null; <TSelected>(options: { optional?: false | undefined; selector: (state: MessagePartState) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: MessagePartState) => TSelected) | undefined; }): MessagePartState | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: MessagePartState) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: MessagePartState) => TSelected) | undefined; }): MessagePartState | TSelected | null; };
+```
+
+### useMessagePartData
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#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.
+</Callout>
+
+```tsx
+const part = useAuiState((s) =>
+  s.part.type === "data" && (!name || s.part.name === name)
+    ? s.part
+    : null,
+);
+```
+
+See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+
+<ParametersTable {...useMessagePartData} />
+
+### useMessagePartFile
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#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.
+</Callout>
+
+```tsx
+const file = useAuiState((s) => {
+  if (s.part.type !== "file") return null;
+  return s.part;
+});
+```
+
+See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+
+```ts
+const useMessagePartFile: () => FileMessagePart & { readonly status: MessagePartStatus | ToolCallMessagePartStatus; };
+```
+
+### useMessagePartImage
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#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.
+</Callout>
+
+```tsx
+const image = useAuiState((s) => {
+  if (s.part.type !== "image") return null;
+  return s.part;
+});
+```
+
+See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+
+```ts
+const useMessagePartImage: () => ImageMessagePart & { readonly status: MessagePartStatus | ToolCallMessagePartStatus; };
+```
+
+### useMessagePartReasoning
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#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.
+</Callout>
+
+```tsx
+const reasoning = useAuiState((s) => {
+  if (s.part.type !== "reasoning") return null;
+  return s.part;
+});
+```
+
+See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+
+```ts
+const useMessagePartReasoning: () => ReasoningMessagePart & { readonly status: MessagePartStatus | ToolCallMessagePartStatus; };
+```
+
+### useMessagePartRuntime
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAui](/docs/api-reference/hooks/state#useaui) with `aui.part()` instead. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+<ParametersTable {...useMessagePartRuntime} />
+
+### useMessagePartSource
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#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.
+</Callout>
+
+```tsx
+const source = useAuiState((s) => {
+  if (s.part.type !== "source") return null;
+  return s.part;
+});
+```
+
+See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+
+```ts
+const useMessagePartSource: () => ({ readonly type: "source"; readonly sourceType: "url"; readonly id: string; readonly url: string; readonly title?: string; readonly providerMetadata?: SourceProviderMetadata; readonly parentId?: string; } & { readonly status: MessagePartStatus | ToolCallMessagePartStatus; }) | ({ readonly type: "source"; readonly sourceType: "document"; readonly id: string; readonly url?: undefined; readonly title: string; readonly mediaType: string; readonly filename?: string; readonly providerMetadata?: SourceProviderMetadata; readonly parentId?: string; } & { readonly status: MessagePartStatus | ToolCallMessagePartStatus; });
+```
+
+### useMessagePartText
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#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.
+</Callout>
+
+```tsx
+const text = useAuiState((s) => {
+  if (s.part.type !== "text" && s.part.type !== "reasoning") return null;
+  return s.part;
+});
+```
+
+See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+
+```ts
+const useMessagePartText: () => (TextMessagePart & { readonly status: MessagePartStatus | ToolCallMessagePartStatus; }) | (ReasoningMessagePart & { readonly status: MessagePartStatus | ToolCallMessagePartStatus; });
+```
+
+### useMessageQuote
+
+Hook that returns the quote info for the current message, if any.
+
+Reads from `message.metadata.custom.quote`.
+
+```tsx
+function QuoteBlock() {
+  const quote = useMessageQuote();
+  if (!quote) return null;
+  return <blockquote>{quote.text}</blockquote>;
+}
+```
+
+```ts
+const useMessageQuote: () => QuoteInfo;
+```
+
+### useMessageRuntime
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAui](/docs/api-reference/hooks/state#useaui) with `aui.message()` instead. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+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.
+
+```tsx
+// Before:
+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>
+  );
+}
+
+// After:
+function MessageActions() {
+  const aui = useAui();
+  const handleReload = () => {
+    aui.message().reload();
+  };
+  const handleEdit = () => {
+    aui.message().startEdit();
+  };
+  return (
+    <div>
+      <button onClick={handleReload}>Reload</button>
+      <button onClick={handleEdit}>Edit</button>
+    </div>
+  );
+}
+```
+
+<ParametersTable {...useMessageRuntime} />
+
+### useMessageTiming
+
+Hook that returns timing information for the current assistant message.
+
+Reads from `message.metadata.timing`.
+
+```tsx
+function MessageStats() {
+  const timing = useMessageTiming();
+  if (!timing) return null;
+  return <span>{timing.tokensPerSecond?.toFixed(1)} tok/s</span>;
+}
+```
+
+```ts
+const useMessageTiming: () => MessageTiming;
+```
+
+### useRuntimeAdapters
+
+```ts
+type RuntimeAdapters = {
+  modelContext?: ModelContextProvider | undefined;
+  history?: ThreadHistoryAdapter | undefined;
+  attachments?: AttachmentAdapter | undefined;
+};
+
+const useRuntimeAdapters: () => RuntimeAdapters | null;
+```
+
+### useScrollLock
+
+Locks scroll position during collapsible/height animations and hides scrollbar.
+
+This utility prevents page jumps when content height changes during animations,
+providing a smooth user experience. It finds the nearest scrollable ancestor and
+temporarily locks its scroll position while the animation completes.
+
+- Prevents forced reflows: no layout reads, mutations scoped to scrollable parent only
+- Reactive: only intercepts scroll events when browser actually adjusts
+- Cleans up automatically after animation duration
+
+```tsx
+const collapsibleRef = useRef<HTMLDivElement>(null);
+const lockScroll = useScrollLock(collapsibleRef, 200);
+
+const handleCollapse = () => {
+  lockScroll(); // Lock scroll before collapsing
+  setIsOpen(false);
+};
+```
+
+<ParametersTable {...useScrollLock} />
+
+### useThread
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#useauistate): `useAuiState((s) => s.thread)`. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+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.
+
+```tsx
+// Before:
+function ThreadStatus() {
+  const isRunning = useThread((state) => state.isRunning);
+  const messageCount = useThread((state) => state.messages.length);
+  return <div>Running: {isRunning}, Messages: {messageCount}</div>;
+}
+
+// After:
+function ThreadStatus() {
+  const isRunning = useAuiState((s) => s.thread.isRunning);
+  const messageCount = useAuiState((s) => s.thread.messages.length);
+  return <div>Running: {isRunning}, Messages: {messageCount}</div>;
+}
+```
+
+```ts
+const useThread: { (): ThreadState; <TSelected>(selector: (state: ThreadState) => TSelected): TSelected; <TSelected>(selector: ((state: ThreadState) => TSelected) | undefined): ThreadState | TSelected; (options: { optional?: false | undefined; }): ThreadState; (options: { optional?: boolean | undefined; }): ThreadState | null; <TSelected>(options: { optional?: false | undefined; selector: (state: ThreadState) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: ThreadState) => TSelected) | undefined; }): ThreadState | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: ThreadState) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: ThreadState) => TSelected) | undefined; }): ThreadState | TSelected | null; };
+```
+
+### useThreadComposer
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#useauistate): `useAuiState((s) => s.thread.composer)`. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+```ts
+const useThreadComposer: { (): ThreadComposerState; <TSelected>(selector: (state: ThreadComposerState) => TSelected): TSelected; <TSelected>(selector: ((state: ThreadComposerState) => TSelected) | undefined): ThreadComposerState | TSelected; (options: { optional?: false | undefined; }): ThreadComposerState; (options: { optional?: boolean | undefined; }): ThreadComposerState | null; <TSelected>(options: { optional?: false | undefined; selector: (state: ThreadComposerState) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: ThreadComposerState) => TSelected) | undefined; }): ThreadComposerState | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: ThreadComposerState) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: ThreadComposerState) => TSelected) | undefined; }): ThreadComposerState | TSelected | null; };
+```
+
+### useThreadComposerAttachment
+
+```ts
+const useThreadComposerAttachment: { (): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }); <TSelected>(selector: (state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; })) => TSelected): TSelected; <TSelected>(selector: ((state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; })) => TSelected) | undefined): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | TSelected; (options: { optional?: false | undefined; }): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }); (options: { optional?: boolean | undefined; }): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | null; <TSelected>(options: { optional?: false | undefined; selector: (state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; })) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; })) => TSelected) | undefined; }): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; })) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; })) => TSelected) | undefined; }): ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: PendingAttachmentStatus; file: File; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | ({ id: string; type: "image" | "document" | "file" | (string & {}); name: string; contentType?: string | undefined; file?: File; content?: ThreadUserMessagePart[]; } & { status: CompleteAttachmentStatus; content: ThreadUserMessagePart[]; } & { readonly source: "thread-composer"; } & { source: "thread-composer"; }) | TSelected | null; };
+```
+
+### useThreadComposerAttachmentRuntime
+
+<ParametersTable {...useThreadComposerAttachmentRuntime} />
+
+### useThreadList
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#useauistate): `useAuiState((s) => s.threads)`. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+```ts
+const useThreadList: { (): ThreadListState; <TSelected>(selector: (state: ThreadListState) => TSelected): TSelected; <TSelected>(selector: ((state: ThreadListState) => TSelected) | undefined): ThreadListState | TSelected; (options: { optional?: false | undefined; }): ThreadListState; (options: { optional?: boolean | undefined; }): ThreadListState | null; <TSelected>(options: { optional?: false | undefined; selector: (state: ThreadListState) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: ThreadListState) => TSelected) | undefined; }): ThreadListState | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: ThreadListState) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: ThreadListState) => TSelected) | undefined; }): ThreadListState | TSelected | null; };
+```
+
+### useThreadListItem
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAuiState](/docs/api-reference/hooks/state#useauistate): `useAuiState((s) => s.threadListItem)`. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+```ts
+const useThreadListItem: { (): ThreadListItemState; <TSelected>(selector: (state: ThreadListItemState) => TSelected): TSelected; <TSelected>(selector: ((state: ThreadListItemState) => TSelected) | undefined): ThreadListItemState | TSelected; (options: { optional?: false | undefined; }): ThreadListItemState; (options: { optional?: boolean | undefined; }): ThreadListItemState | null; <TSelected>(options: { optional?: false | undefined; selector: (state: ThreadListItemState) => TSelected; }): TSelected; <TSelected>(options: { optional?: false | undefined; selector: ((state: ThreadListItemState) => TSelected) | undefined; }): ThreadListItemState | TSelected; <TSelected>(options: { optional?: boolean | undefined; selector: (state: ThreadListItemState) => TSelected; }): TSelected | null; <TSelected>(options: { optional?: boolean | undefined; selector: ((state: ThreadListItemState) => TSelected) | undefined; }): ThreadListItemState | TSelected | null; };
+```
+
+### useThreadListItemRuntime
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAui](/docs/api-reference/hooks/state#useaui) with `aui.threadListItem()` instead. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+<ParametersTable {...useThreadListItemRuntime} />
+
+### useThreadRuntime
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [useAui](/docs/api-reference/hooks/state#useaui) with `aui.thread()` instead. See the [migration guide](https://assistant-ui.com/docs/migrations/v0-12).
+</Callout>
+
+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.
+
+```tsx
+// Before:
+function MyComponent() {
+  const runtime = useThreadRuntime();
+  const handleSendMessage = (text: string) => {
+    runtime.append({ role: "user", content: [{ type: "text", text }] });
+  };
+  return <button onClick={() => handleSendMessage("Hello!")}>Send</button>;
+}
+
+// After:
+function MyComponent() {
+  const aui = useAui();
+  const handleSendMessage = (text: string) => {
+    aui.thread().append({ role: "user", content: [{ type: "text", text }] });
+  };
+  return <button onClick={() => handleSendMessage("Hello!")}>Send</button>;
+}
+```
+
+<ParametersTable {...useThreadRuntime} />
+
+### useThreadViewport
+
+```ts
+const useThreadViewport: { (): ThreadViewportState; <TSelected>(selector: (state: ThreadViewportState) => TSelected): TSelected; (options: { optional: true; }): ThreadViewportState | null; <TSelected>(options: { optional: true; selector?: (state: ThreadViewportState) => TSelected; }): TSelected | null; };
+```
+
+### useThreadViewportAutoScroll
+
+<ParametersTable {...useThreadViewportAutoScroll} />
+
+### useThreadViewportStore
+
+```ts
+const useThreadViewportStore: { (): ReadonlyStore<ThreadViewportState>; (options: { optional: true; }): ReadonlyStore<ThreadViewportState> | null; };
+```
+{/* api-reference:end */}