@assistant-ui/core 0.2.18 → 0.2.20

package/src/react/interactables-legacy/Interactables.ts

@@ -0,0 +1,332 @@
+import { useState, useEffect, useCallback, useRef, useMemo } from "react";
+import { resource } from "@assistant-ui/tap";
+import {
+  useAssistantClientRef,
+  type ClientOutput,
+  attachTransformScopes,
+} from "@assistant-ui/store";
+import type {
+  InteractablesState,
+  InteractableRegistration,
+  InteractableStateSchema,
+  InteractablePersistedState,
+  InteractablePersistenceAdapter,
+} from "./scopes";
+import { toJSONSchema, toPartialJSONSchema } from "assistant-stream";
+import { ModelContext } from "../../store";
+import { buildInteractableModelContext } from "./interactable-model-context";
+
+const PERSISTENCE_DEBOUNCE_MS = 500;
+
+const useInteractables = (): ClientOutput<"interactables"> => {
+  const [state, setState] = useState<InteractablesState>(() => ({
+    definitions: {},
+    persistence: {},
+  }));
+
+  const clientRef = useAssistantClientRef();
+
+  const stateRef = useRef(state);
+  useEffect(() => {
+    stateRef.current = state;
+  }, [state]);
+
+  const subscribersRef = useRef(new Set<() => void>());
+  const partialSchemaCacheRef = useRef(
+    new Map<string, InteractableStateSchema>(),
+  );
+  const detachedStateRef = useRef(new Map<string, unknown>());
+
+  const adapterRef = useRef<InteractablePersistenceAdapter | undefined>(
+    undefined,
+  );
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(
+    undefined,
+  );
+  const syncSeqRef = useRef(0);
+  const hasPendingLocalChangeRef = useRef(false);
+  const flushResolversRef = useRef<Array<() => void>>([]);
+  const dirtyIdsRef = useRef(new Set<string>());
+
+  const runPersistence = useCallback(async () => {
+    const adapter = adapterRef.current;
+    if (!adapter) {
+      for (const resolve of flushResolversRef.current) resolve();
+      flushResolversRef.current = [];
+      return;
+    }
+
+    const seq = ++syncSeqRef.current;
+    const dirtyIds = new Set(dirtyIdsRef.current);
+    dirtyIdsRef.current.clear();
+    hasPendingLocalChangeRef.current = true;
+
+    // Snapshot before any await so unregistered definitions are still included.
+    const exported = stateRef.current.definitions;
+    const payload: InteractablePersistedState = {};
+    for (const [id, def] of Object.entries(exported)) {
+      payload[id] = { name: def.name, state: def.state };
+    }
+
+    setState((prev) => ({
+      ...prev,
+      persistence: {
+        ...prev.persistence,
+        ...Object.fromEntries(
+          [...dirtyIds].map((id) => [
+            id,
+            { isPending: true, error: undefined },
+          ]),
+        ),
+      },
+    }));
+
+    try {
+      await adapter.save(payload);
+      if (syncSeqRef.current === seq) {
+        hasPendingLocalChangeRef.current = false;
+        setState((prev) => {
+          const persistence = { ...prev.persistence };
+          for (const id of dirtyIds) delete persistence[id];
+          return { ...prev, persistence };
+        });
+      }
+    } catch (e) {
+      if (syncSeqRef.current === seq) {
+        hasPendingLocalChangeRef.current = false;
+        setState((prev) => ({
+          ...prev,
+          persistence: {
+            ...prev.persistence,
+            ...Object.fromEntries(
+              [...dirtyIds].map((id) => [id, { isPending: false, error: e }]),
+            ),
+          },
+        }));
+      }
+    } finally {
+      if (dirtyIdsRef.current.size > 0 && adapterRef.current) {
+        runPersistence();
+      } else {
+        for (const resolve of flushResolversRef.current) resolve();
+        flushResolversRef.current = [];
+      }
+    }
+  }, []);
+
+  const schedulePersistence = useCallback(
+    (id: string) => {
+      if (!adapterRef.current) return;
+      dirtyIdsRef.current.add(id);
+      if (debounceTimerRef.current !== undefined) {
+        clearTimeout(debounceTimerRef.current);
+      }
+      debounceTimerRef.current = setTimeout(() => {
+        debounceTimerRef.current = undefined;
+        if (!hasPendingLocalChangeRef.current) {
+          runPersistence();
+        } else {
+          debounceTimerRef.current = setTimeout(() => {
+            debounceTimerRef.current = undefined;
+            runPersistence();
+          }, PERSISTENCE_DEBOUNCE_MS);
+        }
+      }, PERSISTENCE_DEBOUNCE_MS);
+    },
+    [runPersistence],
+  );
+
+  const exportState = useCallback((): InteractablePersistedState => {
+    const result: InteractablePersistedState = {};
+    for (const [id, def] of Object.entries(stateRef.current.definitions)) {
+      result[id] = { name: def.name, state: def.state };
+    }
+    return result;
+  }, []);
+
+  const importState = useCallback((saved: InteractablePersistedState) => {
+    for (const [id, entry] of Object.entries(saved)) {
+      detachedStateRef.current.set(id, entry.state);
+    }
+    setState((prev) => {
+      let changed = false;
+      const definitions = { ...prev.definitions };
+      for (const [id, entry] of Object.entries(saved)) {
+        if (definitions[id]) {
+          definitions[id] = { ...definitions[id], state: entry.state };
+          changed = true;
+        }
+      }
+      return changed ? { ...prev, definitions } : prev;
+    });
+  }, []);
+
+  const setPersistenceAdapter = useCallback(
+    (adapter: InteractablePersistenceAdapter | undefined) => {
+      adapterRef.current = adapter;
+    },
+    [],
+  );
+
+  const flush = useCallback(async () => {
+    if (debounceTimerRef.current !== undefined) {
+      clearTimeout(debounceTimerRef.current);
+      debounceTimerRef.current = undefined;
+    }
+    if (!adapterRef.current) return;
+    if (!hasPendingLocalChangeRef.current && dirtyIdsRef.current.size === 0)
+      return;
+    const p = new Promise<void>((resolve) => {
+      flushResolversRef.current.push(resolve);
+    });
+    if (!hasPendingLocalChangeRef.current) {
+      runPersistence();
+    }
+    return p;
+  }, [runPersistence]);
+
+  const flushIfPending = useCallback(() => {
+    if (adapterRef.current && debounceTimerRef.current !== undefined) {
+      clearTimeout(debounceTimerRef.current);
+      debounceTimerRef.current = undefined;
+      runPersistence();
+    }
+  }, [runPersistence]);
+
+  const setDefState = useCallback(
+    (id: string, updater: (prev: unknown) => unknown) => {
+      setState((prev) => {
+        const existing = prev.definitions[id];
+        if (!existing) return prev;
+        return {
+          ...prev,
+          definitions: {
+            ...prev.definitions,
+            [id]: { ...existing, state: updater(existing.state) },
+          },
+        };
+      });
+      if (stateRef.current.definitions[id]) schedulePersistence(id);
+    },
+    [schedulePersistence],
+  );
+
+  const setDefSelected = useCallback((id: string, selected: boolean) => {
+    setState((prev) => {
+      const existing = prev.definitions[id];
+      if (!existing) return prev;
+      return {
+        ...prev,
+        definitions: {
+          ...prev.definitions,
+          [id]: { ...existing, selected },
+        },
+      };
+    });
+  }, []);
+
+  const provider = useMemo(
+    () => ({
+      getModelContext: () => {
+        const defs = stateRef.current.definitions;
+        return (
+          buildInteractableModelContext(
+            defs,
+            partialSchemaCacheRef.current,
+            setDefState,
+          ) ?? {}
+        );
+      },
+      subscribe: (callback: () => void) => {
+        subscribersRef.current.add(callback);
+        return () => {
+          subscribersRef.current.delete(callback);
+        };
+      },
+    }),
+    [setDefState],
+  );
+
+  useEffect(() => {
+    for (const cb of subscribersRef.current) cb();
+  }, [state]);
+
+  useEffect(() => {
+    return clientRef.current!.modelContext().register(provider);
+  }, [clientRef, provider]);
+
+  const register = useCallback(
+    (def: InteractableRegistration) => {
+      try {
+        const jsonSchema = toJSONSchema(def.stateSchema);
+        partialSchemaCacheRef.current.set(
+          def.id,
+          toPartialJSONSchema(jsonSchema),
+        );
+      } catch (e) {
+        console.warn(
+          `[Interactables] Failed to create partial schema for "${def.name}". The update tool will require all fields.`,
+          e,
+        );
+      }
+
+      const detached = detachedStateRef.current.get(def.id);
+      detachedStateRef.current.delete(def.id);
+
+      setState((prev) => ({
+        ...prev,
+        definitions: {
+          ...prev.definitions,
+          [def.id]: {
+            id: def.id,
+            name: def.name,
+            description: def.description,
+            stateSchema: def.stateSchema,
+            state:
+              prev.definitions[def.id]?.state ?? detached ?? def.initialState,
+            selected: def.selected,
+          },
+        },
+      }));
+
+      return () => {
+        flushIfPending();
+        setState((prev) => {
+          const existing = prev.definitions[def.id];
+          if (existing) {
+            detachedStateRef.current.set(def.id, existing.state);
+          }
+          partialSchemaCacheRef.current.delete(def.id);
+          const { [def.id]: _, ...rest } = prev.definitions;
+          const { [def.id]: __, ...restPersistence } = prev.persistence;
+          return { ...prev, definitions: rest, persistence: restPersistence };
+        });
+      };
+    },
+    [flushIfPending],
+  );
+
+  return {
+    getState: () => state,
+    register,
+    setState: setDefState,
+    setSelected: setDefSelected,
+    exportState,
+    importState,
+    setPersistenceAdapter,
+    flush,
+  };
+};
+
+/**
+ * @deprecated Since 2026-06-14 — migrate to the Unstable / Experimental API.
+ * Scheduled for removal on/after 2026-09-14. See
+ * {@link https://www.assistant-ui.com/docs/tools/interactables#migrating-from-the-previous-api | Interactables migration guide}.
+ */
+export const Interactables = resource(useInteractables);
+
+attachTransformScopes(useInteractables, (scopes, parent) => {
+  if (!scopes.modelContext && parent.modelContext.source === null) {
+    scopes.modelContext = ModelContext();
+  }
+});

