docs: align canvas host port guidance

docs/android/connect.md

@@ -105,20 +105,20 @@ The Android node’s Chat sheet uses the gateway’s **primary session key** (`m
 
 If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point the node at the Gateway canvas host.
 
-Note: the Gateway must be bound to a LAN/tailnet interface (`gateway.bind=lan|tailnet`) so the node can reach `:18789`.
+Note: nodes always use the standalone canvas host on `canvasHost.port` (default `18793`), bound to the bridge interface.
 
 1) Create `~/clawd/canvas/index.html` on the gateway host.
 
 2) Navigate the node to it (LAN):
 
 ```bash
-clawdis nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__clawdis__/canvas/"}'
+clawdis nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__clawdis__/canvas/"}'
 ```
 
-Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18789/__clawdis__/canvas/`.
+Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__clawdis__/canvas/`.
 
 This server injects a live-reload client into HTML and reloads on file changes.
-The A2UI host lives at `http://<gateway-host>:18789/__clawdis__/a2ui/`.
+The A2UI host lives at `http://<gateway-host>:18793/__clawdis__/a2ui/`.
 
 Canvas commands (foreground only):
 - `canvas.eval`, `canvas.snapshot`, `canvas.navigate` (use `{"url":""}` or `{"url":"/"}` to return to the default scaffold). `canvas.snapshot` returns `{ format, base64 }` (default `format="jpeg"`).

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.
-- By default: the Gateway exposes a Canvas host on the **same port** as the Gateway WS, serving `~/clawd/canvas` at `/__clawdis__/canvas/` with live-reload; disable via `canvasHost.enabled=false` or `CLAWDIS_SKIP_CANVAS_HOST=1`.
+- By default: the Gateway exposes a Canvas host on `canvasHost.port` (default `18793`), serving `~/clawd/canvas` at `/__clawdis__/canvas/` with live-reload; disable via `canvasHost.enabled=false` or `CLAWDIS_SKIP_CANVAS_HOST=1`.
 
 ## Components and flows
 - **Gateway (daemon)**  

docs/bonjour.md

@@ -93,7 +93,7 @@ The Gateway advertises small non-secret hints to make UI flows convenient:
 - `sshPort=<port>` (defaults to 22 when not overridden)
 - `gatewayPort=<port>` (informational; the Gateway WS is typically loopback-only)
 - `bridgePort=<port>` (only when bridge is enabled)
-- `canvasPort=<port>` (only when the canvas host is enabled + reachable; same as `gatewayPort`; serves `/__clawdis__/canvas/`)
+- `canvasPort=<port>` (only when the canvas host is enabled + reachable; default `18793`; serves `/__clawdis__/canvas/`)
 - `cliPath=<path>` (optional; absolute path to a runnable `clawdis` entrypoint or binary)
 - `tailnetDns=<magicdns>` (optional hint; auto-detected from Tailscale when available; may be absent)
 

docs/browser.md

@@ -46,7 +46,7 @@ Clawdis already uses:
 For the clawd browser-control server, use "family" ports:
 - Browser control HTTP API: `18791` (bridge + 1)
 - Browser CDP/debugging port: `18792` (control + 1)
-- Canvas host HTTP: **same as the Gateway port** (`18789`), mounted at `/__clawdis__/canvas/`
+- Canvas host HTTP: `18793` by default, mounted at `/__clawdis__/canvas/`
 
 The user usually only configures the **control URL** (port `18791`). CDP is an
 internal detail.

docs/configuration.md

@@ -237,13 +237,15 @@ The Gateway serves a directory of HTML/CSS/JS over HTTP so iOS/Android nodes can
 
 Default root: `~/clawd/canvas`  
 Default port: `18793` (chosen to avoid the clawd browser CDP port `18792`)  
-The server listens on `0.0.0.0` so it works on LAN **and** Tailnet (Tailscale is optional).
+The server listens on the **bridge bind host** (LAN or Tailnet) so nodes can reach it.
 
 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)
