@assistant-ui/mcp-docs-server 0.1.15 → 0.1.17

package/.docs/organized/code-examples/store-example.md

@@ -82,10 +82,10 @@ export default function Home() {
     <div className="min-h-screen bg-gradient-to-br from-gray-50 to-gray-100 p-8 dark:from-gray-900 dark:to-gray-800">
       <div className="mx-auto max-w-4xl">
         <div className="mb-8">
-          <h1 className="mb-2 text-4xl font-bold text-gray-900 dark:text-white">
+          <h1 className="mb-2 font-bold text-4xl text-gray-900 dark:text-white">
             @assistant-ui/store Example
           </h1>
-          <p className="text-lg text-gray-600 dark:text-gray-400">
+          <p className="text-gray-600 text-lg dark:text-gray-400">
             Demonstrating tap-based state management with scopes, lists, and
             providers
           </p>
@@ -104,57 +104,59 @@ export default function Home() {
 ```tsx
 "use client";
 
+import { useState } from "react";
 import {
   useAssistantClient,
   AssistantProvider,
   useAssistantState,
+  useAssistantEvent,
 } from "@assistant-ui/store";
 import { FooList, FooListResource } from "./store/foo-store";
 
-import "./store/foo-scope"; // Register the fooList scope (demonstrates scope registry)
-
 /**
  * Single Foo component - displays and allows editing a single foo
  */
 const Foo = () => {
   const aui = useAssistantClient();
-  const fooState = useAssistantState(({ foo }) => {
-    console.log("selector called with state", foo);
-    return foo;
+  const fooId = useAssistantState(({ foo }) => foo.id);
+  const fooBar = useAssistantState(({ foo }) => foo.bar);
+
+  // Each foo logs its own events - only receives events from THIS foo instance
+  useAssistantEvent("foo.updated", (payload) => {
+    console.log(`[${fooId}] Updated to: ${payload.newValue}`);
   });
 
   const handleUpdate = () => {
     aui.foo().updateBar(`Updated at ${new Date().toLocaleTimeString()}`);
-    console.log("Foo state", aui.foo().getState(), fooState);
   };
 
   return (
     <div className="rounded-lg border border-gray-200 bg-white p-6 shadow-md transition-shadow hover:shadow-lg dark:border-gray-700 dark:bg-gray-800">
       <div className="space-y-3">
         <div className="flex items-center gap-2">
-          <span className="text-sm font-semibold text-gray-500 dark:text-gray-400">
+          <span className="font-semibold text-gray-500 text-sm dark:text-gray-400">
             ID:
           </span>
-          <span className="font-mono text-sm text-gray-900 dark:text-white">
-            {fooState.id}
+          <span className="font-mono text-gray-900 text-sm dark:text-white">
+            {fooId}
           </span>
         </div>
         <div className="flex items-center gap-2">
-          <span className="text-sm font-semibold text-gray-500 dark:text-gray-400">
+          <span className="font-semibold text-gray-500 text-sm dark:text-gray-400">
             Value:
           </span>
-          <span className="text-gray-900 dark:text-white">{fooState.bar}</span>
+          <span className="text-gray-900 dark:text-white">{fooBar}</span>
         </div>
         <div className="mt-2 flex gap-2">
           <button
             onClick={handleUpdate}
-            className="flex-1 rounded-md bg-blue-600 px-4 py-2 font-medium text-white transition-colors hover:bg-blue-700 focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:outline-none dark:focus:ring-offset-gray-800"
+            className="flex-1 rounded-md bg-blue-600 px-4 py-2 font-medium text-white transition-colors hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:focus:ring-offset-gray-800"
           >
             Update
           </button>
           <button
             onClick={() => aui.foo().remove()}
-            className="rounded-md bg-red-600 px-4 py-2 font-medium text-white transition-colors hover:bg-red-700 focus:ring-2 focus:ring-red-500 focus:ring-offset-2 focus:outline-none dark:focus:ring-offset-gray-800"
+            className="rounded-md bg-red-600 px-4 py-2 font-medium text-white transition-colors hover:bg-red-700 focus:outline-none focus:ring-2 focus:ring-red-500 focus:ring-offset-2 dark:focus:ring-offset-gray-800"
           >
             Delete
           </button>
@@ -178,13 +180,73 @@ const AddFooButton = () => {
   return (
     <button
       onClick={() => aui.fooList().addFoo()}
-      className="rounded-md bg-green-600 px-4 py-2 font-medium text-white transition-colors hover:bg-green-700 focus:ring-2 focus:ring-green-500 focus:ring-offset-2 focus:outline-none dark:focus:ring-offset-gray-800"
+      className="rounded-md bg-green-600 px-4 py-2 font-medium text-white transition-colors hover:bg-green-700 focus:outline-none focus:ring-2 focus:ring-green-500 focus:ring-offset-2 dark:focus:ring-offset-gray-800"
     >
       Add New
     </button>
   );
 };
 
+type EventLogEntry = {
+  id: number;
+  event: string;
+  payload: unknown;
+  timestamp: Date;
+};
+
+let idCounter = 0;
+/**
+ * EventLog component - demonstrates event subscription
+ */
+const EventLog = () => {
+  const [logs, setLogs] = useState<EventLogEntry[]>([]);
+
+  // Subscribe to all events using the wildcard selector
+  useAssistantEvent("*", (data) => {
+    setLogs((prev) => [
+      {
+        id: ++idCounter,
+        event: data.event,
+        payload: data.payload,
+        timestamp: new Date(),
+      },
+      ...prev.slice(0, 9), // Keep last 10 entries
+    ]);
+  });
+
+  return (
+    <div className="rounded-lg border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-700 dark:bg-gray-800">
+      <h3 className="mb-3 font-semibold text-gray-900 dark:text-white">
+        Event Log
+      </h3>
+      <div className="max-h-48 space-y-2 overflow-y-auto">
+        {logs.length === 0 ? (
+          <p className="text-gray-500 text-sm dark:text-gray-400">
+            No events yet. Try updating or deleting a foo.
+          </p>
+        ) : (
+          logs.map((log) => (
+            <div
+              key={log.id}
+              className="rounded border border-gray-100 bg-gray-50 p-2 font-mono text-xs dark:border-gray-600 dark:bg-gray-700"
+            >
+              <span className="font-semibold text-blue-600 dark:text-blue-400">
+                {log.event}
+              </span>
+              <span className="ml-2 text-gray-600 dark:text-gray-300">
+                {JSON.stringify(log.payload)}
+              </span>
+              <span className="ml-2 text-gray-400 dark:text-gray-500">
+                {log.timestamp.toLocaleTimeString()}
+              </span>
+            </div>
+          ))
+        )}
+      </div>
+    </div>
+  );
+};
+
 /**
  * Example App - demonstrates the store with styled components
  *
@@ -192,27 +254,28 @@ const AddFooButton = () => {
  * but we're explicitly passing it here for clarity in the example.
  */
 export const ExampleApp = () => {
-  const rootClient = useAssistantClient({
-    fooList: FooListResource(),
+  const aui = useAssistantClient({
+    fooList: FooListResource({ initialValues: true }),
   });
 
   return (
-    <AssistantProvider client={rootClient}>
+    <AssistantProvider client={aui}>
       <div className="space-y-6">
         <div className="rounded-lg border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-700 dark:bg-gray-800">
           <div className="flex items-center justify-between">
-            <h2 className="text-xl font-semibold text-gray-900 dark:text-white">
+            <h2 className="font-semibold text-gray-900 text-xl dark:text-white">
               Foo List <FooListLength />
             </h2>
             <AddFooButton />
           </div>
-          <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">
+          <p className="mt-1 text-gray-600 text-sm dark:text-gray-400">
             Each item is rendered in its own FooProvider with scoped access
           </p>
         </div>
         <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
           <FooList components={{ Foo }} />
         </div>
+        <EventLog />
       </div>
     </AssistantProvider>
   );
@@ -223,46 +286,48 @@ export const ExampleApp = () => {
 ## lib/store/foo-scope.ts
 
 ```typescript
-/**
- * Scope registration for the foo example
- * Import this file to register the default fooList scope
- */
-import { registerAssistantScope } from "@assistant-ui/store";
+type FooState = { id: string; bar: string };
+type FooMethods = {
+  getState: () => FooState;
+  updateBar: (newBar: string) => void;
+  remove: () => void;
+};
+type FooMeta = {
+  source: "fooList";
+  query: { index: number } | { key: string };
+};
+type FooEvents = {
+  "foo.updated": { id: string; newValue: string };
+  "foo.removed": { id: string };
+};
+
+type FooListState = { foos: FooState[] };
+type FooListMethods = {
+  getState: () => FooListState;
+  foo: (lookup: FooMeta["query"]) => FooMethods;
+  addFoo: () => void;
+};
+type FooListEvents = {
+  "fooList.added": { id: string };
+};
 
-/**
- * Define scopes via module augmentation
- * Implement the scope definition raw without importing ScopeDefinition
- */
 declare module "@assistant-ui/store" {
-  interface AssistantScopeRegistry {
+  interface ClientRegistry {
     foo: {
-      value: {
-        getState: () => { id: string; bar: string };
-        updateBar: (newBar: string) => void;
-        remove: () => void;
-      };
-      source: "fooList";
-      query: { index: number } | { id: string };
+      state: FooState;
+      methods: FooMethods;
+      meta: FooMeta;
+      events: FooEvents;
     };
     fooList: {
-      value: {
-        getState: () => { foos: Array<{ id: string; bar: string }> };
-        foo: (
-          lookup: { index: number } | { id: string },
-        ) => AssistantScopeRegistry["foo"]["value"];
-        addFoo: (id?: string) => void;
-      };
-      source: "root";
-      query: Record<string, never>;
+      state: FooListState;
+      methods: FooListMethods;
+      events: FooListEvents;
     };
   }
 }
 
-// Register the fooList scope with a default implementation
-registerAssistantScope({
-  name: "fooList",
-  defaultInitialize: { error: "FooList is not configured" },
-});
+export default {};
 
 ```
 
@@ -271,77 +336,88 @@ registerAssistantScope({
 ```tsx
 "use client";
 
+import "./foo-scope";
+
 import React from "react";
-import { resource, tapState } from "@assistant-ui/tap";
+import { resource, tapMemo, tapState } from "@assistant-ui/tap";
 import {
   useAssistantClient,
   AssistantProvider,
-  tapApi,
-  tapStoreList,
-  DerivedScope,
+  tapClientList,
+  Derived,
   useAssistantState,
+  tapAssistantEmit,
+  type ClientOutput,
 } from "@assistant-ui/store";
 
-/**
- * Single Foo item resource
- * Manages the state and actions for a single foo item
- */
+type FooData = { id: string; bar: string };
+
 export const FooItemResource = resource(
   ({
-    initialValue: { id, initialBar },
+    getInitialData,
     remove,
-  }: {
-    initialValue: { id: string; initialBar: string };
-    remove: () => void;
-  }) => {
-    const [state, setState] = tapState<{ id: string; bar: string }>({
-      id,
-      bar: initialBar,
-    });
+  }: tapClientList.ResourceProps<FooData>): ClientOutput<"foo"> => {
+    const emit = tapAssistantEmit();
+
+    const [state, setState] = tapState<FooData>(getInitialData);
 
     const updateBar = (newBar: string) => {
       setState({ ...state, bar: newBar });
+      emit("foo.updated", { id: state.id, newValue: newBar });
     };
 
-    return tapApi(
-      {
+    const handleRemove = () => {
+      emit("foo.removed", { id: state.id });
+      remove();
+    };
+
+    return {
+      state,
+      methods: {
         getState: () => state,
         updateBar,
-        remove,
+        remove: handleRemove,
       },
-      { key: id },
-    );
+    };
   },
 );
 
-/**
- * FooList resource implementation
- * Manages a list of foos using tapStoreList
- */
 let counter = 3;
-export const FooListResource = resource(() => {
-  const idGenerator = () => `foo-${++counter}`;
-
-  const foos = tapStoreList({
-    initialValues: [
-      { id: "foo-1", initialBar: "First Foo" },
-      { id: "foo-2", initialBar: "Second Foo" },
-      { id: "foo-3", initialBar: "Third Foo" },
-    ],
-    resource: FooItemResource,
-    idGenerator,
-  });
+export const FooListResource = resource(
+  ({ initialValues }: { initialValues: boolean }): ClientOutput<"fooList"> => {
+    const emit = tapAssistantEmit();
+
+    const foos = tapClientList({
+      initialValues: initialValues
+        ? [
+            { id: "foo-1", bar: "First Foo" },
+            { id: "foo-2", bar: "Second Foo" },
+            { id: "foo-3", bar: "Third Foo" },
+          ]
+        : [],
+      getKey: (foo) => foo.id,
+      resource: FooItemResource,
+    });
 
-  return tapApi({
-    getState: () => ({ foos: foos.state }),
-    foo: foos.api,
-    addFoo: (id?: string) => foos.add(id),
-  });
-});
+    const addFoo = () => {
+      const id = `foo-${++counter}`;
+      foos.add({ id: id, bar: `New Foo` });
+      emit("fooList.added", { id: id });
+    };
+
+    const state = tapMemo(() => ({ foos: foos.state }), [foos.state]);
+
+    return {
+      state,
+      methods: {
+        getState: () => state,
+        foo: foos.get,
+        addFoo,
+      },
+    };
+  },
+);
 
-/**
- * FooProvider - Provides foo scope for a specific index
- */
 export const FooProvider = ({
   index,
   children,
@@ -349,11 +425,10 @@ export const FooProvider = ({
   index: number;
   children: React.ReactNode;
 }) => {
-  // Create a derived client with the foo scope at the specified index
   const aui = useAssistantClient({
-    foo: DerivedScope({
+    foo: Derived({
       source: "fooList",
-      query: { index },
+      query: { index: index },
       get: (aui) => aui.fooList().foo({ index }),
     }),
   });
@@ -361,10 +436,6 @@ export const FooProvider = ({
   return <AssistantProvider client={aui}>{children}</AssistantProvider>;
 };
 
-/**
- * FooList component - minimal mapping component
- * Maps over the list and renders each item in a FooProvider
- */
 export const FooList = ({
   components,
 }: {
@@ -408,24 +479,21 @@ export default nextConfig;
   "scripts": {
     "dev": "next dev",
     "build": "next build",
-    "start": "next start",
-    "lint": "eslint"
+    "start": "next start"
   },
   "dependencies": {
     "@assistant-ui/store": "workspace:*",
     "@assistant-ui/tap": "workspace:*",
-    "next": "16.0.4",
-    "react": "19.2.0",
-    "react-dom": "19.2.0"
+    "next": "16.0.10",
+    "react": "19.2.3",
+    "react-dom": "19.2.3"
   },
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4",
-    "@types/node": "^24",
+    "@types/node": "^25",
     "@types/react": "19.2.7",
     "@types/react-dom": "19.2.3",
-    "eslint": "^9",
-    "eslint-config-next": "16.0.4",
     "tailwindcss": "^4",
     "typescript": "^5"
   }
@@ -442,9 +510,10 @@ This is a Next.js application demonstrating the `@assistant-ui/store` package.
 
 ## Features Demonstrated
 
-- **Scope Definition**: Module augmentation for type-safe scopes
-- **tapApi**: Wrapping API objects for stability and reactivity
-- **tapLookupResources**: Managing lists with index and ID lookup
+- **Client Registry**: Module augmentation for type-safe client definitions
+- **tapClientList**: Managing lists with index and key lookup
+- **tapAssistantEmit**: Emitting and subscribing to scoped events
+- **Derived**: Creating derived client scopes from parent resources
 - **Provider Pattern**: Scoped access to list items via FooProvider
 - **Component Composition**: Render props pattern with components prop
 
@@ -463,33 +532,42 @@ Open [http://localhost:3000](http://localhost:3000) to see the example.
 
 ## Project Structure
 
-- `lib/store/foo-store.tsx` - Clean store implementation with:
-  - Scope definitions (foo, fooList) via module augmentation
+- `lib/store/foo-scope.ts` - Type definitions via module augmentation:
+  - Client registry definitions (foo, fooList)
+  - State, methods, meta, and events types
+- `lib/store/foo-store.tsx` - Store implementation with:
   - Resource implementations (FooItemResource, FooListResource)
   - Provider component (FooProvider)
-  - Minimal FooList mapping component
+  - FooList mapping component
 - `lib/example-app.tsx` - Example app with styled components:
-  - Styled Foo component
+  - Foo component with update/delete actions
+  - EventLog component demonstrating event subscriptions
   - ExampleApp with layout and styling
 - `app/page.tsx` - Main page that renders the ExampleApp
 
 ## Key Concepts
 
-### Scope Definition
+### Client Registry
 
 ```typescript
 declare module "@assistant-ui/store" {
-  namespace AssistantStore {
-    interface Scopes {
-      foo: {
-        value: {
-          getState: () => { id: string; bar: string };
-          updateBar: (newBar: string) => void;
-        };
+  interface ClientRegistry {
+    foo: {
+      state: { id: string; bar: string };
+      methods: {
+        getState: () => FooState;
+        updateBar: (newBar: string) => void;
+        remove: () => void;
+      };
+      meta: {
         source: "fooList";
-        query: { index: number } | { id: string };
+        query: { index: number } | { key: string };
       };
-    }
+      events: {
+        "foo.updated": { id: string; newValue: string };
+        "foo.removed": { id: string };
+      };
+    };
   }
 }
 ```
@@ -497,33 +575,57 @@ declare module "@assistant-ui/store" {
 ### Resource Implementation
 
 ```typescript
-const FooListResource = resource(() => {
-  const items = [
-    /* ... */
-  ];
-  const foos = tapLookupResources(
-    items.map((item) => FooItemResource(item, { key: item.id })),
-  );
+const FooListResource = resource(
+  ({ initialValues }): ClientOutput<"fooList"> => {
+    const emit = tapAssistantEmit();
+
+    const foos = tapClientList({
+      initialValues: initialValues ? [/* ... */] : [],
+      getKey: (foo) => foo.id,
+      resource: FooItemResource,
+    });
 
-  return tapApi({
-    getState: () => ({ foos: foos.state }),
-    foo: foos.api,
-  });
-});
+    return {
+      state: { foos: foos.state },
+      methods: {
+        getState: () => state,
+        foo: foos.get,
+        addFoo: () => { /* ... */ },
+      },
+    };
+  },
+);
 ```
 
-### Provider Pattern
+### Provider Pattern with Derived
 
 ```typescript
 const FooProvider = ({ index, children }) => {
-  const parentAui = useAssistantClient();
   const aui = useAssistantClient({
-    foo: resource(() => parentAui.fooList().foo({ index }))(),
+    foo: Derived({
+      source: "fooList",
+      query: { index },
+      get: (aui) => aui.fooList().foo({ index }),
+    }),
   });
-  return <AssistantClientProvider client={aui}>{children}</AssistantClientProvider>;
+  return <AssistantProvider client={aui}>{children}</AssistantProvider>;
 };
 ```
 
+### Event Subscriptions
+
+```typescript
+// Subscribe to specific events within a scope
+useAssistantEvent("foo.updated", (payload) => {
+  console.log(`Updated to: ${payload.newValue}`);
+});
+
+// Subscribe to all events using wildcard
+useAssistantEvent("*", (data) => {
+  console.log(data.event, data.payload);
+});
+```
+
 ## Learn More
 
 - [@assistant-ui/store Documentation](../store/README.md)