Signed release pipeline (macOS/Windows/Linux/Web); README community note

Ports photocraft's release workflow + packaging (signing, notarization, MSI/DMG/deb/rpm/AppImage/web), adds `cargo xtask version`. File-type associations omitted for now (route B); app keeps its own .desktop. Fresh WiX UpgradeCode. README 'about' note updated. Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-10-14 19:26:56 -04:00 · 2026-10-02 11:35:29 -04:00
1 parent 7b37dd1da5
commit da8a14dd04
@@ -0,0 +1,16 @@
+# Apache (see HOSTING.md). Needs mod_mime; mod_deflate and mod_headers are optional.
+AddType application/wasm .wasm
+AddType text/javascript .js
+
+<IfModule mod_deflate.c>
+  AddOutputFilterByType DEFLATE application/wasm text/javascript text/html
+</IfModule>
+
+<IfModule mod_headers.c>
+  <FilesMatch "\.(wasm|js)$">
+    Header set Cache-Control "public, max-age=31536000, immutable"
+  </FilesMatch>
+  <FilesMatch "^index\.html$">
+    Header set Cache-Control "no-cache"
+  </FilesMatch>
+</IfModule>
@@ -0,0 +1,89 @@
+# Hosting VectorCraft for the web
+
+`vectorcraft-web-<version>.zip` (from the GitHub release, or `packaging/web/package.sh`) holds a
+static site in `vectorcraft-web-<version>/`:
+
+| File | What it is |
+|---|---|
+| `index.html` | The page. It loads everything through relative URLs. |
+| `vectorcraft-web-<hash>.js` | wasm-bindgen glue (generated, ES module) |
+| `vectorcraft-web-<hash>_bg.wasm` | The app, about 13 MB, or 5 MB with compression |
+| `_headers`, `.htaccess` | Sample header rules for Netlify/Cloudflare Pages and Apache |
+
+There is no server-side code. Upload the folder's contents anywhere that serves static files.
+
+## Any path works
+
+All URLs in `index.html` are relative (`public_url = "./"` in `apps/vectorcraft-web/Trunk.toml`),
+so the site works at a domain root (`https://example.com/`), under a prefix
+(`https://example.com/tools/vectorcraft/`) and from a CDN bucket. The asset names carry a content
+hash, so they can be cached forever. Only `index.html` needs revalidation.
+
+## Required server settings
+
+- **MIME type:** serve `.wasm` as `application/wasm`. Browsers refuse to stream-compile it under
+  any other type, and the app then loads slowly or not at all. Serve `.js` as `text/javascript`.
+  Most hosts already do both. For nginx, check that `mime.types` has `application/wasm wasm;`.
+- **Compression:** turn on gzip or Brotli for `.wasm`, `.js` and `.html`. That takes the
+  download from about 13 MB to about 5 MB. You can also precompress (`brotli -k *.wasm`) and let
+  the server send `Content-Encoding: br`.
+- **Caching:** `Cache-Control: public, max-age=31536000, immutable` on the hashed `.wasm` and
+  `.js` files, and `no-cache` on `index.html`.
+- **HTTPS:** WebGPU (and the clipboard) only work in a secure context, which means `https://`
+  or `http://localhost`. Over plain HTTP elsewhere, the app falls back to WebGL2.
+- **No special isolation headers:** VectorCraft doesn't use `SharedArrayBuffer`, so it doesn't
+  need `Cross-Origin-Opener-Policy` or `Cross-Origin-Embedder-Policy`. If your site already sends
+  COEP `require-corp`, also send `Cross-Origin-Resource-Policy: same-origin` (or `cross-origin`
+  when the files live on a CDN) on the app's files.
+
+nginx example:
+
+```nginx
+location /vectorcraft/ {
+    types { application/wasm wasm; text/javascript js; text/html html; }
+    gzip on;
+    gzip_types application/wasm text/javascript text/html;
+    location ~* \.(wasm|js)$ { add_header Cache-Control "public, max-age=31536000, immutable"; }
+    location ~* index\.html$ { add_header Cache-Control "no-cache"; }
+}
+```
+
+Local test: `python3 -m http.server 8765` inside the folder, then open http://localhost:8765/.
+
+## Embedding in a page (iframe)
+
+```html
+<iframe
+  src="https://example.com/vectorcraft/"
+  title="VectorCraft image editor"
+  style="width: 100%; height: 720px; border: 0;"
+  allow="fullscreen; clipboard-read; clipboard-write"
+  allowfullscreen>
+</iframe>
+```
+
+- The app fills the iframe and follows its size, so size the iframe and not the app.
+- Keyboard shortcuts go to the iframe after the user clicks into it, as with any embedded app.
+- **Cross-origin embeds** work. Preferences are kept in the iframe's `localStorage`. Browsers
+  that partition or block third-party storage may forget them between visits, and the app
+  then starts with defaults.
+- **Sandboxed iframes** need at least
+  `sandbox="allow-scripts allow-same-origin allow-downloads allow-popups"`. Without
+  `allow-same-origin` there's no storage. Without `allow-downloads`, Save and Export (browser
+  downloads) are blocked.
+- Don't send `X-Frame-Options: DENY` or a `frame-ancestors` CSP that excludes the embedding page.
+
+## Renderer selection and fallback flags
+
+VectorCraft renders with wgpu. It uses **WebGPU** when the browser has it and falls back to
+**WebGL2** on its own. URL query flags override this, and they work on the iframe `src` too:
+
+| Flag | Effect |
+|---|---|
+| *(none)* | WebGPU if available, otherwise WebGL2 |
+| `?webgl` | Force the WebGL2 backend (useful when a WebGPU driver misbehaves) |
+| `?cpu` | Force the CPU canvas path (slowest, most compatible) |
+
+For example: `<iframe src="https://example.com/vectorcraft/?webgl" ...>`.
+
+A browser with neither WebGPU nor WebGL2 gets a message in place of the app.
@@ -0,0 +1,13 @@
+# Netlify / Cloudflare Pages header rules (see HOSTING.md). Other hosts: set the same headers.
+/*
+  X-Content-Type-Options: nosniff
+
+/*.wasm
+  Content-Type: application/wasm
+  Cache-Control: public, max-age=31536000, immutable
+
+/*.js
+  Cache-Control: public, max-age=31536000, immutable
+
+/index.html
+  Cache-Control: no-cache
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Build the browser version and zip it:  $DIST/vectorcraft-web-<version>.zip
+#
+# Usage: packaging/web/package.sh [--skip-build]
+#
+# Needs: trunk (brew install trunk / cargo install trunk --locked) and the wasm32-unknown-unknown
+# target. The zip holds a self-contained static site in vectorcraft-web-<version>/ that works
+# from any URL path and inside an <iframe>. Hosting notes: packaging/web/README.md.
+set -euo pipefail
+# shellcheck source=../env.sh
+. "$(dirname "${BASH_SOURCE[0]}")/../env.sh"
+HERE="$ROOT/packaging/web"
+
+if [ "${1:-}" != "--skip-build" ]; then
+  command -v trunk >/dev/null || { echo "error: trunk not found (cargo install trunk --locked)" >&2; exit 1; }
+  (cd "$ROOT/apps/vectorcraft-web" && trunk build --release)
+fi
+
+SITE="$ROOT/dist/web"
+[ -f "$SITE/index.html" ] || { echo "error: $SITE/index.html missing; run without --skip-build" >&2; exit 1; }
+# Paths must be relative so the site works under any prefix (public_url = "./" in Trunk.toml).
+if grep -Eq '(src|href)="/[^/]' "$SITE/index.html"; then
+  echo "error: $SITE/index.html has root-absolute URLs; it would break when served from a sub-path" >&2
+  exit 1
+fi
+
+NAME="vectorcraft-web-$VERSION"
+WORK="$CARGO_TARGET_DIR/web-package"
+rm -rf "$WORK"
+mkdir -p "$WORK/$NAME"
+cp -R "$SITE/." "$WORK/$NAME/"
+# Sample server configs (MIME type, caching, compression); harmless where unused.
+cp "$HERE/_headers" "$HERE/.htaccess" "$WORK/$NAME/"
+cp "$HERE/README.md" "$WORK/$NAME/HOSTING.md"
+copy_docs "$WORK/$NAME"
+rm -f "$DIST/$NAME.zip"
+(cd "$WORK" && zip -qr9 "$DIST/$NAME.zip" "$NAME")
+echo "wrote $DIST/$NAME.zip"
+ls -lh "$DIST/$NAME.zip"