@vibevibes/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,622 @@
+import React from 'react';
+import { z } from 'zod';
+
+/**
+ * Experience SDK Types - Simplified state sync
+ */
+
+type ToolRisk = "low" | "medium" | "high";
+/**
+ * Netcode mode declaration — experiences declare their sync strategy.
+ * The runtime picks the right optimizations automatically.
+ */
+type NetcodeMode = "default" | "tick" | "p2p-ephemeral";
+/**
+ * JSON Patch operation (RFC 6902 subset).
+ */
+type JsonPatchOp = {
+    op: "add" | "remove" | "replace";
+    path: string;
+    value?: any;
+};
+type ExperienceImport = {
+    experienceId: string;
+    tools: string[] | '*';
+    prefix?: string;
+};
+/**
+ * Event emitted after a tool executes (used by typed event subscriptions).
+ */
+type ToolEvent = {
+    id: string;
+    ts: number;
+    actorId: string;
+    owner?: string;
+    tool: string;
+    input: any;
+    output?: any;
+    error?: string;
+};
+/**
+ * Agent slot definition for multi-agent rooms.
+ * Experience authors define named agent roles with system prompts and tool restrictions.
+ */
+type AgentSlot = {
+    role: string;
+    systemPrompt: string;
+    allowedTools?: string[];
+    autoSpawn?: boolean;
+    maxInstances?: number;
+};
+type ExperienceManifest = {
+    id: string;
+    version: string;
+    title: string;
+    description: string;
+    requested_capabilities: string[];
+    imports?: ExperienceImport[];
+    agentSlots?: AgentSlot[];
+    category?: string;
+    tags?: string[];
+    /** Sync strategy: 'default' | 'tick' | 'p2p-ephemeral'. Default: 'default'. */
+    netcode?: NetcodeMode;
+    /** For 'tick' netcode: server tick interval in ms (e.g. 50 = 20Hz). */
+    tickRateMs?: number;
+    /** State keys routed through fast ephemeral channel (no tool gate). */
+    hotKeys?: string[];
+};
+/**
+ * Simplified Tool Context (no yjs, no events array)
+ *
+ * Use the generic parameter for typed state:
+ *   handler: async (ctx: ToolCtx<{ count: number }>, input) => {
+ *     const current = ctx.state.count; // typed
+ *   }
+ */
+type ToolCtx<TState extends Record<string, any> = Record<string, any>> = {
+    roomId: string;
+    actorId: string;
+    owner?: string;
+    state: TState;
+    setState: (newState: TState) => void;
+    timestamp: number;
+    memory: Record<string, any>;
+    setMemory: (updates: Record<string, any>) => void;
+    /**
+     * Spawn a child room with a specified experience.
+     * Only available when manifest declares "room.spawn" in requested_capabilities.
+     * Rate limited to 5 spawns per room per 5 minutes.
+     */
+    spawnRoom?: (opts: SpawnRoomOpts) => Promise<SpawnRoomResult>;
+};
+type ToolDef<TInput = any, TOutput = any> = {
+    name: string;
+    description: string;
+    input_schema: z.ZodTypeAny;
+    risk: ToolRisk;
+    capabilities_required: string[];
+    handler: (ctx: ToolCtx, input: TInput) => Promise<TOutput>;
+    emits?: string[];
+    on?: Record<string, (ctx: ToolCtx, event: ToolEvent) => Promise<void>>;
+    /**
+     * If false, skip persisting state + event to DB after execution.
+     * State is still broadcast to clients. Use for high-frequency tools
+     * like cursor moves, animations, etc. Default: true.
+     */
+    persist?: boolean;
+};
+/**
+ * Simplified Canvas Props - Hybrid State Model
+ *
+ * Use the generic parameter for typed sharedState:
+ *   const Canvas: React.FC<CanvasProps<{ count: number }>> = ({ sharedState }) => {
+ *     const count = sharedState.count; // fully typed
+ *   };
+ */
+type CanvasProps<TState extends Record<string, any> = Record<string, any>> = {
+    roomId: string;
+    actorId: string;
+    sharedState: TState;
+    callTool: (name: string, input: any, predictFn?: (state: TState) => TState) => Promise<any>;
+    /** Batch multiple tool calls in a single round-trip. */
+    callTools?: (calls: Array<{
+        name: string;
+        input: any;
+    }>) => Promise<any[]>;
+    ephemeralState: Record<string, Record<string, any>>;
+    setEphemeral: (data: Record<string, any>) => void;
+    /** Fire a client-authoritative action via Broadcast (no tool gate, no persistence). */
+    dispatchEphemeralAction?: (name: string, input: any) => void;
+    /** Subscribe to ephemeral actions from other participants. */
+    onEphemeralAction?: (handler: (action: {
+        name: string;
+        input: any;
+        actorId: string;
+        ts: number;
+    }) => void) => () => void;
+    participants: string[];
+};
+/**
+ * Assertion chain returned by `expect()` in test helpers.
+ */
+type ExpectChain<T> = {
+    toBe: (expected: T) => void;
+    toEqual: (expected: any) => void;
+    toBeTruthy: () => void;
+    toBeFalsy: () => void;
+    toContain: (item: any) => void;
+    toHaveProperty: (key: string, value?: any) => void;
+    not: ExpectChain<T>;
+};
+/**
+ * Helpers injected into each test's `run` function.
+ *
+ * - `tool(name)` looks up a tool from the experience's tools array
+ * - `ctx(opts?)` creates a mock ToolCtx; call `getState()` after mutations
+ * - `expect(actual)` returns an assertion chain for type-safe assertions
+ * - `snapshot(label, value)` stores/compares values within a test session
+ *
+ * Tests signal failure by throwing. If `run` resolves, the test passed.
+ */
+type TestHelpers = {
+    tool: (name: string) => ToolDef;
+    ctx: (opts?: {
+        state?: Record<string, any>;
+        actorId?: string;
+        roomId?: string;
+        owner?: string;
+    }) => ToolCtx & {
+        getState: () => Record<string, any>;
+    };
+    expect: <T>(actual: T) => ExpectChain<T>;
+    snapshot: (label: string, value: any) => void;
+};
+/**
+ * Inline test for experience tool handlers.
+ * Throw to fail; resolve to pass.
+ */
+type TestDef = {
+    name: string;
+    run: (helpers: TestHelpers) => Promise<void>;
+};
+/**
+ * Declarative hint for agents about when to act.
+ * Experience authors include these to guide agent behavior.
+ */
+type AgentHint = {
+    trigger: string;
+    condition?: string;
+    suggestedTools: string[];
+    priority?: 'low' | 'medium' | 'high';
+    cooldownMs?: number;
+    /** Cross-room agent coordination: follow linked rooms and react to activity there. */
+    crossRoom?: {
+        linkTypes?: string[];
+        watchFor?: string[];
+    };
+};
+/**
+ * Client-authoritative action that bypasses the tool gate entirely.
+ * Goes through Supabase Broadcast directly — no persistence, no server validation.
+ * Use for cursor positions, hover states, drag previews, etc.
+ */
+type EphemeralActionDef = {
+    name: string;
+    description: string;
+    input_schema: z.ZodTypeAny;
+};
+/**
+ * Performance metrics exposed by the room sync system.
+ */
+type PerfMetrics = {
+    toolCallRtts: number[];
+    broadcastLatencies: number[];
+    stateSize: number;
+    rendersPerSecond: number;
+    pendingOptimistic: number;
+};
+/**
+ * Follow protocol: allows participants to "follow" another user's viewport/actions.
+ * Stored in ephemeral state under the `_follow` key.
+ */
+type FollowState = {
+    targetActorId: string;
+    mode: 'viewport' | 'actions' | 'both';
+    since: number;
+};
+/**
+ * Multi-agent message for negotiation protocol.
+ * Agents communicate through shared state under the `_agentMessages` key.
+ */
+type AgentMessage = {
+    id: string;
+    from: string;
+    to: string | '*';
+    type: 'proposal' | 'vote' | 'delegate' | 'inform' | 'request';
+    content: string;
+    data?: Record<string, any>;
+    ts: number;
+    ttl?: number;
+};
+/**
+ * State migration function for experience versioning.
+ * Called when a room's experience version changes.
+ */
+type StateMigration = {
+    from: string;
+    to: string;
+    migrate: (oldState: Record<string, any>) => Record<string, any>;
+};
+/**
+ * Webhook event types that can be filtered.
+ */
+type WebhookEventType = 'tool.executed' | 'tool.error' | 'participant.joined' | 'participant.left' | 'state.changed' | 'room.created' | 'room.reset';
+/**
+ * Options for spawning a child room from a tool handler.
+ * Requires "room.spawn" in manifest.requested_capabilities.
+ */
+type SpawnRoomOpts = {
+    experienceId: string;
+    name?: string;
+    initialState?: Record<string, any>;
+    /** If true, store parent roomId in child state as _parentRoom */
+    linkBack?: boolean;
+};
+type SpawnRoomResult = {
+    roomId: string;
+    url: string;
+};
+/**
+ * A link between two rooms (parent/child relationship).
+ */
+type RoomLink = {
+    parentRoomId: string;
+    childRoomId: string;
+    linkType: 'spawned' | 'referenced' | 'forked';
+    metadata?: Record<string, any>;
+    createdAt: string;
+};
+type ExperienceModule = {
+    manifest: ExperienceManifest;
+    Canvas: React.FC<CanvasProps>;
+    tools: ToolDef[];
+    tests?: TestDef[];
+    agentHints?: AgentHint[];
+    /** Client-authoritative actions that bypass the tool gate. */
+    ephemeralActions?: EphemeralActionDef[];
+    /** State migrations for version upgrades. */
+    migrations?: StateMigration[];
+};
+
+declare function defineTool<TInput, TOutput>(config: {
+    name: string;
+    description: string;
+    input_schema: z.ZodType<TInput>;
+    risk?: ToolRisk;
+    capabilities_required?: string[];
+    handler: ToolDef<TInput, TOutput>["handler"];
+}): ToolDef<TInput, TOutput>;
+declare function defineTest(config: {
+    name: string;
+    run: TestDef["run"];
+}): TestDef;
+declare function defineEphemeralAction(config: {
+    name: string;
+    description: string;
+    input_schema: z.ZodTypeAny;
+}): EphemeralActionDef;
+/**
+ * Reduced-boilerplate tool definition.
+ * Auto-derives defaults: risk="low", capabilities=["state.write"],
+ * and spreads input into state if no handler is provided.
+ *
+ * Usage:
+ *   quickTool("counter.increment", "Add 1 to count", z.object({}), async (ctx) => {
+ *     ctx.setState({ ...ctx.state, count: (ctx.state.count ?? 0) + 1 });
+ *   })
+ */
+declare function quickTool<TInput>(name: string, description: string, input_schema: z.ZodType<TInput>, handler: ToolDef<TInput, any>["handler"]): ToolDef<TInput, any>;
+declare function defineExperience(module: ExperienceModule): ExperienceModule;
+declare function validateExperience(module: ExperienceModule): {
+    valid: boolean;
+    errors: string[];
+};
+
+/**
+ * React hooks for experience authors.
+ *
+ * These hooks simplify common patterns in experience Canvas components:
+ * - useToolCall: wraps callTool with loading/error state
+ * - useSharedState: typed accessor for a specific state key
+ * - useOptimisticTool: optimistic updates with rollback on error
+ * - useParticipants: parsed participant list with structured data
+ *
+ * Hooks rely on React being available as a global (provided by the bundler runtime).
+ */
+type CallToolFn = (name: string, input: any) => Promise<any>;
+type UseToolCallReturn = {
+    call: (name: string, input: any) => Promise<any>;
+    loading: boolean;
+    error: string | null;
+};
+/**
+ * Wraps callTool with loading and error tracking.
+ *
+ * Usage:
+ *   const { call, loading, error } = useToolCall(callTool);
+ *   <button onClick={() => call('counter.increment', {})} disabled={loading}>
+ */
+declare function useToolCall(callTool: CallToolFn): UseToolCallReturn;
+/**
+ * Typed accessor for a specific key in shared state.
+ *
+ * Usage:
+ *   const count = useSharedState<number>(sharedState, 'count', 0);
+ */
+declare function useSharedState<T>(sharedState: Record<string, any>, key: string, defaultValue?: T): T;
+type UseOptimisticToolReturn = {
+    call: (name: string, input: any, optimisticState: Record<string, any>) => Promise<any>;
+    state: Record<string, any>;
+    pending: boolean;
+};
+/**
+ * Applies an optimistic state update immediately, then reverts on error.
+ *
+ * Usage:
+ *   const { call, state, pending } = useOptimisticTool(callTool, sharedState);
+ *   call('counter.increment', {}, { count: sharedState.count + 1 });
+ */
+declare function useOptimisticTool(callTool: CallToolFn, sharedState: Record<string, any>): UseOptimisticToolReturn;
+/**
+ * Decouples render frequency from state sync frequency.
+ * State updates are buffered and applied at most once per animation frame.
+ * Optional interpolation function smooths transitions between states.
+ *
+ * Usage:
+ *   const displayState = useAnimationFrame(sharedState);
+ *   // OR with interpolation:
+ *   const displayState = useAnimationFrame(sharedState, (prev, next, t) => ({
+ *     ...next,
+ *     x: prev.x + (next.x - prev.x) * t,
+ *   }));
+ */
+declare function useAnimationFrame(sharedState: Record<string, any>, interpolate?: (prev: Record<string, any>, next: Record<string, any>, t: number) => Record<string, any>): Record<string, any>;
+type ParsedParticipant = {
+    id: string;
+    username: string;
+    type: 'human' | 'ai' | 'unknown';
+    index: number;
+};
+/**
+ * Parses the participant ID list into structured objects.
+ *
+ * Participant IDs follow the format: {username}-{type}-{N}
+ * e.g., "alice-human-1", "claude-ai-2"
+ */
+declare function useParticipants(participants: string[]): ParsedParticipant[];
+type FollowMode = 'viewport' | 'actions' | 'both';
+type FollowData = {
+    targetActorId: string;
+    mode: FollowMode;
+    since: number;
+};
+type EphemeralAction = {
+    name: string;
+    input: any;
+    actorId: string;
+    ts: number;
+};
+type DispatchEphemeralActionFn = (name: string, input: any) => void;
+type OnEphemeralActionFn = (handler: (action: EphemeralAction) => void) => () => void;
+type SetEphemeralFn = (data: Record<string, any>) => void;
+type UseFollowReturn = {
+    /** Start following a target participant. */
+    follow: (targetActorId: string, mode: FollowMode) => void;
+    /** Stop following. */
+    unfollow: () => void;
+    /** Who you are currently following, or null. */
+    following: FollowData | null;
+    /** List of actor IDs that are following you. */
+    followers: Array<{
+        actorId: string;
+        mode: FollowMode;
+        since: number;
+    }>;
+};
+/**
+ * Manages follow-mode state via ephemeral presence.
+ *
+ * Stores follow intent in ephemeral state under `_follow` key and dispatches
+ * `follow.started` / `follow.stopped` ephemeral actions to notify participants.
+ *
+ * Usage:
+ *   const { follow, unfollow, following, followers } = useFollow(
+ *     actorId, participants, ephemeralState, setEphemeral,
+ *     onEphemeralAction, dispatchEphemeralAction
+ *   );
+ *   follow('alice-human-1', 'viewport');
+ */
+declare function useFollow(actorId: string, participants: string[], ephemeralState: Record<string, Record<string, any>>, setEphemeral: SetEphemeralFn, _onEphemeralAction?: OnEphemeralActionFn, dispatchEphemeralAction?: DispatchEphemeralActionFn): UseFollowReturn;
+/**
+ * Manages typing/activity indicators via ephemeral state.
+ *
+ * Usage:
+ *   const { setTyping, typingUsers } = useTypingIndicator(actorId, ephemeralState, setEphemeral);
+ *
+ *   // Call setTyping(true) when the user starts typing
+ *   // Call setTyping(false) when they stop (auto-clears after 3s)
+ *   // typingUsers is an array of actor IDs currently typing
+ */
+declare function useTypingIndicator(actorId: string, ephemeralState: Record<string, Record<string, any>>, setEphemeral: (data: Record<string, any>) => void, timeoutMs?: number): {
+    setTyping: (isTyping: boolean) => void;
+    typingUsers: string[];
+};
+
+/**
+ * Pre-built UI components for experiences.
+ *
+ * These components use inline styles (no Tailwind dependency) so they work
+ * reliably inside bundled experience canvases. They provide sensible defaults
+ * and can be overridden via the `style` prop.
+ *
+ * Usage in experiences:
+ *   import { Button, Card, Input, Badge, Stack, Grid } from "@vibevibes/experience-sdk";
+ */
+type ButtonProps = {
+    children?: any;
+    onClick?: () => void;
+    disabled?: boolean;
+    variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
+    size?: 'sm' | 'md' | 'lg';
+    style?: Record<string, any>;
+};
+declare function Button({ children, onClick, disabled, variant, size, style }: ButtonProps): any;
+type CardProps = {
+    children?: any;
+    title?: string;
+    style?: Record<string, any>;
+};
+declare function Card({ children, title, style }: CardProps): any;
+type InputProps = {
+    value?: string;
+    onChange?: (value: string) => void;
+    placeholder?: string;
+    type?: string;
+    disabled?: boolean;
+    style?: Record<string, any>;
+};
+declare function Input({ value, onChange, placeholder, type, disabled, style }: InputProps): any;
+type BadgeProps = {
+    children?: any;
+    color?: 'gray' | 'blue' | 'green' | 'red' | 'yellow' | 'purple';
+    style?: Record<string, any>;
+};
+declare function Badge({ children, color, style }: BadgeProps): any;
+type StackProps = {
+    children?: any;
+    direction?: 'row' | 'column';
+    gap?: string | number;
+    align?: string;
+    justify?: string;
+    style?: Record<string, any>;
+};
+declare function Stack({ children, direction, gap, align, justify, style }: StackProps): any;
+type GridProps = {
+    children?: any;
+    columns?: number | string;
+    gap?: string | number;
+    style?: Record<string, any>;
+};
+declare function Grid({ children, columns, gap, style }: GridProps): any;
+
+/**
+ * Multi-agent negotiation protocol.
+ * Provides pre-built tools for agent-to-agent communication.
+ */
+
+declare function createAgentProtocolTools(namespace: string, z: any): ToolDef[];
+
+/**
+ * Pre-built agent hints for the negotiation protocol.
+ */
+
+declare function createAgentProtocolHints(namespace: string): AgentHint[];
+
+/**
+ * State migration runner for experience versioning.
+ *
+ * Pure functions (no side effects, no async) so they can run in Edge Functions,
+ * Node.js, or the browser.
+ */
+
+interface MigrationResult {
+    migrated: boolean;
+    fromVersion: string;
+    toVersion: string;
+    state: Record<string, any>;
+}
+/**
+ * Get the state version from a state object.
+ * Stored in state._version, defaults to "0.0.0" if absent.
+ */
+declare function getStateVersion(state: Record<string, any>): string;
+/**
+ * Compare two semver strings.
+ * Returns -1 if a < b, 0 if equal, 1 if a > b.
+ *
+ * Handles standard major.minor.patch format. Missing segments default to 0.
+ */
+declare function compareSemver(a: string, b: string): number;
+/**
+ * Run all applicable migrations on a state object.
+ *
+ * - Reads state._version (default "0.0.0") as the starting version
+ * - Sorts migrations by their to version (ascending semver)
+ * - Applies each migration where migration.to > stateVersion and migration.to <= currentVersion
+ * - Sets state._version = currentVersion after all migrations
+ * - Returns a MigrationResult indicating whether any migrations were applied
+ *
+ * The migration runner is pure: it does not mutate the input state object.
+ * It returns a new state object with migrations applied.
+ */
+declare function migrateState(state: Record<string, any>, migrations: StateMigration[], currentVersion: string): MigrationResult;
+
+/**
+ * Storage adapter interface for vibe vibes
+ * Allows multiple storage backends: in-memory, Supabase, GitHub, etc.
+ */
+interface ExperienceListing {
+    id: string;
+    title: string;
+    description: string;
+    version: string;
+    source: 'builtin' | 'github' | 'supabase';
+    github_repo?: string;
+    github_url?: string;
+}
+interface RoomState {
+    roomId: string;
+    experienceId: string;
+    sharedState: Record<string, any>;
+    updatedAt: number;
+}
+interface StorageToolEvent {
+    id: string;
+    ts: number;
+    actor_id: string;
+    tool: string;
+    input: unknown;
+    output: unknown;
+}
+/**
+ * Storage adapter interface
+ * All methods are async to support both local and remote storage
+ */
+interface StorageAdapter {
+    saveRoomState(roomId: string, state: RoomState): Promise<void>;
+    loadRoomState(roomId: string): Promise<RoomState | null>;
+    appendEvent(roomId: string, event: StorageToolEvent): Promise<void>;
+    loadEvents(roomId: string, limit?: number): Promise<StorageToolEvent[]>;
+    listExperiences(userId?: string): Promise<ExperienceListing[]>;
+    saveUserProfile?(userId: string, profile: any): Promise<void>;
+    loadUserProfile?(userId: string): Promise<any | null>;
+}
+/**
+ * In-memory storage adapter
+ * No persistence - data lost on restart
+ * Perfect for local development and demos
+ */
+declare class InMemoryAdapter implements StorageAdapter {
+    private roomStates;
+    private events;
+    private profiles;
+    saveRoomState(roomId: string, state: RoomState): Promise<void>;
+    loadRoomState(roomId: string): Promise<RoomState | null>;
+    appendEvent(roomId: string, event: StorageToolEvent): Promise<void>;
+    loadEvents(roomId: string, limit?: number): Promise<StorageToolEvent[]>;
+    listExperiences(_userId?: string): Promise<ExperienceListing[]>;
+    saveUserProfile(userId: string, profile: any): Promise<void>;
+    loadUserProfile(userId: string): Promise<any | null>;
+}
+
+export { type AgentHint, type AgentMessage, type AgentSlot, Badge, Button, type CanvasProps, Card, type EphemeralActionDef, type ExpectChain, type ExperienceImport, type ExperienceListing, type ExperienceManifest, type ExperienceModule, type FollowState, Grid, InMemoryAdapter, Input, type JsonPatchOp, type MigrationResult, type NetcodeMode, type ParsedParticipant, type PerfMetrics, type RoomLink, type RoomState, type SpawnRoomOpts, type SpawnRoomResult, Stack, type StateMigration, type StorageAdapter, type StorageToolEvent, type TestDef, type TestHelpers, type ToolCtx, type ToolDef, type ToolEvent, type ToolRisk, type UseFollowReturn, type UseOptimisticToolReturn, type UseToolCallReturn, type WebhookEventType, compareSemver, createAgentProtocolHints, createAgentProtocolTools, defineEphemeralAction, defineExperience, defineTest, defineTool, getStateVersion, migrateState, quickTool, useAnimationFrame, useFollow, useOptimisticTool, useParticipants, useSharedState, useToolCall, useTypingIndicator, validateExperience };