@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.

Install

npm install @vibevibes/sdk

Peer dependencies: react (18 or 19), zod. Optional: yjs.

Quick Start

import { defineExperience, defineTool } from "@vibevibes/sdk";
import { z } from "zod";

const tools = [
  defineTool({
    name: "counter.increment",
    description: "Add to the counter",
    input_schema: z.object({
      amount: z.number().default(1).describe("Amount to add"),
    }),
    handler: async (ctx, input) => {
      const count = (ctx.state.count || 0) + input.amount;
      ctx.setState({ ...ctx.state, count });
      return { count };
    },
  }),
];

function Canvas({ sharedState, callTool }) {
  return (
    <div>
      <h1>{sharedState.count || 0}</h1>
      <button onClick={() => callTool("counter.increment", { amount: 1 })}>
        +1
      </button>
    </div>
  );
}

export default defineExperience({
  manifest: {
    id: "counter",
    version: "0.0.1",
    title: "Counter",
    description: "A shared counter",
    requested_capabilities: [],
  },
  Canvas,
  tools,
});

That's a complete experience. Humans click the button. Agents call the same tool via MCP. Both mutate the same state. Both see the same canvas.

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.

Canvas is a React component. It receives the current shared state and a callTool function. It 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

import { defineTool, quickTool } from "@vibevibes/sdk";

// Full form
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 };
  },
});

// Shorthand
quickTool("board.clear", "Clear the board", z.object({}), async (ctx) => {
  ctx.setState({ ...ctx.state, board: {} });
});

Tool Handler Context

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, shallow merge)
  timestamp: number;
  memory: Record<string, any>;         // Agent's persistent memory
  setMemory: (updates: Record<string, any>) => void;
};

Always spread existing state: ctx.setState({ ...ctx.state, key: value }).

Canvas Props

type CanvasProps = {
  roomId: string;
  actorId: string;
  sharedState: Record<string, any>;
  callTool: (name: string, input: any) => Promise<any>;
  participants: string[];
  ephemeralState: Record<string, Record<string, any>>;
  setEphemeral: (data: Record<string, any>) => void;
};

Hooks

| Hook | Signature | Purpose | |------|-----------|---------| | useToolCall | (callTool) => { call, loading, error } | Wraps callTool with loading/error tracking | | useSharedState | (sharedState, key, default?) => value | Typed accessor for a state key | | useOptimisticTool | (callTool, sharedState) => { call, state, pending } | Optimistic updates with rollback | | useParticipants | (participants) => ParsedParticipant[] | Parse actor IDs into { id, username, type, index } | | useAnimationFrame | (sharedState, interpolate?) => displayState | Buffer state updates to animation frames | | useFollow | (actorId, participants, ephemeral, setEphemeral) => { follow, unfollow, following, followers } | Follow-mode protocol | | useTypingIndicator | (actorId, ephemeral, setEphemeral) => { setTyping, typingUsers } | Typing indicators | | useUndo | (sharedState, callTool, opts?) => { undo, redo, canUndo, canRedo } | Undo/redo via state snapshots. Requires undoTool(z) in tools array. | | useDebounce | (callTool, delayMs?) => debouncedCallTool | Debounced tool calls (search, text input) | | useThrottle | (callTool, intervalMs?) => throttledCallTool | Throttled tool calls (cursors, brushes, sliders) |

Components

Pre-built, inline-styled (no Tailwind needed):

| Component | Key Props | |-----------|-----------| | Button | onClick, disabled, variant: 'primary'\|'secondary'\|'danger'\|'ghost', size: 'sm'\|'md'\|'lg' | | Card | title, style | | Input | value, onChange: (value) => void, placeholder, type, disabled | | Badge | color: 'gray'\|'blue'\|'green'\|'red'\|'yellow'\|'purple' | | Stack | direction: 'row'\|'column', gap, align, justify | | Grid | columns, gap | | Slider | value, onChange, min, max, step, label | | Textarea | value, onChange, placeholder, rows | | Modal | open, onClose, title | | ColorPicker | value, onChange, presets: string[] | | Dropdown | value, onChange, options: [{value, label}], placeholder | | Tabs | tabs: [{id, label}], activeTab, onTabChange |

Agent Slots

Define named agent roles for multi-agent experiences:

manifest: {
  agentSlots: [
    {
      role: "game-master",
      systemPrompt: "You are the game master. Narrate the world, control NPCs, manage encounters.",
      allowedTools: ["world.narrate", "npc.speak", "combat.enemy_turn"],
      autoSpawn: true,
      maxInstances: 1,
    },
  ],
}

Room Configuration

Experiences can declare configurable parameters. Rooms are spawned with specific configs:

import { defineRoomConfig } from "@vibevibes/sdk";

roomConfig: defineRoomConfig({
  schema: z.object({
    mode: z.enum(["combat", "explore"]).describe("Game mode"),
    difficulty: z.number().min(1).max(10).default(5),
  }),
  presets: {
    "boss-fight": { mode: "combat", difficulty: 10 },
    "peaceful": { mode: "explore", difficulty: 1 },
  },
})

Undo/Redo

import { undoTool, useUndo } from "@vibevibes/sdk";

// Add to tools array
const tools = [...yourTools, undoTool(z)];

// In Canvas
const { undo, redo, canUndo, canRedo } = useUndo(sharedState, callTool);

Tests

Inline tests for tool handlers, run with npm test:

import { defineTest } from "@vibevibes/sdk";

tests: [
  defineTest({
    name: "increment adds to count",
    run: async ({ tool, ctx, expect }) => {
      const inc = tool("counter.increment");
      const c = ctx({ state: { count: 5 } });
      await inc.handler(c, { amount: 3 });
      expect(c.getState().count).toBe(8);
    },
  }),
]

Manifest

type ExperienceManifest = {
  id: string;
  version: string;
  title: string;
  description: string;
  requested_capabilities: string[];   // e.g. ["room.spawn"]
  agentSlots?: AgentSlot[];
  category?: string;                  // "games", "productivity", "creative", etc.
  tags?: string[];
  netcode?: "default" | "tick" | "p2p-ephemeral";
  tickRateMs?: number;                // For tick netcode
  hotKeys?: string[];                 // Keys routed through ephemeral channel
};

How It Works

Browser (Canvas)  <--WebSocket-->  Server  <--HTTP-->  MCP (Agent)
      |                              |
  callTool(name, input)     validates input (Zod)
                            runs handler(ctx, input)
                            ctx.setState(newState)
                            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.

License

MIT