@assistant-ui/store

Tap-based state management with React Context integration.

Quick Start

import { resource, tapState } from "@assistant-ui/tap";
import { useAui, useAuiState, AuiProvider, type ClientOutput } from "@assistant-ui/store";

// 1. Define client type
declare module "@assistant-ui/store" {
  interface ScopeRegistry {
    counter: { methods: { getState: () => { count: number }; increment: () => void } };
  }
}

// 2. Create resource
const CounterClient = resource((): ClientOutput<"counter"> => {
  const [state, setState] = tapState({ count: 0 });
  return { getState: () => state, increment: () => setState({ count: state.count + 1 }) };
});

// 3. Use in React
function App() {
  const aui = useAui({ counter: CounterClient() });
  return <AuiProvider value={aui}><Counter /></AuiProvider>;
}

function Counter() {
  const count = useAuiState((s) => s.counter.count);
  const aui = useAui();
  return <button onClick={() => aui.counter().increment()}>{count}</button>;
}

Concepts

Clients: Named state containers registered via module augmentation.

declare module "@assistant-ui/store" {
  interface ScopeRegistry {
    myClient: {
      methods: MyMethods; // must include getState(): MyState
      meta?: { source: "parent"; query: { id: string } };
      events?: { "myClient.updated": { id: string } };
    };
  }
}

Derived Clients: Access nested clients from parents.

useAui({
  item: Derived({ source: "list", query: { index: 0 }, get: (aui) => aui.list().item({ index: 0 }) }),
});

Events:

const emit = tapAssistantEmit();
emit("myClient.updated", { id: "123" });

useAuiEvent("myClient.updated", (p) => console.log(p.id));

API

Hook/Component	Description
`useAui()`	Get client from context
`useAui(clients)`	Create/extend client
`useAuiState(selector)`	Subscribe to state
`useAuiEvent(event, cb)`	Subscribe to events
`AuiProvider`	Provide client to tree
`AuiIf`	Conditional rendering

Tap Utility	Description
`tapAssistantClientRef()`	Access client ref in resources
`tapAssistantEmit()`	Emit events from resources
`tapClientResource(element)`	Wrap resource for event scoping (1:1 mappings)
`tapClientLookup(map, fn, deps)`	Lookup by `{index}` or `{key}`
`tapClientList(config)`	Dynamic list with add/remove
`attachTransformScopes(resource, fn)`	Attach scope transform

Type	Description
`ClientOutput<K>`	Resource return type (methods object)
`ScopeRegistry`	Module augmentation interface
`AssistantClient`	Full client type