+- also serves A2UI at `/__clawdis__/a2ui/` and is advertised to nodes as `canvasHostUrl`
+  (always used by nodes for Canvas/A2UI)
 
 ```json5
 {

docs/discovery.md

@@ -54,7 +54,7 @@ Troubleshooting and beacon details: `docs/bonjour.md`.
   - `sshPort=22` (or whatever is advertised)
   - `gatewayPort=18789` (loopback WS port; informational)
   - `bridgePort=18790` (when bridge is enabled)
-  - `canvasPort=18789` (same as `gatewayPort` when the canvas host is enabled + gateway bind is non-loopback; serves `/__clawdis__/canvas/`)
+  - `canvasPort=18793` (default canvas host port; serves `/__clawdis__/canvas/`)
   - `cliPath=<path>` (optional; absolute path to a runnable `clawdis` entrypoint or binary)
   - `tailnetDns=<magicdns>` (optional hint; auto-detected when Tailscale is available)
 

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:<port>` (default 18789).
-- Starts a Canvas file server by default on the **same port** as the Gateway (`http://<gateway-host>:18789/__clawdis__/canvas/`, serves `~/clawd/canvas`). Disable with `canvasHost.enabled=false` or `CLAWDIS_SKIP_CANVAS_HOST=1`.
+- Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://<gateway-host>:18793/__clawdis__/canvas/` from `~/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).

docs/index.md

@@ -35,7 +35,7 @@ WhatsApp / Telegram
   ┌──────────────────────────┐
   │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
   │     (single source)       │  tcp://0.0.0.0:18790 (Bridge)
-  │                          │  http://<gateway-host>:18789/__clawdis__/canvas/ (Canvas host)
+  │                          │  http://<gateway-host>:18793/__clawdis__/canvas/ (Canvas host)
   └───────────┬───────────────┘
               │
               ├─ Pi agent (RPC)
@@ -53,7 +53,7 @@ Most operations flow through the **Gateway** (`clawdis gateway`), a single long-
 - **Loopback-first**: Gateway WS defaults to `ws://127.0.0.1:18789`.
   - For Tailnet access, run `clawdis gateway --bind tailnet --token ...` (token is required for non-loopback binds).
 - **Bridge for nodes**: optional LAN/tailnet-facing bridge on `tcp://0.0.0.0:18790` for paired nodes (Bonjour-discoverable).
-- **Canvas host**: HTTP file server on the Gateway port, serving `/__clawdis__/canvas/` for node WebViews; see `docs/configuration.md` (`canvasHost`).
+- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdis__/canvas/` for node WebViews; see `docs/configuration.md` (`canvasHost`).
 - **Remote use**: SSH tunnel or tailnet/VPN; see `docs/remote.md` and `docs/discovery.md`.
 
 ## Features (high level)

docs/ios/connect.md

@@ -126,20 +126,20 @@ The iOS node runs a WKWebView “Canvas” scaffold which exposes:
 
 If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point it at the Gateway canvas host.
 
-Note: the Gateway must be bound to a LAN/tailnet interface (`gateway.bind=lan|tailnet`) so the node can reach `:18789`.
+Note: nodes always use the standalone canvas host on `canvasHost.port` (default `18793`), bound to the bridge interface.
 
 1) Create `~/clawd/canvas/index.html` on the gateway host.
 
 2) Navigate the node to it (LAN):
 
 ```bash
-clawdis nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__clawdis__/canvas/"}'
+clawdis nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__clawdis__/canvas/"}'
 ```
 
 Notes:
 - The server injects a live-reload client into HTML and reloads on file changes.
-- A2UI is hosted on the same canvas host at `http://<gateway-host>:18789/__clawdis__/a2ui/`.
-- Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18789/__clawdis__/canvas/`.
+- A2UI is hosted on the same canvas host at `http://<gateway-host>:18793/__clawdis__/a2ui/`.
+- Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__clawdis__/canvas/`.
 - iOS may require App Transport Security allowances to load plain `http://` URLs; if it fails to load, prefer HTTPS or adjust the iOS app’s ATS config.
 
 ### Draw with `canvas.eval`

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 exposes a Canvas file server (`canvasHost`) on the **same port** as the Gateway, so nodes can `canvas.navigate` to `http://<lanHost>:18789/__clawdis__/canvas/` and auto-reload on file changes (`docs/configuration.md`).
+- The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://<lanHost>:18793/__clawdis__/canvas/` and auto-reload on file changes (`docs/configuration.md`).
 - macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android (`docs/mac/canvas.md`).
 - Voice wake forwards via `GatewayChannel` to Gateway `agent` (mac app: `VoiceWakeForwarder` → `GatewayConnection.sendAgent`).
 
