@assistant-ui/store 0.2.9 → 0.2.11

package/dist/useAuiState.js

@@ -2,18 +2,35 @@ import { useSyncExternalStore, useDebugValue } from "react";
 import { useAui } from "./useAui.js";
 import { getProxiedAssistantState } from "./utils/proxied-assistant-state.js";
 /**
- * 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 = (selector) => {

package/dist/useAuiState.js.map

@@ -1 +1 @@
-{"version":3,"file":"useAuiState.js","sourceRoot":"","sources":["../src/useAuiState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE5D,OAAO,EAAE,MAAM,EAAE,oBAAiB;AAClC,OAAO,EAAE,wBAAwB,EAAE,2CAAwC;AAE3E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAI,QAAsC,EAAK,EAAE;IAC1E,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,MAAM,YAAY,GAAG,wBAAwB,CAAC,GAAG,CAAC,CAAC;IAEnD,MAAM,KAAK,GAAG,oBAAoB,CAChC,GAAG,CAAC,SAAS,EACb,GAAG,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,EAC5B,GAAG,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,CAC7B,CAAC;IAEF,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,oGAAoG,CACrG,CAAC;IACJ,CAAC;IAED,aAAa,CAAC,KAAK,CAAC,CAAC;IAErB,OAAO,KAAK,CAAC;AACf,CAAC,CAAC"}
+{"version":3,"file":"useAuiState.js","sourceRoot":"","sources":["../src/useAuiState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE5D,OAAO,EAAE,MAAM,EAAE,oBAAiB;AAClC,OAAO,EAAE,wBAAwB,EAAE,2CAAwC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAI,QAAsC,EAAK,EAAE;IAC1E,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,MAAM,YAAY,GAAG,wBAAwB,CAAC,GAAG,CAAC,CAAC;IAEnD,MAAM,KAAK,GAAG,oBAAoB,CAChC,GAAG,CAAC,SAAS,EACb,GAAG,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,EAC5B,GAAG,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,CAC7B,CAAC;IAEF,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,oGAAoG,CACrG,CAAC;IACJ,CAAC;IAED,aAAa,CAAC,KAAK,CAAC,CAAC;IAErB,OAAO,KAAK,CAAC;AACf,CAAC,CAAC"}

package/dist/utils/react-assistant-context.d.ts

@@ -6,17 +6,30 @@ export declare const DefaultAssistantClient: AssistantClient;
 export declare const createRootAssistantClient: () => AssistantClient;
 export declare 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 declare const AuiProvider: ({ value, children, }: {
+    /** Assistant client to expose to descendants. */
     value: AssistantClient;
+    /** Subtree that may read from the client. */
     children: React.ReactNode;
 }) => React.ReactElement;
 //# sourceMappingURL=react-assistant-context.d.ts.map