package/src/react/interactables-legacy/interactable-model-context.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildInteractableModelContext } from "./interactable-model-context";
+import type { InteractableDefinition } from "./scopes";
+
+const def = (
+  id: string,
+  name: string,
+  state: unknown,
+  selected = false,
+): InteractableDefinition => ({
+  id,
+  name,
+  description: `desc of ${name}`,
+  stateSchema: { type: "object" as const, properties: {} },
+  state,
+  selected,
+});
+
+describe("legacy buildInteractableModelContext", () => {
+  it("preserves per-instance update tools and selected system context", async () => {
+    const definitions = {
+      "note-1": def("note-1", "note", { title: "one" }, true),
+      "note-2": def("note-2", "note", { title: "two" }),
+    };
+    const setDefState = vi.fn(
+      (id: string, updater: (prev: unknown) => unknown) => {
+        const current = definitions[id as keyof typeof definitions];
+        if (current) current.state = updater(current.state);
+      },
+    );
+
+    const ctx = buildInteractableModelContext(
+      definitions,
+      new Map(),
+      setDefState,
+    );
+
+    expect(Object.keys(ctx!.tools).sort()).toEqual([
+      "update_note_note-1",
+      "update_note_note-2",
+    ]);
+    expect(ctx!.system).toContain(
+      'Interactable component "note" [id="note-1"] (SELECTED)',
+    );
+
+    await ctx!.tools["update_note_note-2"]!.execute!(
+      { title: "updated" },
+      {} as never,
+    );
+
+    expect(definitions["note-1"].state).toEqual({ title: "one" });
+    expect(definitions["note-2"].state).toEqual({ title: "updated" });
+  });
+});

