---

name: debug-connection description: Debug WebSocket connection issues between CLI and FigJam plugin. Use when diagrams aren't syncing, connection fails, plugin shows "Connecting..." indefinitely, or patches aren't being applied to canvas.

WebSocket Connection Debugging

Architecture

CopyCLI serve (Bun) ←── WebSocket ──→ Plugin UI (ui.ts) ←── postMessage ──→ Plugin Main (code.ts)
     │                                  │                                    │
  File watcher                    Browser APIs                          Figma API
  YAML parsing                    WebSocket client                      Canvas rendering

Common Issues

Debugging Steps

1. CLI side: Check terminal for errors, verify YAML with bun run packages/cli/src/index.ts build diagram.yaml
2. Plugin UI: Right-click plugin → Inspect → Console for WebSocket events
3. Plugin Main: Figma Desktop → Plugins → Development → Open console

Message Flow

CopyPlugin                          CLI
  │                              │
  │──── hello ─────────────────►│  {type:"hello", docId, secret?}
  │◄──── full ─────────────────│  {type:"full", rev, ir}
  │                              │
  │      [YAML changes]          │
  │◄──── patch ────────────────│  {type:"patch", baseRev, nextRev, ops}
  │                              │
  │      [Reconnect]             │
  │──── requestFull ───────────►│  {type:"requestFull", docId}
  │◄──── full ─────────────────│

JSON Import Errors

• JSON must be an object with version, docId, nodes
• DSL format: nodes as array
• IR format: nodes as object (Record)
• Validation errors shown in alert with path + message

Quick Test

Copy# Start server
bun run packages/cli/src/index.ts serve examples/diagram.yaml

# Test with wscat
wscat -c ws://localhost:3456
> {"type":"hello","docId":"test"}