@assistant-ui/store 0.2.10 → 0.2.12

package/dist/wrapperResource.js

@@ -1,11 +1,14 @@
-import { resource, withKey, } from "@assistant-ui/tap";
-export const wrapperResource = (fn) => {
-    const res = resource(fn);
-    return (props) => {
-        const el = res(props);
-        if (props.key === undefined)
-            return el;
-        return withKey(props.key, el);
-    };
+import { resource, withKey } from "@assistant-ui/tap";
+//#region src/wrapperResource.ts
+const wrapperResource = (fn) => {
+	const res = resource(fn);
+	return (props) => {
+		const el = res(props);
+		if (props.key === void 0) return el;
+		return withKey(props.key, el);
+	};
 };
+//#endregion
+export { wrapperResource };
+
 //# sourceMappingURL=wrapperResource.js.map

package/dist/wrapperResource.js.map

@@ -1 +1 @@
-{"version":3,"file":"wrapperResource.js","sourceRoot":"","sources":["../src/wrapperResource.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,QAAQ,EACR,OAAO,GACR,MAAM,mBAAmB,CAAC;AAE3B,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,EAAoC,EACH,EAAE;IACnC,MAAM,GAAG,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;IACzB,OAAO,CAAC,KAAyB,EAAE,EAAE;QACnC,MAAM,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;QACtB,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACvC,OAAO,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAChC,CAAC,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"wrapperResource.js","names":[],"sources":["../src/wrapperResource.ts"],"sourcesContent":["import {\n  type ResourceElement,\n  type Resource,\n  resource,\n  withKey,\n} from \"@assistant-ui/tap\";\n\nexport const wrapperResource = <R, P>(\n  fn: (props: ResourceElement<P>) => R,\n): Resource<R, ResourceElement<P>> => {\n  const res = resource(fn);\n  return (props: ResourceElement<P>) => {\n    const el = res(props);\n    if (props.key === undefined) return el;\n    return withKey(props.key, el);\n  };\n};\n"],"mappings":";;AAOA,MAAa,mBACX,OACoC;CACpC,MAAM,MAAM,SAAS,EAAE;CACvB,QAAQ,UAA8B;EACpC,MAAM,KAAK,IAAI,KAAK;EACpB,IAAI,MAAM,QAAQ,KAAA,GAAW,OAAO;EACpC,OAAO,QAAQ,MAAM,KAAK,EAAE;CAC9B;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/store",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Tap-based state management for @assistant-ui",
   "keywords": [
     "state-management",
@@ -30,7 +30,7 @@
     "use-effect-event": "^2.0.3"
   },
   "peerDependencies": {
-    "@assistant-ui/tap": "^0.5.11",
+    "@assistant-ui/tap": "^0.5.12",
     "@types/react": "*",
     "react": "^18 || ^19"
   },
@@ -41,13 +41,13 @@
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",
-    "@types/react": "^19.2.14",
+    "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
-    "react": "^19.2.5",
-    "vitest": "^4.1.5",
-    "@assistant-ui/tap": "0.5.11",
-    "@assistant-ui/x-buildutils": "0.0.7"
+    "react": "^19.2.6",
+    "vitest": "^4.1.7",
+    "@assistant-ui/tap": "0.5.12",
+    "@assistant-ui/x-buildutils": "0.0.9"
   },
   "publishConfig": {
     "access": "public",

package/src/AuiIf.ts

@@ -5,10 +5,44 @@ import { useAuiState } from "./useAuiState";
 import type { AssistantState } from "./types/client";
 
 export namespace AuiIf {
-  export type Props = PropsWithChildren<{ condition: AuiIf.Condition }>;
+  /** Props for `AuiIf`. */
+  export type Props = PropsWithChildren<{
+    /**
+     * Selector that decides whether to render `children`. Children render
+     * when this returns `true` and unmount when it returns `false`.
+     */
+    condition: AuiIf.Condition;
+  }>;
+
+  /**
+   * Selector passed to `AuiIf`. Receives the assistant state and must
+   * return a boolean.
+   */
   export type Condition = (state: AssistantState) => boolean;
 }
 
+/**
+ * Conditionally renders children based on a slice of assistant state.
+ *
+ * A thin wrapper around {@link useAuiState} that renders its children
+ * when `condition` returns `true` and unmounts them when it returns
+ * `false`. Keeps render logic declarative without mounting unused
+ * subtrees.
+ *
+ * @example
+ * ```tsx
+ * <AuiIf condition={(s) => s.thread.isRunning}>
+ *   <CancelButton />
+ * </AuiIf>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <AuiIf condition={(s) => s.thread.messages.length === 0}>
+ *   <EmptyState />
+ * </AuiIf>
+ * ```
+ */
 export const AuiIf: FC<AuiIf.Props> = ({ children, condition }) => {
   const result = useAuiState(condition);
   return result ? children : null;

package/src/Derived.ts

@@ -42,5 +42,5 @@ export namespace Derived {
    */
   export type Props<K extends ClientNames> = {
     get: (client: AssistantClient) => ReturnType<AssistantClientAccessor<K>>;
-  } & (ClientMeta<K> | { getMeta: (client: AssistantClient) => ClientMeta<K> });
+  } & ClientMeta<K>;
 }

package/src/types/client.ts

@@ -15,12 +15,11 @@ export interface ClientMethods {
 type ClientMetaType = { source: ClientNames; query: Record<string, unknown> };
 
 /**
- * Schema of a client in the assistant system (internal type).
+ * Schema of a client in the assistant system.
  * @template TState - The state type for this client
  * @template TMethods - The methods available on this client
  * @template TMeta - Source/query metadata (optional)
  * @template TEvents - Events that this client can emit (optional)
- * @internal
  */
 export type ClientSchema<
   TMethods extends ClientMethods = ClientMethods,

package/src/useAui.ts

@@ -5,7 +5,6 @@ import {
   resource,
   tapMemo,
   tapResources,
-  tapEffectEvent,
   tapEffect,
   tapRef,
   tapResource,
@@ -19,7 +18,7 @@ import type {
   ClientElement,
   ClientMeta,
 } from "./types/client";
-import type { Derived, DerivedElement } from "./Derived";
+import type { DerivedElement } from "./Derived";
 import {
   useAssistantContextValue,
   DefaultAssistantClient,
@@ -209,24 +208,6 @@ const RootClientsAccessorsResource = resource(
   },
 );
 
-type MetaMemo<K extends ClientNames> = {
-  meta?: ClientMeta<K>;
-  dep?: unknown;
-};
-
-const getMeta = <K extends ClientNames>(
-  props: Derived.Props<K>,
-  clientRef: { parent: AssistantClient; current: AssistantClient | null },
-  memo: MetaMemo<K>,
-): ClientMeta<K> => {
-  if ("source" in props && "query" in props) return props;
-  if (memo.dep === props) return memo.meta!;
-  const meta = props.getMeta(clientRef.current!);
-  memo.meta = meta;
-  memo.dep = props;
-  return meta;
-};
-
 const DerivedClientAccessorResource = resource(
   <K extends ClientNames>({
     element,
@@ -237,17 +218,24 @@ const DerivedClientAccessorResource = resource(
     clientRef: { parent: AssistantClient; current: AssistantClient | null };
     name: K;
   }) => {
-    const get = tapEffectEvent(() => element.props);
+    // Track the latest props on a ref updated in render. The fiber is
+    // keyed on the scope's meta by DerivedClientsAccessorsResource, so
+    // source/query are stable for this fiber's lifetime and the only
+    // value that can change between renders for the same fiber is the
+    // identity of the `get` closure. Routing reads through the ref
+    // avoids the one-commit lag that the previous `tapEffectEvent`
+    // path imposed.
+    const propsRef = tapRef(element.props);
+    propsRef.current = element.props;
 
     return tapMemo(() => {
-      const clientFunction = () => get().get(clientRef.current!);
-      const metaMemo = {};
+      const clientFunction = () => propsRef.current.get(clientRef.current!);
       Object.defineProperties(clientFunction, {
         source: {
-          get: () => getMeta(get(), clientRef, metaMemo).source,
+          value: propsRef.current.source,
         },
         query: {
-          get: () => getMeta(get(), clientRef, metaMemo).query,
+          value: propsRef.current.query,
         },
         name: {
           value: name,
@@ -259,6 +247,26 @@ const DerivedClientAccessorResource = resource(
   },
 );
 
+const serializeMeta = <K extends ClientNames>(
+  name: K,
+  meta: ClientMeta<K>,
+): string => {
+  // Sort top-level keys so {a, b} and {b, a} hash to the same fiber
+  // identity, and guard JSON.stringify against unusual values (BigInt,
+  // circular refs) so render never throws here.
+  let queryKey: string;
+  try {
+    const sorted: Record<string, unknown> = {};
+    for (const k of Object.keys(meta.query as object).sort()) {
+      sorted[k] = (meta.query as Record<string, unknown>)[k];
+    }
+    queryKey = JSON.stringify(sorted);
+  } catch {
+    queryKey = String(meta.query);
+  }
+  return `${name}::${meta.source}::${queryKey}`;
+};
+
 const DerivedClientsAccessorsResource = resource(
   ({
     clients,
@@ -270,16 +278,18 @@ const DerivedClientsAccessorsResource = resource(
     return tapShallowMemoArray(
       tapResources(
         () =>
-          Object.keys(clients).map((key) =>
-            withKey(
-              key,
+          Object.keys(clients).map((key) => {
+            const name = key as keyof typeof clients;
+            const element = clients[name]!;
+            return withKey(
+              serializeMeta(name, element.props),
               DerivedClientAccessorResource({
-                element: clients[key as keyof typeof clients]!,
+                element,
                 clientRef,
-                name: key as keyof typeof clients,
+                name,
               }),
-            ),
-          ),
+            );
+          }),
         [clients, clientRef],
       ),
     );
@@ -359,8 +369,67 @@ export namespace useAui {
   };
 }
 
+/**
+ * Returns the current `AssistantClient` from context.
+ *
+ * Read the client supplied by the nearest {@link AuiProvider} or
+ * {@link AssistantRuntimeProvider}, then access a scope on it —
+ * `aui.thread()`, `aui.composer()`, `aui.message()`, and so on. Pair
+ * with {@link useAuiState} to read reactive state and {@link useAuiEvent}
+ * to subscribe to events. The returned client also exposes lower-level
+ * methods such as `aui.on(...)` and `aui.subscribe(...)`; prefer
+ * `useAuiEvent` for React event subscriptions.
+ *
+ * Rendered outside a provider, the returned client's scope accessors
+ * throw a descriptive error whenever they are called.
+ *
+ * @example
+ * ```tsx
+ * const aui = useAui();
+ *
+ * const onSend = () => aui.composer().send();
+ * const onCancel = () => aui.thread().cancelRun();
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Combine with useAuiState to drive disabled state.
+ * const aui = useAui();
+ * const isRunning = useAuiState((s) => s.thread.isRunning);
+ *
+ * return (
+ *   <button disabled={isRunning} onClick={() => aui.composer().send()}>
+ *     Send
+ *   </button>
+ * );
+ * ```
+ */
 export function useAui(): AssistantClient;
+/**
+ * Extends the parent `AssistantClient` with additional scopes.
+ *
+ * Advanced overload used when building primitives or providers — for example,
+ * when a custom provider needs to register a `message`, `part`, or other scope
+ * onto the client visible to its descendants. Application code rarely reaches
+ * for this; use {@link useAui} with no arguments to read the existing client.
+ *
+ * @example
+ * ```tsx
+ * const aui = useAui({
+ *   message: Derived({
+ *     source: "thread",
+ *     query: { index: 0 },
+ *     get: (aui) => aui.thread().message({ index: 0 }),
+ *   }),
+ * });
+ *
+ * const role = useAuiState((s) => s.message.role);
+ * ```
+ */
 export function useAui(clients: useAui.Props): AssistantClient;
+/**
+ * Extends an explicit parent `AssistantClient` with additional scopes.
+ */
 export function useAui(
   clients: useAui.Props,
   config: { parent: null | AssistantClient },

package/src/useAuiEvent.ts

@@ -8,6 +8,47 @@ import type {
 } from "./types/events";
 import { normalizeEventSelector } from "./types/events";
 
+/**
+ * Subscribes to an assistant event for the lifetime of the component.
+ *
+ * The subscription is established on mount and re-established whenever the
+ * scope or event name changes. The `callback` is wrapped in an effect-event
+ * shim, so the latest closure is invoked on each emission — you do not
+ * need to memoize it.
+ *
+ * @param selector - Either a dotted event name like
+ *   `"thread.modelContextUpdate"` or an object `{ scope, event }`. Use
+ *   `scope: "*"` to subscribe at the root client and receive emissions
+ *   from any descendant scope, regardless of which one is in React
+ *   context.
+ * @param callback - Invoked with the event payload. The most recent
+ *   reference is always called. Return values are ignored, async callbacks
+ *   are not awaited, and the callback cannot be called during render.
+ *
+ * @example
+ * ```tsx
+ * // React to transient model-context changes.
+ * useAuiEvent("thread.modelContextUpdate", ({ threadId }) => {
+ *   analytics.track("model_context_update", { threadId });
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // React to thread switches.
+ * useAuiEvent("threadListItem.switchedTo", () => {
+ *   resetLocalState();
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Listen from the root client rather than the current React context.
+ * useAuiEvent({ scope: "*", event: "thread.modelContextUpdate" }, (payload) => {
+ *   analytics.track("model_context_update", payload);
+ * });
+ * ```
+ */
 export const useAuiEvent = <TEvent extends AssistantEventName>(
   selector: AssistantEventSelector<TEvent>,
   callback: AssistantEventCallback<TEvent>,

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;

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,oBAAiB;AAClC,OAAO,EAAE,WAAW,EAAE,yBAAsB;AAC5C,OAAO,EAAE,WAAW,EAAE,yBAAsB;AAC5C,OAAO,EAAE,0BAA0B,EAAE,wCAAqC;AAG1E,OAAO,EAAE,KAAK,EAAE,mBAAgB;AAChC,OAAO,EAAE,WAAW,EAAE,2CAAwC;AAG9D,OAAO,EAAE,OAAO,EAAE,qBAAkB;AACpC,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,mCAAgC;AACjC,YAAY,EAAE,YAAY,EAAE,mCAAgC;AAG5D,OAAO,EACL,qBAAqB,EACrB,gBAAgB,GACjB,yCAAsC;AACvC,OAAO,EAAE,iBAAiB,EAAE,+BAA4B;AACxD,OAAO,EAAE,eAAe,EAAE,6BAA0B;AACpD,OAAO,EAAE,aAAa,EAAE,2BAAwB;AAGhD,YAAY,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,UAAU,EACV,aAAa,EACb,WAAW,EACX,uBAAuB,EACvB,eAAe,EACf,cAAc,GACf,0BAAuB;AACxB,OAAO,EACL,sBAAsB,EACtB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,GACzB,0BAAuB"}

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,OAAO,EAAE,MAAM,EAAE,oBAAiB;AAClC,OAAO,EAAE,WAAW,EAAE,yBAAsB;AAC5C,OAAO,EAAE,WAAW,EAAE,yBAAsB;AAC5C,OAAO,EAAE,0BAA0B,EAAE,wCAAqC;AAE1E,aAAa;AACb,OAAO,EAAE,KAAK,EAAE,mBAAgB;AAChC,OAAO,EAAE,WAAW,EAAE,2CAAwC;AAE9D,YAAY;AACZ,OAAO,EAAE,OAAO,EAAE,qBAAkB;AACpC,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,mCAAgC;AAGjC,YAAY;AACZ,OAAO,EACL,qBAAqB,EACrB,gBAAgB,GACjB,yCAAsC;AACvC,OAAO,EAAE,iBAAiB,EAAE,+BAA4B;AACxD,OAAO,EAAE,eAAe,EAAE,6BAA0B;AACpD,OAAO,EAAE,aAAa,EAAE,2BAAwB;AAiBhD,OAAO,EACL,sBAAsB,GAMvB,0BAAuB"}

package/dist/types/client.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/types/client.ts"],"names":[],"mappings":""}