@shaykec/bridge

Communication hub for Socrates -- HTTP server with WebSocket, SSE, and REST endpoints. Routes visual commands from the Claude Code plugin to browser clients (canvas app and Chrome extension) and user events back.

npm install @shaykec/bridge

Architecture

Plugin (Claude Code)
    |  POST /api/visual
    v
Bridge Server (:3456)
    |
    +---> WebSocket /ws         (Tier 1: Extension + Canvas)
    +---> SSE /sse              (Tier 2: Canvas only)
    +---> REST /api/event       (Tier 2: Canvas user events)
    +---> Static files /        (Serves canvas app)

Endpoints

| Endpoint | Method | Purpose | Tier | |----------|--------|---------|------| | /ws | WebSocket | Bidirectional connection for extension + canvas | 1 | | /sse | GET (SSE) | Server-push event stream for canvas | 2 | | /api/event | POST | Canvas sends user events back | 2 | | /api/visual | POST | Plugin pushes visual commands | All | | /api/tier | GET | Query current connection tier | All | | /api/capture | POST | Web captures from extension | 1 | | /api/progress | GET | Current progress data | 2, 3 | | /api/events | GET | Poll for pending browser events | 2 | | /health | GET | Health check | All |

Key Files

• src/server.js -- HTTP + WebSocket server (Node.js http + ws)
• src/protocol.js -- Tier negotiation logic
• src/router.js -- Event routing between clients
• src/templates.js -- HTML template engine for visual types

Templates

Located in templates/. Pre-built HTML for each visual type:

• dashboard.html -- Progress dashboard
• diagram-mermaid.html, diagram-flow.html, diagram-architecture.html -- Diagrams
• quiz-drag-order.html, quiz-matching.html, quiz-fill-blank.html, quiz-timed-choice.html -- Quizzes
• code-playground.html -- Monaco editor with sandboxed execution
• celebrate.html -- Confetti and level-up animations

Dependencies

• ws -- WebSocket server
• @shaykec/shared -- Protocol and constants

Usage

# Start directly
node packages/bridge/src/server.js

# Or via CLI
socrates serve --port 3456

See the root README for full documentation.