@assistant-ui/core 0.2.18 → 0.2.19

package/src/react/model-context/interactableTool.tsx

@@ -0,0 +1,175 @@
+import type { ReactNode } from "react";
+import type { Unstable_InteractableStateSchema } from "../types/scopes/interactables";
+import type { ToolDefinition } from "./toolbox";
+import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
+import {
+  unstable_useInteractable as useInteractable,
+  type Unstable_InferInteractableState,
+  type Unstable_InteractableVersionInfo,
+} from "./useInteractable";
+import { unstable_useInteractableState as useInteractableState } from "./useInteractableState";
+
+export type Unstable_InteractableToolRenderProps<TState> = {
+  /**
+   * The live state. While `streaming` is true, fields the model has not
+   * finished generating may still be missing.
+   */
+  state: TState;
+  setState: (updater: TState | ((prev: TState) => TState)) => void;
+  /**
+   * This message's version of the instance: its state as of this point in the
+   * conversation, whether it is the most recent edit, and a `restore()` back
+   * to it. `undefined` while streaming.
+   */
+  version: Unstable_InteractableVersionInfo<TState> | undefined;
+  id: string;
+  /** True while the tool call's arguments are still streaming in. */
+  streaming: boolean;
+};
+
+export type Unstable_InteractableToolConfig<
+  TSchema extends Unstable_InteractableStateSchema,
+> = {
+  description: string;
+  stateSchema: TSchema;
+  render: (
+    props: Unstable_InteractableToolRenderProps<
+      Unstable_InferInteractableState<TSchema>
+    >,
+  ) => ReactNode;
+};
+
+const noop = () => {};
+
+const UPDATE_TOOL_PREFIX = "update_";
+
+/**
+ * Defines a tool that creates a thread-scoped interactable from its arguments,
+ * for assignment to a toolkit entry — the entry key is the interactable name:
+ *
+ * ```tsx
+ * notepad: unstable_interactableTool({
+ *   description: "A notepad the user can read and edit.",
+ *   stateSchema: notepadSchema,
+ *   render: (props) => <Notepad {...props} />,
+ * }),
+ * ```
+ *
+ * `render` shows at the creating call and — installed automatically — at every
+ * `update_{name}` call, with streaming previews, instance-id wiring, and
+ * registration handled. It receives the live `state`/`setState` plus this
+ * message's `version`; whether older messages render frozen history or stay
+ * live-editable is the render function's choice.
+ *
+ * @deprecated Unstable / Experimental (not actually removed).
+ */
+export const unstable_interactableTool = <
+  TSchema extends Unstable_InteractableStateSchema,
+>(
+  config: Unstable_InteractableToolConfig<TSchema>,
+): ToolDefinition<Record<string, unknown>, { success: true }> => {
+  type TState = Unstable_InferInteractableState<TSchema>;
+  type UpdateArgs = { id?: string | undefined } & Record<string, unknown>;
+  type UpdateResult =
+    | { success: true; id: string }
+    | { success: false; error: string };
+
+  const Anchor = ({
+    name,
+    id,
+    initial,
+  }: {
+    name: string;
+    id?: string | undefined;
+    initial: TState;
+  }) => {
+    const [state, { id: resolvedId, setState, version }] = useInteractable(
+      name,
+      {
+        id,
+        description: config.description,
+        stateSchema: config.stateSchema,
+        initialState: initial,
+        updateRender: UpdateToolUI,
+      },
+    );
+    return (
+      <>
+        {config.render({
+          state,
+          setState,
+          version,
+          id: resolvedId,
+          streaming: false,
+        })}
+      </>
+    );
+  };
+
+  const StreamingUpdate = ({ id }: { id: string }) => {
+    const [state, { setState }] = useInteractableState<TState>(id);
+    if (state === undefined) return null;
+    return (
+      <>
+        {config.render({
+          state,
+          setState,
+          version: undefined,
+          id,
+          streaming: true,
+        })}
+      </>
+    );
+  };
+
+  const UpdateToolUI: ToolCallMessagePartComponent<
+    UpdateArgs,
+    UpdateResult
+  > = ({ toolName, args, result }) => {
+    if (!result) {
+      return typeof args.id === "string" ? (
+        <StreamingUpdate id={args.id} />
+      ) : null;
+    }
+    if (!result.success) return null;
+    const { id: _id, ...partial } = args;
+    // The interactable name is the creating tool's name (the toolkit entry
+    // key), so the update tool's name reverses by stripping the prefix.
+    return (
+      <Anchor
+        name={toolName.slice(UPDATE_TOOL_PREFIX.length)}
+        initial={partial as TState}
+      />
+    );
+  };
+
+  const InteractableToolUI: ToolCallMessagePartComponent<
+    Record<string, unknown>,
+    { success: true }
+  > = ({ toolName, toolCallId, args, result }) => {
+    const state = args as TState;
+    if (!result) {
+      return (
+        <>
+          {config.render({
+            state,
+            setState: noop,
+            version: undefined,
+            id: toolCallId,
+            streaming: true,
+          })}
+        </>
+      );
+    }
+    return <Anchor name={toolName} id={toolCallId} initial={state} />;
+  };
+
+  return {
+    type: "frontend",
+    description: config.description,
+    parameters: config.stateSchema,
+    display: "standalone",
+    execute: async () => ({ success: true as const }),
+    render: InteractableToolUI,
+  };
+};

