Files
materialcraft/packaging/web/README.md
bflatasticandClaude Opus 5.5 6e952a9a10 Node engine: document model, image buffers, 120 nodes, cached graph cooking, packages, session and commands
A clean-room, pure-Rust foundation for MaterialCraft's node-based material
authoring: the package/graph/node model, float image planes, the node
library (atomic nodes, tileable noises, patterns, filters, PBR utilities,
function graphs for the pixel processor), a content-addressed cooking cache,
.mcraft packages and texture export, and the command-driven session with
snapshot undo. Infrastructure (xtask, CI, packaging) copied from TextureCraft.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 02:58:46 +07:00

89 lines
4.2 KiB
Markdown

# 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) |
| `_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.
## 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. 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`.
For nginx, check that `mime.types` has `application/wasm wasm;`.
- **Compression:** turn on gzip or Brotli for `.wasm`, `.js` and `.html` (a wasm file typically
shrinks to well under half). 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:** the app 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 /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)
```html
<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"`. 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
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.