@assistant-ui/store 0.2.9 → 0.2.11

package/src/useAuiState.ts

@@ -4,18 +4,35 @@ import { useAui } from "./useAui";
 import { getProxiedAssistantState } from "./utils/proxied-assistant-state";
 
 /**
- * Hook to access a slice of the assistant state with automatic subscription
+ * Subscribes to a slice of {@link AssistantState} and re-renders the
+ * component whenever that slice changes.
  *
- * @param selector - Function to select a slice of the state
- * @returns The selected state slice
+ * The `selector` is called on every store update; its return value is
+ * compared by `Object.is`, and the component re-renders only when the
+ * selected slice changes. Returning the entire state object is not
+ * supported and throws at runtime — select a specific field instead, or
+ * compose multiple `useAuiState` calls. Returning a new object or array
+ * literal, including spreading `s.thread` into a new object, causes a
+ * re-render on every store update; either select primitives or return a
+ * memoized reference.
+ *
+ * @param selector - Pure function that derives a value from the current
+ *   assistant state. Should be cheap and referentially stable for equal
+ *   inputs (plain field reads, primitives, or memoized values).
+ * @returns The currently selected slice.
  *
  * @example
- * ```typescript
- * const aui = useAui({
- *   foo: RootScope({ ... }),
- * });
+ * ```tsx
+ * // Disable a button while a run is in flight.
+ * const isRunning = useAuiState((s) => s.thread.isRunning);
+ * ```
  *
- * const bar = useAuiState((s) => s.foo.bar);
+ * @example
+ * ```tsx
+ * // Prefer multiple selectors over an inline object literal, which would
+ * // create a new reference on every render.
+ * const text = useAuiState((s) => s.composer.text);
+ * const canSend = useAuiState((s) => s.composer.canSend);
  * ```
  */
 export const useAuiState = <T>(selector: (state: AssistantState) => T): T => {

package/src/utils/react-assistant-context.tsx

@@ -85,20 +85,33 @@ export const useAssistantContextValue = (): AssistantClient => {
 };
 
 /**
- * Provider component for AssistantClient
+ * Supplies an `AssistantClient` to the React tree.
+ *
+ * Place near the root of any subtree that uses {@link useAui} or the
+ * primitives built on it. Components rendered outside an `AuiProvider`
+ * receive a default client whose scope accessors throw on use, so
+ * missing-provider mistakes surface at the point of use.
+ *
+ * When mounting a runtime built with one of the runtime hooks, use
+ * {@link AssistantRuntimeProvider} — it installs an `AuiProvider`
+ * internally — rather than wiring `AuiProvider` yourself.
  *
  * @example
- * ```typescript
- * <AuiProvider value={aui}>
- *   <YourApp />
- * </AuiProvider>
+ * ```tsx
+ * function ScopedAssistant({ children, scopes }) {
+ *   const aui = useAui(scopes);
+ *
+ *   return <AuiProvider value={aui}>{children}</AuiProvider>;
+ * }
  * ```
  */
 export const AuiProvider = ({
   value,
   children,
 }: {
+  /** Assistant client to expose to descendants. */
   value: AssistantClient;
+  /** Subtree that may read from the client. */
   children: React.ReactNode;
 }): React.ReactElement => {
   return (

package/src/utils/splitClients.ts

@@ -6,7 +6,7 @@ import type {
 } from "../types/client";
 import { getTransformScopes } from "../attachTransformScopes";
 import type { useAui } from "../useAui";
-import { tapMemo } from "@assistant-ui/tap";
+import { tapMemo, type ResourceElement } from "@assistant-ui/tap";
 
 export type RootClients = Partial<
   Record<ClientNames, ClientElement<ClientNames>>
@@ -35,7 +35,9 @@ function splitClients(clients: useAui.Props, baseClient: AssistantClient) {
       if (visited.has(clientElement.type)) continue;
       visited.add(clientElement.type);
 
-      const transform = getTransformScopes(clientElement.type);
+      const transform = getTransformScopes(
+        clientElement.type as (props: any) => ResourceElement<any>,
+      );
       if (transform) {
         transform(scopes, baseClient);
         changed = true;