Topaz uses WebAssembly in products with different owners and trust boundaries. Choose the product before choosing a command.
1. Playground: first browser experiment
Use the site Playground to edit, check, and run a small Topaz program without installing the CLI. The browser loads the compiler and interpreter WebAssembly inside a Worker. This proves an interactive source experiment, not a deployed application or unrestricted browser access.
Start with First Program when you need the same experiment from an installed CLI.
2. Raw Web: an existing host calls Topaz
Choose Raw Web when an existing JavaScript ES-module host owns the UI and calls selected exported Topaz functions.
topaz build --target web main.tpz --release --out-dir web-product
The product contains topaz-web.js, topaz-web.d.ts, topaz-web.wasm, and
the common artifact files. Import instantiateTopaz from the generated module
and serve the directory over HTTP. The host must follow the generated typed ABI.
3. Worker: keep the same ABI off the main thread
Choose Worker when the existing host also needs generated request/response transport around the Raw Web product.
topaz build main.tpz --target web-worker --release --out-dir worker-product
The product adds topaz-web-worker.js and
topaz-web-worker-client.js. This does not create a UI or grant extra
capabilities; the JavaScript host still owns both.
4. Managed Web Application: Topaz owns the UI
Choose web-app when Topaz owns model, messages, update, view, and declared
browser capabilities.
topaz init --target web-app --root hello-web
topaz lock --root hello-web
topaz check --root hello-web --locked
topaz test hello-web/tests/app.tpz --root hello-web --locked
topaz dev --root hello-web --port 8000
topaz build --root hello-web --locked --release --out-dir web-app-product
This package-only target creates a complete static product with index.html,
the checked topaz-app.js host, Raw Web files, capability metadata, and
declared styles or assets. topaz dev is loopback-only and is not a production
server.
Requirements and recovery
Raw Web, Worker, and managed Web builds require Rust with
wasm32-unknown-unknown. The finished browser product does not require the
Topaz CLI or Rust. Serve it over HTTP; ES modules and WASM loaded directly
through file:// are not the supported path.
If the browser reports a host/runtime identity mismatch, deploy the complete directory from one build instead of mixing old JavaScript with new WASM. If a managed output directory has changed, preserve it and build into a new empty directory.