Add chidori-wasm: the engine + replay runtime in the browser (#147)

Author: kvey

.github/workflows/docs.yml

@@ -12,6 +12,11 @@ on:
       - "docs/**"
       - "website/**"
       - ".github/workflows/docs.yml"
+      # The /playground page ships the wasm runtime + browser SDK.
+      - "crates/chidori-wasm/**"
+      - "crates/chidori-js/**"
+      - "sdk/browser/**"
+      - "scripts/build-wasm.sh"
   workflow_dispatch:
 
 permissions:
@@ -35,6 +40,20 @@ jobs:
           node-version: 22
           cache: npm
           cache-dependency-path: website/package-lock.json
+      # Build the /playground wasm assets (engine + browser SDK) into
+      # website/public/chidori-wasm before the site build. wasm-bindgen-cli
+      # must match the wasm-bindgen pin in crates/chidori-wasm/Cargo.toml.
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: docs-wasm
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: wasm-bindgen@0.2.126
+      - name: Build wasm playground assets
+        run: scripts/build-wasm.sh
       - name: Install dependencies
         run: npm ci
         working-directory: website

.gitignore

@@ -7,6 +7,9 @@
 # Vendored Test262 conformance suite (fetched by scripts/test262.sh, ~56k files)
 /vendor/test262/
 
+# wasm-bindgen output for the browser demo (regenerate with scripts/build-wasm.sh)
+/crates/chidori-wasm/www/pkg/
+
 # macOS
 .DS_Store
 
@@ -56,6 +59,8 @@ node_modules/
 /website/out/
 /website/.source/
 /website/next-env.d.ts
+# Playground runtime assets, mirrored from the wasm build by scripts/build-wasm.sh
+/website/public/chidori-wasm/
 
 # Secrets / local env
 .env

Cargo.lock

@@ -2,6 +2,7 @@
 members = [
     "crates/chidori",
     "crates/chidori-js",
+    "crates/chidori-wasm",
     "crates/test262-runner",
 ]
 # Bare `cargo run` / `cargo build` at the workspace root mean the CLI — the

Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "chidori-wasm"
+version = "0.1.0"
+edition = "2021"
+# oxc 0.133 (via chidori-js) relies on `if let` guards, stabilized in Rust 1.95.
+rust-version = "1.95"
+description = "Browser embedding of the chidori-js engine and durable replay runtime, via wasm-bindgen."
+publish = false
+readme.workspace = true
+repository.workspace = true
+license.workspace = true
+
+[lib]
+# cdylib for the wasm-bindgen artifact; rlib so the native workspace build and
+# `cargo test --workspace` can compile and run this crate's unit tests.
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+chidori-js = { path = "../chidori-js", version = "0.3.3" }
+# TypeScript stripping for browser-authored agents, mirroring the native
+# runtime's transpile defaults (crates/chidori/src/runtime/typescript). Same
+# version/features as chidori-js, so this adds no new crates to the build.
+oxc = { version = "0.133", features = ["semantic", "transformer", "codegen"] }
+serde_json = "1"
+# Kept in lockstep with the wasm-bindgen-cli version used by
+# scripts/build-wasm.sh — the CLI refuses to process a module built by a
+# different crate version.
+wasm-bindgen = "0.2.126"
+
+# Workspace-wide lint levels (see [workspace.lints] in the root Cargo.toml).
+[lints]
+workspace = true

crates/chidori-wasm/Cargo.toml

@@ -0,0 +1,60 @@
+# chidori-wasm
+
+The chidori-js engine — bytecode compiler, VM, GC, builtins, and the durable
+replay runtime — compiled to WebAssembly and driven from a browser page.
+
+The engine crate is pure Rust (`#![forbid(unsafe_code)]`, no C, no threads, no
+filesystem), so it builds for `wasm32-unknown-unknown` unmodified. This crate
+adds only the boundary: a `wasm-bindgen` wrapper around
+`chidori_js::replay::ReplayRuntime` that exposes the record/replay pump to
+JavaScript.
+
+## The pump protocol
+
+The page owns the event loop and the host effects (fetch, time, randomness,
+prompts). The runtime is a pump:
+
+```js
+const rt = new WasmRuntime(bundle, ['now', 'random', 'httpFetch']);
+for (;;) {
+  const status = JSON.parse(rt.runUntilBlocked());
+  if (status.status === 'completed') break;
+  // status: { status: 'blocked', opId, name, args }
+  const result = await host[status.name](...status.args);   // e.g. fetch()
+  rt.resolveOp(status.opId, JSON.stringify(result));        // journaled
+}
+const blob = rt.toBlob();   // durable artifact: bundle + effects + journal
+```
+
+`WasmRuntime.fromBlob(blob)` restores in replay mode: journaled effects are
+served from the journal (no network, no reruns of anything non-deterministic),
+and the pump only surfaces ops past the recorded frontier — so a suspended run
+can resume in a fresh tab, or a completed run can replay with byte-identical
+output and zero live host calls. The blob is the same `DurableBlob` artifact
+the native runtime uses.
+
+## Build and run the demo
+
+```sh
+rustup target add wasm32-unknown-unknown
+cargo install wasm-bindgen-cli   # version must match Cargo.toml's wasm-bindgen pin
+
+scripts/build-wasm.sh
+python3 -m http.server -d crates/chidori-wasm/www 8080
+# open http://localhost:8080 — record a run, then replay it offline
+```
+
+## What stays native
+
+The `chidori` CLI crate is deliberately not part of the wasm build: it is the
+*host* side — tokio, reqwest, axum, SQLite session stores, OS sandboxing
+(seccomp/Landlock) — and in the browser those responsibilities belong to the
+page (fetch, IndexedDB/localStorage, the browser sandbox). The engine and the
+journal format are shared; the host is swapped.
+
+## Tests
+
+The driver core is plain Rust (`src/lib.rs`, `driver` module), so the full
+record → suspend → resolve → replay cycle runs under `cargo test -p
+chidori-wasm` on the native target; browser behavior is exercised by the demo
+page.