@assistant-ui/react 0.14.27 → 0.14.29

package/src/primitives/composer/ComposerInput.test.tsx

@@ -9,6 +9,7 @@ import { ComposerPrimitiveInput } from "./ComposerInput";
 const setText = vi.fn<(text: string) => void>();
 const setCursorPosition = vi.fn<(pos: number) => void>();
 const sendSpy = vi.fn<(options?: { steer?: boolean }) => void>();
+const addAttachment = vi.fn<(file: File) => Promise<void>>();
 
 const composerState = {
   isEditing: true,
@@ -42,7 +43,7 @@ vi.mock("@assistant-ui/store", () => {
       getState: () => composerState,
       cancel: () => {},
       send: sendSpy,
-      addAttachment: async () => {},
+      addAttachment,
     }),
     thread: () => ({
       getState: () => threadState,
@@ -140,6 +141,16 @@ const fireKeyDown = (
   return event;
 };
 
+const firePaste = (textarea: HTMLTextAreaElement, files: File[]) => {
+  const event = new Event("paste", { bubbles: true, cancelable: true });
+  Object.defineProperty(event, "clipboardData", {
+    value: { files },
+    configurable: true,
+  });
+  textarea.dispatchEvent(event);
+  return event;
+};
+
 const setMatchMedia = (matches: boolean) => {
   Object.defineProperty(window, "matchMedia", {
     writable: true,
@@ -169,6 +180,7 @@ describe("ComposerPrimitiveInput", () => {
     setText.mockReset();
     setCursorPosition.mockReset();
     sendSpy.mockReset();
+    addAttachment.mockReset();
     composerState.isEditing = true;
     composerState.text = "";
     composerState.isEmpty = true;
@@ -501,4 +513,89 @@ describe("ComposerPrimitiveInput", () => {
       expect(event.defaultPrevented).toBe(true);
     });
   });
+
+  describe("paste attachments", () => {
+    it("attempts every pasted file and prevents default when attachments are supported", async () => {
+      threadState.capabilities = { queue: false, attachments: true };
+
+      const textarea = await mount();
+
+      let event!: Event;
+      await act(async () => {
+        event = firePaste(textarea, [
+          new File(["a"], "first.txt", { type: "text/plain" }),
+          new File(["b"], "second.txt", { type: "text/plain" }),
+          new File(["c"], "third.txt", { type: "text/plain" }),
+        ]);
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(addAttachment).toHaveBeenCalledTimes(3);
+      expect(addAttachment.mock.calls.map(([file]) => file.name)).toEqual([
+        "first.txt",
+        "second.txt",
+        "third.txt",
+      ]);
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("continues processing other files when one attachment fails without console.error", async () => {
+      threadState.capabilities = { queue: false, attachments: true };
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      addAttachment
+        .mockRejectedValueOnce(new Error("upload failed"))
+        .mockResolvedValueOnce(undefined)
+        .mockResolvedValueOnce(undefined);
+
+      const textarea = await mount();
+
+      await act(async () => {
+        firePaste(textarea, [
+          new File(["a"], "first.txt", { type: "text/plain" }),
+          new File(["b"], "second.txt", { type: "text/plain" }),
+          new File(["c"], "third.txt", { type: "text/plain" }),
+        ]);
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(addAttachment).toHaveBeenCalledTimes(3);
+      expect(errorSpy).not.toHaveBeenCalled();
+      errorSpy.mockRestore();
+    });
+
+    it("does not add attachments on paste when attachments are unsupported", async () => {
+      threadState.capabilities = { queue: false, attachments: false };
+
+      const textarea = await mount();
+
+      let event!: Event;
+      await act(async () => {
+        event = firePaste(textarea, [
+          new File(["a"], "first.txt", { type: "text/plain" }),
+        ]);
+        await Promise.resolve();
+      });
+
+      expect(addAttachment).not.toHaveBeenCalled();
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it("skips attachment handling when addAttachmentOnPaste is false", async () => {
+      threadState.capabilities = { queue: false, attachments: true };
+
+      const textarea = await mount({ addAttachmentOnPaste: false });
+
+      await act(async () => {
+        firePaste(textarea, [
+          new File(["a"], "first.txt", { type: "text/plain" }),
+        ]);
+        await Promise.resolve();
+      });
+
+      expect(addAttachment).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/primitives/composer/ComposerInput.tsx

@@ -271,14 +271,16 @@ export const ComposerPrimitiveInput = forwardRef<
       const files = Array.from(e.clipboardData?.files || []);
 
       if (threadCapabilities.attachments && files.length > 0) {
-        try {
-          e.preventDefault();
-          await Promise.all(
-            files.map((file) => aui.composer().addAttachment(file)),
-          );
-        } catch (error) {
-          console.error("Error adding attachment:", error);
-        }
+        e.preventDefault();
+        await Promise.all(
+          files.map(async (file) => {
+            try {
+              await aui.composer().addAttachment(file);
+            } catch {
+              // The composer runtime emits composer.attachmentAddError before rejecting.
+            }
+          }),
+        );
       }
     };
 

package/src/primitives/composer/ComposerRoot.test.tsx

@@ -1,12 +1,12 @@
-/**
- * @vitest-environment jsdom
- */
+/** @vitest-environment jsdom */
 import { act } from "react";
-import type { ReactNode } from "react";
+import type { MouseEvent, ReactNode } from "react";
+import { createPortal } from "react-dom";
 import { createRoot } from "react-dom/client";
 import type { Root } from "react-dom/client";
 import type * as AssistantStore from "@assistant-ui/store";
 import type * as ComposerSendModule from "./ComposerSend";
+import { fireEvent, render } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { useComposerCompactContextOptional } from "./ComposerCompactContext";
 import type { ComposerCompactContextValue } from "./ComposerCompactContext";
@@ -58,7 +58,228 @@ const resetStoreState = () => {
   storeState.composer.text = "";
 };
 
-describe("ComposerPrimitiveRoot", () => {
+describe("ComposerPrimitiveRoot click-to-focus", () => {
+  beforeEach(() => {
+    resetStoreState();
+  });
+
+  const setupComposer = (props?: ComposerPrimitiveRoot.Props) => {
+    const { getByTestId } = render(
+      <ComposerPrimitiveRoot {...props}>
+        <div data-testid="blank-space">
+          <textarea data-testid="composer-input" />
+        </div>
+      </ComposerPrimitiveRoot>,
+    );
+    return {
+      blankSpace: getByTestId("blank-space"),
+      textarea: getByTestId("composer-input"),
+    };
+  };
+
+  it("focuses the textarea when primary-button mousedown starts on blank form space", () => {
+    const { blankSpace, textarea } = setupComposer();
+
+    fireEvent.mouseDown(blankSpace, { button: 0 });
+
+    expect(document.activeElement).toBe(textarea);
+  });
+
+  it("does not move focus to the textarea when mousedown starts on an interactive child", () => {
+    const { getByTestId } = render(
+      <ComposerPrimitiveRoot>
+        <button data-testid="interactive-child" type="button">
+          Action
+        </button>
+        <textarea data-testid="composer-input" />
+      </ComposerPrimitiveRoot>,
+    );
+
+    const notPrevented = fireEvent.mouseDown(getByTestId("interactive-child"), {
+      button: 0,
+    });
+
+    expect(notPrevented).toBe(true);
+    expect(document.activeElement).not.toBe(getByTestId("composer-input"));
+  });
+
+  it("does not steal focus from a role-based widget carrying a tabindex", () => {
+    const { getByTestId } = render(
+      <ComposerPrimitiveRoot>
+        <div role="slider" tabIndex={0} data-testid="widget" />
+        <textarea data-testid="composer-input" />
+      </ComposerPrimitiveRoot>,
+    );
+
+    const notPrevented = fireEvent.mouseDown(getByTestId("widget"), {
+      button: 0,
+    });
+
+    expect(notPrevented).toBe(true);
+    expect(document.activeElement).not.toBe(getByTestId("composer-input"));
+  });
+
+  it("does not steal focus from a roving-tabindex child with tabindex=-1", () => {
+    const { getByTestId } = render(
+      <ComposerPrimitiveRoot>
+        <span tabIndex={-1} data-testid="roving-item">
+          Item
+        </span>
+        <textarea data-testid="composer-input" />
+      </ComposerPrimitiveRoot>,
+    );
+
+    const notPrevented = fireEvent.mouseDown(getByTestId("roving-item"), {
+      button: 0,
+    });
+
+    expect(notPrevented).toBe(true);
+    expect(document.activeElement).not.toBe(getByTestId("composer-input"));
+  });
+
+  it("does not move focus to the textarea on non-primary mousedown", () => {
+    const { blankSpace, textarea } = setupComposer();
+
+    const notPrevented = fireEvent.mouseDown(blankSpace, { button: 2 });
+
+    expect(notPrevented).toBe(true);
+    expect(document.activeElement).not.toBe(textarea);
+  });
+
+  it("focuses a contenteditable composer target when primary-button mousedown starts on blank form space", () => {
+    const { getByTestId } = render(
+      <ComposerPrimitiveRoot>
+        <div data-testid="blank-space">
+          <div contentEditable data-testid="composer-input" tabIndex={0} />
+        </div>
+      </ComposerPrimitiveRoot>,
+    );
+
+    fireEvent.mouseDown(getByTestId("blank-space"), { button: 0 });
+
+    expect(document.activeElement).toBe(getByTestId("composer-input"));
+  });
+
+  it("still focuses the textarea when the form is hosted inside a tabindex=-1 wrapper", () => {
+    const { getByTestId } = render(
+      <div tabIndex={-1}>
+        <ComposerPrimitiveRoot>
+          <div data-testid="blank-space">
+            <textarea data-testid="composer-input" />
+          </div>
+        </ComposerPrimitiveRoot>
+      </div>,
+    );
+
+    fireEvent.mouseDown(getByTestId("blank-space"), { button: 0 });
+
+    expect(document.activeElement).toBe(getByTestId("composer-input"));
+  });
+
+  it("ignores mousedown on portaled descendants rendered outside the form's DOM", () => {
+    const { getByTestId } = render(
+      <ComposerPrimitiveRoot>
+        {createPortal(<div data-testid="portal-blank" />, document.body)}
+        <textarea data-testid="composer-input" />
+      </ComposerPrimitiveRoot>,
+    );
+
+    const notPrevented = fireEvent.mouseDown(getByTestId("portal-blank"), {
+      button: 0,
+    });
+
+    expect(notPrevented).toBe(true);
+    expect(document.activeElement).not.toBe(getByTestId("composer-input"));
+  });
+
+  it("keeps the mousedown default when the only textarea is disabled", () => {
+    const { getByTestId } = render(
+      <ComposerPrimitiveRoot>
+        <div data-testid="blank-space">
+          <textarea disabled data-testid="composer-input" />
+        </div>
+      </ComposerPrimitiveRoot>,
+    );
+
+    const notPrevented = fireEvent.mouseDown(getByTestId("blank-space"), {
+      button: 0,
+    });
+
+    expect(notPrevented).toBe(true);
+    expect(document.activeElement).not.toBe(getByTestId("composer-input"));
+  });
+
+  it("skips a disabled textarea and focuses the next composer input", () => {
+    const { getByTestId } = render(
+      <ComposerPrimitiveRoot>
+        <div data-testid="blank-space">
+          <textarea disabled data-testid="disabled-input" />
+          <div contentEditable data-testid="composer-input" tabIndex={0} />
+        </div>
+      </ComposerPrimitiveRoot>,
+    );
+
+    fireEvent.mouseDown(getByTestId("blank-space"), { button: 0 });
+
+    expect(document.activeElement).toBe(getByTestId("composer-input"));
+  });
+
+  it("keeps the mousedown default when the form contains no composer input", () => {
+    const { getByTestId } = render(
+      <ComposerPrimitiveRoot>
+        <div data-testid="blank-space" />
+      </ComposerPrimitiveRoot>,
+    );
+
+    const notPrevented = fireEvent.mouseDown(getByTestId("blank-space"), {
+      button: 0,
+    });
+
+    expect(notPrevented).toBe(true);
+  });
+
+  it("lets descendants keep native mousedown defaults via stopPropagation", () => {
+    const { getByTestId } = render(
+      <ComposerPrimitiveRoot>
+        <div data-testid="selectable" onMouseDown={(e) => e.stopPropagation()}>
+          Selectable content
+        </div>
+        <textarea data-testid="composer-input" />
+      </ComposerPrimitiveRoot>,
+    );
+
+    const notPrevented = fireEvent.mouseDown(getByTestId("selectable"), {
+      button: 0,
+    });
+
+    expect(notPrevented).toBe(true);
+    expect(document.activeElement).not.toBe(getByTestId("composer-input"));
+  });
+
+  it("lets consumer onMouseDown prevent the default focus behavior", () => {
+    const onMouseDown = vi.fn((event: MouseEvent<HTMLFormElement>) => {
+      event.preventDefault();
+    });
+    const { blankSpace, textarea } = setupComposer({ onMouseDown });
+
+    fireEvent.mouseDown(blankSpace, { button: 0 });
+
+    expect(onMouseDown).toHaveBeenCalledTimes(1);
+    expect(document.activeElement).not.toBe(textarea);
+  });
+
+  it("runs consumer onMouseDown and preserves default focus behavior when it does not prevent default", () => {
+    const onMouseDown = vi.fn();
+    const { blankSpace, textarea } = setupComposer({ onMouseDown });
+
+    fireEvent.mouseDown(blankSpace, { button: 0 });
+
+    expect(onMouseDown).toHaveBeenCalledTimes(1);
+    expect(document.activeElement).toBe(textarea);
+  });
+});
+
+describe("ComposerPrimitiveRoot compact mode", () => {
   let container: HTMLDivElement;
   let root: Root;
 

package/src/primitives/composer/ComposerRoot.tsx

@@ -8,12 +8,36 @@ import {
   type FormEvent,
   forwardRef,
   type ComponentPropsWithoutRef,
+  type MouseEvent,
   useMemo,
   useState,
 } from "react";
 import { useComposerSend } from "./ComposerSend";
 import { ComposerCompactContext } from "./ComposerCompactContext";
 
+const CONTENT_EDITABLE_SELECTOR =
+  "[contenteditable]:not([contenteditable='false'])";
+
+const COMPOSER_INPUT_SELECTOR = `textarea:not(:disabled), ${CONTENT_EDITABLE_SELECTOR}`;
+
+// Keeps tabindex="-1": roving-tabindex widgets click-focus items at -1.
+const INTERACTIVE_ELEMENT_SELECTOR = [
+  "a",
+  "audio[controls]",
+  "button",
+  "details",
+  "embed",
+  "iframe",
+  "input",
+  "label",
+  "select",
+  "summary",
+  "textarea",
+  "video[controls]",
+  CONTENT_EDITABLE_SELECTOR,
+  "[tabindex]",
+].join(", ");
+
 export namespace ComposerPrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.form>;
   /**
@@ -40,6 +64,11 @@ export namespace ComposerPrimitiveRoot {
  * is submitted (e.g., via Enter key or submit button). It automatically prevents the
  * default form submission and triggers the composer's send functionality.
  *
+ * Clicking blank form space focuses the composer input (the first textarea or
+ * contenteditable inside the form). Text selection cannot start from blank
+ * areas; descendants that need native mousedown defaults can call
+ * `stopPropagation()` in their own `onMouseDown`.
+ *
  * @example
  * ```tsx
  * <ComposerPrimitive.Root>
@@ -51,7 +80,7 @@ export namespace ComposerPrimitiveRoot {
 export const ComposerPrimitiveRoot = forwardRef<
   ComposerPrimitiveRoot.Element,
   ComposerPrimitiveRoot.Props
->(({ onSubmit, compact, ...rest }, forwardedRef) => {
+>(({ onSubmit, onMouseDown, compact, ...rest }, forwardedRef) => {
   const send = useComposerSend();
 
   const [multiline, setMultiline] = useState(false);
@@ -74,6 +103,25 @@ export const ComposerPrimitiveRoot = forwardRef<
     send();
   };
 
+  const handleMouseDown = (e: MouseEvent<HTMLFormElement>) => {
+    if (e.button !== 0) return;
+    const target = e.target;
+    // Portaled descendants (e.g. a dialog overlay) propagate mousedown through
+    // the React tree while their DOM nodes live outside the form.
+    if (!(target instanceof Element) || !e.currentTarget.contains(target))
+      return;
+    // Bound the ancestor walk to the form: hosts like AssistantModal render
+    // the composer inside a wrapper carrying tabindex="-1" (Radix FocusScope).
+    const interactive = target.closest(INTERACTIVE_ELEMENT_SELECTOR);
+    if (interactive && e.currentTarget.contains(interactive)) return;
+    const input = e.currentTarget.querySelector<HTMLElement>(
+      COMPOSER_INPUT_SELECTOR,
+    );
+    if (!input) return;
+    e.preventDefault();
+    input.focus();
+  };
+
   return (
     <ComposerCompactContext.Provider value={compact ? compactContext : null}>
       <Primitive.form
@@ -81,6 +129,7 @@ export const ComposerPrimitiveRoot = forwardRef<
         data-compact={isCompact ? "" : undefined}
         ref={forwardedRef}
         onSubmit={composeEventHandlers(onSubmit, handleSubmit)}
+        onMouseDown={composeEventHandlers(onMouseDown, handleMouseDown)}
       />
     </ComposerCompactContext.Provider>
   );

package/src/primitives/messagePart/useMessagePartData.ts

@@ -5,8 +5,9 @@ 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.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
  *
  * @example
  * ```tsx

package/src/primitives/messagePart/useMessagePartFile.ts

@@ -1,12 +1,26 @@
 "use client";
 
-import type { FileMessagePart, MessagePartState } from "@assistant-ui/core";
+import type {
+  FileMessagePart,
+  MessagePartState,
+  MessagePartStatus,
+} from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_FILE_PART: MessagePartState & FileMessagePart = Object.freeze({
+  type: "file",
+  data: "",
+  mimeType: "",
+  status: COMPLETE_STATUS,
+});
+
 /**
  * @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.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
  *
  * @example
  * ```tsx
@@ -19,11 +33,9 @@ import { useAuiState } from "@assistant-ui/store";
  * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useMessagePartFile = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
   const file = useAuiState((s) => {
-    if (s.part.type !== "file")
-      throw new Error(
-        "MessagePartFile can only be used inside file message parts.",
-      );
+    if (s.part.type !== "file") return EMPTY_FILE_PART;
 
     return s.part as MessagePartState & FileMessagePart;
   });

package/src/primitives/messagePart/useMessagePartImage.ts

@@ -1,12 +1,25 @@
 "use client";
 
-import type { ImageMessagePart, MessagePartState } from "@assistant-ui/core";
+import type {
+  ImageMessagePart,
+  MessagePartState,
+  MessagePartStatus,
+} from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_IMAGE_PART: MessagePartState & ImageMessagePart = Object.freeze({
+  type: "image",
+  image: "",
+  status: COMPLETE_STATUS,
+});
+
 /**
  * @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.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
  *
  * @example
  * ```tsx
@@ -19,11 +32,9 @@ import { useAuiState } from "@assistant-ui/store";
  * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useMessagePartImage = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
   const image = useAuiState((s) => {
-    if (s.part.type !== "image")
-      throw new Error(
-        "MessagePartImage can only be used inside image message parts.",
-      );
+    if (s.part.type !== "image") return EMPTY_IMAGE_PART;
 
     return s.part as MessagePartState & ImageMessagePart;
   });

package/src/primitives/messagePart/useMessagePartReasoning.ts

@@ -3,13 +3,24 @@
 import type {
   ReasoningMessagePart,
   MessagePartState,
+  MessagePartStatus,
 } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_REASONING_PART: MessagePartState & ReasoningMessagePart =
+  Object.freeze({
+    type: "reasoning",
+    text: "",
+    status: COMPLETE_STATUS,
+  });
+
 /**
  * @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.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
  *
  * @example
  * ```tsx
@@ -22,11 +33,9 @@ import { useAuiState } from "@assistant-ui/store";
  * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useMessagePartReasoning = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
   const text = useAuiState((s) => {
-    if (s.part.type !== "reasoning")
-      throw new Error(
-        "MessagePartReasoning can only be used inside reasoning message parts.",
-      );
+    if (s.part.type !== "reasoning") return EMPTY_REASONING_PART;
 
     return s.part as MessagePartState & ReasoningMessagePart;
   });

package/src/primitives/messagePart/useMessagePartSource.ts

@@ -1,12 +1,27 @@
 "use client";
 
-import type { SourceMessagePart, MessagePartState } from "@assistant-ui/core";
+import type {
+  SourceMessagePart,
+  MessagePartState,
+  MessagePartStatus,
+} from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_SOURCE_PART: MessagePartState & SourceMessagePart = Object.freeze({
+  type: "source",
+  sourceType: "url",
+  id: "",
+  url: "",
+  status: COMPLETE_STATUS,
+});
+
 /**
  * @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.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
  *
  * @example
  * ```tsx
@@ -19,11 +34,9 @@ import { useAuiState } from "@assistant-ui/store";
  * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useMessagePartSource = () => {
+  // Sentinel instead of throw: see useMessagePartText for the invariant.
   const source = useAuiState((s) => {
-    if (s.part.type !== "source")
-      throw new Error(
-        "MessagePartSource can only be used inside source message parts.",
-      );
+    if (s.part.type !== "source") return EMPTY_SOURCE_PART;
 
     return s.part as MessagePartState & SourceMessagePart;
   });