@assistant-ui/core 0.1.16 → 0.1.17

package/src/react/primitives/message/MessageParts.tsx

@@ -208,7 +208,7 @@ export namespace MessagePrimitiveParts {
      * @param endIndex - Index of the last tool call in the group
      * @param children - Rendered tool call components to display within the group
      *
-     * @deprecated This feature is still experimental and subject to change.
+     * @deprecated Use `<MessagePrimitive.GroupedParts>` with a custom `groupBy` instead.
      */
     ToolGroup?: ComponentType<
       PropsWithChildren<{ startIndex: number; endIndex: number }>
@@ -220,6 +220,8 @@ export namespace MessagePrimitiveParts {
      * @param startIndex - Index of the first reasoning part in the group
      * @param endIndex - Index of the last reasoning part in the group
      * @param children - Rendered reasoning part components
+     *
+     * @deprecated Use `<MessagePrimitive.GroupedParts>` with a custom `groupBy` instead.
      */
     ReasoningGroup?: ReasoningGroupComponent;
 
@@ -234,6 +236,11 @@ export namespace MessagePrimitiveParts {
    * `ToolGroup` components cannot be used alongside it.
    */
   type ChainOfThoughtComponents = BaseComponents & {
+    /**
+     * @deprecated Use `<MessagePrimitive.GroupedParts>` with a `groupBy`
+     * that returns `["group-thought", ...]` for reasoning and tool-call
+     * parts. See `@assistant-ui/ui` for a worked example.
+     */
     ChainOfThought: ComponentType;
 
     Reasoning?: never;
@@ -604,70 +611,88 @@ const EMPTY_RUNNING_TEXT_PART: Extract<EnrichedPartState, { type: "text" }> =
     status: RUNNING_STATUS,
   });
 
+/**
+ * @internal
+ * Renders a single part by index, calling `children` with the
+ * {@link EnrichedPartState} (tool/data UI enrichments + addResult/resume
+ * for tool calls). Shared between `<MessagePrimitive.Parts>` and
+ * `<MessagePrimitive.GroupedParts>`. Returns whatever `children`
+ * returns — callers decide how to handle a `null` return.
+ */
+export const MessagePartChildren: FC<{
+  index: number;
+  children: (value: { part: EnrichedPartState }) => ReactNode;
+}> = ({ index, children }) => {
+  const aui = useAui();
+  // Subscribed (not snapshotted like `tools`) so fallbacks registered
+  // after the first render trigger a re-render and `hasUI` re-evaluates.
+  const dataRenderers = useAuiState((s) => s.dataRenderers);
+
+  return (
+    <PartByIndexProvider index={index}>
+      <RenderChildrenWithAccessor
+        getItemState={(aui) => aui.message().part({ index }).getState()}
+      >
+        {(getItem) =>
+          children({
+            get part() {
+              const state = getItem();
+              if (state.type === "tool-call") {
+                const entry = aui.tools().getState().tools[state.toolName];
+                const hasUI = Array.isArray(entry) ? !!entry[0] : !!entry;
+                const partMethods = aui.message().part({ index });
+                return {
+                  ...state,
+                  toolUI: hasUI ? <RegisteredToolUI /> : null,
+                  addResult: partMethods.addToolResult,
+                  resume: partMethods.resumeToolCall,
+                };
+              }
+              if (state.type === "data") {
+                const hasUI =
+                  getDataRenderer(dataRenderers, state.name, undefined) !==
+                  undefined;
+                return {
+                  ...state,
+                  dataRendererUI: hasUI ? <RegisteredDataRendererUI /> : null,
+                };
+              }
+              return state;
+            },
+          })
+        }
+      </RenderChildrenWithAccessor>
+    </PartByIndexProvider>
+  );
+};
+
 const MessagePrimitivePartsInner: FC<{
   children: (value: { part: EnrichedPartState }) => ReactNode;
 }> = ({ children }) => {
-  const aui = useAui();
   const contentLength = useAuiState((s) => s.message.parts.length);
   const isRunning = useAuiState(
     (s) => (s.message.status?.type ?? "complete") === "running",
   );
   const isEmptyRunning = contentLength === 0 && isRunning;
-  // Subscribed (not snapshotted like `tools`) so fallbacks registered after
-  // the first render trigger a re-render and `hasUI` re-evaluates.
-  const dataRenderers = useAuiState((s) => s.dataRenderers);
-
-  // biome-ignore lint/correctness/useExhaustiveDependencies: aui accessors are stable refs
-  return useMemo(() => {
-    if (contentLength === 0) {
-      if (!isEmptyRunning) return null;
 
-      return (
-        <TextMessagePartProvider text="" isRunning>
-          {children({ part: EMPTY_RUNNING_TEXT_PART })}
-        </TextMessagePartProvider>
-      );
-    }
+  if (contentLength === 0) {
+    if (!isEmptyRunning) return null;
+    return (
+      <TextMessagePartProvider text="" isRunning>
+        {children({ part: EMPTY_RUNNING_TEXT_PART })}
+      </TextMessagePartProvider>
+    );
+  }
 
-    return Array.from({ length: contentLength }, (_, index) => (
-      <PartByIndexProvider key={index} index={index}>
-        <RenderChildrenWithAccessor
-          getItemState={(aui) => aui.message().part({ index }).getState()}
-        >
-          {(getItem) => {
-            const result = children({
-              get part() {
-                const state = getItem();
-                if (state.type === "tool-call") {
-                  const entry = aui.tools().getState().tools[state.toolName];
-                  const hasUI = Array.isArray(entry) ? !!entry[0] : !!entry;
-                  const partMethods = aui.message().part({ index });
-                  return {
-                    ...state,
-                    toolUI: hasUI ? <RegisteredToolUI /> : null,
-                    addResult: partMethods.addToolResult,
-                    resume: partMethods.resumeToolCall,
-                  };
-                }
-                if (state.type === "data") {
-                  const hasUI =
-                    getDataRenderer(dataRenderers, state.name, undefined) !==
-                    undefined;
-                  return {
-                    ...state,
-                    dataRendererUI: hasUI ? <RegisteredDataRendererUI /> : null,
-                  };
-                }
-                return state;
-              },
-            });
-            if (result !== null) return result;
-            return <DefaultPartFallback />;
-          }}
-        </RenderChildrenWithAccessor>
-      </PartByIndexProvider>
-    ));
-  }, [contentLength, children, isEmptyRunning, dataRenderers]);
+  return (
+    <>
+      {Array.from({ length: contentLength }, (_, index) => (
+        <MessagePartChildren key={index} index={index}>
+          {(value) => children(value) ?? <DefaultPartFallback />}
+        </MessagePartChildren>
+      ))}
+    </>
+  );
 };
 
 /**

package/src/react/utils/groupParts.ts

@@ -0,0 +1,152 @@
+/**
+ * Hierarchical adjacent-coalescing grouping for message parts.
+ *
+ * Given a group path per part (from `groupBy`), builds a tree of group
+ * nodes wrapping individual parts. Adjacent parts sharing a path prefix
+ * coalesce into the same group; ungrouped parts are direct children of
+ * the root.
+ *
+ * Each node gets a structural `nodeKey` built from sibling indices
+ * (`"0.1.0"`), stable under append-only streaming.
+ */
+
+/**
+ * Public group key type. Group keys must be prefixed with `group-` so
+ * that a unified `switch (part.type)` in the renderer can distinguish
+ * a group key (e.g. `"group-thought"`) from a real part type
+ * (`"text"`, `"tool-call"`).
+ */
+export type GroupKey<TKey extends `group-${string}` = `group-${string}`> =
+  | TKey
+  | readonly TKey[]
+  | null
+  | undefined;
+
+export type GroupNode = GroupNodeGroup | GroupNodePart;
+
+export interface GroupNodeGroup {
+  readonly type: "group";
+  /** Current-level group key (last segment of the path). */
+  readonly key: string;
+  /** Structural React key: sibling-index path, e.g. `"0.1.0"`. */
+  readonly nodeKey: string;
+  /** Indices of parts in this subtree, in order. */
+  readonly indices: readonly number[];
+  readonly children: readonly GroupNode[];
+}
+
+export interface GroupNodePart {
+  readonly type: "part";
+  /** Index of the part in the message. */
+  readonly index: number;
+  /** Structural React key: sibling-index path within parent. */
+  readonly nodeKey: string;
+}
+
+const EMPTY_PATH: readonly string[] = Object.freeze([]);
+
+/**
+ * Normalize a `groupBy` return value to a path array.
+ * `null`/`undefined`/`[]` → `[]` (ungrouped).
+ * `"foo"` → `["foo"]`. Arrays pass through.
+ */
+export const normalizeGroupKey = (key: GroupKey): readonly string[] => {
+  if (key == null) return EMPTY_PATH;
+  if (typeof key === "string") return [key];
+  return key;
+};
+
+interface BuildFrame {
+  key: string;
+  nodeKey: string;
+  indices: number[];
+  children: GroupNode[];
+  nextChildIdx: number;
+}
+
+const makeChildNodeKey = (parent: BuildFrame): string => {
+  const idx = parent.nextChildIdx++;
+  return parent.nodeKey === "" ? String(idx) : `${parent.nodeKey}.${idx}`;
+};
+
+/**
+ * Build the group tree from an array of normalized group paths.
+ * `paths[i]` is the path for part `i`. The output tree contains one
+ * `part` node per part and one `group` node per coalesced run.
+ */
+export const buildGroupTree = (
+  paths: readonly (readonly string[])[],
+): readonly GroupNode[] => {
+  const root: BuildFrame = {
+    key: "",
+    nodeKey: "",
+    indices: [],
+    children: [],
+    nextChildIdx: 0,
+  };
+  const stack: BuildFrame[] = [root];
+
+  const closeTop = (): void => {
+    const closing = stack.pop()!;
+    const parent = stack[stack.length - 1]!;
+    parent.children.push({
+      type: "group",
+      key: closing.key,
+      nodeKey: closing.nodeKey,
+      indices: closing.indices,
+      children: closing.children,
+    });
+  };
+
+  for (let i = 0; i < paths.length; i++) {
+    const path = paths[i]!;
+
+    // Find the longest prefix shared between currently-open groups
+    // (excluding root) and this part's path.
+    let common = 0;
+    while (
+      common < stack.length - 1 &&
+      common < path.length &&
+      stack[common + 1]!.key === path[common]
+    ) {
+      common++;
+    }
+
+    // Close groups not on this path.
+    while (stack.length - 1 > common) {
+      closeTop();
+    }
+
+    // Open new groups down to the part's depth.
+    while (stack.length - 1 < path.length) {
+      const parent = stack[stack.length - 1]!;
+      stack.push({
+        key: path[stack.length - 1]!,
+        nodeKey: makeChildNodeKey(parent),
+        indices: [],
+        children: [],
+        nextChildIdx: 0,
+      });
+    }
+
+    // Push this part as a leaf in the deepest open group (or root).
+    const top = stack[stack.length - 1]!;
+    top.children.push({
+      type: "part",
+      index: i,
+      nodeKey: makeChildNodeKey(top),
+    });
+
+    // Record the part index in every open ancestor group.
+    for (let s = 1; s < stack.length; s++) {
+      stack[s]!.indices.push(i);
+    }
+  }
+
+  // Close any still-open groups.
+  while (stack.length > 1) {
+    closeTop();
+  }
+
+  return root.children;
+};

package/src/runtime/api/composer-runtime.ts

@@ -12,6 +12,7 @@ import {
   SKIP_UPDATE,
 } from "../../subscribable/subscribable";
 import type {
+  ComposerRuntimeEventCallback,
   ComposerRuntimeEventType,
   DictationState,
   EditComposerRuntimeCore,
@@ -222,9 +223,9 @@ export type ComposerRuntime = {
   /**
    * @deprecated This API is still under active development and might change without notice.
    */
-  unstable_on(
-    event: ComposerRuntimeEventType,
-    callback: () => void,
+  unstable_on<E extends ComposerRuntimeEventType>(
+    event: E,
+    callback: ComposerRuntimeEventCallback<E>,
   ): Unsubscribe;
 };
 
@@ -332,19 +333,19 @@ export abstract class ComposerRuntimeImpl implements ComposerRuntime {
     EventSubscriptionSubject<ComposerRuntimeEventType>
   >();
 
-  public unstable_on(
-    event: ComposerRuntimeEventType,
-    callback: () => void,
+  public unstable_on<E extends ComposerRuntimeEventType>(
+    event: E,
+    callback: ComposerRuntimeEventCallback<E>,
   ): Unsubscribe {
     let subject = this._eventSubscriptionSubjects.get(event);
     if (!subject) {
-      subject = new EventSubscriptionSubject({
-        event: event,
+      subject = new EventSubscriptionSubject<ComposerRuntimeEventType>({
+        event,
         binding: this._core,
       });
       this._eventSubscriptionSubjects.set(event, subject);
     }
-    return subject.subscribe(callback);
+    return subject.subscribe(callback as (payload?: unknown) => void);
   }
 
   public abstract getAttachmentByIndex(idx: number): AttachmentRuntime;

package/src/runtime/api/thread-list-item-runtime.ts

@@ -3,7 +3,26 @@ import type { SubscribableWithState } from "../../subscribable/subscribable";
 import type { ThreadListItemRuntimePath } from "./paths";
 import type { ThreadListRuntimeCoreBinding } from "./thread-list-runtime";
 
-export type ThreadListItemEventType = "switchedTo" | "switchedAway";
+export type ThreadListItemEventPayload = {
+  /**
+   * @deprecated State-derivable. Compare `s.threads.mainThreadId` against the
+   * item's `s.threadListItem.id` via `useAuiState` instead. Kept for backward
+   * compatibility.
+   */
+  switchedTo: Record<string, never>;
+  /**
+   * @deprecated State-derivable. Compare `s.threads.mainThreadId` against the
+   * item's `s.threadListItem.id` via `useAuiState` instead. Kept for backward
+   * compatibility.
+   */
+  switchedAway: Record<string, never>;
+};
+
+export type ThreadListItemEventType = keyof ThreadListItemEventPayload;
+
+export type ThreadListItemEventCallback<E extends ThreadListItemEventType> = (
+  payload: ThreadListItemEventPayload[E],
+) => void;
 
 import type { ThreadListItemState } from "./bindings";
 import type { ThreadListItemStatus } from "../interfaces/thread-list-runtime-core";
@@ -27,9 +46,9 @@ export type ThreadListItemRuntime = {
 
   subscribe(callback: () => void): Unsubscribe;
 
-  unstable_on(
-    event: ThreadListItemEventType,
-    callback: () => void,
+  unstable_on<E extends ThreadListItemEventType>(
+    event: E,
+    callback: ThreadListItemEventCallback<E>,
   ): Unsubscribe;
 
   __internal_getRuntime(): ThreadListItemRuntime;
@@ -112,7 +131,10 @@ export class ThreadListItemRuntimeImpl implements ThreadListItemRuntime {
     return this._threadListBinding.generateTitle(state.id);
   }
 
-  public unstable_on(event: ThreadListItemEventType, callback: () => void) {
+  public unstable_on<E extends ThreadListItemEventType>(
+    event: E,
+    callback: ThreadListItemEventCallback<E>,
+  ) {
     let prevIsMain = this._core.getState().isMain;
     let prevThreadId = this._core.getState().id;
     return this.subscribe(() => {
@@ -125,7 +147,7 @@ export class ThreadListItemRuntimeImpl implements ThreadListItemRuntime {
 
       if (event === "switchedTo" && !newIsMain) return;
       if (event === "switchedAway" && newIsMain) return;
-      callback();
+      (callback as (payload?: unknown) => void)({});
     });
   }
 

package/src/runtime/api/thread-runtime.ts

@@ -4,6 +4,7 @@ import type {
   ThreadRuntimeCore,
   SpeechState,
   VoiceSessionState,
+  ThreadRuntimeEventCallback,
   ThreadRuntimeEventType,
   StartRunConfig,
   ResumeRunConfig,
@@ -329,7 +330,10 @@ export type ThreadRuntime = {
   muteVoice(): void;
   unmuteVoice(): void;
 
-  unstable_on(event: ThreadRuntimeEventType, callback: () => void): Unsubscribe;
+  unstable_on<E extends ThreadRuntimeEventType>(
+    event: E,
+    callback: ThreadRuntimeEventCallback<E>,
+  ): Unsubscribe;
 };
 
 export class ThreadRuntimeImpl implements ThreadRuntime {
@@ -601,18 +605,18 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     EventSubscriptionSubject<ThreadRuntimeEventType>
   >();
 
-  public unstable_on(
-    event: ThreadRuntimeEventType,
-    callback: () => void,
+  public unstable_on<E extends ThreadRuntimeEventType>(
+    event: E,
+    callback: ThreadRuntimeEventCallback<E>,
   ): Unsubscribe {
     let subject = this._eventSubscriptionSubjects.get(event);
     if (!subject) {
-      subject = new EventSubscriptionSubject({
-        event: event,
+      subject = new EventSubscriptionSubject<ThreadRuntimeEventType>({
+        event,
         binding: this._threadBinding,
       });
       this._eventSubscriptionSubjects.set(event, subject);
     }
-    return subject.subscribe(callback);
+    return subject.subscribe(callback as (payload?: unknown) => void);
   }
 }

package/src/runtime/base/base-composer-runtime-core.ts

@@ -14,7 +14,10 @@ import {
   fileMatchesAccept,
 } from "../../adapters/attachment";
 import type {
+  AttachmentAddErrorReason,
   ComposerRuntimeCore,
+  ComposerRuntimeEventCallback,
+  ComposerRuntimeEventPayload,
   ComposerRuntimeEventType,
   DictationState,
   SendOptions,
@@ -189,7 +192,7 @@ export abstract class BaseComposerRuntimeCore
     };
 
     this.handleSend(message, options);
-    this._notifyEventSubscribers("send");
+    this._notifyEventSubscribers("send", {});
   }
 
   public cancel() {
@@ -215,14 +218,15 @@ export abstract class BaseComposerRuntimeCore
           adapter.accept,
         )
       ) {
-        try {
-          this._notifyEventSubscribers("attachmentAddError");
-        } catch {
-          // prevent subscriber errors from masking the original error
-        }
-        throw new Error(
-          `File type ${fileOrAttachment.contentType || "unknown"} is not accepted. Accepted types: ${adapter.accept}`,
+        const message = `File type ${fileOrAttachment.contentType || "unknown"} is not accepted. Accepted types: ${adapter.accept}`;
+        const err = new Error(message);
+        this._safeEmitAttachmentAddError(
+          "not-accepted",
+          message,
+          undefined,
+          err,
         );
+        throw err;
       }
 
       const a: CompleteAttachment = {
@@ -235,7 +239,7 @@ export abstract class BaseComposerRuntimeCore
       };
       this._attachments = [...this._attachments, a];
       this._notifySubscribers();
-      this._notifyEventSubscribers("attachmentAdd");
+      this._notifyEventSubscribers("attachmentAdd", {});
       return;
     }
 
@@ -256,22 +260,28 @@ export abstract class BaseComposerRuntimeCore
       this._notifySubscribers();
     };
 
-    let lastAttachment: PendingAttachment | undefined;
-    try {
-      const adapter = this.getAttachmentAdapter();
-      if (!adapter) throw new Error("Attachments are not supported");
+    const adapter = this.getAttachmentAdapter();
+    if (!adapter) {
+      const message = "Attachments are not supported";
+      const err = new Error(message);
+      this._safeEmitAttachmentAddError("no-adapter", message, undefined, err);
+      throw err;
+    }
 
-      if (
-        !fileMatchesAccept(
-          { name: fileOrAttachment.name, type: fileOrAttachment.type },
-          adapter.accept,
-        )
-      ) {
-        throw new Error(
-          `File type ${fileOrAttachment.type || "unknown"} is not accepted. Accepted types: ${adapter.accept}`,
-        );
-      }
+    if (
+      !fileMatchesAccept(
+        { name: fileOrAttachment.name, type: fileOrAttachment.type },
+        adapter.accept,
+      )
+    ) {
+      const message = `File type ${fileOrAttachment.type || "unknown"} is not accepted. Accepted types: ${adapter.accept}`;
+      const err = new Error(message);
+      this._safeEmitAttachmentAddError("not-accepted", message, undefined, err);
+      throw err;
+    }
 
+    let lastAttachment: PendingAttachment | undefined;
+    try {
       const promiseOrGenerator = adapter.add({ file: fileOrAttachment });
       if (Symbol.asyncIterator in promiseOrGenerator) {
         for await (const r of promiseOrGenerator) {
@@ -289,20 +299,48 @@ export abstract class BaseComposerRuntimeCore
           status: { type: "incomplete", reason: "error" },
         });
       }
-      try {
-        this._notifyEventSubscribers("attachmentAddError");
-      } catch {
-        // prevent subscriber errors from masking the original error
-      }
+      this._safeEmitAttachmentAddError(
+        "adapter-error",
+        e instanceof Error ? e.message : String(e),
+        lastAttachment?.id,
+        e instanceof Error ? e : undefined,
+      );
       throw e;
     }
 
     const hasError =
       lastAttachment?.status.type === "incomplete" &&
       lastAttachment.status.reason === "error";
-    this._notifyEventSubscribers(
-      hasError ? "attachmentAddError" : "attachmentAdd",
-    );
+    if (hasError) {
+      this._safeEmitAttachmentAddError(
+        "adapter-error",
+        "Attachment upload did not complete successfully.",
+        lastAttachment?.id,
+      );
+    } else {
+      this._notifyEventSubscribers("attachmentAdd", {});
+    }
+  }
+
+  private _safeEmitAttachmentAddError(
+    reason: AttachmentAddErrorReason,
+    message: string,
+    attachmentId?: string,
+    error?: Error,
+  ) {
+    try {
+      this._notifyEventSubscribers("attachmentAddError", {
+        reason,
+        message,
+        ...(attachmentId !== undefined && { attachmentId }),
+        ...(error !== undefined && { error }),
+      });
+    } catch (subscriberError) {
+      console.error(
+        "[assistant-ui] attachmentAddError subscriber threw:",
+        subscriberError,
+      );
+    }
   }
 
   async removeAttachment(attachmentId: string) {
@@ -471,28 +509,33 @@ export abstract class BaseComposerRuntimeCore
 
   private _eventSubscribers = new Map<
     ComposerRuntimeEventType,
-    Set<() => void>
+    Set<(payload?: unknown) => void>
   >();
 
-  protected _notifyEventSubscribers(event: ComposerRuntimeEventType) {
+  protected _notifyEventSubscribers<E extends ComposerRuntimeEventType>(
+    event: E,
+    payload: ComposerRuntimeEventPayload[E],
+  ) {
     const subscribers = this._eventSubscribers.get(event);
     if (!subscribers) return;
 
-    for (const callback of subscribers) callback();
+    for (const callback of subscribers) callback(payload);
   }
 
-  public unstable_on(event: ComposerRuntimeEventType, callback: () => void) {
-    const subscribers = this._eventSubscribers.get(event);
+  public unstable_on<E extends ComposerRuntimeEventType>(
+    event: E,
+    callback: ComposerRuntimeEventCallback<E>,
+  ) {
+    const wrapped = callback as (payload?: unknown) => void;
+    let subscribers = this._eventSubscribers.get(event);
     if (!subscribers) {
-      this._eventSubscribers.set(event, new Set([callback]));
-    } else {
-      subscribers.add(callback);
+      subscribers = new Set();
+      this._eventSubscribers.set(event, subscribers);
     }
+    subscribers.add(wrapped);
 
     return () => {
-      const subscribers = this._eventSubscribers.get(event);
-      if (!subscribers) return;
-      subscribers.delete(callback);
+      this._eventSubscribers.get(event)?.delete(wrapped);
     };
   }
 }