@assistant-ui/mcp-docs-server 0.1.16 → 0.1.18

package/.docs/organized/code-examples/{store-example.md → with-store.md}

@@ -1,4 +1,4 @@
-# Example: store-example
+# Example: with-store
 
 ## app/globals.css
 
@@ -118,14 +118,16 @@ import { FooList, FooListResource } from "./store/foo-store";
  */
 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 (
@@ -136,14 +138,14 @@ const Foo = () => {
             ID:
           </span>
           <span className="font-mono text-gray-900 text-sm dark:text-white">
-            {fooState.id}
+            {fooId}
           </span>
         </div>
         <div className="flex items-center gap-2">
           <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
@@ -252,12 +254,12 @@ const EventLog = () => {
  * 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">
@@ -284,47 +286,48 @@ export const ExampleApp = () => {
 ## lib/store/foo-scope.ts
 
 ```typescript
-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 };
+};
 
 declare module "@assistant-ui/store" {
-  interface AssistantScopeRegistry {
+  interface ClientRegistry {
     foo: {
-      value: {
-        getState: () => { id: string; bar: string };
-        updateBar: (newBar: string) => void;
-        remove: () => void;
-      };
-      meta: { source: "fooList"; query: { index: number } | { id: string } };
-      events: {
-        "foo.updated": { id: string; newValue: string };
-        "foo.removed": { 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;
-      };
-      meta: { source: "root"; query: Record<string, never> };
-      events: {
-        "fooList.added": { id: string };
-      };
+      state: FooListState;
+      methods: FooListMethods;
+      events: FooListEvents;
     };
   }
 }
 
-registerAssistantScope({
-  name: "fooList",
-  defaultInitialize: { error: "FooList is not configured" },
-});
-
-registerAssistantScope({
-  name: "foo",
-  defaultInitialize: { error: "Foo is not configured" },
-});
+export default {};
 
 ```
 
@@ -333,92 +336,88 @@ registerAssistantScope({
 ```tsx
 "use client";
 
-// Import scope types first to ensure module augmentation is available
 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,
-  tapStoreContext,
+  tapAssistantEmit,
+  type ClientOutput,
 } from "@assistant-ui/store";
 
+type FooData = { id: string; bar: string };
+
 export const FooItemResource = resource(
   ({
-    initialValue: { id, initialBar },
+    getInitialData,
     remove,
-  }: {
-    initialValue: { id: string; initialBar: string };
-    remove: () => void;
-  }) => {
-    const { events } = tapStoreContext();
-
-    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 });
-      events.emit("foo.updated", { id, newValue: newBar });
+      emit("foo.updated", { id: state.id, newValue: newBar });
     };
 
     const handleRemove = () => {
-      events.emit("foo.removed", { id });
+      emit("foo.removed", { id: state.id });
       remove();
     };
 
-    return tapApi(
-      {
+    return {
+      state,
+      methods: {
         getState: () => state,
         updateBar,
         remove: handleRemove,
       },
-      { key: id },
-    );
+    };
   },
 );
 
-/**
- * FooList resource implementation
- * Manages a list of foos using tapStoreList
- */
 let counter = 3;
-export const FooListResource = resource(() => {
-  const { events } = tapStoreContext();
-  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,
+    });
 
-  const addFoo = (id?: string) => {
-    const newId = id ?? idGenerator();
-    foos.add(newId);
-    events.emit("fooList.added", { id: newId });
-  };
+    const addFoo = () => {
+      const id = `foo-${++counter}`;
+      foos.add({ id: id, bar: `New Foo` });
+      emit("fooList.added", { id: id });
+    };
 
-  return tapApi({
-    getState: () => ({ foos: foos.state }),
-    foo: foos.api,
-    addFoo,
-  });
-});
+    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,
@@ -426,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 }),
     }),
   });
@@ -438,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,
 }: {
@@ -479,9 +473,10 @@ export default nextConfig;
 
 ```json
 {
-  "name": "store-example",
-  "version": "0.1.0",
+  "name": "with-store",
+  "version": "0.0.0",
   "private": true,
+  "type": "module",
   "scripts": {
     "dev": "next dev",
     "build": "next build",
@@ -490,18 +485,20 @@ export default nextConfig;
   "dependencies": {
     "@assistant-ui/store": "workspace:*",
     "@assistant-ui/tap": "workspace:*",
-    "next": "16.0.7",
-    "react": "19.2.1",
-    "react-dom": "19.2.1"
+    "next": "16.1.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3"
   },
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
-    "@tailwindcss/postcss": "^4",
-    "@types/node": "^24",
-    "@types/react": "19.2.7",
-    "@types/react-dom": "19.2.3",
-    "tailwindcss": "^4",
-    "typescript": "^5"
+    "@tailwindcss/postcss": "^4.1.18",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4.1.18",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.9.3"
   }
 }
 
@@ -516,9 +513,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
 
@@ -537,33 +535,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 };
       };
-    }
+    };
   }
 }
 ```
@@ -571,33 +578,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)
@@ -609,18 +640,11 @@ const FooProvider = ({ index, children }) => {
 
 ```json
 {
-  "extends": "@assistant-ui/x-buildutils/ts/base",
+  "extends": "@assistant-ui/x-buildutils/ts/next",
   "compilerOptions": {
-    "paths": {
-      "@/*": ["./*"],
-      "@assistant-ui/*": ["../../packages/*/src"],
-      "@assistant-ui/react/*": ["../../packages/react/src/*"],
-      "@assistant-ui/tap/*": ["../../packages/tap/src/*"],
-      "assistant-stream": ["../../packages/assistant-stream/src"],
-      "assistant-stream/*": ["../../packages/assistant-stream/src/*"]
-    }
+    "paths": { "@/*": ["./*"] }
   },
-  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
   "exclude": ["node_modules"]
 }
 

