@prototyperco/bridge

Yjs-powered Live Canvas server for real-time AI-to-browser design sessions. Provides a REST API for session management and spec operations, with a Hocuspocus WebSocket layer for live CRDT sync.

Quick Start

npm install @prototyperco/bridge

# Run as standalone server
npx prototyper-bridge         # default port 4321
npx prototyper-bridge 8080    # custom port

Programmatic Usage

import { BridgeServer } from "@prototyperco/bridge";

const server = new BridgeServer({ port: 4321 });
const port = await server.start();
console.log(`Bridge running on port ${port}`);

// later
server.stop();

API Endpoints

| Method | Path | Description | | -------- | ---------------------------- | ---------------------- | | GET | /health | Health check | | POST | /api/sessions | Create a new session | | GET | /api/sessions | List all sessions | | GET | /api/sessions/:id | Get session metadata | | GET | /api/sessions/:id/state | Get full session state | | POST | /api/sessions/:id/ops | Apply spec operations | | POST | /api/sessions/:id/presence | Update agent presence | | DELETE | /api/sessions/:id | Close/delete a session | | WS | /ws | Yjs WebSocket sync |

Architecture

The Bridge server runs a single node:http server that handles REST requests and upgrades WebSocket connections to a Hocuspocus Yjs backend. Design specs are stored as Yjs documents, enabling conflict-free real-time collaboration between AI agents and browser previews. Sessions are persisted to ~/.prototyper-sessions by default.

Exports

• @prototyperco/bridge -- BridgeServer, Yjs utilities, persistence helpers
• @prototyperco/bridge/types -- Type-only export (Spec, UIElement, ThemeParams, SpecOp, etc.)

License

MIT