my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	# Canvas Skill
#2
#3	Display HTML content on connected SolanaOS nodes (Mac app, iOS, Android).
#4
#5	## Overview
#6
#7	The canvas tool lets you present web content on any connected node's canvas view. Great for:
#8
#9	- Displaying games, visualizations, dashboards
#10	- Showing generated HTML content
#11	- Interactive demos
#12
#13	## How It Works
#14
#15	### Architecture
#16
#17	```
#18	┌─────────────────┐ ┌──────────────────┐ ┌─────────────┐
#19	│ Canvas Host │────▶│ Node Bridge │────▶│ Node App │
#20	│ (HTTP Server) │ │ (TCP Server) │ │ (Mac/iOS/ │
#21	│ Port 18793 │ │ Port 18790 │ │ Android) │
#22	└─────────────────┘ └──────────────────┘ └─────────────┘
#23	```
#24
#25	1. Canvas Host Server: Serves static HTML/CSS/JS files from `canvasHost.root` directory
#26	2. Node Bridge: Communicates canvas URLs to connected nodes
#27	3. Node Apps: Render the content in a WebView
#28
#29	### Tailscale Integration
#30
#31	The canvas host server binds based on `gateway.bind` setting:
#32
#33	\| Bind Mode \| Server Binds To \| Canvas URL Uses \|
#34	\| ---------- \| ------------------- \| -------------------------- \|
#35	\| `loopback` \| 127.0.0.1 \| localhost (local only) \|
#36	\| `lan` \| LAN interface \| LAN IP address \|
#37	\| `tailnet` \| Tailscale interface \| Tailscale hostname \|
#38	\| `auto` \| Best available \| Tailscale > LAN > loopback \|
#39
#40	Key insight: The `canvasHostHostForBridge` is derived from `bridgeHost`. When bound to Tailscale, nodes receive URLs like:
#41
#42	```
#43	http://<tailscale-hostname>:18793/__solanaos__/canvas/<file>.html
#44	```
#45
#46	This is why localhost URLs don't work - the node receives the Tailscale hostname from the bridge!
#47
#48	## Actions
#49
#50	\| Action \| Description \|
#51	\| ---------- \| ------------------------------------ \|
#52	\| `present` \| Show canvas with optional target URL \|
#53	\| `hide` \| Hide the canvas \|
#54	\| `navigate` \| Navigate to a new URL \|
#55	\| `eval` \| Execute JavaScript in the canvas \|
#56	\| `snapshot` \| Capture screenshot of canvas \|
#57
#58	## Configuration
#59
#60	In `~/.solanaos/solanaos.json`:
#61
#62	```json
#63	{
#64	"canvasHost": {
#65	"enabled": true,
#66	"port": 18793,
#67	"root": "/Users/you/clawd/canvas",
#68	"liveReload": true
#69	},
#70	"gateway": {
#71	"bind": "auto"
#72	}
#73	}
#74	```
#75
#76	### Live Reload
#77
#78	When `liveReload: true` (default), the canvas host:
#79
#80	- Watches the root directory for changes (via chokidar)
#81	- Injects a WebSocket client into HTML files
#82	- Automatically reloads connected canvases when files change
#83
#84	Great for development!
#85
#86	## Workflow
#87
#88	### 1. Create HTML content
#89
#90	Place files in the canvas root directory (default `~/clawd/canvas/`):
#91
#92	```bash
#93	cat > ~/clawd/canvas/my-game.html << 'HTML'
#94	<!DOCTYPE html>
#95	<html>
#96	<head><title>My Game</title></head>
#97	<body>
#98	<h1>Hello Canvas!</h1>
#99	</body>
#100	</html>
#101	HTML
#102	```
#103
#104	### 2. Find your canvas host URL
#105
#106	Check how your gateway is bound:
#107
#108	```bash
#109	cat ~/.solanaos/solanaos.json \| jq '.gateway.bind'
#110	```
#111
#112	Then construct the URL:
#113
#114	- loopback: `http://127.0.0.1:18793/__solanaos__/canvas/<file>.html`
#115	- lan/tailnet/auto: `http://<hostname>:18793/__solanaos__/canvas/<file>.html`
#116
#117	Find your Tailscale hostname:
#118
#119	```bash
#120	tailscale status --json \| jq -r '.Self.DNSName' \| sed 's/\.$//'
#121	```
#122
#123	### 3. Find connected nodes
#124
#125	```bash
#126	solanaos nodes list
#127	```
#128
#129	Look for Mac/iOS/Android nodes with canvas capability.
#130
#131	### 4. Present content
#132
#133	```
#134	canvas action:present node:<node-id> target:<full-url>
#135	```
#136
#137	Example:
#138
#139	```
#140	canvas action:present node:mac-63599bc4-b54d-4392-9048-b97abd58343a target:http://peters-mac-studio-1.sheep-coho.ts.net:18793/__solanaos__/canvas/snake.html
#141	```
#142
#143	### 5. Navigate, snapshot, or hide
#144
#145	```
#146	canvas action:navigate node:<node-id> url:<new-url>
#147	canvas action:snapshot node:<node-id>
#148	canvas action:hide node:<node-id>
#149	```
#150
#151	## Debugging
#152
#153	### White screen / content not loading
#154
#155	Cause: URL mismatch between server bind and node expectation.
#156
#157	Debug steps:
#158
#159	1. Check server bind: `cat ~/.solanaos/solanaos.json \| jq '.gateway.bind'`
#160	2. Check what port canvas is on: `lsof -i :18793`
#161	3. Test URL directly: `curl http://<hostname>:18793/__solanaos__/canvas/<file>.html`
#162
#163	Solution: Use the full hostname matching your bind mode, not localhost.
#164
#165	### "node required" error
#166
#167	Always specify `node:<node-id>` parameter.
#168
#169	### "node not connected" error
#170
#171	Node is offline. Use `solanaos nodes list` to find online nodes.
#172
#173	### Content not updating
#174
#175	If live reload isn't working:
#176
#177	1. Check `liveReload: true` in config
#178	2. Ensure file is in the canvas root directory
#179	3. Check for watcher errors in logs
#180
#181	## URL Path Structure
#182
#183	The canvas host serves from `/__solanaos__/canvas/` prefix:
#184
#185	```
#186	http://<host>:18793/__solanaos__/canvas/index.html → ~/clawd/canvas/index.html
#187	http://<host>:18793/__solanaos__/canvas/games/snake.html → ~/clawd/canvas/games/snake.html
#188	```
#189
#190	The `/__solanaos__/canvas/` prefix is defined by `CANVAS_HOST_PATH` constant.
#191
#192	## Tips
#193
#194	- Keep HTML self-contained (inline CSS/JS) for best results
#195	- Use the default index.html as a test page (has bridge diagnostics)
#196	- The canvas persists until you `hide` it or navigate away
#197	- Live reload makes development fast - just save and it updates!
#198	- A2UI JSON push is WIP - use HTML files for now
#199

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public