From f237222bc99f93a4f464de7c474e7c77cef1bcdf Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 18 Dec 2025 23:32:48 +0100 Subject: [PATCH] Docs: update canvas host defaults and snapshot formats --- docs/android/connect.md | 2 +- docs/architecture.md | 2 +- docs/camera.md | 7 ++++--- docs/configuration.md | 15 +++++++++------ docs/gateway.md | 2 +- docs/ios/connect.md | 2 +- docs/ios/spec.md | 2 +- 7 files changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/android/connect.md b/docs/android/connect.md index 65c3b8c5b..49c467b70 100644 --- a/docs/android/connect.md +++ b/docs/android/connect.md @@ -118,7 +118,7 @@ Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tai This server injects a live-reload client into HTML and reloads on file changes. Canvas commands (foreground only): -- `canvas.eval`, `canvas.snapshot`, `canvas.navigate` (use `{"url":""}` or `{"url":"/"}` to return to the default canvas/A2UI scaffold) +- `canvas.eval`, `canvas.snapshot`, `canvas.navigate` (use `{"url":""}` or `{"url":"/"}` to return to the default canvas/A2UI scaffold). `canvas.snapshot` returns `{ format, base64 }` (default `format="jpeg"`). - A2UI: `canvas.a2ui.push`, `canvas.a2ui.reset` (`canvas.a2ui.pushJSONL` legacy alias) Camera commands (foreground only; permission-gated): diff --git a/docs/architecture.md b/docs/architecture.md index 2bfbefe69..ceba263c3 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -11,7 +11,7 @@ Last updated: 2025-12-09 - A single long-lived **Gateway** process owns all messaging surfaces (WhatsApp via Baileys, Telegram when enabled) and the control/event plane. - All clients (macOS app, CLI, web UI, automations) connect to the Gateway over one transport: **WebSocket on 127.0.0.1:18789** (tunnel or VPN for remote). - One Gateway per host; it is the only place that is allowed to open a WhatsApp session. All sends/agent runs go through it. -- Optional: the Gateway can expose a LAN/tailnet HTTP canvas host (`canvasHost`) to serve `~/clawd/canvas` to node WebViews (live-reloads on file changes). +- By default: the Gateway exposes a LAN/tailnet HTTP canvas host (`canvasHost`) to serve `~/clawd/canvas` to node WebViews (live-reloads on file changes); disable via `canvasHost.enabled=false` or `CLAWDIS_SKIP_CANVAS_HOST=1`. ## Components and flows - **Gateway (daemon)** diff --git a/docs/camera.md b/docs/camera.md index 900e4e6e7..0bda1aba5 100644 --- a/docs/camera.md +++ b/docs/camera.md @@ -39,7 +39,7 @@ All camera access is gated behind **user-controlled settings**. - `camera.clip` - Params: - `facing`: `front|back` (default: `front`) - - `durationMs`: number (default `3000`, clamped to a max) + - `durationMs`: number (default `3000`, clamped to a max of `60000`) - `includeAudio`: boolean (default `true`) - `format`: currently `mp4` - Response payload: @@ -83,7 +83,8 @@ Notes: - `CAMERA` for both `camera.snap` and `camera.clip`. - `RECORD_AUDIO` for `camera.clip` when `includeAudio=true`. -If permissions are denied, `camera.*` requests fail with a `*_PERMISSION_REQUIRED` error. +If permissions are missing, the app will prompt when possible; if denied, `camera.*` requests fail with a +`*_PERMISSION_REQUIRED` error. ### Foreground requirement @@ -118,4 +119,4 @@ Notes: ## Safety + practical limits - Camera and microphone access trigger the usual OS permission prompts (and require usage strings in Info.plist). -- Video clips are intentionally short to avoid oversized bridge payloads (base64 overhead + WebSocket message limits). +- Video clips are capped (currently `<= 60s`) to avoid oversized bridge payloads (base64 overhead + message limits). diff --git a/docs/configuration.md b/docs/configuration.md index 8a8962849..2a04fc5eb 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -156,28 +156,31 @@ Defaults: ### `canvasHost` (LAN/tailnet Canvas file server + live reload) -The Gateway can optionally serve a directory of HTML/CSS/JS over HTTP so iOS/Android nodes can simply `canvas.navigate` to it. +The Gateway serves a directory of HTML/CSS/JS over HTTP so iOS/Android nodes can simply `canvas.navigate` to it. Default root: `~/clawd/canvas` Default port: `18793` (chosen to avoid the clawd browser CDP port `18792`) -Default bind: `lan` (`0.0.0.0`, reachable on LAN and on Tailscale when present) +The server listens on `0.0.0.0` so it works on LAN **and** Tailnet (Tailscale is optional). -When enabled, the server: +The server: - serves files under `canvasHost.root` - injects a tiny live-reload client into served HTML - watches the directory and broadcasts reloads over a WebSocket endpoint at `/__clawdis/ws` +- auto-creates a starter `index.html` when the directory is empty (so you see something immediately) ```json5 { canvasHost: { - enabled: true, root: "~/clawd/canvas", - port: 18793, - bind: "lan" + port: 18793 } } ``` +Disable with: +- config: `canvasHost: { enabled: false }` +- env: `CLAWDIS_SKIP_CANVAS_HOST=1` + ### `bridge` (node bridge server) The Gateway can expose a simple TCP bridge for nodes (iOS/Android), typically on port `18790`. diff --git a/docs/gateway.md b/docs/gateway.md index 56fc47909..a27ae6dc7 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -21,7 +21,7 @@ pnpm clawdis gateway --port 18789 --verbose pnpm clawdis gateway --force ``` - Binds WebSocket control plane to `127.0.0.1:` (default 18789). -- Optionally starts a LAN/tailnet Canvas file server when `canvasHost.enabled` is `true` (default `http://0.0.0.0:18793`, serves `~/clawd/canvas`). +- Starts a LAN/tailnet Canvas file server by default (default `http://0.0.0.0:18793`, serves `~/clawd/canvas`). Disable with `canvasHost.enabled=false` or `CLAWDIS_SKIP_CANVAS_HOST=1`. - Logs to stdout; use launchd/systemd to keep it alive and rotate logs. - Pass `--verbose` to mirror debug logging (handshakes, req/res, events) from the log file into stdio when troubleshooting. - `--force` uses `lsof` to find listeners on the chosen port, sends SIGTERM, logs what it killed, then starts the gateway (fails fast if `lsof` is missing). diff --git a/docs/ios/connect.md b/docs/ios/connect.md index 472b69f25..8a73f274e 100644 --- a/docs/ios/connect.md +++ b/docs/ios/connect.md @@ -154,7 +154,7 @@ JSON clawdis nodes invoke --node 192.168.0.88 --command canvas.snapshot --params '{"maxWidth":900}' ``` -The response includes `base64` PNG data (for debugging/verification). +The response includes `{ format, base64 }` image data (default `format="jpeg"`; pass `{"format":"png"}` when you specifically need lossless PNG). ## Common gotchas diff --git a/docs/ios/spec.md b/docs/ios/spec.md index e99976199..d3cd71499 100644 --- a/docs/ios/spec.md +++ b/docs/ios/spec.md @@ -30,7 +30,7 @@ Non-goals (v1): ## Current repo reality (constraints we respect) - The Gateway WebSocket server binds to `127.0.0.1:18789` (`src/gateway/server.ts`) with an optional `CLAWDIS_GATEWAY_TOKEN`. -- The Gateway can optionally expose a LAN/tailnet Canvas file server (`canvasHost`) so nodes can `canvas.navigate` to `http://:/` and auto-reload when files change (`docs/configuration.md`). +- The Gateway exposes a LAN/tailnet Canvas file server (`canvasHost`) by default so nodes can `canvas.navigate` to `http://:/` and auto-reload when files change (`docs/configuration.md`). - macOS “Canvas” exists today, but is **mac-only** and controlled via mac app IPC (`clawdis-mac canvas ...`) rather than the Gateway protocol (`docs/mac/canvas.md`). - Voice wake forwards via `GatewayChannel` to Gateway `agent` (mac app: `VoiceWakeForwarder` → `GatewayConnection.sendAgent`).