@vibevibes/sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React$1 from 'react';
 import { z } from 'zod';
 
 /**
@@ -65,6 +65,48 @@ type ExperienceManifest = {
     /** State keys routed through fast ephemeral channel (no tool gate). */
     hotKeys?: string[];
 };
+/**
+ * Room configuration schema + metadata.
+ *
+ * Experience authors declare what values a room accepts when spawned.
+ * Each room becomes an instance of the experience with a specific config.
+ * Think of it as: experience = game engine, config = level parameters.
+ *
+ * Example:
+ *   roomConfig: defineRoomConfig({
+ *     schema: z.object({
+ *       mode: z.enum(["combat", "explore", "dialogue"]).describe("Room game mode"),
+ *       difficulty: z.number().min(1).max(10).default(5).describe("Difficulty level"),
+ *       theme: z.string().default("forest").describe("Visual theme"),
+ *     }),
+ *     defaults: { mode: "explore", difficulty: 5, theme: "forest" },
+ *     presets: {
+ *       "boss-fight": { mode: "combat", difficulty: 10, theme: "volcano" },
+ *       "peaceful":   { mode: "explore", difficulty: 1, theme: "meadow" },
+ *     },
+ *   })
+ */
+type RoomConfigDef<TConfig extends Record<string, any> = Record<string, any>> = {
+    /** Zod schema defining the config shape. Used for validation + JSON schema generation. */
+    schema: z.ZodTypeAny;
+    /** Default config values for rooms that don't specify config at spawn time. */
+    defaults?: Partial<TConfig>;
+    /** Named presets: quick ways to spawn rooms with predefined configs. */
+    presets?: Record<string, TConfig>;
+    /** Human-readable description of what this config controls. */
+    description?: string;
+};
+/** Stream definition for high-frequency continuous state updates.
+ *  Bypasses the full tool handler pipeline but still validates and persists to state. */
+type StreamDef<TInput = any> = {
+    name: string;
+    description?: string;
+    input_schema: z.ZodTypeAny;
+    /** Pure merge function: takes current state, stream input, and actorId, returns new state. */
+    merge: (state: Record<string, any>, input: TInput, actorId: string) => Record<string, any>;
+    /** Max inputs per second per actor (server-enforced). Default: 60. */
+    rateLimit?: number;
+};
 /**
  * Simplified Tool Context (no yjs, no events array)
  *
@@ -73,7 +115,7 @@ type ExperienceManifest = {
  *     const current = ctx.state.count; // typed
  *   }
  */
