# @shaykec/bridge

[![npm version](https://img.shields.io/npm/v/@shaykec/bridge)](https://www.npmjs.com/package/@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.

```bash
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

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

# Or via CLI
socrates serve --port 3456
```

See the [root README](../../README.md) for full documentation.