package/src/react/interactables-legacy/interactable-model-context.ts

@@ -0,0 +1,80 @@
+import type { Tool } from "assistant-stream";
+import type { InteractableDefinition, InteractableStateSchema } from "./scopes";
+
+export function shallowMerge(prev: unknown, partial: unknown): unknown {
+  if (
+    typeof prev !== "object" ||
+    prev === null ||
+    typeof partial !== "object" ||
+    partial === null ||
+    Array.isArray(prev) ||
+    Array.isArray(partial)
+  ) {
+    return partial;
+  }
+  return {
+    ...(prev as Record<string, unknown>),
+    ...(partial as Record<string, unknown>),
+  };
+}
+
+export function buildInteractableModelContext(
+  definitions: Record<string, InteractableDefinition>,
+  partialSchemaCache: Map<string, InteractableStateSchema>,
+  setDefState: (id: string, updater: (prev: unknown) => unknown) => void,
+): { system: string; tools: Record<string, Tool<any, any>> } | undefined {
+  const entries = Object.values(definitions);
+  if (entries.length === 0) return undefined;
+
+  const byName = new Map<string, InteractableDefinition[]>();
+  for (const def of entries) {
+    const list = byName.get(def.name) ?? [];
+    list.push(def);
+    byName.set(def.name, list);
+  }
+
+  const systemParts: string[] = [];
+  const tools: Record<string, Tool<any, any>> = {};
+
+  for (const [name, instances] of byName) {
+    const isMulti = instances.length > 1;
+
+    for (const def of instances) {
+      const selectedTag = def.selected ? " (SELECTED)" : "";
+      const idTag = isMulti ? ` [id="${def.id}"]` : "";
+
+      systemParts.push(
+        `Interactable component "${name}"${idTag}${selectedTag} (${def.description}). Current state: ${JSON.stringify(def.state)}`,
+      );
+
+      const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+      const safeId = def.id.replace(/[^a-zA-Z0-9_-]/g, "_");
+      const toolName = isMulti
+        ? `update_${safeName}_${safeId}`
+        : `update_${safeName}`;
+
+      const partialSchema = partialSchemaCache.get(def.id) ?? def.stateSchema;
+
+      tools[toolName] = {
+        type: "frontend" as const,
+        description: `Update the state of interactable component "${name}"${isMulti ? ` (id: ${def.id})` : ""}. Only include the fields you want to change; omitted fields keep their current values. ${def.description}`,
+        parameters: partialSchema,
+        streamCall: async (reader) => {
+          try {
+            for await (const partialArgs of reader.args.streamValues()) {
+              setDefState(def.id, (prev) => shallowMerge(prev, partialArgs));
+            }
+          } catch {
+            // Non-fatal: execute handles the final state
+          }
+        },
+        execute: async (partialState: unknown) => {
+          setDefState(def.id, (prev) => shallowMerge(prev, partialState));
+          return { success: true };
+        },
+      };
+    }
+  }
+
+  return { system: systemParts.join("\n"), tools };
+}

