@shaykec/bridge 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @shaykec/bridge
+
+Communication hub for ClaudeTeach -- 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.
+
+## 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
+claude-teach serve --port 3456
+```
+
+See the [root README](../../README.md) for full documentation.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@shaykec/bridge",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Communication hub — HTTP + WebSocket + SSE server with template engine",
+  "main": "src/server.js",
+  "exports": {
+    ".": "./src/server.js",
+    "./src/server.js": "./src/server.js",
+    "./protocol": "./src/protocol.js",
+    "./router": "./src/router.js",
+    "./templates": "./src/templates.js"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "vitest run --config ../../vitest.config.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.16.0",
+    "@shaykec/shared": "0.1.0"
+  }
+}

package/src/protocol.js

@@ -0,0 +1,303 @@
+/**
+ * Tier negotiation logic for ClaudeTeach bridge server.
+ * Tracks connected clients and auto-detects the current tier.
+ */
+
+import {
+  TIER_FULL,
+  TIER_CANVAS,
+  TIER_TERMINAL,
+  TIER_LABELS,
+  CLIENT_EXTENSION,
+  CLIENT_CANVAS,
+  HEARTBEAT_INTERVAL_MS,
+} from '@shaykec/shared';
+
+import {
+  PROTOCOL_VERSION,
+  createEnvelope,
+  MSG_SYS_TIER_CHANGE,
+  MSG_SYS_HEARTBEAT,
+} from '@shaykec/shared';
+
+/**
+ * Client connection tracker and tier negotiation.
+ */
+export class TierManager {
+  constructor() {
+    /** @type {Map<string, { ws: object, clientType: string, connectedAt: number }>} */
+    this.wsClients = new Map();
+
+    /** @type {Map<string, { res: object, clientType: string, connectedAt: number }>} */
+    this.sseClients = new Map();
+
+    /** Current detected tier */
+    this.currentTier = TIER_TERMINAL;
+
+    /** Tier change listeners */
+    this._listeners = [];
+
+    /** Heartbeat interval handle */
+    this._heartbeatInterval = null;
+  }
+
+  /**
+   * Start heartbeat broadcasting.
+   */
+  startHeartbeat() {
+    this._heartbeatInterval = setInterval(() => {
+      this.broadcastHeartbeat();
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  /**
+   * Stop heartbeat broadcasting.
+   */
+  stopHeartbeat() {
+    if (this._heartbeatInterval) {
+      clearInterval(this._heartbeatInterval);
+      this._heartbeatInterval = null;
+    }
+  }
+
+  /**
+   * Register a WebSocket client.
+   * @param {string} id - Unique client ID
+   * @param {object} ws - WebSocket connection
+   * @param {string} clientType - 'extension' or 'canvas'
+   */
+  addWsClient(id, ws, clientType) {
+    this.wsClients.set(id, {
+      ws,
+      clientType,
+      connectedAt: Date.now(),
+    });
+    this._recalculateTier();
+  }
+
+  /**
+   * Register an SSE client.
+   * @param {string} id - Unique client ID
+   * @param {object} res - HTTP response object for SSE stream
+   * @param {string} clientType - 'extension' or 'canvas'
+   */
+  addSseClient(id, res, clientType) {
+    this.sseClients.set(id, {
+      res,
+      clientType,
+      connectedAt: Date.now(),
+    });
+    this._recalculateTier();
+  }
+
+  /**
+   * Remove a WebSocket client.
+   * @param {string} id
+   */
+  removeWsClient(id) {
+    this.wsClients.delete(id);
+    this._recalculateTier();
+  }
+
+  /**
+   * Remove an SSE client.
+   * @param {string} id
+   */
+  removeSseClient(id) {
+    this.sseClients.delete(id);
+    this._recalculateTier();
+  }
+
+  /**
+   * Get the current tier.
+   * @returns {number}
+   */
+  getTier() {
+    return this.currentTier;
+  }
+
+  /**
+   * Get tier info for the API response.
+   * @returns {{ tier: number, label: string, clients: object }}
+   */
+  getTierInfo() {
+    const wsClientTypes = [];
+    for (const [, client] of this.wsClients) {
+      wsClientTypes.push(client.clientType);
+    }
+    const sseClientTypes = [];
+    for (const [, client] of this.sseClients) {
+      sseClientTypes.push(client.clientType);
+    }
+
+    return {
+      tier: this.currentTier,
+      label: TIER_LABELS[this.currentTier],
+      clients: {
+        websocket: wsClientTypes,
+        sse: sseClientTypes,
+        total: this.wsClients.size + this.sseClients.size,
+      },
+    };
+  }
+
+  /**
+   * Check if an extension is connected (via WS).
+   * @returns {boolean}
+   */
+  hasExtension() {
+    for (const [, client] of this.wsClients) {
+      if (client.clientType === CLIENT_EXTENSION) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Check if a canvas client is connected (via WS or SSE).
+   * @returns {boolean}
+   */
+  hasCanvas() {
+    for (const [, client] of this.wsClients) {
+      if (client.clientType === CLIENT_CANVAS) return true;
+    }
+    for (const [, client] of this.sseClients) {
+      if (client.clientType === CLIENT_CANVAS) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Listen for tier changes.
+   * @param {function} fn - Callback(oldTier, newTier)
+   */
+  onTierChange(fn) {
+    this._listeners.push(fn);
+  }
+
+  /**
+   * Broadcast heartbeat to all connected clients.
+   */
+  broadcastHeartbeat() {
+    const msg = JSON.stringify(createEnvelope(MSG_SYS_HEARTBEAT, {}, 'bridge'));
+
+    for (const [, client] of this.wsClients) {
+      try {
+        if (client.ws.readyState === 1) { // WebSocket.OPEN
+          client.ws.send(msg);
+        }
+      } catch {
+        // Client may have disconnected
+      }
+    }
+
+    for (const [, client] of this.sseClients) {
+      try {
+        client.res.write(`data: ${msg}\n\n`);
+      } catch {
+        // Client may have disconnected
+      }
+    }
+  }
+
+  /**
+   * Send a message to all WebSocket clients.
+   * @param {string} data - Serialized JSON message
+   */
+  broadcastWs(data) {
+    for (const [, client] of this.wsClients) {
+      try {
+        if (client.ws.readyState === 1) {
+          client.ws.send(data);
+        }
+      } catch {
+        // Ignore send errors
+      }
+    }
+  }
+
+  /**
+   * Send a message to all SSE clients.
+   * @param {string} data - Serialized JSON message
+   */
+  broadcastSse(data) {
+    for (const [, client] of this.sseClients) {
+      try {
+        client.res.write(`data: ${data}\n\n`);
+      } catch {
+        // Ignore write errors
+      }
+    }
+  }
+
+  /**
+   * Recalculate the current tier based on connected clients.
+   */
+  _recalculateTier() {
+    const oldTier = this.currentTier;
+    let newTier;
+
+    if (this.hasExtension() && this.hasCanvas()) {
+      newTier = TIER_FULL;
+    } else if (this.hasCanvas()) {
+      newTier = TIER_CANVAS;
+    } else {
+      newTier = TIER_TERMINAL;
+    }
+
+    this.currentTier = newTier;
+
+    if (oldTier !== newTier) {
+      const tierChangeMsg = JSON.stringify(
+        createEnvelope(MSG_SYS_TIER_CHANGE, { oldTier, newTier }, 'bridge')
+      );
+
+      // Notify all connected clients
+      this.broadcastWs(tierChangeMsg);
+      this.broadcastSse(tierChangeMsg);
+
+      // Notify listeners
+      for (const fn of this._listeners) {
+        try {
+          fn(oldTier, newTier);
+        } catch {
+          // Ignore listener errors
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Generate a unique client ID.
+ * @returns {string}
+ */
+export function generateClientId() {
+  return `client-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Validate a sys:connect handshake payload.
+ * @param {object} payload
+ * @returns {{ valid: boolean, error: string|null }}
+ */
+export function validateHandshake(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return { valid: false, error: 'Handshake payload must be an object' };
+  }
+
+  const { clientType, protocolVersion } = payload;
+
+  if (clientType !== CLIENT_EXTENSION && clientType !== CLIENT_CANVAS) {
+    return { valid: false, error: `Invalid clientType: ${clientType}. Must be "extension" or "canvas"` };
+  }
+
+  if (typeof protocolVersion !== 'number') {
+    return { valid: false, error: 'Missing protocolVersion' };
+  }
+
+  if (protocolVersion > PROTOCOL_VERSION) {
+    return { valid: false, error: `Incompatible protocol version: ${protocolVersion} (server: ${PROTOCOL_VERSION})` };
+  }
+
+  return { valid: true, error: null };
+}