diff --git a/crates/copper-cloud/assets/CANVAS_APP_REF b/crates/copper-cloud/assets/CANVAS_APP_REF
new file mode 100644
index 0000000..b1758d0
--- /dev/null
+++ b/crates/copper-cloud/assets/CANVAS_APP_REF
@@ -0,0 +1 @@
+c425198d038b3d563acb3e9102f0f5e71676f6a8
diff --git a/crates/copper-cloud/assets/canvas-app.html b/crates/copper-cloud/assets/canvas-app.html
index 139903a..4dccca6 100644
--- a/crates/copper-cloud/assets/canvas-app.html
+++ b/crates/copper-cloud/assets/canvas-app.html
@@ -7,49 +7,49 @@
Canvas
-
-
diff --git a/crates/copper-cloud/src/canvas_app.rs b/crates/copper-cloud/src/canvas_app.rs
index 9354089..664a13f 100644
--- a/crates/copper-cloud/src/canvas_app.rs
+++ b/crates/copper-cloud/src/canvas_app.rs
@@ -1,11 +1,12 @@
//! Canvas App at `/canvas/`: the canvas in any browser, for people who are not on Copper
-//! (`copper-browser/canvas-app`, its `dist/web/index.html`, vendored as `assets/canvas-app.html`
-//! by `packaging/sync-canvas-app.sh`). Served from the server's own origin so its REST calls
-//! need no CORS (the server grants none, and the gate would refuse a preflight); it reaches
-//! the linked Canvas Cloud through the same `/v1/canvases…` proxy Copper uses, and its room
-//! socket carries the gate credential as `?instance=`
-//! (`copper_cloud_core::app::INSTANCE_QUERY`), since a browser cannot set headers on a
-//! WebSocket. The page is one self-contained file with its own CSP in a `` tag.
+//! (`copper-browser/canvas-app`, its `dist/web/index.html` at the commit pinned in
+//! `assets/CANVAS_APP_REF`, vendored as `assets/canvas-app.html` by
+//! `packaging/sync-canvas-app.sh`). Served from the server's own origin so its REST calls need
+//! no CORS (the server grants none, and the gate would refuse a preflight); it reaches the
+//! linked Canvas Cloud through the same `/v1/canvases…` proxy Copper uses, and its room socket
+//! carries the gate credential as `?instance=` (`copper_cloud_core::app::INSTANCE_QUERY`), since
+//! a browser cannot set headers on a WebSocket. The page is one self-contained file with its own
+//! CSP in a `` tag.
use axum::http::{header, HeaderValue, StatusCode};
use axum::response::{IntoResponse, Redirect, Response};
diff --git a/docs/canvas.md b/docs/canvas.md
index b0b8664..985b9fd 100644
--- a/docs/canvas.md
+++ b/docs/canvas.md
@@ -142,9 +142,12 @@ Under the Copper button it links to `/canvas/#/join/{token}` for people who are
## Canvas App (`/canvas/`)
`GET /canvas/` serves [Canvas App](https://github.com/copper-browser/canvas-app): the canvas in
-any browser. It is one self-contained file, vendored as
-`crates/copper-cloud/assets/canvas-app.html`. `packaging/sync-canvas-app.sh [REF]` updates it;
-`--check` compares it. The route is ungated, like the landing page, and holds no data.
+any browser. It is one self-contained file, canvas-app's `dist/web/index.html` at the commit
+pinned in `crates/copper-cloud/assets/CANVAS_APP_REF`, vendored as
+`crates/copper-cloud/assets/canvas-app.html`. `packaging/sync-canvas-app.sh REF` pins a new
+commit and fetches its build; with no argument it re-fetches the pinned one, and `--check`
+compares the vendored file with it. The route is ungated, like the landing page, and holds no
+data.
The app reaches the linked Canvas Cloud through the same proxy Copper uses. It runs on the
server's own origin, so its REST calls need no CORS, which copper-cloud never grants. To use it,
diff --git a/packaging/sync-canvas-app.sh b/packaging/sync-canvas-app.sh
index 5cc9c5b..6a2d056 100755
--- a/packaging/sync-canvas-app.sh
+++ b/packaging/sync-canvas-app.sh
@@ -1,24 +1,35 @@
#!/usr/bin/env bash
-# Vendor Canvas App (copper-browser/canvas-app, dist/web/index.html) as
+# Canvas App lives in copper-browser/canvas-app. copper-cloud vendors its web build,
+# dist/web/index.html, at the commit pinned in crates/copper-cloud/assets/CANVAS_APP_REF, as
# crates/copper-cloud/assets/canvas-app.html, which the server serves at /canvas/.
-# packaging/sync-canvas-app.sh [REF] fetch REF (default main) from GitHub
-# packaging/sync-canvas-app.sh --from FILE copy a local build
-# packaging/sync-canvas-app.sh --check [REF] exit 1 if the vendored copy differs
+# packaging/sync-canvas-app.sh re-fetch the pinned build (e.g. after editing CANVAS_APP_REF)
+# packaging/sync-canvas-app.sh REF pin REF (a canvas-app commit, tag or branch, resolved to a commit) and fetch it
+# packaging/sync-canvas-app.sh --check exit 1 if canvas-app.html is not the pinned build
+# packaging/sync-canvas-app.sh --from FILE vendor a local build (canvas-app: bun run build) — for trying changes; pin before merging
set -euo pipefail
-cd "$(dirname "$0")/.."
-dest=crates/copper-cloud/assets/canvas-app.html
-check=0
-if [[ "${1:-}" == --check ]]; then check=1; shift; fi
+cd "$(dirname "$0")/../crates/copper-cloud/assets"
+repo=copper-browser/canvas-app
+pin=CANVAS_APP_REF
+dest=canvas-app.html
+fetch() {
+ curl -fsSL "https://raw.githubusercontent.com/$repo/$1/dist/web/index.html" -o "$2"
+ grep -q 'id="web-root"' "$2" || { echo "sync: $1 has no Canvas App web build" >&2; exit 2; }
+}
tmp=$(mktemp); trap 'rm -f "$tmp"' EXIT
-if [[ "${1:-}" == --from ]]; then
- cp "$2" "$tmp"
-else
- ref=${1:-main}
- curl -fsSL "https://raw.githubusercontent.com/copper-browser/canvas-app/$ref/dist/web/index.html" -o "$tmp"
-fi
-grep -q 'id="web-root"' "$tmp" || { echo "not a Canvas App build" >&2; exit 2; }
-if (( check )); then
- cmp -s "$tmp" "$dest" && echo "canvas-app.html is up to date" || { echo "canvas-app.html differs from ${ref:-the given file}" >&2; exit 1; }
-else
- cp "$tmp" "$dest" && echo "vendored $(wc -c <"$dest") bytes into $dest"
-fi
+case "${1:-}" in
+ --check)
+ fetch "$(cat "$pin")" "$tmp"
+ cmp -s "$tmp" "$dest" && echo "canvas-app.html matches canvas-app $(cat "$pin")" || { echo "canvas-app.html differs from canvas-app $(cat "$pin"): run packaging/sync-canvas-app.sh" >&2; exit 1; }
+ ;;
+ --from)
+ cp "$2" "$dest"; echo "vendored $2 (not pinned: run packaging/sync-canvas-app.sh REF before merging)"
+ ;;
+ "")
+ fetch "$(cat "$pin")" "$dest"; echo "vendored canvas-app $(cat "$pin")"
+ ;;
+ *)
+ sha=$(gh api "repos/$repo/commits/$1" --jq .sha 2>/dev/null || git ls-remote "https://github.com/$repo.git" "$1" | cut -f1)
+ [[ -n "$sha" ]] || { echo "sync: no canvas-app ref $1" >&2; exit 2; }
+ fetch "$sha" "$dest"; echo "$sha" > "$pin"; echo "pinned canvas-app $sha"
+ ;;
+esac