-type ToolCtx<TState extends Record<string, any> = Record<string, any>> = {
+type ToolCtx<TState extends Record<string, any> = Record<string, any>, TConfig extends Record<string, any> = Record<string, any>> = {
     roomId: string;
     actorId: string;
     owner?: string;
@@ -82,12 +124,22 @@ type ToolCtx<TState extends Record<string, any> = Record<string, any>> = {
     timestamp: number;
     memory: Record<string, any>;
     setMemory: (updates: Record<string, any>) => void;
+    /**
+     * This room's config values. Set at spawn time, immutable after creation.
+     * Allows tools to behave differently based on the room's modality.
+     * e.g. `ctx.roomConfig.mode === "combat"` to branch tool behavior.
+     */
+    roomConfig: TConfig;
     /**
      * 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>;
+    /** Store a binary blob (pixel buffers, audio, etc). Returns the blob key. */
+    setBlob?: (key: string, data: ArrayBuffer) => string;
+    /** Retrieve a binary blob by key. */
+    getBlob?: (key: string) => ArrayBuffer | undefined;
 };
 type ToolDef<TInput = any, TOutput = any> = {
     name: string;
@@ -113,7 +165,7 @@ type ToolDef<TInput = any, TOutput = any> = {
  *     const count = sharedState.count; // fully typed
  *   };
  */
-type CanvasProps<TState extends Record<string, any> = Record<string, any>> = {
+type CanvasProps<TState extends Record<string, any> = Record<string, any>, TConfig extends Record<string, any> = Record<string, any>> = {
     roomId: string;
     actorId: string;
     sharedState: TState;
@@ -134,7 +186,15 @@ type CanvasProps<TState extends Record<string, any> = Record<string, any>> = {
         actorId: string;
         ts: number;
     }) => void) => () => void;
+    /** Send high-frequency continuous input via WebSocket stream. Bypasses tool gate. */
+    stream?: (name: string, input: any) => void;
     participants: string[];
+    /**
+     * This room's config values, set at spawn time.
+     * Use this to adapt the UI based on the room's modality.
+     * e.g. render a combat UI vs exploration UI based on `roomConfig.mode`.
+     */
+    roomConfig: TConfig;
 };
 /**
  * Assertion chain returned by `expect()` in test helpers.
@@ -165,6 +225,7 @@ type TestHelpers = {
         actorId?: string;
         roomId?: string;
         owner?: string;
+        roomConfig?: Record<string, any>;
     }) => ToolCtx & {
         getState: () => Record<string, any>;
     };
@@ -180,20 +241,15 @@ type TestDef = {
     run: (helpers: TestHelpers) => Promise<void>;
 };
 /**
- * Declarative hint for agents about when to act.
- * Experience authors include these to guide agent behavior.
+ * Combined context for the agent's Stop hook.
+ * Returned by the /agent-context endpoint — everything the agent needs
+ * to decide what to do next in a single HTTP call.
  */
-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[];
-    };
+type AgentContext = {
+    events: ToolEvent[];
+    observation: Record<string, any>;
+    participants: string[];
+    sharedState: Record<string, any>;
 };
 /**
  * Client-authoritative action that bypasses the tool gate entirely.
@@ -261,10 +317,18 @@ type SpawnRoomOpts = {
     initialState?: Record<string, any>;
     /** If true, store parent roomId in child state as _parentRoom */
     linkBack?: boolean;
+    /**
+     * Config values for the new room. Validated against the experience's roomConfig schema.
+     * If a preset name is given as a string, the preset's config is used.
+     * If omitted, the experience's default config is applied.
+     */
+    config?: Record<string, any> | string;
 };
 type SpawnRoomResult = {
     roomId: string;
     url: string;
+    /** The resolved config applied to the spawned room. */
+    config: Record<string, any>;
 };
 /**
  * A link between two rooms (parent/child relationship).
@@ -276,16 +340,75 @@ type RoomLink = {
     metadata?: Record<string, any>;
     createdAt: string;
 };
+/**
+ * A single entry in the experience registry (vibevibes.registry.json).
+ * Maps an experience ID to its source path for cross-experience room spawning.
+ */
+type RegistryEntry = {
+    path: string;
+};
+/**
+ * Per-project experience registry format (vibevibes.registry.json).
+ * Enables cross-experience room spawning by mapping experience IDs to source paths.
+ */
+type ExperienceRegistry = {
+    experiences: Record<string, RegistryEntry>;
+};
 type ExperienceModule = {
     manifest: ExperienceManifest;
-    Canvas: React.FC<CanvasProps>;
+    Canvas: React$1.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[];
+    /**
+     * Zod schema for the shared state shape. Provides:
+     * - Type safety: ctx.state and sharedState are typed throughout
+     * - Runtime validation: tool mutations are validated against the schema
+     * - Auto-generated initialState: defaults from the schema populate initial state
+     * - Agent legibility: agents can inspect the schema to understand state shape
+     *
+     * Usage:
+     *   stateSchema: z.object({
+     *     count: z.number().default(0).describe("Current counter value"),
+     *     players: z.array(z.object({
+     *       name: z.string(),
+     *       score: z.number().default(0),
+     *     })).default([]).describe("Active players"),
+     *     phase: z.enum(["setup", "playing", "finished"]).default("setup"),
+     *   })
+     *
+     * If both stateSchema and initialState are provided, initialState takes
+     * precedence but is validated against the schema at startup.
+     */
+    stateSchema?: z.ZodTypeAny;
+    /**
+     * Room configuration schema.
+     * Declares what values each room instance accepts at spawn time.
+     * Turns your experience into a configurable engine:
+     *   experience = engine, roomConfig = level/mode parameters.
+     *
+     * Example: A dungeon crawler where each room is a different biome:
+     *   roomConfig: defineRoomConfig({
+     *     schema: z.object({
+     *       biome: z.enum(["forest", "cave", "desert"]),
+     *       enemyDensity: z.number().min(0).max(1).default(0.5),
+     *     }),
+     *     presets: {
+     *       "dark-cave": { biome: "cave", enemyDensity: 0.8 },
+     *       "peaceful-forest": { biome: "forest", enemyDensity: 0.1 },
+     *     },
+     *   })
+     */
+    roomConfig?: RoomConfigDef;
+    /** Stream definitions for high-frequency continuous state updates (brush strokes, sliders, dragging).
+     *  Bypasses the full tool handler pipeline but still validates and persists to state. */
+    streams?: StreamDef[];
+    /** Agent observation function. Computes a curated view of state for MCP agents.
+     *  Called after each tool execution. If not defined, agents see the full state. */
+    observe?: (state: Record<string, any>, event: ToolEvent | null, actorId: string) => Record<string, any>;
 };
 
 declare function defineTool<TInput, TOutput>(config: {
@@ -316,10 +439,108 @@ declare function defineEphemeralAction(config: {
  *   })
  */
 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): {
+/**
+ * Pre-built tool that restores shared state to a previous snapshot.
+ * Required for useUndo/useRedo to work. Add it to your tools array:
+ *
+ *   tools: [...yourTools, undoTool(z)]
+ */
+declare function undoTool(zod: any): ToolDef<{
+    state: Record<string, any>;
+}, {
+    restored: boolean;
+}>;
+/**
+ * Pre-built tool for phase transitions. Required for usePhase to work.
+ * Add it to your tools array:
+ *
+ *   tools: [...yourTools, phaseTool(z)]
+ *
+ * Optionally pass the list of valid phases for validation:
+ *   phaseTool(z, ["setup", "playing", "scoring", "finished"])
+ */
+declare function phaseTool(zod: any, validPhases?: readonly string[]): ToolDef<{
+    phase: string;
+}, {
+    phase: string;
+}>;
+/**
+ * Define a room configuration schema.
+ * Rooms spawned with this experience will be validated against this schema.
+ *
+ * Usage:
+ *   import { defineRoomConfig } from "@vibevibes/sdk";
+ *   import { z } from "zod";
+ *
+ *   const roomConfig = defineRoomConfig({
+ *     schema: z.object({
+ *       mode: z.enum(["combat", "explore", "dialogue"]),
+ *       difficulty: z.number().min(1).max(10).default(5),
+ *     }),
+ *     defaults: { mode: "explore", difficulty: 5 },
+ *     presets: {
+ *       "boss-fight": { mode: "combat", difficulty: 10 },
+ *       "peaceful":   { mode: "explore", difficulty: 1 },
+ *     },
+ *     description: "Configure the room's game mode and difficulty",
+ *   });
+ */
+declare function defineRoomConfig<TConfig extends Record<string, any>>(config: RoomConfigDef<TConfig>): RoomConfigDef<TConfig>;
+/**
+ * Define a continuous state stream for high-frequency human input.
+ * Streams bypass the full tool handler pipeline but still validate input
+ * and persist to shared state via a pure merge function.
+ *
+ * Usage:
+ *   import { defineStream } from "@vibevibes/sdk";
+ *   import { z } from "zod";
+ *
+ *   const brushStream = defineStream({
+ *     name: "brush.stroke",
+ *     description: "Continuous brush stroke data",
+ *     input_schema: z.object({
+ *       x: z.number(),
+ *       y: z.number(),
+ *       pressure: z.number().min(0).max(1),
+ *       color: z.string(),
+ *     }),
+ *     merge: (state, input, actorId) => ({
+ *       ...state,
+ *       strokes: [...(state.strokes || []), { ...input, actorId, ts: Date.now() }],
+ *     }),
+ *     rateLimit: 60, // max 60 inputs/sec/actor
+ *   });
+ */
+declare function defineStream<TInput>(config: {
+    name: string;
+    description?: string;
+    input_schema: z.ZodType<TInput>;
+    merge: (state: Record<string, any>, input: TInput, actorId: string) => Record<string, any>;
+    rateLimit?: number;
+}): StreamDef<TInput>;
+declare function defineExperience(module: ExperienceModule & {
+    /** Initial state for the experience. If stateSchema is provided and initialState is not,
+     *  defaults are extracted from the schema automatically. */
+    initialState?: Record<string, any>;
+    /** Agent slot configurations. */
+    agents?: Array<{
+        role: string;
+        systemPrompt: string;
+        allowedTools?: string[];
+        autoSpawn?: boolean;
+        maxInstances?: number;
+    }>;
+    /** Display name (convenience, copied to manifest.title if manifest.title is missing). */
+    name?: string;
+}): ExperienceModule & {
+    initialState?: Record<string, any>;
+};
+declare function validateExperience(module: ExperienceModule & {
+    initialState?: Record<string, any>;
+}): {
     valid: boolean;
     errors: string[];
+    warnings: string[];
 };
 
 /**
@@ -333,7 +554,7 @@ declare function validateExperience(module: ExperienceModule): {
  *
  * Hooks rely on React being available as a global (provided by the bundler runtime).
  */
-type CallToolFn = (name: string, input: any) => Promise<any>;
+type CallToolFn$3 = (name: string, input: any) => Promise<any>;
 type UseToolCallReturn = {
     call: (name: string, input: any) => Promise<any>;
     loading: boolean;
@@ -346,7 +567,7 @@ type UseToolCallReturn = {
  *   const { call, loading, error } = useToolCall(callTool);
  *   <button onClick={() => call('counter.increment', {})} disabled={loading}>
  */
-declare function useToolCall(callTool: CallToolFn): UseToolCallReturn;
+declare function useToolCall(callTool: CallToolFn$3): UseToolCallReturn;
 /**
  * Typed accessor for a specific key in shared state.
  *
@@ -366,7 +587,7 @@ type UseOptimisticToolReturn = {
  *   const { call, state, pending } = useOptimisticTool(callTool, sharedState);
  *   call('counter.increment', {}, { count: sharedState.count + 1 });
  */
-declare function useOptimisticTool(callTool: CallToolFn, sharedState: Record<string, any>): UseOptimisticToolReturn;
+declare function useOptimisticTool(callTool: CallToolFn$3, sharedState: Record<string, any>): UseOptimisticToolReturn;
 /**
  * Decouples render frequency from state sync frequency.
  * State updates are buffered and applied at most once per animation frame.
@@ -451,6 +672,117 @@ declare function useTypingIndicator(actorId: string, ephemeralState: Record<stri
     setTyping: (isTyping: boolean) => void;
     typingUsers: string[];
 };
+type UseUndoReturn = {
+    /** Undo the last state change. No-op if nothing to undo. */
+    undo: () => void;
+    /** Redo the last undone state change. No-op if nothing to redo. */
+    redo: () => void;
+    /** Whether undo is available. */
+    canUndo: boolean;
+    /** Whether redo is available. */
+    canRedo: boolean;
+    /** Number of states in the undo stack. */
+    undoCount: number;
+    /** Number of states in the redo stack. */
+    redoCount: number;
+};
+/**
+ * Undo/redo for shared state via tool calls.
+ *
+ * Tracks state snapshots as sharedState changes. Undo/redo restore
+ * previous/next snapshots by calling a tool (default: "_state.restore").
+ *
+ * The server needs a `_state.restore` tool registered (or pass a custom
+ * restoreTool name). If the tool doesn't exist, undo triggers callTool
+ * which will return an error — but it won't crash.
+ *
+ * Usage:
+ *   const { undo, redo, canUndo, canRedo } = useUndo(sharedState, callTool);
+ *   <button onClick={undo} disabled={!canUndo}>Undo</button>
+ *   <button onClick={redo} disabled={!canRedo}>Redo</button>
+ */
+declare function useUndo(sharedState: Record<string, any>, callTool: CallToolFn$3, opts?: {
+    maxHistory?: number;
+    restoreTool?: string;
+}): UseUndoReturn;
+/**
+ * Returns a debounced version of callTool. Calls are delayed by `delayMs`
+ * and collapsed — only the last call within the window fires.
+ *
+ * Perfect for search inputs, text fields, sliders.
+ *
+ * Usage:
+ *   const debouncedCall = useDebounce(callTool, 300);
+ *   <input onChange={(e) => debouncedCall('search.update', { query: e.target.value })} />
+ */
+declare function useDebounce(callTool: CallToolFn$3, delayMs?: number): CallToolFn$3;
+/**
+ * Returns a throttled version of callTool. At most one call fires per
+ * `intervalMs`. Trailing calls are queued and fire after the interval.
+ *
+ * Perfect for cursor positions, brush strokes, drag events.
+ *
+ * Usage:
+ *   const throttledCall = useThrottle(callTool, 50);
+ *   onMouseMove={(e) => throttledCall('cursor.move', { x: e.clientX, y: e.clientY })}
+ */
+declare function useThrottle(callTool: CallToolFn$3, intervalMs?: number): CallToolFn$3;
+type PhaseConfig<TPhase extends string = string> = {
+    /** Ordered list of phase names. */
+    phases: readonly TPhase[];
+    /** The state key that stores the current phase. Default: "phase". */
+    stateKey?: string;
+    /** Tool name for phase transitions. Default: "_phase.set". */
+    toolName?: string;
+};
+type UsePhaseReturn<TPhase extends string = string> = {
+    /** Current phase name. */
+    current: TPhase;
+    /** Index of current phase (0-based). */
+    index: number;
+    /** Whether current phase is the first. */
+    isFirst: boolean;
+    /** Whether current phase is the last. */
+    isLast: boolean;
+    /** Advance to the next phase. No-op if already last. */
+    next: () => void;
+    /** Go back to the previous phase. No-op if already first. */
+    prev: () => void;
+    /** Jump to a specific phase by name. */
+    goTo: (phase: TPhase) => void;
+    /** Check if the current phase matches. */
+    is: (phase: TPhase) => boolean;
+};
+/**
+ * Manages a linear phase/stage machine via shared state.
+ *
+ * Almost every experience has phases: setup → active → review,
+ * ideate → cluster → prioritize, listen → improvise → refine.
+ * This hook compresses that pattern into a one-liner.
+ *
+ * Usage:
+ *   const phase = usePhase(sharedState, callTool, {
+ *     phases: ["setup", "playing", "scoring", "finished"] as const,
+ *   });
+ *
+ *   if (phase.is("setup")) return <SetupScreen />;
+ *   if (phase.is("playing")) return <GameBoard />;
+ *
+ *   <button onClick={phase.next} disabled={phase.isLast}>Next Phase</button>
+ *
+ * Requires a tool to be registered (or use the built-in phaseTool):
+ *   tools: [...yourTools, phaseTool(z)]
+ */
+declare function usePhase<TPhase extends string>(sharedState: Record<string, any>, callTool: CallToolFn$3, config: PhaseConfig<TPhase>): UsePhaseReturn<TPhase>;
+/**
+ * Fetches and caches a binary blob from the server.
+ * Returns the ArrayBuffer when loaded, null while loading.
+ *
+ * Usage:
+ *   const pixels = useBlob(sharedState.canvasBlobId);
+ *   if (pixels) { // render pixels }
+ */
+declare function useBlob(blobKey: string | null | undefined, serverUrl?: string): ArrayBuffer | null;
 
 /**
  * Pre-built UI components for experiences.
@@ -508,6 +840,65 @@ type GridProps = {
     style?: Record<string, any>;
 };
 declare function Grid({ children, columns, gap, style }: GridProps): any;
+type SliderProps = {
+    value?: number;
+    onChange?: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    disabled?: boolean;
+    label?: string;
+    style?: Record<string, any>;
+};
+declare function Slider({ value, onChange, min, max, step, disabled, label, style }: SliderProps): any;
+type TextareaProps = {
+    value?: string;
+    onChange?: (value: string) => void;
+    placeholder?: string;
+    rows?: number;
+    disabled?: boolean;
+    style?: Record<string, any>;
+};
+declare function Textarea({ value, onChange, placeholder, rows, disabled, style }: TextareaProps): any;
+type ModalProps = {
+    children?: any;
+    open?: boolean;
+    onClose?: () => void;
+    title?: string;
+    style?: Record<string, any>;
+};
+declare function Modal({ children, open, onClose, title, style }: ModalProps): any;
+type ColorPickerProps = {
+    value?: string;
+    onChange?: (color: string) => void;
+    presets?: string[];
+    disabled?: boolean;
+    style?: Record<string, any>;
+};
+declare function ColorPicker({ value, onChange, presets, disabled, style }: ColorPickerProps): any;
+type DropdownProps = {
+    value?: string;
+    onChange?: (value: string) => void;
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+    placeholder?: string;
+    disabled?: boolean;
+    style?: Record<string, any>;
+};
+declare function Dropdown({ value, onChange, options, placeholder, disabled, style }: DropdownProps): any;
+type TabsProps = {
+    tabs: Array<{
+        id: string;
+        label: string;
+    }>;
+    activeTab?: string;
+    onTabChange?: (id: string) => void;
+    children?: any;
+    style?: Record<string, any>;
+};
+declare function Tabs({ tabs, activeTab, onTabChange, children, style }: TabsProps): any;
 
 /**
  * Multi-agent negotiation protocol.
@@ -516,12 +907,6 @@ declare function Grid({ children, columns, gap, style }: GridProps): any;
 
 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.
  *
@@ -619,4 +1004,873 @@ declare class InMemoryAdapter implements StorageAdapter {
     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 };
+/**
+ * Scene Graph Type Definitions
+ *
+ * The scene graph is a serializable JSON structure that lives in sharedState._scene.
+ * Both humans (via Canvas UI) and agents (via MCP tools) read and write this structure.
+ * The renderer reads it and produces SVG output.
+ *
+ * Every type here MUST be JSON-serializable (no functions, no class instances, no circular refs).
+ */
+type Vec2 = {
+    x: number;
+    y: number;
+};
+type Transform = {
+    x?: number;
+    y?: number;
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+    originX?: number;
+    originY?: number;
+};
+type GradientStop = {
+    offset: number;
+    color: string;
+};
+type LinearGradient = {
+    type: 'linear';
+    id: string;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    stops: GradientStop[];
+};
+type RadialGradient = {
+    type: 'radial';
+    id: string;
+    cx: number;
+    cy: number;
+    r: number;
+    fx?: number;
+    fy?: number;
+    stops: GradientStop[];
+};
+type Gradient = LinearGradient | RadialGradient;
+type FilterType = 'blur' | 'shadow' | 'glow' | 'brightness' | 'contrast' | 'saturate' | 'hue-rotate';
+type FilterDef = {
+    id: string;
+    type: FilterType;
+    params: Record<string, number | string>;
+};
+type Style = {
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+    strokeLinecap?: 'butt' | 'round' | 'square';
+    strokeLinejoin?: 'miter' | 'round' | 'bevel';
+    opacity?: number;
+    fillOpacity?: number;
+    strokeOpacity?: number;
+    filter?: string;
+    cursor?: string;
+    pointerEvents?: 'auto' | 'none';
+    visible?: boolean;
+};
+type TextStyle = Style & {
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: number | string;
+    textAnchor?: 'start' | 'middle' | 'end';
+    dominantBaseline?: 'auto' | 'middle' | 'hanging' | 'text-top';
+    letterSpacing?: number;
+};
+type SceneNodeBase = {
+    id: string;
+    name?: string;
+    transform?: Transform;
+    style?: Style;
+    interactive?: boolean;
+    data?: Record<string, any>;
+    tween?: TweenDef;
+};
+type RectNode = SceneNodeBase & {
+    type: 'rect';
+    width: number;
+    height: number;
+    rx?: number;
+    ry?: number;
+};
+type CircleNode = SceneNodeBase & {
+    type: 'circle';
+    radius: number;
+};
+type EllipseNode = SceneNodeBase & {
+    type: 'ellipse';
+    rx: number;
+    ry: number;
+};
+type LineNode = SceneNodeBase & {
+    type: 'line';
+    x2: number;
+    y2: number;
+};
+type PolylineNode = SceneNodeBase & {
+    type: 'polyline';
+    points: Vec2[];
+};
+type PolygonNode = SceneNodeBase & {
+    type: 'polygon';
+    points: Vec2[];
+};
+type PathNode = SceneNodeBase & {
+    type: 'path';
+    d: string;
+};
+type TextNode = SceneNodeBase & {
+    type: 'text';
+    text: string;
+    style?: TextStyle;
+};
+type ImageNode = SceneNodeBase & {
+    type: 'image';
+    href: string;
+    width: number;
+    height: number;
+    preserveAspectRatio?: string;
+};
+type GroupNode = SceneNodeBase & {
+    type: 'group';
+    children: SceneNode[];
+    clipPath?: string;
+};
+type SpriteAnimation = {
+    frames: number[];
+    fps: number;
+    loop?: boolean;
+    playing?: boolean;
+};
+type SpriteNode = SceneNodeBase & {
+    type: 'sprite';
+    href: string;
+    frameWidth: number;
+    frameHeight: number;
+    frame: number;
+    columns?: number;
+    animation?: SpriteAnimation;
+};
+type TilemapNode = SceneNodeBase & {
+    type: 'tilemap';
+    href: string;
+    tileWidth: number;
+    tileHeight: number;
+    columns: number;
+    data: number[][];
+    width: number;
+    height: number;
+};
+type ParticleEmitter = {
+    x: number;
+    y: number;
+    rate: number;
+    lifetime: number;
+    speed: {
+        min: number;
+        max: number;
+    };
+    direction: {
+        min: number;
+        max: number;
+    };
+    gravity?: number;
+    color?: string | string[];
+    size?: {
+        min: number;
+        max: number;
+    };
+    fadeOut?: boolean;
+    shape?: 'circle' | 'square';
+};
+type Particle = {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    age: number;
+    lifetime: number;
+    size: number;
+    color: string;
+};
+type ParticlesNode = SceneNodeBase & {
+    type: 'particles';
+    emitters: ParticleEmitter[];
+    maxParticles?: number;
+    _particles?: Particle[];
+};
+type SceneNode = RectNode | CircleNode | EllipseNode | LineNode | PolylineNode | PolygonNode | PathNode | TextNode | ImageNode | GroupNode | SpriteNode | TilemapNode | ParticlesNode;
+type SceneNodeType = SceneNode['type'];
+type EasingType = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'ease-in-quad' | 'ease-out-quad' | 'ease-in-out-quad' | 'ease-in-cubic' | 'ease-out-cubic' | 'ease-in-out-cubic' | 'ease-in-elastic' | 'ease-out-elastic' | 'ease-in-bounce' | 'ease-out-bounce';
+type TweenDef = {
+    property: string;
+    from: number;
+    to: number;
+    duration: number;
+    easing?: EasingType;
+    delay?: number;
+    repeat?: number;
+    yoyo?: boolean;
+    startedAt?: number;
+};
+type Camera = {
+    x: number;
+    y: number;
+    zoom: number;
+    rotation?: number;
+    bounds?: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+};
+type SceneGraph = {
+    _sceneVersion?: number;
+    root: GroupNode;
+    camera?: Camera;
+    background?: string;
+    gradients?: Gradient[];
+    filters?: FilterDef[];
+    width?: number;
+    height?: number;
+};
+type SceneRendererProps = {
+    scene: SceneGraph;
+    width?: number;
+    height?: number;
+    className?: string;
+    style?: Record<string, any>;
+    onNodeClick?: (nodeId: string, event: {
+        x: number;
+        y: number;
+    }) => void;
+    onNodeHover?: (nodeId: string | null) => void;
+    onNodeDragStart?: (nodeId: string, pos: Vec2) => void;
+    onNodeDrag?: (nodeId: string, pos: Vec2) => void;
+    onNodeDragEnd?: (nodeId: string, pos: Vec2) => void;
+    onViewportClick?: (pos: Vec2) => void;
+    onViewportPan?: (delta: Vec2) => void;
+    onViewportZoom?: (zoom: number, center: Vec2) => void;
+    selectedNodeIds?: string[];
+    debug?: boolean;
+};
+type SceneHitEvent = {
+    nodeId: string;
+    x: number;
+    y: number;
+    screenX: number;
+    screenY: number;
+};
+
+/**
+ * Unified SceneRenderer component.
+ * Defaults to PixiJS (WebGL) renderer. Falls back to SVG if pixi.js is not available.
+ */
+
+/**
+ * Auto-selecting SceneRenderer.
+ * Uses PixiJS (WebGL) when available, falls back to SVG.
+ * Experience authors can also import PixiSceneRenderer or SvgSceneRenderer directly.
+ */
+declare function SceneRenderer(props: SceneRendererProps): any;
+
+/**
+ * SVG Scene Renderer.
+ *
+ * Takes a SceneGraph and renders it as SVG using React createElement calls.
+ * Uses the same getReact()/h() pattern as components.ts — no JSX, no import.
+ */
+
+declare function SvgSceneRenderer(props: SceneRendererProps): any;
+
+/**
+ * PixiJS WebGL Scene Renderer.
+ *
+ * Takes a SceneGraph and renders it to a WebGL canvas using PixiJS v8.
+ * Uses retained-mode rendering: on scene change, diffs and updates Pixi display objects
+ * rather than recreating the tree. Implements the same SceneRendererProps interface
+ * as SvgSceneRenderer.
+ *
+ * PixiJS is an optional dependency. If not available, the component renders a fallback
+ * message instructing the user to install pixi.js.
+ *
+ * Uses the getReact()/h() pattern — no JSX, no import React.
+ */
+
+declare function PixiSceneRenderer(props: SceneRendererProps): any;
+
+/**
+ * Pre-built scene manipulation tools.
+ *
+ * Factory function createSceneTools(namespace, z) returns ToolDef[] ready to
+ * spread into defineExperience({ tools: [...sceneTools(z)] }).
+ *
+ * Follows the same pattern as createAgentProtocolTools in agent-protocol.ts.
+ *
+ * 5 tools total — minimal surface area, maximum expressiveness:
+ *   scene.add     — add nodes
+ *   scene.update  — update any node (props, transform, style, tween)
+ *   scene.remove  — remove nodes
+ *   scene.set     — scene-level settings (camera, background, gradients, clear)
+ *   scene.batch   — multiple operations in one state update
+ */
+
+declare function createSceneTools(namespace: string, z: any): ToolDef[];
+
+/**
+ * Scene-specific React hooks.
+ *
+ * These hooks handle client-side concerns: interaction tracking, drag,
+ * selection, viewport pan/zoom, tween interpolation, and particle simulation.
+ *
+ * Uses the same lazy React access pattern as sdk/src/hooks.ts.
+ */
+
+type CallToolFn$2 = (name: string, input: any) => Promise<any>;
+type SceneInteractionEvent = {
+    type: 'click' | 'hover' | 'hoverEnd';
+    nodeId: string;
+    x: number;
+    y: number;
+};
+type UseSceneInteractionReturn = {
+    lastEvent: SceneInteractionEvent | null;
+    hoveredNodeId: string | null;
+    onNodeClick: (nodeId: string, event: {
+        x: number;
+        y: number;
+    }) => void;
+    onNodeHover: (nodeId: string | null) => void;
+};
+/**
+ * Track click/hover events on scene nodes.
+ * Returns callbacks to wire into SceneRenderer props.
+ */
+declare function useSceneInteraction(): UseSceneInteractionReturn;
+type UseSceneDragReturn = {
+    dragging: string | null;
+    dragOffset: Vec2 | null;
+    onNodeDragStart: (nodeId: string, pos: Vec2) => void;
+    onNodeDrag: (nodeId: string, pos: Vec2) => void;
+    onNodeDragEnd: (nodeId: string, pos: Vec2) => void;
+};
+/**
+ * Drag scene nodes. On drag end, commits position via scene.transform tool call.
+ */
+declare function useSceneDrag(callTool: CallToolFn$2, toolNamespace?: string): UseSceneDragReturn;
+type UseSceneSelectionReturn = {
+    selectedIds: string[];
+    select: (nodeId: string) => void;
+    deselect: (nodeId: string) => void;
+    toggle: (nodeId: string) => void;
+    clear: () => void;
+    isSelected: (nodeId: string) => boolean;
+};
+/**
+ * Local multi-select state for scene nodes.
+ */
+declare function useSceneSelection(): UseSceneSelectionReturn;
+type UseSceneViewportReturn = {
+    camera: Camera;
+    onViewportPan: (delta: Vec2) => void;
+    onViewportZoom: (newZoom: number, center: Vec2) => void;
+};
+/**
+ * Pan/zoom the scene camera. Debounces tool calls to persist camera changes.
+ */
+declare function useSceneViewport(callTool: CallToolFn$2, scene: SceneGraph, toolNamespace?: string): UseSceneViewportReturn;
+/**
+ * Client-side tween interpolation at 60fps.
+ * Walks the scene graph, finds nodes with active tweens, interpolates
+ * their values, and returns a new SceneGraph with interpolated properties.
+ *
+ * Does NOT modify shared state — purely display-side.
+ */
+declare function useSceneTweens(scene: SceneGraph): SceneGraph;
+/**
+ * Client-side particle simulation at 60fps.
+ * Finds ParticlesNode nodes, spawns and ticks particles, returns scene
+ * with updated _particles arrays.
+ *
+ * Does NOT modify shared state — purely display-side.
+ */
+declare function useParticleTick(scene: SceneGraph): SceneGraph;
+
+/**
+ * Scene graph utility functions.
+ *
+ * These are pure functions that operate on the SceneGraph type.
+ * Used by tool handlers, experience authors, and hooks.
+ */
+
+/**
+ * Create an empty scene graph with sensible defaults.
+ */
+declare function createScene(opts?: {
+    width?: number;
+    height?: number;
+    background?: string;
+}): SceneGraph;
+/**
+ * Create a new scene node with an auto-generated ID.
+ *
+ * Usage:
+ *   createNode('rect', { width: 100, height: 50, style: { fill: '#f00' } })
+ *   createNode('circle', { radius: 30 })
+ *   createNode('text', { text: 'Hello' })
+ */
+declare function createNode(type: SceneNodeType, props: Omit<any, 'id' | 'type'> & {
+    id?: string;
+}): SceneNode;
+/**
+ * Find a node by ID anywhere in the scene graph.
+ * Returns null if not found.
+ */
+declare function nodeById(scene: SceneGraph, id: string): SceneNode | null;
+/**
+ * Find all nodes matching a predicate.
+ */
+declare function findNodes(scene: SceneGraph, predicate: (node: SceneNode) => boolean): SceneNode[];
+/**
+ * Walk all nodes in the scene graph, calling the visitor for each.
+ */
+declare function walkNodes(node: SceneNode, visitor: (node: SceneNode) => void): void;
+/**
+ * Get a flat list of all node IDs in the scene.
+ */
+declare function allNodeIds(scene: SceneGraph): string[];
+/**
+ * Count total nodes in the scene graph.
+ */
+declare function nodeCount(scene: SceneGraph): number;
+/**
+ * Deep clone a scene graph (JSON round-trip).
+ */
+declare function cloneScene(scene: SceneGraph): SceneGraph;
+/**
+ * Remove a node from the scene graph by ID. Returns true if found and removed.
+ */
+declare function removeNodeById(root: GroupNode, id: string): boolean;
+/**
+ * Find a node's parent group. Returns null if node is the root or not found.
+ */
+declare function findParent(root: GroupNode, nodeId: string): GroupNode | null;
+/**
+ * Return all pre-built scene tools ready to spread into defineExperience.
+ *
+ * Usage:
+ *   import { sceneTools } from "@vibevibes/sdk";
+ *   export default defineExperience({
+ *     tools: [...myTools, ...sceneTools(z)],
+ *   });
+ */
+declare function sceneTools(z: any, namespace?: string): ToolDef[];
+
+/**
+ * Fluent API for building SVG path `d` strings.
+ *
+ * Agents can also construct d strings directly, but this gives experience
+ * authors a programmatic API for generating complex paths in tool handlers
+ * or Canvas components.
+ *
+ * Usage:
+ *   const d = PathBuilder.from()
+ *     .moveTo(0, 0)
+ *     .lineTo(100, 0)
+ *     .lineTo(100, 100)
+ *     .close()
+ *     .build();
+ *   // "M 0 0 L 100 0 L 100 100 Z"
+ */
+declare class PathBuilder {
+    private commands;
+    moveTo(x: number, y: number): this;
+    lineTo(x: number, y: number): this;
+    horizontalTo(x: number): this;
+    verticalTo(y: number): this;
+    quadTo(cx: number, cy: number, x: number, y: number): this;
+    cubicTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): this;
+    arcTo(rx: number, ry: number, rotation: number, largeArc: boolean, sweep: boolean, x: number, y: number): this;
+    close(): this;
+    rect(x: number, y: number, w: number, h: number): this;
+    roundedRect(x: number, y: number, w: number, h: number, rx: number, ry?: number): this;
+    circle(cx: number, cy: number, r: number): this;
+    ellipse(cx: number, cy: number, rx: number, ry: number): this;
+    star(cx: number, cy: number, points: number, outerR: number, innerR: number): this;
+    arrow(x1: number, y1: number, x2: number, y2: number, headSize?: number): this;
+    build(): string;
+    static from(): PathBuilder;
+}
+
+/**
+ * Easing functions and tween interpolation logic.
+ *
+ * All easing functions take t (0-1) and return a value (0-1).
+ * Used by the renderer for client-side animation interpolation.
+ */
+
+type EasingFn = (t: number) => number;
+declare const easingFunctions: Record<EasingType, EasingFn>;
+/**
+ * Get the value at a given dot-path on an object.
+ * e.g. getPath({ transform: { x: 10 } }, 'transform.x') => 10
+ */
+declare function getPath(obj: any, path: string): any;
+/**
+ * Set a value at a given dot-path on an object (immutable - returns new object).
+ * e.g. setPath({ transform: { x: 10 } }, 'transform.x', 20) => { transform: { x: 20 } }
+ */
+declare function setPath(obj: any, path: string, value: any): any;
+/**
+ * Compute the interpolated value for a tween at a given timestamp.
+ * Returns null if the tween hasn't started yet or has completed (non-repeating).
+ */
+declare function interpolateTween(tween: {
+    from: number;
+    to: number;
+    duration: number;
+    easing?: EasingType;
+    delay?: number;
+    repeat?: number;
+    yoyo?: boolean;
+    startedAt?: number;
+}, now: number): number | null;
+
+/**
+ * Particle system tick logic.
+ *
+ * Pure functions for simulating particles. Used by useParticleTick hook
+ * for client-side particle simulation at 60fps.
+ */
+
+/**
+ * Spawn new particles from an emitter based on elapsed time.
+ */
+declare function spawnParticles(emitter: ParticleEmitter, dt: number): Particle[];
+/**
+ * Tick all particles: update positions, apply gravity, age.
+ * Returns the surviving particles (age < lifetime).
+ */
+declare function tickParticles(particles: Particle[], emitters: ParticleEmitter[], dt: number): Particle[];
+/**
+ * Full particle system tick for a ParticlesNode.
+ * Spawns new particles, ticks existing ones, caps at maxParticles.
+ */
+declare function tickParticleNode(node: ParticlesNode, dt: number): Particle[];
+
+/**
+ * Zod schemas for scene graph validation.
+ *
+ * These schemas are used by scene tools to validate agent input.
+ * They accept `z` as a parameter (same pattern as agent-protocol.ts)
+ * so we don't import zod directly — it's provided by the experience.
+ */
+declare function createSceneSchemas(z: any): {
+    vec2: any;
+    transform: any;
+    style: any;
+    textStyle: any;
+    gradientStop: any;
+    linearGradient: any;
+    radialGradient: any;
+    gradient: any;
+    particleEmitter: any;
+    spriteAnimation: any;
+    nodeSchema: any;
+};
+
+/**
+ * Rule Engine for declarative client-side simulation.
+ *
+ * The agent writes rules as JSON via tool calls. The client evaluates them
+ * at ~10 ticks/sec via useRuleTick. Rules are a delegation mechanism — the
+ * agent teaches the client how to run parts of the simulation at tick speed
+ * so the agent can focus on high-level world design and evolution.
+ *
+ * Exports:
+ *   Types:     Rule, WorldMeta, RuleStats
+ *   Hook:      useRuleTick(scene, rules, worldMeta, callTool)
+ *   Matching:  nodeMatchesSelector(node, selector)
+ *   Tools:     createRuleTools(z) → ToolDef[]
+ *   Shorthand: ruleTools(z) → ToolDef[]
+ */
+
+type Rule = {
+    id: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+    trigger: "tick" | "interaction" | "proximity" | "timer";
+    condition: {
+        selector: string;
+        proximity?: {
+            target: string;
+            distance: number;
+        };
+        state?: Record<string, any>;
+        cooldownMs?: number;
+        probability?: number;
+    };
+    effect: {
+        type: "transform" | "style" | "data" | "counter" | "spawn" | "remove" | "tween";
+        dx?: number;
+        dy?: number;
+        dRotation?: number;
+        styleUpdates?: Record<string, any>;
+        dataUpdates?: Record<string, any>;
+        field?: string;
+        delta?: number;
+        spawnNode?: any;
+        spawnOffset?: {
+            x: number;
+            y: number;
+        };
+        tween?: {
+            property: string;
+            from: number;
+            to: number;
+            duration: number;
+            easing?: string;
+            repeat?: number;
+            yoyo?: boolean;
+        };
+        variance?: number;
+        probability?: number;
+    };
+};
+type WorldMeta = {
+    name: string;
+    description: string;
+    paused: boolean;
+    tickSpeed: number;
+};
+type RuleStats = {
+    rulesEvaluated: number;
+    rulesFired: number;
+    nodesAffected: number;
+    ticksElapsed: number;
+};
+/**
+ * Check if a scene node matches a selector string.
+ *
+ * Selector syntax:
+ *   "*"               — any node with data.entityType
+ *   "entityType:fish" — data.entityType === "fish"
+ *   "tag:swimming"    — data.tags includes "swimming"
+ *   "name:hero"       — node.name === "hero"
+ *   "type:circle"     — node.type === "circle"
+ */
+declare function nodeMatchesSelector(node: any, selector: string): boolean;
+type CallToolFn$1 = (name: string, input: any) => Promise<any>;
+/**
+ * Client-side tick engine. Evaluates enabled tick rules against the scene
+ * graph at ~tickSpeed ms intervals using requestAnimationFrame.
+ *
+ * Transform/style/data/counter/tween effects are applied locally for instant
+ * visual feedback. Spawn/remove effects are batched and flushed through
+ * scene.batch tool calls (debounced 300ms) so they persist in shared state.
+ */
+declare function useRuleTick(scene: SceneGraph, rules: Rule[], worldMeta: WorldMeta, callTool: CallToolFn$1): {
+    simulatedScene: SceneGraph;
+    stats: RuleStats;
+};
+/**
+ * Create rule management tools for an experience.
+ *
+ * Returns 3 tools:
+ *   _rules.set    — create or update a rule
+ *   _rules.remove — delete a rule by ID
+ *   _rules.world  — set world metadata (name, description, paused, tickSpeed)
+ */
+declare function createRuleTools(z: any): ToolDef[];
+/**
+ * Return all pre-built rule tools ready to spread into defineExperience.
+ *
+ * Usage:
+ *   import { ruleTools } from "@vibevibes/sdk";
+ *   export default defineExperience({
+ *     tools: [...sceneTools(z), ...ruleTools(z)],
+ *   });
+ */
+declare function ruleTools(z: any): ToolDef[];
+
+/**
+ * Standardized chat for experiences.
+ *
+ * Provides a collapsible ChatPanel component, a useChat hook,
+ * and tool factories for agent participation.
+ *
+ * Messages are stored in shared state under `_chat` so agents
+ * see them via the stop hook's /agent-context endpoint.
+ *
+ * Usage:
+ *   import { ChatPanel, createChatTools } from "@vibevibes/sdk";
+ *
+ *   const tools = [...myTools, ...createChatTools(z)];
+ *
+ *   function Canvas(props) {
+ *     return <div>
+ *       <ChatPanel {...props} />
+ *     </div>;
+ *   }
+ */
+
+type ChatMessage = {
+    id: string;
+    actorId: string;
+    message: string;
+    replyTo?: string;
+    ts: number;
+};
+type CallToolFn = (name: string, input: any) => Promise<any>;
+type UseChatReturn = {
+    messages: ChatMessage[];
+    sendMessage: (message: string, replyTo?: string) => Promise<void>;
+    clearChat: () => Promise<void>;
+    setTyping: (isTyping: boolean) => void;
+    typingUsers: string[];
+};
+declare function createChatTools(z: any): ToolDef[];
+declare function useChat(sharedState: Record<string, any>, callTool: CallToolFn, actorId: string, ephemeralState: Record<string, Record<string, any>>, setEphemeral: (data: Record<string, any>) => void): UseChatReturn;
+type ChatPanelProps = {
+    sharedState: Record<string, any>;
+    callTool: (name: string, input: any) => Promise<any>;
+    actorId: string;
+    ephemeralState: Record<string, Record<string, any>>;
+    setEphemeral: (data: Record<string, any>) => void;
+    participants: string[];
+    style?: Record<string, any>;
+    /** When true, renders inline (flex column, 100% height) instead of fixed-position floating panel. No toggle button. */
+    embedded?: boolean;
+};
+declare function ChatPanel({ sharedState, callTool, actorId, ephemeralState, setEphemeral, style, embedded, }: ChatPanelProps): any;
+
+/**
+ * Standardized bug reporting for experiences.
+ *
+ * Provides a collapsible ReportBug button that captures a screenshot,
+ * shows a form for an optional description, and submits the report
+ * as a tool call stored in shared state.
+ *
+ * Bug reports are stored in shared state under `_bugReports`,
+ * so agents see them via the stop hook's /agent-context endpoint.
+ *
+ * Usage:
+ *   import { ReportBug, createBugReportTools } from "@vibevibes/sdk";
+ *
+ *   const tools = [...myTools, ...createBugReportTools(z)];
+ *
+ *   function Canvas(props) {
+ *     return <div>
+ *       <ReportBug callTool={props.callTool} actorId={props.actorId} />
+ *     </div>;
+ *   }
+ */
+
+type BugReport = {
+    id: string;
+    actorId: string;
+    description: string;
+    screenshot?: string;
+    metadata?: Record<string, any>;
+    ts: number;
+    status: 'open' | 'resolved';
+};
+declare function createBugReportTools(z: any): ToolDef[];
+type ReportBugProps = {
+    callTool: (name: string, input: any) => Promise<any>;
+    actorId: string;
+    style?: Record<string, any>;
+};
+declare function ReportBug({ callTool, actorId, style }: ReportBugProps): any;
+
+/**
+ * Inter-Experience Composability
+ *
+ * Level 1: importTools — Import tools from another experience's npm package
+ * Level 2: EmbeddedExperience — Embed another experience's Canvas with scoped state
+ */
+
+/**
+ * Import tools from another experience module.
+ *
+ * Usage:
+ *   import chatExp from "@vibevibes/chat";
+ *   const chatTools = importTools(chatExp, ["chat.send", "chat.clear"]);
+ *   export default defineExperience({ tools: [...myTools, ...chatTools], ... });
+ *
+ * Or import all tools:
+ *   const allChatTools = importTools(chatExp, "*");
+ *
+ * Optional prefix to namespace imported tools:
+ *   const chatTools = importTools(chatExp, "*", "chat");
+ *   // "send" becomes "chat.send"
+ */
+declare function importTools(experienceModule: {
+    tools: ToolDef[];
+}, toolNames: string[] | '*', prefix?: string): ToolDef[];
+/**
+ * Props for the EmbeddedExperience component.
+ */
+type EmbeddedExperienceProps = {
+    /** The child experience module to embed. */
+    experience: {
+        Canvas: React.FC<CanvasProps>;
+        tools: ToolDef[];
+    };
+    /** Key in parent state where child experience state lives. */
+    stateKey: string;
+    /** Parent's shared state. */
+    sharedState: Record<string, any>;
+    /** Parent's callTool function. */
+    callTool: (name: string, input: any) => Promise<any>;
+    /** Parent's room ID. */
+    roomId: string;
+    /** Parent's actor ID. */
+    actorId: string;
+    /** Parent's participants. */
+    participants: string[];
+    /** Parent's ephemeral state. */
+    ephemeralState: Record<string, Record<string, any>>;
+    /** Parent's setEphemeral. */
+    setEphemeral: (data: Record<string, any>) => void;
+    /** Parent's room config. */
+    roomConfig?: Record<string, any>;
+    /** Container style. */
+    style?: Record<string, any>;
+    /** Container className. */
+    className?: string;
+};
+/**
+ * Embeds another experience's Canvas as a sub-component with scoped state.
+ *
+ * The child experience reads/writes state under `sharedState[stateKey]` instead
+ * of the root state. Tool calls from the child are namespaced and scoped.
+ *
+ * Usage:
+ *   import chatExp from "@vibevibes/chat";
+ *
+ *   function Canvas(props) {
+ *     return h('div', {},
+ *       h(MyGameUI, props),
+ *       h(EmbeddedExperience, {
+ *         experience: chatExp,
+ *         stateKey: "_chat",
+ *         sharedState: props.sharedState,
+ *         callTool: props.callTool,
+ *         roomId: props.roomId,
+ *         actorId: props.actorId,
+ *         participants: props.participants,
+ *         ephemeralState: props.ephemeralState,
+ *         setEphemeral: props.setEphemeral,
+ *         style: { position: 'absolute', bottom: 0, right: 0, width: 300, height: 400 },
+ *       }),
+ *     );
+ *   }
+ */
+declare function EmbeddedExperience(props: EmbeddedExperienceProps): any;
+
+export { type AgentContext, type AgentMessage, type AgentSlot, Badge, type BugReport, Button, type Camera, type CanvasProps, Card, type ChatMessage, ChatPanel, type CircleNode, ColorPicker, Dropdown, type EasingType, type EllipseNode, EmbeddedExperience, type EmbeddedExperienceProps, type EphemeralActionDef, type ExpectChain, type ExperienceImport, type ExperienceListing, type ExperienceManifest, type ExperienceModule, type ExperienceRegistry, type FilterDef, type FilterType, type FollowState, type Gradient, type GradientStop, Grid, type GroupNode, type ImageNode, InMemoryAdapter, Input, type JsonPatchOp, type LineNode, type LinearGradient, type MigrationResult, Modal, type NetcodeMode, type ParsedParticipant, type Particle, type ParticleEmitter, type ParticlesNode, PathBuilder, type PathNode, type PerfMetrics, type PhaseConfig, PixiSceneRenderer, type PolygonNode, type PolylineNode, type RadialGradient, type RectNode, type RegistryEntry, ReportBug, type RoomConfigDef, type RoomLink, type RoomState, type Rule, type RuleStats, type SceneGraph, type SceneHitEvent, type SceneInteractionEvent, type SceneNode, type SceneNodeBase, type SceneNodeType, SceneRenderer, type SceneRendererProps, Slider, type SpawnRoomOpts, type SpawnRoomResult, type SpriteAnimation, type SpriteNode, Stack, type StateMigration, type StorageAdapter, type StorageToolEvent, type StreamDef, type Style, SvgSceneRenderer, Tabs, type TestDef, type TestHelpers, type TextNode, type TextStyle, Textarea, type TilemapNode, type ToolCtx, type ToolDef, type ToolEvent, type ToolRisk, type Transform, type TweenDef, type UseChatReturn, type UseFollowReturn, type UseOptimisticToolReturn, type UsePhaseReturn, type UseSceneDragReturn, type UseSceneInteractionReturn, type UseSceneSelectionReturn, type UseSceneViewportReturn, type UseToolCallReturn, type UseUndoReturn, type Vec2, type WebhookEventType, type WorldMeta, allNodeIds, cloneScene, compareSemver, createAgentProtocolTools, createBugReportTools, createChatTools, createNode, createRuleTools, createScene, createSceneSchemas, createSceneTools, defineEphemeralAction, defineExperience, defineRoomConfig, defineStream, defineTest, defineTool, easingFunctions, findNodes, findParent, getPath, getStateVersion, importTools, interpolateTween, migrateState, nodeById, nodeCount, nodeMatchesSelector, phaseTool, quickTool, removeNodeById, ruleTools, sceneTools, setPath, spawnParticles, tickParticleNode, tickParticles, undoTool, useAnimationFrame, useBlob, useChat, useDebounce, useFollow, useOptimisticTool, useParticipants, useParticleTick, usePhase, useRuleTick, useSceneDrag, useSceneInteraction, useSceneSelection, useSceneTweens, useSceneViewport, useSharedState, useThrottle, useToolCall, useTypingIndicator, useUndo, validateExperience, walkNodes };