package/dist/utils/react-assistant-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react-assistant-context.d.ts","sourceRoot":"","sources":["../../src/utils/react-assistant-context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAA2B,2BAAwB;AAmDhF,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,EAAE,eAIlC,CAAC;AAMJ,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,QAAO,eAUzC,CAAC;AAOL,eAAO,MAAM,wBAAwB,QAAO,eAE3C,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,sBAGzB;IACD,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,KAAG,KAAK,CAAC,YAMT,CAAC"}
+{"version":3,"file":"react-assistant-context.d.ts","sourceRoot":"","sources":["../../src/utils/react-assistant-context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAA2B,2BAAwB;AAmDhF,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,EAAE,eAIlC,CAAC;AAMJ,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,QAAO,eAUzC,CAAC;AAOL,eAAO,MAAM,wBAAwB,QAAO,eAE3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,WAAW,GAAI,sBAGzB;IACD,iDAAiD;IACjD,KAAK,EAAE,eAAe,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,KAAG,KAAK,CAAC,YAMT,CAAC"}

package/dist/utils/react-assistant-context.js

@@ -53,13 +53,24 @@ export const useAssistantContextValue = () => {
     return useContext(AssistantContext);
 };
 /**
- * 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, }) => {

package/dist/utils/react-assistant-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"react-assistant-context.js","sourceRoot":"","sources":["../../src/utils/react-assistant-context.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAElD,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,GAC/B,qCAAkC;AACnC,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,8BAA2B;AAE/E,MAAM,eAAe,GAAG,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;AAEvC,MAAM,sBAAsB,GAAG,CAC7B,OAAe,EACiB,EAAE;IAClC,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE;QACf,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC,CAAmC,CAAC;IACrC,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC;IACjB,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC;IAChB,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC;AAEF,MAAM,kCACJ,SAAQ,gBAAgB;IAGxB,GAAG,CAAC,CAAU,EAAE,IAAqB;QACnC,IAAI,IAAI,KAAK,WAAW;YAAE,OAAO,eAAe,CAAC;QACjD,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,eAAe,CAAC;QAC1C,IAAI,IAAI,KAAK,8BAA8B;YACzC,OAAO,2CAA2C,CAAC;QACrD,MAAM,aAAa,GAAG,uBAAuB,CAC3C,IAAI,EACJ,wBAAwB,CACzB,CAAC;QACF,IAAI,aAAa,KAAK,KAAK;YAAE,OAAO,aAAa,CAAC;QAClD,OAAO,sBAAsB,CAC3B,oHAAoH,CACrH,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,CAAC,WAAW,EAAE,IAAI,EAAE,8BAA8B,CAAC,CAAC;IAC7D,CAAC;IAED,GAAG,CAAC,CAAU,EAAE,IAAqB;QACnC,OAAO,CACL,IAAI,KAAK,WAAW;YACpB,IAAI,KAAK,IAAI;YACb,IAAI,KAAK,8BAA8B,CACxC,CAAC;IACJ,CAAC;CACF;AACD,iEAAiE;AACjE,MAAM,CAAC,MAAM,sBAAsB,GACjC,IAAI,KAAK,CACP,EAAqB,EACrB,IAAI,kCAAkC,EAAE,CACzC,CAAC;AAEJ,MAAM,2CAA2C,GAAG,2BAA2B,CAC7E,sBAAsB,CACvB,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAoB,EAAE,CAC7D,IAAI,KAAK,CAAkB,EAAqB,EAAE;IAChD,GAAG,CAAC,CAAkB,EAAE,IAAqB;QAC3C,MAAM,aAAa,GAAG,uBAAuB,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;QACvE,IAAI,aAAa,KAAK,KAAK;YAAE,OAAO,aAAa,CAAC;QAElD,OAAO,sBAAsB,CAC3B,sCAAsC,MAAM,CAAC,IAAI,CAAC,aAAa,CAChE,CAAC;IACJ,CAAC;CACF,CAAC,CAAC;AAEL;;GAEG;AACH,MAAM,gBAAgB,GAAG,aAAa,CAAkB,sBAAsB,CAAC,CAAC;AAEhF,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAoB,EAAE;IAC5D,OAAO,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACtC,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAC1B,KAAK,EACL,QAAQ,GAIT,EAAsB,EAAE;IACvB,OAAO,CACL,KAAC,gBAAgB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YACpC,QAAQ,GACiB,CAC7B,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"react-assistant-context.js","sourceRoot":"","sources":["../../src/utils/react-assistant-context.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAElD,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,GAC/B,qCAAkC;AACnC,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,8BAA2B;AAE/E,MAAM,eAAe,GAAG,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;AAEvC,MAAM,sBAAsB,GAAG,CAC7B,OAAe,EACiB,EAAE;IAClC,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE;QACf,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC,CAAmC,CAAC;IACrC,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC;IACjB,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC;IAChB,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC;AAEF,MAAM,kCACJ,SAAQ,gBAAgB;IAGxB,GAAG,CAAC,CAAU,EAAE,IAAqB;QACnC,IAAI,IAAI,KAAK,WAAW;YAAE,OAAO,eAAe,CAAC;QACjD,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,eAAe,CAAC;QAC1C,IAAI,IAAI,KAAK,8BAA8B;YACzC,OAAO,2CAA2C,CAAC;QACrD,MAAM,aAAa,GAAG,uBAAuB,CAC3C,IAAI,EACJ,wBAAwB,CACzB,CAAC;QACF,IAAI,aAAa,KAAK,KAAK;YAAE,OAAO,aAAa,CAAC;QAClD,OAAO,sBAAsB,CAC3B,oHAAoH,CACrH,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,CAAC,WAAW,EAAE,IAAI,EAAE,8BAA8B,CAAC,CAAC;IAC7D,CAAC;IAED,GAAG,CAAC,CAAU,EAAE,IAAqB;QACnC,OAAO,CACL,IAAI,KAAK,WAAW;YACpB,IAAI,KAAK,IAAI;YACb,IAAI,KAAK,8BAA8B,CACxC,CAAC;IACJ,CAAC;CACF;AACD,iEAAiE;AACjE,MAAM,CAAC,MAAM,sBAAsB,GACjC,IAAI,KAAK,CACP,EAAqB,EACrB,IAAI,kCAAkC,EAAE,CACzC,CAAC;AAEJ,MAAM,2CAA2C,GAAG,2BAA2B,CAC7E,sBAAsB,CACvB,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAoB,EAAE,CAC7D,IAAI,KAAK,CAAkB,EAAqB,EAAE;IAChD,GAAG,CAAC,CAAkB,EAAE,IAAqB;QAC3C,MAAM,aAAa,GAAG,uBAAuB,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;QACvE,IAAI,aAAa,KAAK,KAAK;YAAE,OAAO,aAAa,CAAC;QAElD,OAAO,sBAAsB,CAC3B,sCAAsC,MAAM,CAAC,IAAI,CAAC,aAAa,CAChE,CAAC;IACJ,CAAC;CACF,CAAC,CAAC;AAEL;;GAEG;AACH,MAAM,gBAAgB,GAAG,aAAa,CAAkB,sBAAsB,CAAC,CAAC;AAEhF,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAoB,EAAE;IAC5D,OAAO,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACtC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAC1B,KAAK,EACL,QAAQ,GAMT,EAAsB,EAAE;IACvB,OAAO,CACL,KAAC,gBAAgB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YACpC,QAAQ,GACiB,CAC7B,CAAC;AACJ,CAAC,CAAC"}

package/dist/utils/splitClients.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"splitClients.d.ts","sourceRoot":"","sources":["../../src/utils/splitClients.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,cAAc,EAAE,sBAAmB;AAC1D,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,WAAW,EACZ,2BAAwB;AAEzB,OAAO,KAAK,EAAE,MAAM,EAAE,qBAAkB;AAGxC,MAAM,MAAM,WAAW,GAAG,OAAO,CAC/B,MAAM,CAAC,WAAW,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC,CAChD,CAAC;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,CAClC,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC,CACjD,CAAC;AAsDF,eAAO,MAAM,eAAe,GAC1B,SAAS,MAAM,CAAC,KAAK,EACrB,YAAY,eAAe;;;CAQ5B,CAAC"}
+{"version":3,"file":"splitClients.d.ts","sourceRoot":"","sources":["../../src/utils/splitClients.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,cAAc,EAAE,sBAAmB;AAC1D,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,WAAW,EACZ,2BAAwB;AAEzB,OAAO,KAAK,EAAE,MAAM,EAAE,qBAAkB;AAGxC,MAAM,MAAM,WAAW,GAAG,OAAO,CAC/B,MAAM,CAAC,WAAW,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC,CAChD,CAAC;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,CAClC,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC,CACjD,CAAC;AAwDF,eAAO,MAAM,eAAe,GAC1B,SAAS,MAAM,CAAC,KAAK,EACrB,YAAY,eAAe;;;CAQ5B,CAAC"}

package/dist/utils/splitClients.js.map

@@ -1 +1 @@
-{"version":3,"file":"splitClients.js","sourceRoot":"","sources":["../../src/utils/splitClients.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAuB,sBAAmB;AAM1D,OAAO,EAAE,kBAAkB,EAAE,oCAAiC;AAE9D,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAS5C;;;GAGG;AACH,SAAS,YAAY,CAAC,OAAqB,EAAE,UAA2B;IACtE,oEAAoE;IACpE,MAAM,MAAM,GAAG,EAAE,GAAG,OAAO,EAG1B,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IAEnD,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,OAAO,OAAO,EAAE,CAAC;QACf,OAAO,GAAG,KAAK,CAAC;QAChB,KAAK,MAAM,aAAa,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,IAAI,aAAa,CAAC,IAAI,KAAM,OAAmB;gBAAE,SAAS;YAC1D,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC9C,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;YAEhC,MAAM,SAAS,GAAG,kBAAkB,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;YACzD,IAAI,SAAS,EAAE,CAAC;gBACd,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;gBAC9B,OAAO,GAAG,IAAI,CAAC;gBACf,MAAM,CAAC,4DAA4D;YACrE,CAAC;QACH,CAAC;IACH,CAAC;IAED,oCAAoC;IACpC,MAAM,WAAW,GAAgB,EAAE,CAAC;IACpC,MAAM,cAAc,GAAmB,EAAE,CAAC;IAE1C,KAAK,MAAM,CAAC,GAAG,EAAE,aAAa,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAGrD,EAAE,CAAC;QACJ,IAAI,aAAa,CAAC,IAAI,KAAM,OAAmB,EAAE,CAAC;YAChD,cAAc,CAAC,GAAG,CAAC,GAAG,aAA4C,CAAC;QACrE,CAAC;aAAM,CAAC;YACN,WAAW,CAAC,GAAG,CAAC,GAAG,aAA2C,CAAC;QACjE,CAAC;IACH,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,oBAAoB,GAAG,CAAmB,MAAS,EAAE,EAAE;IAC3D,wEAAwE;IACxE,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AACnE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,OAAqB,EACrB,UAA2B,EAC3B,EAAE;IACF,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAE1E,OAAO;QACL,WAAW,EAAE,oBAAoB,CAAC,WAAW,CAAC;QAC9C,cAAc,EAAE,oBAAoB,CAAC,cAAc,CAAC;KACrD,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"splitClients.js","sourceRoot":"","sources":["../../src/utils/splitClients.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAuB,sBAAmB;AAM1D,OAAO,EAAE,kBAAkB,EAAE,oCAAiC;AAE9D,OAAO,EAAE,OAAO,EAAwB,MAAM,mBAAmB,CAAC;AASlE;;;GAGG;AACH,SAAS,YAAY,CAAC,OAAqB,EAAE,UAA2B;IACtE,oEAAoE;IACpE,MAAM,MAAM,GAAG,EAAE,GAAG,OAAO,EAG1B,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IAEnD,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,OAAO,OAAO,EAAE,CAAC;QACf,OAAO,GAAG,KAAK,CAAC;QAChB,KAAK,MAAM,aAAa,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,IAAI,aAAa,CAAC,IAAI,KAAM,OAAmB;gBAAE,SAAS;YAC1D,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC9C,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;YAEhC,MAAM,SAAS,GAAG,kBAAkB,CAClC,aAAa,CAAC,IAA4C,CAC3D,CAAC;YACF,IAAI,SAAS,EAAE,CAAC;gBACd,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;gBAC9B,OAAO,GAAG,IAAI,CAAC;gBACf,MAAM,CAAC,4DAA4D;YACrE,CAAC;QACH,CAAC;IACH,CAAC;IAED,oCAAoC;IACpC,MAAM,WAAW,GAAgB,EAAE,CAAC;IACpC,MAAM,cAAc,GAAmB,EAAE,CAAC;IAE1C,KAAK,MAAM,CAAC,GAAG,EAAE,aAAa,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAGrD,EAAE,CAAC;QACJ,IAAI,aAAa,CAAC,IAAI,KAAM,OAAmB,EAAE,CAAC;YAChD,cAAc,CAAC,GAAG,CAAC,GAAG,aAA4C,CAAC;QACrE,CAAC;aAAM,CAAC;YACN,WAAW,CAAC,GAAG,CAAC,GAAG,aAA2C,CAAC;QACjE,CAAC;IACH,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,oBAAoB,GAAG,CAAmB,MAAS,EAAE,EAAE;IAC3D,wEAAwE;IACxE,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AACnE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,OAAqB,EACrB,UAA2B,EAC3B,EAAE;IACF,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAE1E,OAAO;QACL,WAAW,EAAE,oBAAoB,CAAC,WAAW,CAAC;QAC9C,cAAc,EAAE,oBAAoB,CAAC,cAAc,CAAC;KACrD,CAAC;AACJ,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/store",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "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.10",
+    "@assistant-ui/tap": "^0.5.11",
     "@types/react": "*",
     "react": "^18 || ^19"
   },
@@ -43,11 +43,11 @@
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "jsdom": "^29.1.0",
+    "jsdom": "^29.1.1",
     "react": "^19.2.5",
     "vitest": "^4.1.5",
-    "@assistant-ui/tap": "0.5.10",
-    "@assistant-ui/x-buildutils": "0.0.6"
+    "@assistant-ui/tap": "0.5.11",
+    "@assistant-ui/x-buildutils": "0.0.8"
   },
   "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/RenderChildrenWithAccessor.tsx

@@ -10,18 +10,20 @@ export const useGetItemAccessor = <T,>(
 ) => {
   const aui = useAui();
 
-  // if the consumer never accesses the item, do not trigger rerenders
-  const cacheRef = useRef<T | undefined>(undefined);
+  // Track access with a dedicated flag:
+  // useSyncExternalStore may call getSnapshot() after commit (tearing checks),
+  // which would re-cache the current state and mask later real updates.
+  // Use the current state as the pre-access snapshot so the post-commit check
+  // matches getItemState(aui) and doesn't schedule an unnecessary re-render.
+  const accessedRef = useRef(false);
+  const currentValue = accessedRef.current ? null : getItemState(aui);
   useAuiState(() => {
-    if (cacheRef.current === undefined) {
-      cacheRef.current = getItemState(aui);
-    }
-    return cacheRef.current;
+    if (!accessedRef.current) return currentValue;
+    return getItemState(aui);
   });
 
   return () => {
-    cacheRef.current = undefined; // clear the cache (rerender on next state change)
-
+    accessedRef.current = true;
     return getItemState(aui);
   };
 };

package/src/__tests__/RenderChildrenWithAccessor.test.tsx

@@ -0,0 +1,136 @@
+// @vitest-environment jsdom
+
+import type { ReactNode } from "react";
+import { act, render } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AuiProvider } from "../utils/react-assistant-context";
+import { RenderChildrenWithAccessor } from "../RenderChildrenWithAccessor";
+import { PROXIED_ASSISTANT_STATE_SYMBOL } from "../utils/proxied-assistant-state";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+type Listener = () => void;
+
+const createTestAuiClient = () => {
+  const listeners = new Set<Listener>();
+  let itemState: { value: number; isEditing: boolean } = {
+    value: 1,
+    isEditing: false,
+  };
+
+  const proxiedState = {
+    item: itemState,
+  };
+
+  const client = {
+    subscribe: (listener: Listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    on: () => () => {},
+    [PROXIED_ASSISTANT_STATE_SYMBOL]: proxiedState,
+  } as const;
+
+  return {
+    client,
+    getItemState: () => itemState,
+    update: (next: Partial<typeof itemState>) => {
+      itemState = { ...itemState, ...next };
+      proxiedState.item = itemState;
+      // biome-ignore lint/suspicious/useIterableCallbackReturn: forEach callback intentionally has no return
+      listeners.forEach((listener) => listener());
+    },
+  };
+};
+
+describe("RenderChildrenWithAccessor", () => {
+  it("re-renders when accessed state updates (regression: issue #3838)", () => {
+    const testClient = createTestAuiClient();
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <AuiProvider value={testClient.client as never}>{children}</AuiProvider>
+    );
+
+    const { container } = render(
+      <RenderChildrenWithAccessor
+        getItemState={() => testClient.getItemState()}
+      >
+        {(getItem) => {
+          const item = getItem();
+          return <div>{item.isEditing ? "editing" : "viewing"}</div>;
+        }}
+      </RenderChildrenWithAccessor>,
+      { wrapper },
+    );
+
+    expect(container.textContent).toBe("viewing");
+
+    act(() => {
+      testClient.update({ isEditing: true });
+    });
+
+    expect(container.textContent).toBe("editing");
+
+    act(() => {
+      testClient.update({ isEditing: false });
+    });
+
+    expect(container.textContent).toBe("viewing");
+  });
+
+  it("does not schedule an extra render on first access (initial snapshot matches getItemState)", () => {
+    const testClient = createTestAuiClient();
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <AuiProvider value={testClient.client as never}>{children}</AuiProvider>
+    );
+
+    const renderSpy = vi.fn();
+
+    render(
+      <RenderChildrenWithAccessor
+        getItemState={() => testClient.getItemState()}
+      >
+        {(getItem) => {
+          renderSpy();
+          const item = getItem();
+          return <div>{item.value}</div>;
+        }}
+      </RenderChildrenWithAccessor>,
+      { wrapper },
+    );
+
+    // first mount accesses the item; useSyncExternalStore's post-commit
+    // tearing check should see a stable snapshot and not force a re-render
+    expect(renderSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not re-render when item is never accessed", () => {
+    const testClient = createTestAuiClient();
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <AuiProvider value={testClient.client as never}>{children}</AuiProvider>
+    );
+
+    const renderSpy = vi.fn();
+
+    render(
+      <RenderChildrenWithAccessor
+        getItemState={() => testClient.getItemState()}
+      >
+        {() => {
+          renderSpy();
+          return <div>static</div>;
+        }}
+      </RenderChildrenWithAccessor>,
+      { wrapper },
+    );
+
+    const initialRenderCount = renderSpy.mock.calls.length;
+
+    act(() => {
+      testClient.update({ value: 99 });
+    });
+
+    expect(renderSpy.mock.calls.length).toBe(initialRenderCount);
+  });
+});

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>,