playground: self-contain + publish to Pages at /playground/

Make wasm/playground/ self-contained so it deploys as a static dir: vendor the C-ABI driver (transpile.mjs + wasi-shim.mjs) and check in the prebuilt compiler roundhouse_wasm.wasm (3.2 MB) + a seed fixture.json; playground.js now imports/fetches from ./ instead of ../browser-spike/.

Add a build-site CI step that bundles _site/playground/ (copies the dir, regenerates fixture.json from the freshly-built real-blog so the editor's seed app tracks create-blog), mirroring how /blog/ is assembled. Link it from the landing page and the demo page.

The compiler wasm is checked in, NOT built in CI: a runner build needs the WASI SDK + a published ruby-rbs-sys (upstream-pending as ruby/rbs#2992). Rather than block on that, the binary is committed and refreshed by hand on compiler/emit changes (see wasm/playground/README.md). Switch to a CI build + drop the binary once #2992 lands. Documented in docs/browser-demo-plan.md (new 'Publishing to Pages' section).

Verified: self-contained playground and the CI-assembled bundle both pass verify-playground.mjs (Playwright); ci.yml is valid YAML.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rubys

.github/workflows/ci.yml

@@ -1317,6 +1317,33 @@ jobs:
           cp -R "$DEMO"/dist/. _site/blog/
           echo "blog demo files:"; find _site/blog -maxdepth 2 -type f | sort
 
+      # In-browser playground demo → _site/playground/. Where the blog ships
+      # the *emitted app*, this ships the *compiler itself* as wasm: edit Ruby,
+      # transpile to any target, in the browser. The self-contained
+      # wasm/playground/ dir (editor + vendored driver + prebuilt
+      # roundhouse_wasm.wasm) copies in as-is; fixture.json — the editor's seed
+      # app — is regenerated from the just-built real-blog so it tracks
+      # create-blog. The compiler wasm is CHECKED IN, not built here: a runner
+      # build needs the WASI SDK + a published ruby-rbs-sys (upstream-pending as
+      # ruby/rbs#2992) — see wasm/playground/README.md and the "Publishing to
+      # Pages" section of docs/browser-demo-plan.md. Pure static files (no
+      # npm/vite, no COOP/COEP), so it serves straight off Pages.
+      - name: Bundle the in-browser playground demo (→ _site/playground)
+        run: |
+          set -euo pipefail
+          mkdir -p _site/playground
+          cp wasm/playground/index.html \
+             wasm/playground/editor.js \
+             wasm/playground/playground.js \
+             wasm/playground/transpile.mjs \
+             wasm/playground/wasi-shim.mjs \
+             wasm/playground/roundhouse_wasm.wasm \
+             _site/playground/
+          # Fresh seed app from the just-generated real-blog fixture.
+          (cd wasm/browser-spike && node gen-fixture.mjs)
+          cp wasm/browser-spike/fixture.json _site/playground/fixture.json
+          echo "playground files:"; find _site/playground -type f | sort
+
       # Bench results page — fetched from the Hetzner publishing endpoint
       # (cron-driven, populates bench/results/latest on each run). The
       # render step degrades gracefully: if Hetzner is unreachable, the

docs/browser-demo-plan.md

@@ -115,6 +115,50 @@ verifiable development cycle."**
 Total: rung A alone **~2–3 days**; full arc through D.2 **~9–14 days**.
 A is independently shippable and de-risks everything after it.
 
+## Publishing to Pages
+
+The demos publish to `rubys.github.io/roundhouse/` through the same CI
+`build-site` job that ships `/blog/`, `/browse/`, and `/bench/`. The job
+assembles `_site/` (via `roundhouse::project::build_site`, which copies `site/`
+wholesale + writes the `browse/` archives) and then layers on the dynamic
+demos as extra steps before `upload-pages-artifact`. Two kinds of content:
+
+- **Static** → anything under `site/` is copied as-is (this is how `/demo/`
+  and the landing page ship). Links to the playground live in
+  `site/index.html` and `site/demo/index.html`.
+- **Generated** → a CI step writes into `_site/<dir>/`. `/blog/` emits the
+  worker-profile app and vite-builds it; **`/playground/`** copies the
+  self-contained `wasm/playground/` dir and regenerates `fixture.json` from the
+  just-built real-blog fixture (CI step "Bundle the in-browser playground
+  demo").
+
+**The playground is published with a checked-in compiler wasm — deliberately,
+not blocked on #2992.** Building `roundhouse_wasm.wasm` on a runner needs the
+WASI SDK *and* a `ruby-rbs-sys` reachable from CI; today that's a local-path
+`[patch.crates-io]` (the wasm32 build support is upstream-pending as
+ruby/rbs#2992). Rather than wait — it may be days, weeks, or never — the
+~3.2 MB `wasm/playground/roundhouse_wasm.wasm` is committed and the CI step
+just copies it. The cost is a manual refresh: after compiler/emit changes,
+rebuild and recommit the binary (`WASI_SDK_PATH=/opt/wasi-sdk cargo build
+--release --target wasm32-wasip1` in `wasm/`, copy it in, re-run
+`verify-playground.mjs`). See `wasm/playground/README.md` § Maintenance.
+
+**Switch-to-CI-build trigger:** when #2992 merges and `ruby-rbs-sys` publishes
+(or the patched crate is pushed to a CI-reachable git ref), replace the copy
+with a build step (install WASI SDK → `cargo build --target wasm32-wasip1` →
+regenerate fixture) and delete the checked-in binary. That closes honest-gap
+#1's second half. Until then, the playground is the only published surface
+carrying a binary artifact in git.
+
+The playground is pure static files (no npm/vite at serve time, no COOP/COEP),
+so — like `/blog/` — it serves straight off plain GitHub Pages. One thing to
+eyeball on the **first** deploy: that Pages serves the `.mjs` modules with a
+JS MIME (ES-module imports are MIME-strict) and the `./roundhouse_wasm.wasm`
+fetch succeeds. `transpile.mjs` uses `WebAssembly.instantiate(arrayBuffer)`
+(not `instantiateStreaming`), so the wasm's own MIME is irrelevant — only that
+the bytes load. If a `.mjs` MIME ever bites, rename the two driver modules to
+`.js`.
+
 ## The honest last-mile gaps (read before estimating)
 
 1. **WASI-in-browser (rung A, Phase 0). — RESOLVED.** The hand-rolled

site/demo/index.html

@@ -176,6 +176,8 @@ <h2>How it's tested</h2>
     <h2>See it</h2>
     <p>
       <a href="../blog/">Run the blog live</a> (TypeScript worker target) ·
+      <a href="../playground/">Transpile it yourself</a> in the browser — edit
+      the Ruby, watch any target's output update live ·
       <a href="../browse/">Browse the generated output</a> for every target ·
       <a href="../bench/">benchmark results</a> across the live targets ·
       <a href="../create-blog">download the generator script</a> ·

site/index.html

@@ -21,6 +21,7 @@ <h1>Roundhouse</h1>
 
     <nav class="landing-nav">
       <a href="demo/">The demo blog</a>
+      <a href="playground/">Playground</a>
       <a href="browse/">Browse generated output</a>
       <a href="bench/">Benchmark results</a>
       <a href="https://github.com/rubys/roundhouse">GitHub</a>

wasm/playground/README.md

@@ -4,10 +4,9 @@ The multi-target playground from `docs/browser-demo-plan.md` Phase 1: an
 editable Monaco source tree → in-browser `transpile` (wasm) → emitted output,
 with a target dropdown. No WebContainer, no npm, no bundler.
 
-Builds directly on the Phase 0 spike (`../browser-spike/`): it reuses that
-dir's `transpile.mjs` driver and its already-generated `roundhouse_wasm.wasm`
-+ `fixture.json`. What's net-new over the spike is the **editable** loop —
-source tree, editor, debounced edit → re-transpile.
+**Self-contained**: every asset it needs sits in this directory, so the whole
+dir copies straight to GitHub Pages at `/playground/` with no rewrite. This is
+what gets published (see "Publishing" below).
 
 ## Files
 
@@ -16,22 +15,22 @@ source tree, editor, debounced edit → re-transpile.
 | `index.html` | three-pane layout (sources / editor / output) | yes |
 | `editor.js` | editor abstraction: Monaco via CDN, `<textarea>` fallback | yes |
 | `playground.js` | app: tree, debounced transpile loop, output, test hooks | yes |
+| `transpile.mjs` / `wasi-shim.mjs` | C-ABI driver (vendored from `../browser-spike/`) | yes |
+| `roundhouse_wasm.wasm` | **prebuilt** compiler (~3.2 MB) — see Maintenance | yes |
+| `fixture.json` | seed app (real-blog), generated by `../browser-spike/gen-fixture.mjs` | yes |
 | `verify-playground.mjs` | Playwright: drive edit→transpile→render in chromium | yes |
 | `playground.png` | screenshot from the verifier | no (gitignored) |
 
 ## Run
 
-Serve the **`wasm/` directory** (one level up — so `../browser-spike/`
-imports + fetches resolve), then open `/playground/`:
+It's self-contained — serve **this** directory as the web root:
 
 ```sh
-# from wasm/ (after the spike's artifacts exist — see ../browser-spike/README.md):
-#   ../browser-spike/roundhouse_wasm.wasm and ../browser-spike/fixture.json
-python3 -m http.server 8099        # run from wasm/
-open http://localhost:8099/playground/
+python3 -m http.server 8099        # run from wasm/playground/
+open http://localhost:8099/
 
 # automated smoke check (chromium via tests/browser_smoke/node_modules):
-node playground/verify-playground.mjs
+node verify-playground.mjs
 ```
 
 ## What works
@@ -43,12 +42,31 @@ node playground/verify-playground.mjs
 - Monaco loads from a CDN; offline / headless / strict-CSP falls back to a
   `<textarea>` (the loop is identical through both — see `editor.js`).
 
+## Publishing
+
+The CI `build-site` job copies this dir into `_site/playground/` and
+regenerates `fixture.json` from the freshly-built real-blog fixture, so the
+published demo lands at `rubys.github.io/roundhouse/playground/`. See the
+"Publishing to Pages" section of `docs/browser-demo-plan.md`.
+
+## Maintenance (the prebuilt wasm)
+
+`roundhouse_wasm.wasm` is **checked in**, not built in CI — building it on a
+runner needs the WASI SDK plus a published `ruby-rbs-sys` (the wasm32 build
+support is upstream-pending as ruby/rbs#2992). Until that lands, refresh the
+compiler by hand after compiler/emit changes:
+
+```sh
+WASI_SDK_PATH=/opt/wasi-sdk cargo build --release --target wasm32-wasip1   # in wasm/
+cp ../target/wasm32-wasip1/release/roundhouse_wasm.wasm .
+node verify-playground.mjs    # confirm still green, then commit the new wasm
+```
+
+When #2992 (or a published patched `ruby-rbs-sys`) lands, switch the CI step to
+build the wasm and drop the checked-in binary.
+
 ## Known gaps / follow-ons
 
-- **Not yet packaged as a self-contained deploy dir.** It currently imports +
-  fetches from `../browser-spike/`, so it must be served from `wasm/` root.
-  Promoting the shared driver + artifacts into a deploy bundle (for
-  `rubys.github.io/roundhouse/playground/`) is follow-on packaging.
 - **ruby / spinel / kotlin / swift** are not in the target list — they aren't
   wired into `wasm/src/lib.rs`'s `match` yet (a one-line addition each).
 - **Output is read-only `<pre>`** (no syntax highlight); Monaco-for-output is

wasm/playground/fixture.json

@@ -1,21 +1,19 @@
 // Phase 1 — multi-target playground (rung A of docs/browser-demo-plan.md).
 //
-// Builds directly on the Phase 0 spike: reuses ../browser-spike/transpile.mjs
-// (the C-ABI driver) and the spike's already-generated artifacts
-// (roundhouse_wasm.wasm + fixture.json). What's net-new here over the spike:
-// an EDITABLE multi-file source tree, an editor (Monaco w/ textarea fallback),
-// and a debounced edit -> transpile -> render loop.
+// Self-contained: every asset it needs (the C-ABI driver transpile.mjs +
+// wasi-shim.mjs, the compiler roundhouse_wasm.wasm, and the seed app
+// fixture.json) sits in THIS directory, so the whole dir copies straight to
+// GitHub Pages at /playground/ with no rewrite. transpile.mjs + wasi-shim.mjs
+// are vendored copies of the Phase 0 spike's driver (kept in sync by hand —
+// they're small and stable). What's net-new over the spike: an EDITABLE
+// source tree, an editor (Monaco w/ textarea fallback), and a debounced
+// edit -> transpile -> render loop.
 //
-// Serve from the wasm/ directory root and visit /playground/ so the
-// ../browser-spike/ imports + fetches resolve. (Self-contained packaging into
-// its own deploy dir is a follow-on — see README.)
+// Serve THIS directory as the web root (e.g. `python3 -m http.server` here).
 
-import { loadCompiler } from "../browser-spike/transpile.mjs";
+import { loadCompiler } from "./transpile.mjs";
 import { createEditor } from "./editor.js";
 
-// Shared driver + artifacts live in the spike dir, one level up from here.
-const SPIKE = "../browser-spike";
-
 // The six targets the wasm entry point routes to today. (ruby/spinel/kotlin/
 // swift are not yet wired into wasm/src/lib.rs — a one-line match extension.)
 const TARGETS = ["typescript", "go", "rust", "python", "elixir", "crystal"];
@@ -144,8 +142,8 @@ async function boot() {
 
   setStatus("loading wasm + fixture…");
   const [wasmBytes, fixture] = await Promise.all([
-    fetch(`${SPIKE}/roundhouse_wasm.wasm`).then((r) => r.arrayBuffer()),
-    fetch(`${SPIKE}/fixture.json`).then((r) => r.json()),
+    fetch("./roundhouse_wasm.wasm").then((r) => r.arrayBuffer()),
+    fetch("./fixture.json").then((r) => r.json()),
   ]);
   srcMap = fixture;
   compiler = await loadCompiler(wasmBytes, {

wasm/playground/playground.js

@@ -0,0 +1,45 @@
+// Shared compiler driver: wraps the roundhouse-wasm C-ABI
+// (rh_alloc / transpile / rh_dealloc, packed u64 return) in a clean
+// transpile(language, srcMap) -> { files | error } interface. Uses only
+// WebAssembly + TextEncoder/Decoder, so the same module drives both the
+// Node validator and the browser page.
+
+import { makeWasi } from "./wasi-shim.mjs";
+
+// wasmBytes: ArrayBuffer | Uint8Array of roundhouse_wasm.wasm.
+// Returns { transpile(language, srcMap) } where srcMap is { path: content }.
+export async function loadCompiler(wasmBytes, wasiOpts = {}) {
+  const memoryRef = { value: null };
+  const wasi = makeWasi(memoryRef, wasiOpts);
+  const { instance } = await WebAssembly.instantiate(wasmBytes, {
+    wasi_snapshot_preview1: wasi,
+  });
+  memoryRef.value = instance.exports.memory;
+  if (instance.exports._initialize) instance.exports._initialize();
+
+  const { rh_alloc, rh_dealloc, transpile, memory } = instance.exports;
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+
+  return {
+    transpile(language, srcMap) {
+      const input = JSON.stringify({ language, src: srcMap });
+      const inputBytes = encoder.encode(input);
+
+      const inputPtr = rh_alloc(inputBytes.length);
+      new Uint8Array(memory.buffer, inputPtr, inputBytes.length).set(inputBytes);
+
+      const packed = transpile(inputPtr, inputBytes.length);
+      const outPtr = Number(packed & 0xffffffffn);
+      const outLen = Number(packed >> 32n);
+
+      const outBytes = new Uint8Array(memory.buffer, outPtr, outLen).slice();
+      const output = decoder.decode(outBytes);
+
+      rh_dealloc(inputPtr, inputBytes.length);
+      rh_dealloc(outPtr, outLen);
+
+      return JSON.parse(output);
+    },
+  };
+}

wasm/playground/roundhouse_wasm.wasm

@@ -14,15 +14,15 @@
 // the transpiler reflects recognized Rails DSL like `validates`, not arbitrary
 // methods — so the edit assertion uses a validation, which IS reflected.)
 //
-// Serve the wasm/ directory (NOT this dir) so ../browser-spike/ resolves:
-//   python3 -m http.server 8099    # run from wasm/
-//   node playground/verify-playground.mjs
+// Serve THIS directory as the web root (it's self-contained):
+//   python3 -m http.server 8099    # run from wasm/playground/
+//   node verify-playground.mjs
 
 import { createRequire } from "node:module";
 const require = createRequire("/Users/rubys/git/roundhouse/tests/browser_smoke/");
 const { chromium } = require("playwright");
 
-const URL = "http://localhost:8099/playground/index.html";
+const URL = "http://localhost:8099/index.html";
 const MODEL = "app/models/article.rb";
 
 const browser = await chromium.launch();