package/.docs/organized/code-examples/with-tanstack.md

@@ -22,7 +22,8 @@
 
 ```json
 {
-  "name": "assistant-ui-with-tanstack",
+  "name": "with-tanstack",
+  "version": "0.0.0",
   "private": true,
   "type": "module",
   "scripts": {
@@ -35,29 +36,29 @@
     "@assistant-ui/react-markdown": "workspace:*",
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-tooltip": "^1.2.8",
-    "@tailwindcss/vite": "^4.1.17",
-    "@tanstack/react-router": "^1.139.14",
-    "@tanstack/react-start": "^1.139.14",
-    "@tanstack/router-plugin": "^1.139.14",
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/react-router": "^1.141.8",
+    "@tanstack/react-start": "^1.142.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^0.555.0",
-    "nitro": "latest",
-    "openai": "^6.10.0",
-    "react": "^19.2.1",
-    "react-dom": "^19.2.1",
+    "lucide-react": "^0.562.0",
+    "nitro": "^3.0.1-alpha.1",
+    "openai": "^6.15.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
     "remark-gfm": "^4.0.1",
     "tailwind-merge": "^3.4.0",
-    "tailwindcss": "^4.1.17",
-    "vite-tsconfig-paths": "^5.1.4"
+    "tailwindcss": "^4.1.18",
+    "vite-tsconfig-paths": "^6.0.3"
   },
   "devDependencies": {
-    "@types/node": "^22.19.1",
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@types/node": "^25.0.3",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.1",
+    "@vitejs/plugin-react": "^5.1.2",
     "typescript": "^5.9.3",
-    "vite": "^7.2.6"
+    "vite": "^7.3.0"
   }
 }
 
@@ -368,7 +369,7 @@ const ThreadScrollToBottom: FC = () => {
       <TooltipIconButton
         tooltip="Scroll to bottom"
         variant="outline"
-        className="aui-thread-scroll-to-bottom -top-12 absolute z-10 self-center rounded-full p-4 disabled:invisible dark:bg-background dark:hover:bg-accent"
+        className="aui-thread-scroll-to-bottom absolute -top-12 z-10 self-center rounded-full p-4 disabled:invisible dark:bg-background dark:hover:bg-accent"
       >
         <ArrowDownIcon />
       </TooltipIconButton>
@@ -541,7 +542,7 @@ const AssistantActionBar: FC = () => {
       hideWhenRunning
       autohide="not-last"
       autohideFloat="single-branch"
-      className="aui-assistant-action-bar-root -ml-1 col-start-3 row-start-2 flex gap-1 text-muted-foreground data-floating:absolute data-floating:rounded-md data-floating:border data-floating:bg-background data-floating:p-1 data-floating:shadow-sm"
+      className="aui-assistant-action-bar-root col-start-3 row-start-2 -ml-1 flex gap-1 text-muted-foreground data-floating:absolute data-floating:rounded-md data-floating:border data-floating:bg-background data-floating:p-1 data-floating:shadow-sm"
     >
       <ActionBarPrimitive.Copy asChild>
         <TooltipIconButton tooltip="Copy">
@@ -572,12 +573,12 @@ const UserMessage: FC = () => {
         <div className="aui-user-message-content wrap-break-word rounded-3xl bg-muted px-5 py-2.5 text-foreground">
           <MessagePrimitive.Parts />
         </div>
-        <div className="aui-user-action-bar-wrapper -translate-x-full -translate-y-1/2 absolute top-1/2 left-0 pr-2">
+        <div className="aui-user-action-bar-wrapper absolute top-1/2 left-0 -translate-x-full -translate-y-1/2 pr-2">
           <UserActionBar />
         </div>
       </div>
 
-      <BranchPicker className="aui-user-branch-picker -mr-1 col-span-full col-start-1 row-start-3 justify-end" />
+      <BranchPicker className="aui-user-branch-picker col-span-full col-start-1 row-start-3 -mr-1 justify-end" />
     </MessagePrimitive.Root>
   );
 };
@@ -632,7 +633,7 @@ const BranchPicker: FC<BranchPickerPrimitive.Root.Props> = ({
     <BranchPickerPrimitive.Root
       hideWhenSingleBranch
       className={cn(
-        "aui-branch-picker-root -ml-2 mr-2 inline-flex items-center text-muted-foreground text-xs",
+        "aui-branch-picker-root mr-2 -ml-2 inline-flex items-center text-muted-foreground text-xs",
         className,
       )}
       {...rest}
@@ -1516,32 +1517,13 @@ export const chatStream = createServerFn({ method: "POST" })
 
 ```json
 {
-  "include": ["**/*.ts", "**/*.tsx"],
+  "extends": "@assistant-ui/x-buildutils/ts/base",
   "compilerOptions": {
-    "target": "ES2022",
-    "jsx": "react-jsx",
-    "module": "ESNext",
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "types": ["vite/client"],
-
-    /* Bundler mode */
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": false,
-    "noEmit": true,
-
-    /* Linting */
-    "skipLibCheck": true,
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true,
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  }
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
 }
 
 ```
@@ -1558,7 +1540,11 @@ import { nitro } from "nitro/vite";
 
 const config = defineConfig({
   plugins: [
-    nitro(),
+    nitro({
+      output: {
+        dir: "dist",
+      },
+    }),
     viteTsConfigPaths({
       projects: ["./tsconfig.json"],
     }),