@@ -127,7 +127,7 @@ These are values for `node.invoke.command`:
   - `canvas.a2ui.push` with `{ messages: [...] }` (A2UI v0.8 server→client messages)
   - `canvas.a2ui.pushJSONL` with `{ jsonl: "..." }` (legacy alias)
   - `canvas.a2ui.reset`
-  - A2UI is hosted by the Gateway canvas host (`/__clawdis__/a2ui/`); commands fail if the host is unreachable.
+  - A2UI is hosted by the Gateway canvas host (`/__clawdis__/a2ui/`) on `canvasHost.port`. Commands fail if the host is unreachable.
 
 Result pattern:
 - Request is a standard `req/res` with `ok` / `error`.

docs/mac/canvas.md

@@ -99,7 +99,7 @@ Use the main `clawdis` CLI; it invokes canvas commands via `node.invoke`.
 Canvas A2UI is hosted by the **Gateway canvas host** at:
 
 ```
-http(s)://<gateway-host>:18789/__clawdis__/a2ui/
+http://<gateway-host>:18793/__clawdis__/a2ui/
 ```
 
 The macOS app simply renders that page in the Canvas panel. The agent can drive it with JSONL **server→client protocol messages** (one JSON object per line):

docs/refactor/canvas-a2ui.md

@@ -16,10 +16,10 @@ Status: Implemented · Date: 2025-12-20
 - A2UI renders only when the **Gateway is reachable** (acceptable failure mode).
 
 ## Decision
-All A2UI HTML/JS assets are **served by the Gateway HTTP server** (single port,
-same as the Gateway WebSocket). Nodes (mac/iOS/Android) **navigate to the
-Gateway URL** before applying A2UI messages. No local custom-scheme or bundled
-fallback remains.
+All A2UI HTML/JS assets are **served by the Gateway canvas host** on
+`canvasHost.port` (default `18793`), bound to the **bridge interface**. Nodes
+(mac/iOS/Android) **navigate to the advertised `canvasHostUrl`** before applying
+A2UI messages. No local custom-scheme or bundled fallback remains.
 
 ## Why
 - One source of truth (TS) for A2UI rendering.
@@ -37,8 +37,8 @@ fallback remains.
 ## Gateway changes
 
 ### Serve A2UI assets
-Add A2UI HTML/JS to the Gateway Canvas host (same HTTP server as the Gateway
-WS), e.g.:
+Add A2UI HTML/JS to the Gateway Canvas host (standalone HTTP server on
+`canvasHost.port`), e.g.:
 
 ```
 /__clawdis__/a2ui/           -> index.html
@@ -49,14 +49,7 @@ Serve Canvas files at `/__clawdis__/canvas/` and A2UI at `/__clawdis__/a2ui/`.
 Use the shared Canvas host handler (`src/canvas-host/server.ts`) to serve these
 assets and inject the action bridge + live reload if desired.
 
-### Derive HTTP host from WebSocket
-Nodes derive the Canvas host URL from the Gateway WS URL:
-
-```
-ws://host:port  -> http://host:port
-wss://host:port -> https://host:port
-```
-
+### Canonical host URL
 The Gateway exposes a **canonical** `canvasHostUrl` in hello/bridge payloads
 so nodes don’t need to guess.
 
@@ -84,7 +77,7 @@ If `canvasHostUrl` is missing or unreachable:
 1) Gateway
    - Add A2UI assets under `src/canvas-host/`.
    - Serve them at `/__clawdis__/a2ui/` (align with existing naming).
-   - Serve Canvas files at `/__clawdis__/canvas/` on the Gateway port.
+   - Serve Canvas files at `/__clawdis__/canvas/` on `canvasHost.port`.
    - Expose `canvasHostUrl` in handshake + bridge hello payloads.
 2) Node runtimes
    - Update `canvas.a2ui.*` to navigate to `canvasHostUrl`.