* web: ship the SBS library's bitmaps beside the wasm, not inside it The SBS library import (#219) embeds every file under assets/sbs into every build, the browser one included. Its resources/ bitmaps are already compressed PNG/EXR/BMP (14.1 MB, deflate saves 1%), and with them the release wasm grew from 14.3 MB to 33.3 MB, past the 24 MiB gate in packaging/web/package.sh that guards Cloudflare Pages' 25 MiB file cap. The nightly Release dry run has failed on Web (wasm) since. For wasm32 the formats build script now leaves resources/ out of the embedded library and lists it as EXTERNAL_ASSETS. index.html copies assets/sbs/resources to sbs/resources in the dist, and the web app downloads those files at startup (in parallel, before the session is created) and hands them to library::install, so library::read serves them as before. A failed download is logged and surfaces as a missing asset on the nodes that use it; startup goes on. Native builds still embed everything. * web: bound the startup download of the library resources A response that sends headers and then stalls would keep download_library, and with it the loading screen, pending for good. One AbortController now covers every request and body, aborted after two minutes; whatever is still pending fails, is logged, and startup goes on without it.
Hosting MaterialCraft for the web
materialcraft-web-<version>.zip (from the GitHub release, or packaging/web/package.sh) holds a
static site in materialcraft-web-<version>/:
| File | What it is |
|---|---|
index.html |
The page. It loads everything through relative URLs. |
materialcraft-web-<hash>.js |
wasm-bindgen glue (generated by trunk, ES module) |
materialcraft-web-<hash>_bg.wasm |
The app (built with the wasm-release Cargo profile) |
sbs/resources/ |
The SBS library's bitmaps and their licences, downloaded when the app starts |
_headers, .htaccess |
Sample header rules for Netlify/Cloudflare Pages and Apache |
There is no server-side code and no hand-written JavaScript: trunk generates the glue from the
Rust crate apps/materialcraft-web. Upload the folder's contents anywhere that serves static files.
packaging/web/package.sh fails the build when a .wasm grows past 24 MiB, because Cloudflare
Pages and Workers reject any file over 25 MiB. That is why the SBS library's bitmaps ship in
sbs/resources/ instead of inside the wasm.
Any path works
All URLs in index.html are relative (public_url = "./" in apps/materialcraft-web/Trunk.toml),
so the site works at a domain root (https://example.com/), under a prefix
(https://example.com/tools/materialcraft/) and from a CDN bucket. The asset names carry a content
hash, so they can be cached forever. index.html and the files in sbs/ have no hash and need
revalidation.
Required server settings
- MIME type: serve
.wasmasapplication/wasm. Browsers refuse to stream-compile it under any other type, and the app then loads slowly or not at all. Serve.jsastext/javascript. For nginx, check thatmime.typeshasapplication/wasm wasm;. - Compression: turn on gzip or Brotli for
.wasm,.jsand.html(a wasm file typically shrinks to well under half). You can also precompress (brotli -k *.wasm) and let the server sendContent-Encoding: br. - Caching:
Cache-Control: public, max-age=31536000, immutableon the hashed.wasmand.jsfiles, andno-cacheonindex.html. - HTTPS: WebGPU (and the clipboard) only work in a secure context, which means
https://orhttp://localhost. Over plain HTTP elsewhere, the app falls back to WebGL2. - No special isolation headers: the app doesn't use
SharedArrayBuffer, so it doesn't needCross-Origin-Opener-PolicyorCross-Origin-Embedder-Policy. If your site already sends COEPrequire-corp, also sendCross-Origin-Resource-Policy: same-origin(orcross-originwhen the files live on a CDN) on the app's files.
nginx example:
location /materialcraft/ {
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)
<iframe
src="https://example.com/materialcraft/"
title="MaterialCraft procedural material designer"
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-downloads allow-popups". Withoutallow-same-originthere's no storage. Withoutallow-downloads, Save and Export (browser downloads) are blocked. - Don't send
X-Frame-Options: DENYor aframe-ancestorsCSP that excludes the embedding page.
Renderer selection and fallback flags
MaterialCraft 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, and for headless smoke tests) |
The viewport needs a GPU backend, so there is no CPU-only mode. A browser with neither WebGPU nor WebGL2 gets a message in place of the app.