package/src/react/interactables-legacy/scopes.ts

@@ -0,0 +1,66 @@
+import type { Tool } from "assistant-stream";
+import type { Unsubscribe } from "../..";
+
+/**
+ * Schema type matching Tool["parameters"] from assistant-stream.
+ * Accepts both StandardSchemaV1 and JSONSchema7.
+ */
+export type InteractableStateSchema = NonNullable<
+  Extract<Tool, { parameters: unknown }>["parameters"]
+>;
+
+export type InteractableDefinition = {
+  id: string;
+  name: string;
+  description: string;
+  stateSchema: InteractableStateSchema;
+  state: unknown;
+  selected?: boolean | undefined;
+};
+
+export type InteractableRegistration = {
+  id: string;
+  name: string;
+  description: string;
+  stateSchema: InteractableStateSchema;
+  initialState: unknown;
+  selected?: boolean | undefined;
+};
+
+export type InteractablePersistenceStatus = {
+  isPending: boolean;
+  error: unknown;
+};
+
+export type InteractablesState = {
+  /** Keyed by instance id */
+  definitions: Record<string, InteractableDefinition>;
+  /** Per-id persistence sync status */
+  persistence: Record<string, InteractablePersistenceStatus>;
+};
+
+export type InteractablePersistedState = Record<
+  string,
+  { name: string; state: unknown }
+>;
+
+export type InteractablePersistenceAdapter = {
+  save(state: InteractablePersistedState): void | Promise<void>;
+};
+
+export type InteractablesMethods = {
+  getState(): InteractablesState;
+  register(def: InteractableRegistration): Unsubscribe;
+  setState(id: string, updater: (prev: unknown) => unknown): void;
+  setSelected(id: string, selected: boolean): void;
+  exportState(): InteractablePersistedState;
+  importState(saved: InteractablePersistedState): void;
+  setPersistenceAdapter(
+    adapter: InteractablePersistenceAdapter | undefined,
+  ): void;
+  flush(): Promise<void>;
+};
+
+export type InteractablesClientSchema = {
+  methods: InteractablesMethods;
+};

