figcraft/packaging/web

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)
_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.

A site served beside its own figcraft-server can name it in index.html: <meta name="figcraft-server" content="wss://figcraft.example.com/"> (a ws:// or wss:// address without a query). The page then uses it as the server for online sharing, join codes and the server's team list (Home ▸ Online), without anyone setting it in Preferences.

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:

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)

<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.

Host mode (?host=parent, or the page's own document)

A page can embed FigCraft so that it hands files over instead of downloading them and reports unsaved changes. Two opt-in transports carry the same messages:

• ?host=parent on the iframe's URL (https://example.com/figcraft/?host=parent): a same-origin framing page talks to the app over postMessage. Opened outside an iframe, the URL gives the normal app with downloads; with a parent on another origin there is no host mode either (messages to another origin are dropped silently, so saves would be lost while the document looked saved).
• data-host="page" (the exact value page) on the canvas: a page that loads the module into its own document gets the same behaviour over DOM CustomEvents on the canvas, with no iframe (see below).

Message	Direction	Fields
figcraft:ready	app → page	version: the app is running and listening; send a file now
figcraft:open	page → app	name, bytes (an ArrayBuffer or Uint8Array): open like File › Open (a payload over the browser open limit of 512 MB is refused; anything malformed is ignored)
figcraft:save	app → page	name, saveAs, bytes (a transferred ArrayBuffer): every file the app would otherwise download. The page stores it and reports failures itself. saveAs says whether the file becomes the document's file: false after Save of the file the page sent, under its own name; true for a document file (.figcraft, .json) under a name the page didn't send — Save As, or a Save of a document the page never sent — after which the next Save carries that name with false; false for copies and exports that don't become the document (rendered images, SVG, PDF, .fig copies, the variables exports)
figcraft:dirty	app → page	dirty: unsaved changes appeared or went away
figcraft:failed	app → page	error: the app couldn't start (no WebGPU or WebGL2, for example)

Files reach the page through the app's download service, the path this web build saves by: Save As (and a Save of a document with no file yet), the .fig copy, the export panel and its dialog, Export frames as PDF, plugin output and the variables export (Variables panel ▸ Export…). In host mode each arrives as figcraft:save instead of a download.

In host mode the app starts with no document (the home screen), so the page sends the file to edit and guards leaving the page while changes are unsaved. &author= on the URL names the user for comments and board notes.

Same-document host mode

The host application loads the wasm-bindgen module itself and gives FigCraft one of its own canvases, so there is no iframe and no ?host=parent. It opts in with data-host="page" on that canvas — the exact value page — and the canvas keeps the id the app looks up (id="figcraft_canvas"):

<canvas id="figcraft_canvas" data-host="page" style="width: 100%; height: 720px; display: block;"></canvas>

The page and the app then talk with DOM CustomEvents on the canvas instead of postMessage. The app dispatches the same messages it would post to a parent — figcraft:ready, figcraft:save, figcraft:dirty, figcraft:failed — with the message fields (without the type) as the event's detail, and it opens a document when the page dispatches a figcraft:open event with detail: { name, bytes }. Events do not bubble, so listen on the canvas itself (two editors on one page can't hear each other).

Add the listeners before init: the app announces itself with figcraft:ready while init is still running, and a file sent in reply would otherwise be missed.

import init from "./figcraft-web-<hash>.js"; // the wasm-bindgen glue shipped with the app

const canvas = document.getElementById("figcraft_canvas");

canvas.addEventListener("figcraft:ready", async () => {
  // The app is listening; hand it a document now, if you have one.
  const bytes = await documentBytes(); // an ArrayBuffer or Uint8Array
  canvas.dispatchEvent(new CustomEvent("figcraft:open", {
    detail: { name: "Poster.figcraft", bytes },
  }));
});

// Every file FigCraft would otherwise download arrives here.
canvas.addEventListener("figcraft:save", (event) => {
  const { name, saveAs, bytes } = event.detail; // bytes is an ArrayBuffer
  // Store the file under `name`; `saveAs` says whether it becomes the document's file.
  // Report your own errors.
  storeFile(name, bytes, saveAs);
});
canvas.addEventListener("figcraft:dirty", (event) => {
  unsaved = event.detail.dirty; // warn before leaving, as you like
});
canvas.addEventListener("figcraft:failed", (event) => {
  showError(event.detail.error); // the app couldn't start
});

await init({ module_or_path: "./figcraft-web-<hash>_bg.wasm" });

• Saves are not downloads in this mode: the bytes in figcraft:save hold the file, and the host decides where it goes.
• ?author= on the page's URL still names the user for comments and board notes.
• An unframed page that uses ?host=parent keeps the normal app with downloads; only the exact data-host value page turns this mode on.

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:

"/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"