package/src/react/model-context/useInteractable.ts

@@ -0,0 +1,233 @@
+"use client";
+
+import { useEffect, useId, useMemo, useRef } from "react";
+import { useAui, useAuiState } from "@assistant-ui/store";
+import type { Unstable_InteractableStateSchema } from "../types/scopes/interactables";
+import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
+import {
+  unstable_getInteractableVersions as getInteractableVersions,
+  interactableToolName,
+} from "../../model-context/interactable-composer-metadata";
+import { unstable_useInteractableState as useInteractableState } from "./useInteractableState";
+import { useJSONEqual } from "../utils/useJSONEqual";
+
+/**
+ * The state type described by an interactable's `stateSchema`. Resolves the
+ * output type of a StandardSchemaV1 schema (e.g. Zod); plain JSON Schema
+ * falls back to `unknown`.
+ */
+export type Unstable_InferInteractableState<TSchema> = TSchema extends {
+  "~standard": { types?: { output: infer TOutput } | undefined };
+}
+  ? TOutput
+  : unknown;
+
+/**
+ * One message's version of an interactable, for components rendered inside
+ * tool-call parts. Show `state` to display history; call `restore()` to set
+ * the live instance back to it.
+ */
+export type Unstable_InteractableVersionInfo<TState> = {
+  /** The interactable's state as it was at this message. */
+  state: TState;
+  /** Whether this message holds the instance's most recent tool-driven version. */
+  isLatest: boolean;
+  /** Sets the live state back to this version. */
+  restore: () => void;
+};
+
+/**
+ * Unstable / Experimental — the interactables API is still evolving and may change in any release.
+ * @deprecated Unstable / Experimental (not actually removed).
+ */
+export type Unstable_InteractableConfig<
+  TSchema extends Unstable_InteractableStateSchema,
+> = {
+  description: string;
+  stateSchema: TSchema;
+  initialState: Unstable_InferInteractableState<TSchema>;
+  /** Unique instance ID; required to address this instance when multiple interactables share a name. Auto-generated if omitted. */
+  id?: string | undefined;
+  /**
+   * Component installed as the tool UI for this interactable's `update_{name}`
+   * tool calls, so a model edit re-renders the interactable at the message
+   * that made it instead of only mutating an earlier one. Prefer
+   * `unstable_interactableTool`, which wires this up. Pass a stable component reference;
+   * changing identity re-registers the tool UI.
+   */
+  updateRender?: ToolCallMessagePartComponent | undefined;
+};
+
+const useInteractable = <TSchema extends Unstable_InteractableStateSchema>(
+  name: string,
+  config: Unstable_InteractableConfig<TSchema>,
+): readonly [
+  Unstable_InferInteractableState<TSchema>,
+  {
+    id: string;
+    /**
+     * This message's version of the instance, when rendered inside a
+     * tool-created interactable message part; `undefined` elsewhere.
+     */
+    version:
+      | Unstable_InteractableVersionInfo<
+          Unstable_InferInteractableState<TSchema>
+        >
+      | undefined;
+    setState: (
+      updater:
+        | Unstable_InferInteractableState<TSchema>
+        | ((
+            prev: Unstable_InferInteractableState<TSchema>,
+          ) => Unstable_InferInteractableState<TSchema>),
+    ) => void;
+    isPending: boolean;
+    error: unknown;
+    flush: () => Promise<void>;
+  },
+] => {
+  const aui = useAui();
+
+  const autoId = useId().replace(/[^a-zA-Z0-9]/g, "");
+
+  // Whether this component renders inside a message part is fixed for its
+  // lifetime, so conditioning the selectors on it is safe.
+  const inPart = aui.part.source != null;
+  const updateToolName = interactableToolName(name);
+  const part = useAuiState((s) => {
+    if (!inPart) return undefined;
+    const p = s.part;
+    return p.type === "tool-call" ? p : undefined;
+  });
+
+  // Inside an update_{name} part, the instance id comes from the call itself:
+  // the result's resolved id (covers id-less calls), or the id argument.
+  let inferredId: string | undefined;
+  if (part?.toolName === updateToolName) {
+    const result = part.result as Record<string, unknown> | undefined;
+    const args = part.args as Record<string, unknown> | undefined;
+    if (result?.success !== false) {
+      if (typeof result?.id === "string") inferredId = result.id;
+      else if (typeof args?.id === "string") inferredId = args.id;
+    }
+  }
+
+  const id = config.id ?? inferredId ?? autoId;
+  const internalScope =
+    part?.toolName === name || part?.toolName === updateToolName
+      ? "thread"
+      : undefined;
+
+  const stateSchemaRef = useRef(config.stateSchema);
+  stateSchemaRef.current = config.stateSchema;
+  const initialStateRef = useRef(config.initialState);
+  initialStateRef.current = config.initialState;
+
+  const interactables = useAuiState(() => aui.unstable_interactables());
+
+  useEffect(() => {
+    return interactables.register({
+      id,
+      name,
+      description: config.description,
+      stateSchema: stateSchemaRef.current,
+      initialState: initialStateRef.current,
+      updateRender: config.updateRender,
+      ...(internalScope ? { scope: internalScope } : {}),
+    } as Parameters<typeof interactables.register>[0] & {
+      scope?: "thread" | undefined;
+    });
+  }, [
+    interactables,
+    id,
+    name,
+    config.description,
+    internalScope,
+    config.updateRender,
+  ]);
+
+  const myToolCallId = part?.toolCallId;
+
+  const [registeredState, methods] =
+    useInteractableState<Unstable_InferInteractableState<TSchema>>(id);
+  const { setState } = methods;
+
+  const versionValue = useAuiState(
+    useJSONEqual((s) => {
+      if (!internalScope || !myToolCallId) return undefined;
+      const versions = getInteractableVersions(s.thread.messages, id, name);
+      if (!versions.some((v) => v.origin === "create" && v.toolCallId === id)) {
+        return undefined;
+      }
+      const mine = versions.find((v) => v.toolCallId === myToolCallId);
+      if (!mine) return undefined;
+      const latestToolCallId = versions.findLast(
+        (v) => v.toolCallId !== undefined,
+      )?.toolCallId;
+      return { state: mine.state, isLatest: latestToolCallId === myToolCallId };
+    }),
+  );
+
+  const version = useMemo(
+    () =>
+      versionValue && {
+        state: versionValue.state as Unstable_InferInteractableState<TSchema>,
+        isLatest: versionValue.isLatest,
+        restore: () =>
+          setState(
+            versionValue.state as Unstable_InferInteractableState<TSchema>,
+          ),
+      },
+    [versionValue, setState],
+  );
+
+  const state =
+    registeredState === undefined ? config.initialState : registeredState;
+
+  return [state, { id, version, ...methods }] as const;
+};
+
+/**
+ * Registers an interactable with the AI assistant and returns its live state,
+ * like `useState` that the model can also read and update.
+ *
+ * Call this once per place that shows the interactable. Other components can
+ * read and write the same instance by passing its `id` to
+ * `unstable_useInteractableState`.
+ *
+ * For tool-created interactables rendered inside tool-call message parts,
+ * `version` carries this message's version of the instance — its state as of
+ * that point in the conversation, whether it is the most recent tool-driven
+ * version, and a `restore()` back to it. Whether older messages render frozen history or stay
+ * live-editable is the component's choice. Inside an `update_{name}` part the
+ * instance `id` is inferred from the call, so the same component works at the
+ * creating call and at update calls.
+ *
+ * @deprecated Unstable / Experimental (not actually removed).
+ */
+export const unstable_useInteractable: <
+  TSchema extends Unstable_InteractableStateSchema,
+>(
+  name: string,
+  config: Unstable_InteractableConfig<TSchema>,
+) => readonly [
+  Unstable_InferInteractableState<TSchema>,
+  {
+    id: string;
+    version:
+      | Unstable_InteractableVersionInfo<
+          Unstable_InferInteractableState<TSchema>
+        >
+      | undefined;
+    setState: (
+      updater:
+        | Unstable_InferInteractableState<TSchema>
+        | ((
+            prev: Unstable_InferInteractableState<TSchema>,
+          ) => Unstable_InferInteractableState<TSchema>),
+    ) => void;
+    isPending: boolean;
+    error: unknown;
+    flush: () => Promise<void>;
+  },
+] = useInteractable;

