Tutorial

Tutorial 5: WebAssembly and the web

Chapter 5 of 5. The complete example is on this page; every line of code compiles as shown.

Compile the same Rust authoring layer to wasm32-unknown-unknown, then copy its RGBA framebuffer into a canvas. This tutorial adds a small, separate example library to the existing web/ workspace; it does not change the site's ABI or workload registry.

The Rust side owns one Rendered frame. A successful tutorial_render replaces it. A failure returns -1, and the page does not display a new frame. The pointer and length are borrowed observations: JavaScript must copy the pixels before another render can replace the frame. Read memory.buffer after rendering because Wasm memory can grow. The sample page performs no asynchronous work between taking the view and copying it.

This starter has a fixed 640×360 framebuffer. Its HTML theme button is a normal DOM control you can reach by keyboard. The canvas has a descriptive text name, but it does not expose a full semantic tree: integrating application controls, focus, text input, IME, resize and accessibility needs a host bridge. See the repository's web/aster-web/demo/ for the existing interactive adapter. A canvas alone is not a replacement for every app control.

Complete Rust example

Source: tutorial_web.rs web/aster-web/examples/tutorial_web.rs. The paired HTML page web/aster-web/examples/tutorial_web.html contains the full fetch, error handling and canvas-copy code.

Rust
//! A minimal framebuffer-only WebAssembly starter. See docs/tutorials/05-wasm-web.md.
//! The frame is owned here; JavaScript copies it before the next render.
use aster_blueprint::ui::prelude::*;
use std::cell::RefCell;

thread_local! {
    static FRAME: RefCell<Option<Rendered>> = const { RefCell::new(None) };
}

#[unsafe(no_mangle)]
pub extern "C" fn tutorial_render(alternate: u32) -> i32 {
    let theme = if alternate == 0 { Theme::paper_dark() } else { Theme::paper_light() };
    let root = col([
        text("Hello from WebAssembly").style(Type::Headline),
        text("The Rust scene supplies these canvas pixels.").wrap_fit(),
    ]).gap(3).pad(6);
    match Screen::new(&theme).and_then(|screen| screen.size(640, 360).render(&root)) {
        Ok(frame) => { FRAME.with(|slot| *slot.borrow_mut() = Some(frame)); 0 }
        Err(_) => -1,
    }
}

#[unsafe(no_mangle)]
pub extern "C" fn tutorial_frame_ptr() -> *const u8 {
    FRAME.with(|slot| slot.borrow().as_ref().map_or(std::ptr::null(), |f| f.image.rgba.as_ptr()))
}

#[unsafe(no_mangle)]
pub extern "C" fn tutorial_frame_len() -> usize {
    FRAME.with(|slot| slot.borrow().as_ref().map_or(0, |f| f.image.rgba.len()))
}

Compile and serve

Prerequisites: a Rust toolchain supporting edition 2024, its wasm32-unknown-unknown standard library, Python 3, and a browser with WebAssembly and Canvas 2D support. Install the target once if your toolchain does not already provide it:

Shell
rustup target add wasm32-unknown-unknown

The example exports C functions and has no main, so Cargo must build it as a library; without this step cargo check stops with error[E0601]: main function not found in crate tutorial_web. Append this to web/aster-web/Cargo.toml once:

TOML
[[example]]
name = "tutorial_web"
crate-type = ["cdylib"]

Then, from the repository root, use the existing web workspace's vendored dependency configuration:

Shell
cd web
cargo check --locked -p aster-web --example tutorial_web
cargo check --locked -p aster-web --example tutorial_web --target wasm32-unknown-unknown
cargo build --locked --release -p aster-web --example tutorial_web --target wasm32-unknown-unknown
mkdir -p tutorial-preview
cp "${CARGO_TARGET_DIR:-target}/wasm32-unknown-unknown/release/examples/tutorial_web.wasm" tutorial-preview/tutorial_web.wasm
cp aster-web/examples/tutorial_web.html tutorial-preview/index.html
python3 -m http.server 8080 --bind 127.0.0.1 --directory tutorial-preview

Open http://127.0.0.1:8080. Stop the preview with Ctrl-C. The loopback binding keeps this development page local; it is not a deployment command. If the dependency vendor directory is absent in a sparse checkout, use a complete SDK checkout rather than reconstructing it.

What you will see

The page reports when it has loaded and drawn the Rust scene. A canvas displays “Hello from WebAssembly”. Switch theme redraws it with the other paper theme. If fetching or rendering fails, the status text reports the error instead of drawing an invalid frame.

Next steps

Keep the model and screen in Rust as you add interaction. Connect a host's input and accessibility layers explicitly. If you add animation, use requestAnimationFrame to drive the App clock and present only new frames; do not spin a render loop while idle. The SDK's existing web adapter and byte-exact oracle are useful references, but their benchmark results are not performance promises for this example.