@vibevibes/sdk 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,9 @@
 # @vibevibes/sdk
 
-The primitives for building agent-native experiences — shared interactive apps where humans and AI collaborate in real-time through a shared state, shared tools, and a shared canvas.
+Primitives for building shared human-AI experiences — interactive apps where humans and AI agents collaborate in real-time through shared state, shared tools, and a shared canvas.
+
+[![npm](https://img.shields.io/npm/v/@vibevibes/sdk)](https://www.npmjs.com/package/@vibevibes/sdk)
+[![license](https://img.shields.io/npm/l/@vibevibes/sdk)](./LICENSE)
 
 ## Install
 
@@ -21,7 +24,7 @@ const tools = [
     name: "counter.increment",
     description: "Add to the counter",
     input_schema: z.object({
-      amount: z.number().default(1).describe("Amount to add"),
+      amount: z.number().default(1),
     }),
     handler: async (ctx, input) => {
       const count = (ctx.state.count || 0) + input.amount;
@@ -59,44 +62,24 @@ That's a complete experience. Humans click the button. Agents call the same tool
 
 ## Core Concepts
 
-**Tools are the only way to mutate state.** Every tool has a Zod schema for validation and a handler that calls `ctx.setState()`. Humans use tools via the Canvas. Agents use the same tools via MCP. No backdoors.
+**Tools are the only way to mutate state.** Every tool has a Zod schema and a handler that calls `ctx.setState()`. Humans use tools via the Canvas. Agents use the same tools via MCP. No backdoors.
 
-**Canvas is a React component.** It receives the current shared state and a `callTool` function. It re-renders on every state change.
+**Canvas is a React component.** It receives current shared state and a `callTool` function. Re-renders on every state change.
 
 **Agents are actors, not assistants.** They join rooms, watch for events, react with tools, and persist memory. Same participation model as humans.
 
-## Defining Tools
-
-```tsx
-defineTool({
-  name: "board.place",
-  description: "Place a piece on the board",
-  input_schema: z.object({
-    x: z.number(),
-    y: z.number(),
-    piece: z.string(),
-  }),
-  handler: async (ctx, input) => {
-    const board = { ...ctx.state.board };
-    board[`${input.x},${input.y}`] = input.piece;
-    ctx.setState({ ...ctx.state, board });
-    return { placed: true };
-  },
-});
-```
-
-### Tool Handler Context
+## Tool Handler Context
 
 ```tsx
 type ToolCtx = {
   roomId: string;
-  actorId: string;                     // Who called this tool
-  owner?: string;                      // Owner extracted from actorId
-  state: Record<string, any>;          // Current shared state (read)
-  setState: (s: Record<string, any>) => void;  // Set new state (write)
+  actorId: string;        // Who called this tool
+  owner?: string;         // Owner extracted from actorId
+  state: Record<string, any>;     // Current shared state (read)
+  setState: (s) => void;          // Set new state (write)
   timestamp: number;
-  memory: Record<string, any>;         // Agent's persistent memory
-  setMemory: (updates: Record<string, any>) => void;
+  memory: Record<string, any>;    // Agent's persistent memory
+  setMemory: (updates) => void;
 };
 ```
 
@@ -116,28 +99,36 @@ type CanvasProps = {
 };
 ```
 
-## Agent Slots
+## Hooks
+
+| Hook | Returns | Purpose |
+|------|---------|---------|
+| `useToolCall(callTool)` | `{ call, loading, error }` | Loading/error tracking |
+| `useSharedState(state, key, default?)` | `value` | Typed state accessor |
+| `useOptimisticTool(callTool, state)` | `{ call, state, pending }` | Optimistic updates with rollback |
+| `useParticipants(participants)` | `ParsedParticipant[]` | Parse actor IDs |
+| `useAnimationFrame(state, interpolate?)` | `displayState` | Frame-rate buffering |
+
+## Components
 
-Define named agent roles for multi-agent experiences:
+Inline-styled (no Tailwind needed): `Button`, `Card`, `Input`, `Badge`, `Stack`, `Grid`
+
+## Agent Slots
 
 ```tsx
 manifest: {
-  agentSlots: [
-    {
-      role: "game-master",
-      systemPrompt: "You are the game master.",
-      allowedTools: ["world.narrate", "npc.speak"],
-      autoSpawn: true,
-      maxInstances: 1,
-    },
-  ],
+  agentSlots: [{
+    role: "game-master",
+    systemPrompt: "You are the game master.",
+    allowedTools: ["world.narrate"],
+    autoSpawn: true,
+    maxInstances: 1,
+  }],
 }
 ```
 
 ## Tests
 
-Inline tests for tool handlers:
-
 ```tsx
 import { defineTest } from "@vibevibes/sdk";
 
@@ -154,26 +145,7 @@ tests: [
 ]
 ```
 
-## Manifest
-
-```tsx
-type ExperienceManifest = {
-  id: string;
-  version: string;
-  title: string;
-  description: string;
-  requested_capabilities: string[];
-  agentSlots?: AgentSlot[];
-  participantSlots?: ParticipantSlot[];
-  category?: string;
-  tags?: string[];
-  netcode?: "default" | "tick" | "p2p-ephemeral";
-  tickRateMs?: number;
-  hotKeys?: string[];
-};
-```
-
-## How It Works
+## Architecture
 
 ```
 Browser (Canvas)  <--WebSocket-->  Server  <--HTTP-->  MCP (Agent)
@@ -184,15 +156,13 @@ Browser (Canvas)  <--WebSocket-->  Server  <--HTTP-->  MCP (Agent)
                             broadcasts to all clients
 ```
 
-All state lives on the server. The Canvas renders it. Tools are the only mutation path. Both humans and agents use the same tools.
-
 ## Ecosystem
 
 | Package | Description |
 |---------|-------------|
-| **@vibevibes/sdk** (this) | Define experiences — tools, canvas, state |
-| [@vibevibes/mcp](https://github.com/vibevibes/mcp) | Runtime server — MCP + WebSocket + browser viewer |
-| [create-vibevibes](https://github.com/vibevibes/create) | `npx create-vibevibes my-exp` — scaffold in seconds |
+| **@vibevibes/sdk** | Define experiences — tools, canvas, state |
+| [@vibevibes/mcp](https://github.com/vibevibes/mcp) | Runtime engine — MCP server + WebSocket + viewer |
+| [@vibevibes/create](https://github.com/vibevibes/create) | `npx @vibevibes/create` — scaffold in seconds |
 | [experiences](https://github.com/vibevibes/experiences) | Example experiences — fork and remix |
 
 ## License

package/dist/index.cjs

@@ -20,7 +20,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  createChatTools: () => createChatTools,
   defineExperience: () => defineExperience,
   defineStream: () => defineStream,
   defineTest: () => defineTest,
@@ -92,57 +91,8 @@ function defineExperience(module2) {
     }
   };
 }
-
-// src/chat.ts
-function uid() {
-  return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
-}
-function capMessages(msgs, max = 200) {
-  return msgs.length > max ? msgs.slice(-max) : msgs;
-}
-function createChatTools(z) {
-  return [
-    {
-      name: "_chat.send",
-      description: "Send a chat message",
-      input_schema: z.object({
-        message: z.string().min(1).max(2e3),
-        replyTo: z.string().optional()
-      }),
-      risk: "low",
-      capabilities_required: ["state.write"],
-      handler: async (ctx, input) => {
-        const cleanMessage = input.message.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "");
-        const messages = capMessages([
-          ...ctx.state._chat || [],
-          {
-            id: uid(),
-            actorId: ctx.actorId,
-            message: cleanMessage,
-            replyTo: input.replyTo,
-            ts: ctx.timestamp
-          }
-        ]);
-        ctx.setState({ ...ctx.state, _chat: messages });
-        return { sent: true, messageCount: messages.length };
-      }
-    },
-    {
-      name: "_chat.clear",
-      description: "Clear all chat messages",
-      input_schema: z.object({}),
-      risk: "medium",
-      capabilities_required: ["state.write"],
-      handler: async (ctx) => {
-        ctx.setState({ ...ctx.state, _chat: [] });
-        return { cleared: true };
-      }
-    }
-  ];
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createChatTools,
   defineExperience,
   defineStream,
   defineTest,

package/dist/index.d.cts

@@ -181,26 +181,4 @@ declare function defineExperience(module: ExperienceModule & {
     initialState?: Record<string, any>;
 };
 
-/**
- * Chat tool factory for experiences.
- *
- * Messages are stored in shared state under `_chat` so agents
- * see them via the stop hook's /agent-context endpoint.
- *
- * Usage:
- *   import { createChatTools } from "@vibevibes/sdk";
- *   const tools = [...myTools, ...createChatTools(z)];
- *
- *   // In Canvas: read sharedState._chat, send via callTool('_chat.send', { message })
- */
-
-type ChatMessage = {
-    id: string;
-    actorId: string;
-    message: string;
-    replyTo?: string;
-    ts: number;
-};
-declare function createChatTools(z: ZodFactory): ToolDef[];
-
-export { type AgentSlot, type CallToolFn, type CanvasProps, type ChatMessage, type ExpectChain, type ExperienceManifest, type ExperienceModule, type ExperienceRegistry, type ParticipantDetail, type ParticipantSlot, type RegistryEntry, type StreamDef, type TestDef, type TestHelpers, type ToolCtx, type ToolDef, type ToolEvent, type ToolRisk, type ZodFactory, createChatTools, defineExperience, defineStream, defineTest, defineTool };
+export { type AgentSlot, type CallToolFn, type CanvasProps, type ExpectChain, type ExperienceManifest, type ExperienceModule, type ExperienceRegistry, type ParticipantDetail, type ParticipantSlot, type RegistryEntry, type StreamDef, type TestDef, type TestHelpers, type ToolCtx, type ToolDef, type ToolEvent, type ToolRisk, type ZodFactory, defineExperience, defineStream, defineTest, defineTool };

package/dist/index.d.ts

@@ -181,26 +181,4 @@ declare function defineExperience(module: ExperienceModule & {
     initialState?: Record<string, any>;
 };
 
-/**
- * Chat tool factory for experiences.
- *
- * Messages are stored in shared state under `_chat` so agents
- * see them via the stop hook's /agent-context endpoint.
- *
- * Usage:
- *   import { createChatTools } from "@vibevibes/sdk";
- *   const tools = [...myTools, ...createChatTools(z)];
- *
- *   // In Canvas: read sharedState._chat, send via callTool('_chat.send', { message })
- */
-
-type ChatMessage = {
-    id: string;
-    actorId: string;
-    message: string;
-    replyTo?: string;
-    ts: number;
-};
-declare function createChatTools(z: ZodFactory): ToolDef[];
-
-export { type AgentSlot, type CallToolFn, type CanvasProps, type ChatMessage, type ExpectChain, type ExperienceManifest, type ExperienceModule, type ExperienceRegistry, type ParticipantDetail, type ParticipantSlot, type RegistryEntry, type StreamDef, type TestDef, type TestHelpers, type ToolCtx, type ToolDef, type ToolEvent, type ToolRisk, type ZodFactory, createChatTools, defineExperience, defineStream, defineTest, defineTool };
+export { type AgentSlot, type CallToolFn, type CanvasProps, type ExpectChain, type ExperienceManifest, type ExperienceModule, type ExperienceRegistry, type ParticipantDetail, type ParticipantSlot, type RegistryEntry, type StreamDef, type TestDef, type TestHelpers, type ToolCtx, type ToolDef, type ToolEvent, type ToolRisk, type ZodFactory, defineExperience, defineStream, defineTest, defineTool };

package/dist/index.js

@@ -62,56 +62,7 @@ function defineExperience(module) {
     }
   };
 }
-
-// src/chat.ts
-function uid() {
-  return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
-}
-function capMessages(msgs, max = 200) {
-  return msgs.length > max ? msgs.slice(-max) : msgs;
-}
-function createChatTools(z) {
-  return [
-    {
-      name: "_chat.send",
-      description: "Send a chat message",
-      input_schema: z.object({
-        message: z.string().min(1).max(2e3),
-        replyTo: z.string().optional()
-      }),
-      risk: "low",
-      capabilities_required: ["state.write"],
-      handler: async (ctx, input) => {
-        const cleanMessage = input.message.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "");
-        const messages = capMessages([
-          ...ctx.state._chat || [],
-          {
-            id: uid(),
-            actorId: ctx.actorId,
-            message: cleanMessage,
-            replyTo: input.replyTo,
-            ts: ctx.timestamp
-          }
-        ]);
-        ctx.setState({ ...ctx.state, _chat: messages });
-        return { sent: true, messageCount: messages.length };
-      }
-    },
-    {
-      name: "_chat.clear",
-      description: "Clear all chat messages",
-      input_schema: z.object({}),
-      risk: "medium",
-      capabilities_required: ["state.write"],
-      handler: async (ctx) => {
-        ctx.setState({ ...ctx.state, _chat: [] });
-        return { cleared: true };
-      }
-    }
-  ];
-}
 export {
-  createChatTools,
   defineExperience,
   defineStream,
   defineTest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibevibes/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Define shared human-AI experiences — tools, canvas, state",
   "type": "module",
   "main": "./dist/index.js",