Collab Canvas

# Collaborator Canvas

Control Collaborator's spatial canvas from the terminal using the `collab-canvas` CLI.
The canvas is a pannable, zoomable surface where tiles display terminals, files, images, and graphs.

## Coordinate System

All positions and sizes use **grid units**. One grid unit = 20 pixels.
Origin (0,0) is the top-left corner. X increases rightward, Y increases downward.

## Tile Types

| Type    | Use for                          | Default size (w x h) |
|---------|----------------------------------|-----------------------|
| `term`  | Terminal / shell session         | 20 x 25              |
| `note`  | Markdown files (.md)             | 22 x 27              |
| `code`  | Source code files                | 22 x 27              |
| `image` | Images (.png, .jpg, .gif, .webp) | 14 x 14              |
| `graph` | .graph.json or folder graphs     | 30 x 25              |

Type is inferred from the file when `--file` is used:
- `.md`, `.txt` -> `note`
- `.graph.json` -> `graph`
- `.png`, `.jpg`, `.gif`, `.svg`, `.webp` -> `image`
- Directories -> `graph`
- Everything else -> `code`

## Commands

### collab-canvas tile list

List all tiles on the canvas. Returns JSON array with id, type, position, size, and file path for each tile.

```bash
collab-canvas tile list
```

### collab-canvas tile create

Create a new tile on the canvas.

```bash
collab-canvas tile create <type> [--file <path>] [--pos x,y] [--size w,h]
```

- `<type>`: term, note, code, image, or graph
- `--file <path>`: file to display (required for note, code, image, graph; omit for term)
- `--pos x,y`: position in grid units (default: viewport center)
- `--size w,h`: size in grid units (default: per-type default above)

Returns the new tile's ID on stdout.

**Examples:**
```bash
# Open a terminal at position (5, 5)
collab-canvas tile create term --pos 5,5

# Open a markdown file with default placement
collab-canvas tile create note --file ./README.md

# Open a graph file at a specific position and size
collab-canvas tile create graph --file ./entities.graph.json --pos 25,0 --size 35,30
```

### collab-canvas tile rm

Remove a tile from the canvas.

```bash
collab-canvas tile rm <id>
```

### collab-canvas tile move

Reposition a tile.

```bash
collab-canvas tile move <id> --pos x,y
```

### collab-canvas tile resize

Resize a tile.

```bash
collab-canvas tile resize <id> --size w,h
```

### collab-canvas tile focus

Pan and zoom the viewport to bring one or more tiles into view, then flash their focus rings.

```bash
collab-canvas tile focus <id> [<id>...]
```

**Examples:**
```bash
# Focus a single tile
collab-canvas tile focus tile-abc123

# Focus multiple tiles (viewport zooms to fit all)
collab-canvas tile focus tile-abc123 tile-def456
```

### collab-canvas terminal write

Send input to a terminal tile. The tile must be of type `term` with an active PTY session.

```bash
collab-canvas terminal write <id> <input>
```

**Examples:**
```bash
# Run a command in a terminal tile
collab-canvas terminal write tile-abc123 $'ls -la\n'

# Launch Claude Code in headless JSON mode
collab-canvas terminal write tile-abc123 $'claude -p "fix the bug" --output-format json\n'
```

### collab-canvas terminal read

Read recent output from a terminal tile. Returns raw terminal output from the PTY session's ring buffer.

```bash
collab-canvas terminal read <id> [--lines N]
```

- `--lines N`: number of lines to capture (default: 50)

## Composition Patterns

### Side-by-side comparison

Two files next to each other for comparison.

```bash
collab-canvas tile create code --file ./old.ts --pos 0,0
collab-canvas tile create code --file ./new.ts --pos 23,0
```

### Research workspace

Knowledge graph on the left, notes on the right, terminal below.

```bash
collab-canvas tile create graph --file ./research.graph.json --pos 0,0 --size 30,25
collab-canvas tile create note --file ./notes.md --pos 31,0
collab-canvas tile create term --pos 0,26
```

### Dashboard layout

Multiple views arranged in a grid.

```bash
collab-canvas tile create graph --file ./entities.graph.json --pos 0,0 --size 30,25
collab-canvas tile create note --file ./log.md --pos 31,0
collab-canvas tile create note --file ./report.md --pos 31,14
collab-canvas tile create term --pos 0,26
```

### Focus view

Single tile centered with generous size.

```bash
collab-canvas tile create code --file ./main.ts --pos 5,2 --size 40,35
```

### Agent in a terminal

Launch a Claude Code instance in a terminal tile for the human to observe.

```bash
# Create terminal, wait for PTY, then launch agent
collab-canvas tile create term --pos 0,0
# (use tile list to get the tile ID, then)
collab-canvas terminal write <id> $'claude -p "summarize this project" --output-format json\n'
# Read the result when done
collab-canvas terminal read <id> --lines 100
```

## Conventions

1. **Always `tile list` first** to see what's already on the canvas before creating tiles.
2. **Use `tile focus` to frame** after arranging tiles so the user can see them.
3. **Clean up when done**: remove tiles you created when they're no longer needed.
4. **Leave 1 grid unit gap** between adjacent tiles for visual clarity.
5. **File tiles auto-refresh**: when you write to a file that has a tile, the tile updates automatically. No need to close and reopen.
6. **Graph tiles support incremental updates**: append nodes to a `.graph.json` file and the graph tile smoothly incorporates them.
7. **Terminal tiles need time to initialize**: after `tile create term`, wait a few seconds before `terminal write` so the PTY session can start.

## Setup

The `collab-canvas` CLI is installed to `~/.local/bin/`. If the command is not found, the user needs to add it to their PATH:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Add this to `~/.zshrc` (macOS) or `~/.bashrc` (Linux) to persist across sessions.

## Exit Codes

| Code | Meaning                                    |
|------|--------------------------------------------|
| 0    | Success                                    |
| 1    | RPC error (tile not found, invalid params) |
| 2    | Connection failure (Collaborator not running) |