package/src/react/{model-context → interactables-legacy}/useAssistantInteractable.ts

@@ -1,7 +1,12 @@
 import { useEffect, useId, useRef } from "react";
 import { useAui } from "@assistant-ui/store";
-import type { InteractableStateSchema } from "../types/scopes/interactables";
+import type { InteractableStateSchema } from "./scopes";
 
+/**
+ * @deprecated Since 2026-06-14 — migrate to the Unstable / Experimental API.
+ * Scheduled for removal on/after 2026-09-14. See
+ * {@link https://www.assistant-ui.com/docs/tools/interactables#migrating-from-the-previous-api | Interactables migration guide}.
+ */
 export type AssistantInteractableProps = {
   description: string;
   stateSchema: InteractableStateSchema;
@@ -11,6 +16,10 @@ export type AssistantInteractableProps = {
 };
 
 /**
+ * @deprecated Since 2026-06-14 — migrate to the Unstable / Experimental API.
+ * Scheduled for removal on/after 2026-09-14. See
+ * {@link https://www.assistant-ui.com/docs/tools/interactables#migrating-from-the-previous-api | Interactables migration guide}.
+ *
  * Registers an interactable with the AI assistant.
  *
  * This hook handles registration only. To read and write the interactable's

package/src/react/interactables-legacy/useInteractableState.ts

@@ -0,0 +1,67 @@
+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.
+ *
+ * @deprecated Since 2026-06-14 — migrate to the Unstable / Experimental API.
+ * Scheduled for removal on/after 2026-09-14. See
+ * {@link https://www.assistant-ui.com/docs/tools/interactables#migrating-from-the-previous-api | Interactables migration guide}.
+ */
+export const useInteractableState = <TState>(
+  id: string,
+  fallback: TState,
+): [
+  TState,
+  {
+    setState: (updater: StateUpdater<TState>) => void;
+    setSelected: (selected: boolean) => void;
+    isPending: boolean;
+    error: unknown;
+    flush: () => Promise<void>;
+  },
+] => {
+  const aui = useAui();
+
+  const state =
+    (useAuiState((s) => s.interactables.definitions[id]?.state) as TState) ??
+    (fallback as TState);
+
+  const persistenceStatus = useAuiState((s) => s.interactables.persistence[id]);
+
+  const setState = useCallback(
+    (updater: StateUpdater<TState>) => {
+      aui.interactables().setState(id, (prev) => {
+        if (typeof updater === "function") {
+          return (updater as (prev: TState) => TState)(prev as TState);
+        }
+        return updater;
+      });
+    },
+    [aui, id],
+  );
+
+  const setSelected = useCallback(
+    (selected: boolean) => {
+      aui.interactables().setSelected(id, selected);
+    },
+    [aui, id],
+  );
+
+  const flush = useCallback(() => aui.interactables().flush(), [aui]);
+
+  return [
+    state,
+    {
+      setState,
+      setSelected,
+      isPending: persistenceStatus?.isPending ?? false,
+      error: persistenceStatus?.error,
+      flush,
+    },
+  ];
+};