@assistant-ui/core 0.1.16 → 0.2.0

package/src/index.ts

@@ -32,7 +32,9 @@ export type {
 export type {
   Attachment,
   PendingAttachment,
+  PendingAttachmentStatus,
   CompleteAttachment,
+  CompleteAttachmentStatus,
   AttachmentStatus,
   CreateAttachment,
 } from "./types/attachment";
@@ -143,7 +145,11 @@ export type {
 
 // Runtime Core Interface Types
 export type {
+  AttachmentAddErrorEvent,
+  AttachmentAddErrorReason,
   ComposerRuntimeCore,
+  ComposerRuntimeEventCallback,
+  ComposerRuntimeEventPayload,
   ComposerRuntimeEventType,
   DictationState,
   EditComposerRuntimeCore,
@@ -160,6 +166,8 @@ export type {
   SpeechState,
   VoiceSessionState,
   SubmittedFeedback,
+  ThreadRuntimeEventCallback,
+  ThreadRuntimeEventPayload,
   ThreadRuntimeEventType,
   StartRunConfig,
   ResumeRunConfig,
@@ -191,6 +199,8 @@ export type {
 } from "./runtime/api/thread-list-runtime";
 
 export type {
+  ThreadListItemEventCallback,
+  ThreadListItemEventPayload,
   ThreadListItemEventType,
   ThreadListItemRuntime,
 } from "./runtime/api/thread-list-item-runtime";
@@ -234,7 +244,6 @@ export type { ThreadMessageLike } from "./runtime/utils/thread-message-like";
 
 // External Store Message Utilities
 export {
-  getExternalStoreMessage,
   getExternalStoreMessages,
   bindExternalStoreMessage,
 } from "./runtime/utils/external-store-message";
@@ -261,13 +270,10 @@ export type {
   RemoteThreadInitializeResponse,
   RemoteThreadMetadata,
   RemoteThreadListResponse,
+  RemoteThreadListPageOptions,
 } from "./runtimes/remote-thread-list/types";
 
 export { InMemoryThreadListAdapter } from "./runtimes/remote-thread-list/adapter/in-memory";
 
 // Assistant Transport Utilities
-export {
-  toAISDKTools,
-  getEnabledTools,
-  createRequestHeaders,
-} from "./runtimes/assistant-transport/utils";
+export { createRequestHeaders } from "./runtimes/assistant-transport/utils";

package/src/react/index.ts

@@ -163,7 +163,9 @@ export {
   MessagePrimitivePartByIndex,
   defaultComponents as messagePartsDefaultComponents,
   type EnrichedPartState,
+  type PartState,
 } from "./primitives/message/MessageParts";
+export { MessagePrimitiveGroupedParts } from "./primitives/message/MessageGroupedParts";
 export { MessagePrimitiveQuote } from "./primitives/message/MessageQuote";
 export {
   MessagePrimitiveAttachments,
@@ -233,6 +235,7 @@ export { useThreadListItemDelete } from "./primitive-hooks/useThreadListItemDele
 export { useThreadListItemUnarchive } from "./primitive-hooks/useThreadListItemUnarchive";
 export { useThreadListItemTrigger } from "./primitive-hooks/useThreadListItemTrigger";
 export { useThreadListNew } from "./primitive-hooks/useThreadListNew";
+export { useThreadListLoadMore } from "./primitive-hooks/useThreadListLoadMore";
 export { useEditComposerCancel } from "./primitive-hooks/useEditComposerCancel";
 export { useEditComposerSend } from "./primitive-hooks/useEditComposerSend";
 export { useMessageError } from "./primitive-hooks/useMessageError";

package/src/react/primitive-hooks/useThreadListLoadMore.ts

@@ -0,0 +1,15 @@
+import { useCallback } from "react";
+import { useAui, useAuiState } from "@assistant-ui/store";
+
+export const useThreadListLoadMore = () => {
+  const aui = useAui();
+  const disabled = useAuiState(
+    (s) => !s.threads.hasMore || s.threads.isLoading || s.threads.isLoadingMore,
+  );
+
+  const loadMore = useCallback(() => {
+    aui.threads().loadMore();
+  }, [aui]);
+
+  return { loadMore, disabled };
+};

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

@@ -0,0 +1,186 @@
+"use client";
+
+import { Fragment, type FC, type ReactNode, useMemo } from "react";
+import { useAuiState } from "@assistant-ui/store";
+import { useShallow } from "zustand/shallow";
+import type { PartState } from "../../../store/scopes/part";
+import type {
+  MessagePartStatus,
+  ToolCallMessagePartStatus,
+} from "../../../types/message";
+import {
+  buildGroupTree,
+  type GroupKey,
+  type GroupNode,
+  normalizeGroupKey,
+} from "../../utils/groupParts";
+import { MessagePartChildren, type EnrichedPartState } from "./MessageParts";
+
+export namespace MessagePrimitiveGroupedParts {
+  /**
+   * A coalesced group of adjacent parts. Surfaced through the same
+   * `{ part }` channel as a leaf {@link EnrichedPartState} so consumers
+   * dispatch on a single `switch (part.type)`. `type` is the group key
+   * (always `"group-…"`); `status` mirrors the last contained part.
+   */
+  export type GroupPart<TKey extends `group-${string}` = `group-${string}`> = {
+    readonly type: TKey;
+    readonly status: MessagePartStatus | ToolCallMessagePartStatus;
+    readonly indices: readonly number[];
+  };
+
+  export type RenderInfo<TKey extends `group-${string}` = `group-${string}`> = {
+    /**
+     * Either a coalesced group ({@link GroupPart}, identified by a
+     * `group-…` `type`) or a single enriched part. Use one switch over
+     * `part.type` to handle both.
+     */
+    readonly part: GroupPart<TKey> | EnrichedPartState;
+    /**
+     * For group nodes: the recursively-rendered subtree (subgroups +
+     * leaf parts). For leaf parts: a sentinel that throws when rendered
+     * — accidental fall-through (`default: return children;`) errors
+     * loudly instead of silently rendering nothing.
+     */
+    readonly children: ReactNode;
+  };
+
+  export type Props<TKey extends `group-${string}` = `group-${string}`> = {
+    /**
+     * Maps each part to its group key path. Adjacent parts that share a
+     * prefix coalesce up to that prefix. Return `null`, `undefined`, or
+     * `[]` to leave a part ungrouped — it will be rendered as a leaf
+     * through `children` with `part` set to its {@link EnrichedPartState}.
+     *
+     * Keys must start with `"group-"` so the renderer's
+     * `switch (part.type)` can distinguish groups from real part types.
+     *
+     * For best performance, pass a stable reference (module-level
+     * constant or `useCallback`).
+     *
+     * @example
+     * ```ts
+     * const groupBy = (part) =>
+     *   part.type === "reasoning" ? ["group-thought", "group-reasoning"] :
+     *   part.type === "tool-call" ? ["group-thought", "group-tool"] :
+     *   null;
+     * ```
+     */
+    readonly groupBy: (
+      part: PartState,
+      index: number,
+      parts: readonly PartState[],
+    ) => GroupKey<TKey>;
+
+    /**
+     * Render function called once per group node and once per leaf part.
+     * Switch on `part.type`: `"group-…"` cases wrap `children`; real
+     * part types (`"text"`, `"tool-call"`, …) render the part directly.
+     *
+     * Leaf parts receive the same {@link EnrichedPartState} that
+     * `<MessagePrimitive.Parts>` would produce (`toolUI`, `addResult`,
+     * `resume`, `dataRendererUI`).
+     */
+    readonly children: (info: RenderInfo<TKey>) => ReactNode;
+  };
+}
+
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+/**
+ * `children` placeholder passed for leaf-part renders. Leaf parts have no
+ * inner subtree; rendering this sentinel signals the consumer wrote
+ * `default: return children;` and accidentally fell through for a part —
+ * surface the bug loudly instead of silently rendering nothing.
+ */
+const PartChildrenSentinel: FC = () => {
+  throw new Error(
+    "MessagePrimitive.GroupedParts: rendered `children` under a leaf " +
+      "part. `children` is only meaningful for `group-…` cases — add a " +
+      "matching case for the part type or return `null` to skip it.",
+  );
+};
+
+const renderNode = <TKey extends `group-${string}`>(
+  node: GroupNode,
+  parts: readonly PartState[],
+  render: (info: MessagePrimitiveGroupedParts.RenderInfo<TKey>) => ReactNode,
+): ReactNode => {
+  if (node.type === "part") {
+    return (
+      <MessagePartChildren key={node.nodeKey} index={node.index}>
+        {({ part }) => render({ part, children: <PartChildrenSentinel /> })}
+      </MessagePartChildren>
+    );
+  }
+
+  const status = parts[node.indices.at(-1)!]?.status ?? COMPLETE_STATUS;
+  const groupPart: MessagePrimitiveGroupedParts.GroupPart<TKey> = {
+    type: node.key as TKey,
+    status,
+    indices: node.indices,
+  };
+
+  return (
+    <Fragment key={node.nodeKey}>
+      {render({
+        part: groupPart,
+        children: (
+          <>{node.children.map((child) => renderNode(child, parts, render))}</>
+        ),
+      })}
+    </Fragment>
+  );
+};
+
+/**
+ * Groups adjacent message parts into a tree of coalesced runs and
+ * renders each node — group or part — through a single `children`
+ * function.
+ *
+ * The render function receives `{ part, children }` where `part.type`
+ * is either a `"group-…"` literal (for a group, `children` is the
+ * recursively-rendered subtree) or a real part type (`"text"`,
+ * `"tool-call"`, …) for a leaf (`children` is a sentinel that throws
+ * if rendered — use `part.type` to distinguish).
+ *
+ * @example
+ * ```tsx
+ * <MessagePrimitive.GroupedParts
+ *   groupBy={(part) =>
+ *     part.type === "reasoning" ? ["group-thought", "group-reasoning"] :
+ *     part.type === "tool-call" ? ["group-thought", "group-tool"] :
+ *     null
+ *   }
+ * >
+ *   {({ part, children }) => {
+ *     switch (part.type) {
+ *       case "group-thought":   return <Thought>{children}</Thought>;
+ *       case "group-reasoning": return <Reasoning>{children}</Reasoning>;
+ *       case "group-tool":      return <ToolStack>{children}</ToolStack>;
+ *       case "text":            return <MarkdownText />;
+ *       case "tool-call":       return part.toolUI ?? <ToolFallback {...part} />;
+ *       default:                return null;
+ *     }
+ *   }}
+ * </MessagePrimitive.GroupedParts>
+ * ```
+ */
+export const MessagePrimitiveGroupedParts = <TKey extends `group-${string}`>({
+  groupBy,
+  children,
+}: MessagePrimitiveGroupedParts.Props<TKey>): ReactNode => {
+  const parts = useAuiState(useShallow((s) => s.message.parts));
+
+  const tree = useMemo(
+    () =>
+      buildGroupTree(
+        parts.map((part, i) => normalizeGroupKey(groupBy(part, i, parts))),
+      ),
+    [parts, groupBy],
+  );
+
+  return <>{tree.map((node) => renderNode(node, parts, children))}</>;
+};
+
+MessagePrimitiveGroupedParts.displayName = "MessagePrimitive.GroupedParts";

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/runtimes/RemoteThreadListHookInstanceManager.tsx

@@ -94,7 +94,8 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
     }
   }
 
-  // Rendered outside the user's Provider so deferred `children` cannot strand the binding.
+  // Rendered as a child of the user's Provider so the runtime hook can
+  // read context the Provider injects (e.g. RuntimeAdapterProvider).
   private _RuntimeBinder: FC<PropsWithChildren<{ threadId: string }>> = ({
     threadId,
     children,
@@ -172,7 +173,7 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
             console.warn(
               "RemoteThreadListAdapter.unstable_Provider did not render its `children` synchronously. " +
                 "Render `children` on first commit; deferring them behind a loading state, Suspense boundary, " +
-                "or `useEffect` gate leaves thread context unavailable to downstream consumers.",
+                "or `useEffect` gate strands the runtime binder and leaves the thread without context.",
             );
           }
         }, 100);
@@ -183,11 +184,11 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
 
     return (
       <ThreadListItemRuntimeProvider runtime={runtime}>
-        <this._RuntimeBinder threadId={threadId}>
-          <Provider>
+        <Provider>
+          <this._RuntimeBinder threadId={threadId}>
             <ProviderRenderDetector detectorRef={detectorRef} />
-          </Provider>
-        </this._RuntimeBinder>
+          </this._RuntimeBinder>
+        </Provider>
       </ThreadListItemRuntimeProvider>
     );
   });