@assistant-ui/core 0.1.9 → 0.1.10

package/src/react/client/Interactables.ts

@@ -13,34 +13,21 @@ import {
 } from "@assistant-ui/store";
 import type {
   InteractablesState,
-  InteractableDefinition,
   InteractableRegistration,
   InteractableStateSchema,
+  InteractablePersistedState,
+  InteractablePersistenceAdapter,
 } from "../types/scopes/interactables";
 import { toJSONSchema, toPartialJSONSchema } from "assistant-stream";
-import type { Tool } from "assistant-stream";
 import { ModelContext } from "../../store";
+import { buildInteractableModelContext } from "./interactable-model-context";
 
-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>),
-  };
-}
+const PERSISTENCE_DEBOUNCE_MS = 500;
 
 export const Interactables = resource((): ClientOutput<"interactables"> => {
   const [state, setState] = tapState<InteractablesState>(() => ({
     definitions: {},
+    persistence: {},
   }));
 
   const clientRef = tapAssistantClientRef();
@@ -51,12 +38,167 @@ export const Interactables = resource((): ClientOutput<"interactables"> => {
   }, [state]);
 
   const subscribersRef = tapRef(new Set<() => void>());
-
   const partialSchemaCacheRef = tapRef(
     new Map<string, InteractableStateSchema>(),
   );
   const detachedStateRef = tapRef(new Map<string, unknown>());
 
+  const adapterRef = tapRef<InteractablePersistenceAdapter | undefined>(
+    undefined,
+  );
+  const debounceTimerRef = tapRef<ReturnType<typeof setTimeout> | undefined>(
+    undefined,
+  );
+  const syncSeqRef = tapRef(0);
+  const hasPendingLocalChangeRef = tapRef(false);
+  const flushResolversRef = tapRef<Array<() => void>>([]);
+  const dirtyIdsRef = tapRef(new Set<string>());
+
+  const runPersistence = tapCallback(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 = tapCallback(
+    (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 = tapCallback((): 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 = tapCallback((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 = tapCallback(
+    (adapter: InteractablePersistenceAdapter | undefined) => {
+      adapterRef.current = adapter;
+    },
+    [],
+  );
+
+  const flush = tapCallback(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 = tapCallback(() => {
+    if (adapterRef.current && debounceTimerRef.current !== undefined) {
+      clearTimeout(debounceTimerRef.current);
+      debounceTimerRef.current = undefined;
+      runPersistence();
+    }
+  }, [runPersistence]);
+
   const setDefState = tapCallback(
     (id: string, updater: (prev: unknown) => unknown) => {
       setState((prev) => {
@@ -70,8 +212,9 @@ export const Interactables = resource((): ClientOutput<"interactables"> => {
           },
         };
       });
+      if (stateRef.current.definitions[id]) schedulePersistence(id);
     },
-    [],
+    [schedulePersistence],
   );
 
   const setDefSelected = tapCallback((id: string, selected: boolean) => {
@@ -92,63 +235,13 @@ export const Interactables = resource((): ClientOutput<"interactables"> => {
     () => ({
       getModelContext: () => {
         const defs = stateRef.current.definitions;
-        const entries = Object.values(defs);
-        if (entries.length === 0) return {};
-
-        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 =
-              partialSchemaCacheRef.current.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 };
+        return (
+          buildInteractableModelContext(
+            defs,
+            partialSchemaCacheRef.current,
+            setDefState,
+          ) ?? {}
+        );
       },
       subscribe: (callback: () => void) => {
         subscribersRef.current.add(callback);
@@ -162,67 +255,73 @@ export const Interactables = resource((): ClientOutput<"interactables"> => {
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: state dep triggers notification
   tapEffect(() => {
-    for (const cb of subscribersRef.current) {
-      cb();
-    }
+    for (const cb of subscribersRef.current) cb();
   }, [state]);
 
   tapEffect(() => {
     return clientRef.current!.modelContext().register(provider);
   }, [clientRef, provider]);
 
-  const register = tapCallback((def: InteractableRegistration) => {
-    try {
-      const jsonSchema = toJSONSchema(def.stateSchema);
-      partialSchemaCacheRef.current.set(
-        def.id,
-        toPartialJSONSchema(jsonSchema),
-      );
-    } catch (e) {
-      // Fall back to the raw schema; partial updates may not work correctly
-      console.warn(
-        `[Interactables] Failed to create partial schema for "${def.name}". The update tool will require all fields.`,
-        e,
-      );
-    }
+  const register = tapCallback(
+    (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);
+      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,
+      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 () => {
-      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;
-        return { ...prev, definitions: rest };
-      });
-    };
-  }, []);
+      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,
   };
 });
 

package/src/react/client/interactable-model-context.ts

@@ -0,0 +1,83 @@
+import type { Tool } from "assistant-stream";
+import type {
+  InteractableDefinition,
+  InteractableStateSchema,
+} from "../types/scopes/interactables";
+
+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/index.ts

@@ -14,6 +14,10 @@ export {
   makeAssistantDataUI,
 } from "./model-context/makeAssistantDataUI";
 export { useAssistantInstructions } from "./model-context/useAssistantInstructions";
+export {
+  useAssistantContext,
+  type AssistantContextConfig,
+} from "./model-context/useAssistantContext";
 export {
   useAssistantTool,
   type AssistantToolProps,
@@ -29,15 +33,14 @@ export {
 export { useInlineRender } from "./model-context/useInlineRender";
 export type { Toolkit, ToolDefinition } from "./model-context/toolbox";
 export {
-  useInteractable,
-  type UseInteractableConfig,
-  type UseInteractableMetadata,
-} from "./model-context/useInteractable";
+  useAssistantInteractable,
+  type AssistantInteractableProps,
+} from "./model-context/useAssistantInteractable";
+export { useInteractableState } from "./model-context/useInteractableState";
 export {
-  makeInteractable,
-  type InteractableConfig,
-  type AssistantInteractable,
-} from "./model-context/makeInteractable";
+  useToolArgsStatus,
+  type ToolArgsStatus,
+} from "./model-context/useToolArgsStatus";
 
 // client
 export { Tools } from "./client/Tools";
@@ -85,6 +88,9 @@ export type {
   InteractableDefinition,
   InteractableRegistration,
   InteractablesMethods,
+  InteractablePersistedState,
+  InteractablePersistenceAdapter,
+  InteractablePersistenceStatus,
   InteractablesClientSchema,
 } from "./types/scopes/interactables";
 
@@ -211,6 +217,11 @@ export {
 } from "./primitive-hooks/useActionBarFeedback";
 export { useActionBarSpeak } from "./primitive-hooks/useActionBarSpeak";
 export { useActionBarStopSpeaking } from "./primitive-hooks/useActionBarStopSpeaking";
+export {
+  useVoiceState,
+  useVoiceVolume,
+  useVoiceControls,
+} from "./primitive-hooks/useVoice";
 export { useBranchPickerNext } from "./primitive-hooks/useBranchPickerNext";
 export { useBranchPickerPrevious } from "./primitive-hooks/useBranchPickerPrevious";
 export {

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

@@ -0,0 +1,22 @@
+import { useEffect, useRef } from "react";
+import { useAui } from "@assistant-ui/store";
+import type { AssistantContextConfig } from "../..";
+
+export type { AssistantContextConfig };
+
+export const useAssistantContext = (config: AssistantContextConfig) => {
+  const { getContext, disabled = false } = config;
+  const aui = useAui();
+  const getContextRef = useRef(getContext);
+  getContextRef.current = getContext;
+
+  useEffect(() => {
+    if (disabled) return;
+
+    return aui.modelContext().register({
+      getModelContext: () => ({
+        system: getContextRef.current(),
+      }),
+    });
+  }, [aui, disabled]);
+};

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

@@ -0,0 +1,47 @@
+import { useEffect, useId, useRef } from "react";
+import { useAui } from "@assistant-ui/store";
+import type { InteractableStateSchema } from "../types/scopes/interactables";
+
+export type AssistantInteractableProps = {
+  description: string;
+  stateSchema: InteractableStateSchema;
+  initialState: unknown;
+  id?: string;
+  selected?: boolean;
+};
+
+/**
+ * Registers an interactable with the AI assistant.
+ *
+ * This hook handles registration only. To read and write the interactable's
+ * state, use {@link useInteractableState} with the returned id.
+ *
+ * @returns The interactable instance id.
+ */
+export const useAssistantInteractable = (
+  name: string,
+  config: AssistantInteractableProps,
+): string => {
+  const aui = useAui();
+
+  const autoId = useId().replace(/[^a-zA-Z0-9]/g, "");
+  const id = config.id ?? autoId;
+
+  const stateSchemaRef = useRef(config.stateSchema);
+  stateSchemaRef.current = config.stateSchema;
+  const initialStateRef = useRef(config.initialState);
+  initialStateRef.current = config.initialState;
+
+  useEffect(() => {
+    return aui.interactables().register({
+      id,
+      name,
+      description: config.description,
+      stateSchema: stateSchemaRef.current,
+      initialState: initialStateRef.current,
+      selected: config.selected,
+    });
+  }, [aui, id, name, config.description, config.selected]);
+
+  return id;
+};

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

@@ -0,0 +1,63 @@
+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>(
+  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,
+    },
+  ];
+};