WebSocket Connection Debugging
Architecture
CLI 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
| Issue |
Symptom |
Solution |
| CLI not running |
"Connecting..." indefinitely |
Start bun run packages/cli/src/index.ts serve diagram.yaml |
| Port in use |
Connection refused |
Check lsof -i :3456, use different port |
| Secret mismatch |
Connects then immediately closes |
Match --secret value in CLI and plugin |
| YAML errors |
Connected but no updates |
Fix validation errors in CLI output |
| docId mismatch |
No response after hello |
Ensure plugin docId matches YAML docId |
| Patches not applied |
Connected, canvas unchanged |
Check Plugin Main console for render errors |
Debugging Steps
- CLI side: Check terminal for errors, verify YAML with
bun run packages/cli/src/index.ts build diagram.yaml
- Plugin UI: Right-click plugin → Inspect → Console for WebSocket events
- Plugin Main: Figma Desktop → Plugins → Development → Open console
Message Flow
Plugin 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
# 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"}
