Canvas Skill

Files (1)

• SKILL.md

SKILL.md (first lines)

# Canvas Skill

Display HTML content on connected Cybara nodes (Mac app, iOS, Android).

## Overview

The canvas tool lets you present web content on any connected node's canvas view. Great for:
- Displaying games, visualizations, dashboards
- Showing generated HTML content
- Interactive demos

## How It Works

### Architecture

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│  Canvas Host    │────▶│   Node Bridge    │────▶│  Node App   │
│  (HTTP Server)  │     │  (TCP Server)    │     │ (Mac/iOS/   │
│  Port 18793     │     │  Port 18790      │     │  Android)   │
└─────────────────┘     └──────────────────┘     └─────────────┘
```

1. **Canvas Host Server**: Serves static HTML/CSS/JS files from `canvasHost.root` directory
2. **Node Bridge**: Communicates canvas URLs to connected nodes
3. **Node Apps**: Render the content in a WebView

### Tailscale Integration

The canvas host server binds based on `gateway.bind` setting:

| Bind Mode | Server Binds To | Canvas URL Uses |
|-----------|-----------------|-----------------|
| `loopback` | 127.0.0.1 | localhost (local only) |
| `lan` | LAN interface | LAN IP address |
| `tailnet` | Tailscale interface | Tailscale hostname |
| `auto` | Best available | Tailscale > LAN > loopback |

**Key insight:** The `canvasHostHostForBridge` is derived from `bridgeHost`. When bound to Tailscale, nodes receive URLs like:
```
http://<tailscale-hostname>:18793/__cybara__/canvas/<file>.html
```

This is why localhost URLs don't work - the node receives the Tailscale hostname from the bridge!

## Actions

| Action | Description |
|--------|-------------|
| `present` | Show canvas with optional target URL |
| `hide` | Hide the canvas |
| `navigate` | Navigate to a new URL |
| `eval` | Execute JavaScript in the canvas |
| `snapshot` | Capture screenshot of canvas |

## Configuration

In `~/.cybara/config.json`:

```json
{
  "canvasHost": {
    "enabled": true,
    "port": 18793,
    "root": "~/cybara/canvas",
    "liveReload": true
  },
  "gateway": {
    "bind": "auto"
  }
}
```

### Live Reload

When `liveReload: true` (default), the canvas host:
- Watches the root directory for changes (via chokidar)
- Injects a WebSocket client into HTML files
- Automatically reloads connected canvases when files change

Great for development!

## Workflow

### 1. Create HTML content

Place files in the canvas root directory (default `~/cybara/canvas/`):

```bash
cat > ~/cybara/canvas/my-game.html << 'HTML'
<!DOCTYPE html>
<html>
<head><title>My Game</title></head>
<body>
  <h1>Hello Canvas!</h1>
</body>
</html>
HTML
```

### 2. Find your canvas host URL

Check how your gateway is bound:
```bash
cat ~/.cybara/config.json | jq '.gateway.bind'
```

Then construct the URL:
- **loopback**: `http://127.0.0.1:18793/__cybara__/canvas/<file>.html`
- **lan/tailnet/auto**: `http://<hostname>:18793/__cybara__/canvas/<file>.html`

Find your Tailscale hostname:
```bash
tailscale status --json | jq -r '.Self.DNSName' | sed 's/\.$//'
```

### 3. Find connected nodes

```bash

From metaspartan/cybara, MIT.

More from metaspartan/cybara