debug-connection

name	debug-connection
description	Debug WebSocket connection issues between CLI and FigJam plugin. Use when diagrams aren't syncing or connection fails.

WebSocket Connection Debugging

Architecture

┌─────────────┐     WebSocket      ┌─────────────────┐    postMessage    ┌─────────────────┐
│  CLI serve  │ ◄───────────────► │  Plugin UI      │ ◄───────────────► │  Plugin Main    │
│  (Bun)      │   ws://...:3456   │  (ui.ts)        │                   │  (code.ts)      │
└─────────────┘                   └─────────────────┘                   └─────────────────┘
     │                                   │                                     │
     │ File watcher                      │ Browser APIs                        │ Figma API
     │ YAML parsing                      │ WebSocket client                    │ Canvas rendering
     └───────────────────────────────────┴─────────────────────────────────────┘

Common Issues & Solutions

1. Connection Refused

Symptoms: Plugin shows "Connecting..." indefinitely

Check:

# Is CLI serve running?
ps aux | grep "figram serve"

# Check port availability (default: 3456)
lsof -i :3456

Solution: Start CLI with bun run packages/cli/src/index.ts serve diagram.yaml

2. Connection Drops

Symptoms: Works initially, then stops syncing

Check:

• Plugin UI console for WebSocket close events
• CLI terminal for error messages

Solution: Check for YAML parse errors blocking updates

3. Patches Not Applied

Symptoms: Connected but canvas doesn't update

Debug steps:

1. Check CLI output for patch generation
2. Check Plugin UI console for received messages
3. Check Plugin Main console for rendering errors

4. YAML Parse Errors

Symptoms: CLI shows validation errors

Solution: Validate YAML syntax and schema compliance

5. Secret Mismatch

Symptoms: Connection established but immediately closed

Check: Ensure --secret flag value matches between CLI and plugin

6. JSON Import Errors

Symptoms: Import dialog shows an error alert

Check:

• JSON must be an object
• DSL JSON requires version, docId, and nodes array
• IR JSON requires version, docId, and nodes object

Solution: Fix validation errors shown in the alert (path + message)

Debugging Tools

CLI Side

# Run with verbose output
DEBUG=* bun run packages/cli/src/index.ts serve diagram.yaml

# Specify custom port
bun run packages/cli/src/index.ts serve diagram.yaml --port 8080

# With authentication
bun run packages/cli/src/index.ts serve diagram.yaml --secret mysecret

Plugin UI Side

1. Right-click plugin UI → Inspect
2. Check Console for WebSocket events
3. Check Network tab for WS frames

Plugin Main Side

1. Figma Desktop → Plugins → Development → Open console
2. Check for rendering errors

WebSocket Protocol

Plugin → CLI Messages

// Connection initiation
interface HelloMessage {
  type: "hello";
  docId: string;
  secret?: string;  // If server requires authentication
}

// Request full sync (e.g., after reconnection)
interface RequestFullMessage {
  type: "requestFull";
  docId: string;
}

CLI → Plugin Messages

// Full document sync
interface FullMessage {
  type: "full";
  rev: number;        // Current revision number
  ir: IRDocument;     // Complete normalized document
}

// Incremental update
interface PatchMessage {
  type: "patch";
  baseRev: number;    // Expected current revision
  nextRev: number;    // New revision after applying
  ops: PatchOp[];     // Operations to apply
}

// Error notification
interface ErrorMessage {
  type: "error";
  message: string;
}

Patch Operations

type PatchOp =
  | { op: "upsertNode"; node: IRNode }
  | { op: "removeNode"; id: string }
  | { op: "upsertEdge"; edge: IREdge }
  | { op: "removeEdge"; id: string };

Quick Diagnostic

# 1. Start CLI serve (default port: 3456)
bun run packages/cli/src/index.ts serve examples/diagram.yaml

# 2. Test WebSocket with wscat (if installed)
wscat -c ws://localhost:3456

# 3. Send hello message
{"type":"hello","docId":"test"}

# 4. Check YAML is valid
bun run packages/cli/src/index.ts build examples/diagram.yaml

Message Flow

Plugin                          CLI
  │                              │
  │──── HelloMessage ───────────►│  (docId, secret?)
  │                              │
  │◄──── FullMessage ───────────│  (rev, ir)
  │                              │
  │      [YAML file changes]     │
  │                              │
  │◄──── PatchMessage ──────────│  (baseRev, nextRev, ops)
  │                              │
  │      [Plugin reconnects]     │
  │                              │
  │──── RequestFullMessage ─────►│  (docId)
  │                              │
  │◄──── FullMessage ───────────│  (rev, ir)
  │                              │