mirror of
https://github.com/storytold/figcraft.git
synced 2026-10-31 05:46:46 -06:00
BFlat
3c1718bf86
The web transport implements LiveLink::publish and the hosting and sharing background requests over the page's WebSocket. Managing connections run as exchanges (exchange.rs) in the browser client's driver; the requests and what their answers mean are shared with the desktop transport (requests.rs). The Share popover offers online sharing in the browser (no local network), and Publish to server opens there. Fixes #917.
129 lines
6.1 KiB
Markdown
129 lines
6.1 KiB
Markdown
# Hosting FigCraft for the web
|
|
|
|
`figcraft-web-<version>.zip` (from the GitHub release, or `packaging/web/package.sh`) holds a
|
|
static site in `figcraft-web-<version>/`:
|
|
|
|
| File | What it is |
|
|
|---|---|
|
|
| `index.html` | The page. It loads everything through relative URLs. |
|
|
| `figcraft-web-<hash>.js` | wasm-bindgen glue (generated, ES module) |
|
|
| `figcraft-web-<hash>_bg.wasm` | The app: about 18 MiB raw, 7 MiB with gzip, 4.5 MiB with Brotli (see [Sizes](#sizes)) |
|
|
| `_headers`, `.htaccess` | Sample header rules for Netlify/Cloudflare Pages and Apache |
|
|
|
|
There is no server-side code and no hand-written JavaScript: the glue is generated by
|
|
wasm-bindgen from the Rust sources (`apps/figcraft-web`). Upload the folder's contents anywhere
|
|
that serves static files.
|
|
|
|
The editor runs entirely on the visitor's device. The web build starts with one new document;
|
|
there is no desktop TCP control server, and native file dialogs aren't wired up yet. A browser
|
|
with WebGPU or WebGL2 and WebAssembly SIMD is required (any current browser; Safari 16.4 or later).
|
|
|
|
## Fonts
|
|
|
|
The web build draws text with the fonts it was built with. In browsers with Local Font Access
|
|
(Chromium: Chrome, Edge, Opera), the font menu's "Use fonts installed on this computer…" adds the
|
|
computer's fonts after the browser asks for permission; each is read only when text uses it.
|
|
|
|
## Live sessions
|
|
|
|
The web build can join a live session hosted by the desktop app (File ▸ Join live session…, then
|
|
paste the invite link), join files on a `figcraft-server`, and publish files to one (Share ▸ Online with
|
|
the server in Preferences, or Share ▸ Publish to server…); it can't host a session itself. Desktop-hosted sessions use plain `ws://`, which
|
|
browsers block from a page served over `https://` except to the same computer. To join sessions on
|
|
other machines, serve the site over `http://` on a trusted network (or use the desktop app);
|
|
`wss://` comes with the standalone server.
|
|
|
|
## Sizes
|
|
|
|
Measured on the 0.1.0 build (`trunk build --release`; gzip `-9`, Brotli quality 11):
|
|
|
|
| File | Raw | gzip | Brotli |
|
|
|---|---|---|---|
|
|
| `figcraft-web-<hash>_bg.wasm` | 18,534,563 bytes (17.7 MiB) | 7,023,460 (6.7 MiB) | 4,642,764 (4.4 MiB) |
|
|
| `figcraft-web-<hash>.js` | about 148 KB | about 22 KB | |
|
|
|
|
Per-file upload limits: Cloudflare Pages and Workers static assets reject any file over
|
|
**25 MiB** (26,214,400 bytes). `packaging/web/package.sh` fails the build if the wasm ever grows
|
|
past 24 MiB, so a release can't ship a file a common host refuses.
|
|
|
|
## Any path works
|
|
|
|
All URLs in `index.html` are relative (`public_url = "./"` in `apps/figcraft-web/Trunk.toml`),
|
|
so the site works at a domain root (`https://example.com/`), under a prefix
|
|
(`https://example.com/tools/figcraft/`) 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 18 MiB to about 7 MiB (gzip) or 4.5 MiB (Brotli). 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:** FigCraft 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 /figcraft/ {
|
|
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 8767` inside the folder, then open http://localhost:8767/.
|
|
|
|
## Embedding in a page (iframe)
|
|
|
|
```html
|
|
<iframe
|
|
src="https://example.com/figcraft/"
|
|
title="FigCraft interface design tool"
|
|
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.
|
|
- **Sandboxed iframes** need at least `sandbox="allow-scripts allow-same-origin allow-popups"`
|
|
(`allow-popups` lets Help links open in a new tab).
|
|
- Don't send `X-Frame-Options: DENY` or a `frame-ancestors` CSP that excludes the embedding page.
|
|
|
|
## Renderer selection and fallback flags
|
|
|
|
FigCraft renders with wgpu. It uses **WebGPU** when the browser has it and falls back to
|
|
**WebGL2** on its own. A URL query flag overrides this, and it works on the iframe `src` too:
|
|
|
|
| Flag | Effect |
|
|
|---|---|
|
|
| *(none)* | WebGPU if available, otherwise WebGL2 |
|
|
| `?webgl` | Force the WebGL2 backend (useful when a WebGPU driver misbehaves, and in headless browsers) |
|
|
|
|
For example: `<iframe src="https://example.com/figcraft/?webgl" ...>`.
|
|
|
|
A browser with neither WebGPU nor WebGL2 gets a message in place of the app.
|
|
|
|
## Smoke test (headless Chrome)
|
|
|
|
Headless Chrome exposes `navigator.gpu` but its adapter request returns nothing, so force WebGL2
|
|
on SwiftShader:
|
|
|
|
```sh
|
|
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new \
|
|
--use-angle=swiftshader --enable-unsafe-swiftshader --window-size=1440,900 \
|
|
--timeout=30000 --screenshot=figcraft-web.png "http://127.0.0.1:8767/?webgl"
|
|
```
|