Canvas TUI Toolkit

Interactive terminal displays (TUIs) that spawn in tmux split panes and communicate via IPC. Use for calendars, documents, flight bookings, and other rich interactive scenarios.

When to Use

• Displaying calendars and picking meeting times
• Showing markdown documents with text selection
• Comparing flights and selecting seats
• Any scenario requiring visual display + user interaction
• When you need to show rich content without blocking the conversation

Quick Start

cd ${SKILL_DIR}

# Display calendar in current terminal
bun run src/cli.ts show calendar

# Spawn interactive meeting picker in tmux split
bun run src/cli.ts spawn calendar --scenario meeting-picker --config '{
  "calendars": [
    {"name": "Alice", "color": "blue", "events": [...]},
    {"name": "Bob", "color": "green", "events": [...]}
  ]
}'

Available Canvas Types

Spawning Canvases

Always use spawn for interactive scenarios - opens canvas in tmux split pane.

bun run src/cli.ts spawn [kind] --scenario [name] --config '[json]'

Parameters:

• kind: Canvas type (calendar, document, flight)
• --scenario: Interaction mode
• --config: JSON configuration for the canvas
• --id: Optional canvas instance ID for IPC

Calendar Canvas

Display Scenario

View-only calendar display.

bun run src/cli.ts show calendar --config '{
  "title": "My Week",
  "events": [
    {
      "id": "1",
      "title": "Meeting",
      "startTime": "2026-01-07T09:00:00",
      "endTime": "2026-01-07T10:00:00"
    }
  ]
}'

Meeting Picker Scenario

Interactive time slot selection across multiple calendars.

bun run src/cli.ts spawn calendar --scenario meeting-picker --config '{
  "calendars": [
    {
      "name": "Alice",
      "color": "blue",
      "events": [
        {"id": "1", "title": "Standup", "startTime": "2026-01-07T09:00:00", "endTime": "2026-01-07T09:30:00"}
      ]
    }
  ],
  "slotGranularity": 30,
  "minDuration": 30,
  "maxDuration": 120
}'

Controls:

• Mouse click: Select a free time slot
• ←/→: Navigate weeks
• t: Jump to today
• q or Esc: Cancel

Returns:

{
  "startTime": "2026-01-07T14:00:00",
  "endTime": "2026-01-07T15:00:00",
  "duration": 60
}

Document Canvas

Display Scenario

Read-only markdown document.

# Spawn in new tmux pane (recommended)
bun run src/cli.ts spawn document --config '{
  "content": "# Hello World\n\nThis is **markdown**.",
  "title": "My Document"
}'

# Or show inline in current terminal
bun run src/cli.ts show document --config '{
  "content": "# Hello World\n\nThis is **markdown**.",
  "title": "My Document"
}'

Edit Scenario

Interactive document with text selection and diff highlighting.

bun run src/cli.ts spawn document --scenario edit --config '{
  "content": "# Blog Post\n\nSelect some text here.",
  "title": "Edit Mode",
  "diffs": [
    {"startOffset": 20, "endOffset": 30, "type": "add"}
  ]
}'

Controls:

• Mouse click and drag: Select text
• ↑/↓: Navigate document
• q: Close

Returns:

{
  "selectedText": "some text",
  "startOffset": 12,
  "endOffset": 21,
  "startLine": 3,
  "endLine": 3
}

Flight Canvas

Booking Scenario

Flight comparison and seat selection with cyberpunk theme.

bun run src/cli.ts spawn flight --scenario booking --config '{
  "flights": [
    {
      "id": "ua123",
      "airline": "United Airlines",
      "flightNumber": "UA 123",
      "origin": {
        "code": "SFO",
        "name": "San Francisco International",
        "city": "San Francisco",
        "timezone": "PST"
      },
      "destination": {
        "code": "DEN",
        "name": "Denver International",
        "city": "Denver",
        "timezone": "MST"
      },
      "departureTime": "2026-01-08T12:55:00-08:00",
      "arrivalTime": "2026-01-08T16:37:00-07:00",
      "duration": 162,
      "price": 34500,
      "currency": "USD",
      "cabinClass": "economy",
      "aircraft": "Boeing 737-800",
      "stops": 0,
      "seatmap": {
        "rows": 30,
        "seatsPerRow": ["A", "B", "C", "D", "E", "F"],
        "aisleAfter": ["C"],
        "unavailable": ["1A", "1B", "1C"],
        "premium": ["2A", "2B"],
        "occupied": ["3A", "4B"]
      }
    }
  ]
}'

Controls:

• ↑/↓: Navigate between flights
• Tab: Switch to seatmap
• ←/→/↑/↓ (in seatmap): Move cursor
• Space: Select seat
• Enter: Confirm
• q: Cancel

Returns:

{
  "selectedFlight": { ... },
  "selectedSeat": "12A"
}

IPC Communication

Canvases communicate via Unix domain sockets.

Canvas → Controller:

{ type: "ready", scenario }        // Canvas ready
{ type: "selected", data }         // User made selection
{ type: "cancelled", reason? }     // User cancelled
{ type: "error", message }         // Error occurred

Controller → Canvas:

{ type: "update", config }  // Update canvas config
{ type: "close" }           // Close canvas
{ type: "ping" }            // Health check

Programmatic API

import { pickMeetingTime, editDocument, bookFlight } from "${SKILL_DIR}/src/api";

// Meeting picker
const meeting = await pickMeetingTime({
  calendars: [...],
  slotGranularity: 30,
});

// Document editor
const doc = await editDocument({
  content: "# My Document",
  title: "Edit Mode",
});

// Flight booking
const flight = await bookFlight({
  flights: [...]
});

Requirements

• tmux: Canvas spawning requires active tmux session
• Bun: Runtime for executing canvas commands
• Terminal with mouse support: For interactive scenarios

File Structure

canvas/
├── SKILL.md           # This file
├── README.md          # Additional documentation
├── package.json       # Dependencies
├── run-canvas.sh      # Wrapper script
├── src/
│   ├── cli.ts         # CLI entry point
│   ├── canvases/      # React/Ink canvas components
│   ├── scenarios/     # Scenario definitions
│   ├── ipc/           # IPC server/client
│   └── api/           # High-level API
└── scripts/           # Helper scripts

Tips

• Always check for tmux session before spawning: tmux list-sessions
• Use show for quick displays, spawn for interactive scenarios
• Canvas IDs are optional but useful for managing multiple canvases
• IPC sockets are created in /tmp/canvas-*.sock
• Canvases auto-cleanup on exit or error

Examples

Example 1: Pick Meeting Time

# User: "Find a time for Alice and Bob to meet tomorrow"
# You: Spawn meeting picker

bun run src/cli.ts spawn calendar --scenario meeting-picker --config '{
  "calendars": [
    {"name": "Alice", "color": "blue", "events": [...]},
    {"name": "Bob", "color": "green", "events": [...]}
  ],
  "slotGranularity": 30
}'

# Wait for selection, then confirm with user

Example 2: Review Document

# User: "Show me the email draft"
# You: Display email in document canvas

bun run src/cli.ts spawn document --config '{
  "content": "Dear Team,\n\nPlease review...",
  "title": "Email Draft"
}'

Example 3: Book Flight

# User: "Compare these flights and pick a seat"
# You: Spawn flight booking canvas

bun run src/cli.ts spawn flight --scenario booking --config '{
  "flights": [...]
}'

# Wait for user to select flight + seat