package/src/react/model-context/useInteractableState.ts

@@ -1,21 +1,16 @@
+"use client";
+
 import { useCallback } from "react";
 import { useAui, useAuiState } from "@assistant-ui/store";
 
 type StateUpdater<TState> = TState | ((prev: TState) => TState);
 
-/**
- * Reads and writes the state of a registered interactable.
- *
- * Pair with {@link useAssistantInteractable} which handles registration.
- */
-export const useInteractableState = <TState>(
+const useInteractableState = <TState>(
   id: string,
-  fallback: TState,
 ): [
-  TState,
+  TState | undefined,
   {
     setState: (updater: StateUpdater<TState>) => void;
-    setSelected: (selected: boolean) => void;
     isPending: boolean;
     error: unknown;
     flush: () => Promise<void>;
@@ -23,15 +18,17 @@ export const useInteractableState = <TState>(
 ] => {
   const aui = useAui();
 
-  const state =
-    (useAuiState((s) => s.interactables.definitions[id]?.state) as TState) ??
-    (fallback as TState);
+  const state = useAuiState(
+    (s) => s.unstable_interactables.definitions[id]?.state,
+  ) as TState | undefined;
 
-  const persistenceStatus = useAuiState((s) => s.interactables.persistence[id]);
+  const persistenceStatus = useAuiState(
+    (s) => s.unstable_interactables.persistence[id],
+  );
 
   const setState = useCallback(
     (updater: StateUpdater<TState>) => {
-      aui.interactables().setState(id, (prev) => {
+      aui.unstable_interactables().setState(id, (prev) => {
         if (typeof updater === "function") {
           return (updater as (prev: TState) => TState)(prev as TState);
         }
@@ -41,23 +38,34 @@ export const useInteractableState = <TState>(
     [aui, id],
   );
 
-  const setSelected = useCallback(
-    (selected: boolean) => {
-      aui.interactables().setSelected(id, selected);
-    },
-    [aui, id],
-  );
-
-  const flush = useCallback(() => aui.interactables().flush(), [aui]);
+  const flush = useCallback(() => aui.unstable_interactables().flush(), [aui]);
 
   return [
     state,
     {
       setState,
-      setSelected,
       isPending: persistenceStatus?.isPending ?? false,
       error: persistenceStatus?.error,
       flush,
     },
   ];
 };
+
+/**
+ * Reads and writes the state of an interactable registered elsewhere, by id.
+ *
+ * Use this from secondary readers (children, siblings); the owning component
+ * registers with `unstable_useInteractable`, which returns state directly. Returns
+ * `undefined` until the owning interactable is registered.
+ *
+ * @deprecated Unstable / Experimental (not actually removed).
+ */
+export const unstable_useInteractableState: <TState>(id: string) => [
+  TState | undefined,
+  {
+    setState: (updater: StateUpdater<TState>) => void;
+    isPending: boolean;
+    error: unknown;
+    flush: () => Promise<void>;
+  },
+] = useInteractableState;

package/src/react/model-context/useInteractableVersions.ts

@@ -0,0 +1,48 @@
+import { useMemo } from "react";
+import { useAuiState } from "@assistant-ui/store";
+import {
+  unstable_getInteractableVersions as getInteractableVersions,
+  type Unstable_InteractableVersion,
+} from "../../model-context/interactable-composer-metadata";
+import { unstable_useInteractableState as useInteractableState } from "./useInteractableState";
+import { useJSONEqual } from "../utils/useJSONEqual";
+
+const useInteractableVersions = <TState = unknown>(
+  id: string,
+  name: string,
+): (Omit<Unstable_InteractableVersion, "state"> & {
+  state: TState;
+  restore: () => void;
+})[] => {
+  const versions = useAuiState(
+    useJSONEqual((s) => getInteractableVersions(s.thread.messages, id, name)),
+  );
+  const [, { setState }] = useInteractableState<TState>(id);
+
+  return useMemo(
+    () =>
+      versions.map((v) => ({
+        ...v,
+        state: v.state as TState,
+        restore: () => setState(v.state as TState),
+      })),
+    [versions, setState],
+  );
+};
+
+/**
+ * Every version of a tool-created interactable recorded in the current
+ * thread, oldest first: the creating tool call, each user edit, and each
+ * `update_*` call. Each entry carries the full state as of that version and a
+ * `restore()` that sets the live instance back to it — enough for a version
+ * picker like an artifact's history dropdown.
+ *
+ * @deprecated Unstable / Experimental (not actually removed).
+ */
+export const unstable_useInteractableVersions: <TState = unknown>(
+  id: string,
+  name: string,
+) => (Omit<Unstable_InteractableVersion, "state"> & {
+  state: TState;
+  restore: () => void;
+})[] = useInteractableVersions;

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

@@ -0,0 +1,27 @@
+import { useRef } from "react";
+import { useAuiState } from "@assistant-ui/store";
+
+const useThreadMessageIds = (): readonly string[] => {
+  const messages = useAuiState((s) => s.thread.messages);
+  const prevIdsRef = useRef<readonly string[]>([]);
+
+  const ids = messages.map((m) => m.id);
+  const prev = prevIdsRef.current;
+  if (prev.length !== ids.length || prev.some((id, i) => id !== ids[i])) {
+    prevIdsRef.current = ids;
+  }
+
+  return prevIdsRef.current;
+};
+
+/**
+ * Returns the ids of the messages in the current thread, in order.
+ *
+ * The returned array keeps a stable identity across content-only updates (e.g.
+ * streaming), changing reference only when the id sequence itself changes. Pair
+ * with `ThreadPrimitive.Unstable_MessageById` to drive a virtualized or custom
+ * message list.
+ *
+ * @deprecated Unstable / Experimental - may change in any release.
+ */
+export const unstable_useThreadMessageIds = useThreadMessageIds;

package/src/react/primitives/part/PartMessages.test.tsx

@@ -0,0 +1,17 @@
+import { expectTypeOf } from "vitest";
+import { PartPrimitiveMessages } from "./PartMessages";
+
+const checkPartMessagesProps = () => {
+  <PartPrimitiveMessages>{() => null}</PartPrimitiveMessages>;
+  <PartPrimitiveMessages components={{ Message: () => null }} />;
+
+  // @ts-expect-error neither components nor children is allowed
+  <PartPrimitiveMessages />;
+  // @ts-expect-error components must be defined, not undefined
+  <PartPrimitiveMessages components={undefined} />;
+  // @ts-expect-error components and children are mutually exclusive
+  <PartPrimitiveMessages components={{ Message: () => null }}>
+    {() => null}
+  </PartPrimitiveMessages>;
+};
+expectTypeOf(checkPartMessagesProps).toEqualTypeOf<() => void>();

package/src/react/primitives/part/PartMessages.tsx

@@ -8,11 +8,16 @@ import {
 } from "../thread/ThreadMessages";
 
 export namespace PartPrimitiveMessages {
-  export type Props = {
-    components?: ThreadPrimitiveMessages.Props["components"];
-    /** Render function called for each message. Receives the message. */
-    children?: (value: { message: ThreadMessage }) => ReactNode;
-  };
+  export type Props =
+    | {
+        components: NonNullable<ThreadPrimitiveMessages.Props["components"]>;
+        children?: never;
+      }
+    | {
+        /** Render function called for each message. Receives the message. */
+        children: (value: { message: ThreadMessage }) => ReactNode;
+        components?: never;
+      };
 }
 
 const usePartMessages = (): readonly ThreadMessage[] | undefined => {
@@ -57,17 +62,17 @@ export const PartPrimitiveMessagesImpl: FC<PartPrimitiveMessages.Props> = ({
 
   if (!messages?.length) return null;
 
-  if (children) {
+  if (components) {
     return (
       <ReadonlyThreadProvider messages={messages}>
-        <ThreadPrimitiveMessagesImpl>{children}</ThreadPrimitiveMessagesImpl>
+        <ThreadPrimitiveMessagesImpl components={components} />
       </ReadonlyThreadProvider>
     );
   }
 
   return (
     <ReadonlyThreadProvider messages={messages}>
-      <ThreadPrimitiveMessagesImpl components={components!} />
+      <ThreadPrimitiveMessagesImpl>{children}</ThreadPrimitiveMessagesImpl>
     </ReadonlyThreadProvider>
   );
 };