Web playground (WASM) for driving the complement engine from a phone

.github/workflows/web.yml

@@ -0,0 +1,51 @@
+name: web-playground
+
+# Builds the WASM playground (web/) and deploys it to GitHub Pages.
+# Enable once under repo Settings → Pages → Source: "GitHub Actions".
+
+on:
+  push:
+    branches: [main]
+    paths: ['web/**', 'core/**', '.github/workflows/web.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# One deploy at a time; let an in-progress run finish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install wasm target
+        run: rustup target add wasm32-unknown-unknown
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            web/target
+          key: web-wasm-${{ hashFiles('web/Cargo.toml', 'core/Cargo.toml') }}
+      - name: Build playground
+        run: ./web/build.sh
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: web/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@v4

Cargo.toml

@@ -2,8 +2,8 @@
 members  = ["core", "cli", "plugin", "preview"]
 # `fuzz/` is an isolated nightly cargo-fuzz crate (ADR-0010); it is
 # deliberately not a workspace member so stable `--workspace` builds,
-# clippy, and tests never touch it.
-exclude  = ["fuzz"]
+# clippy, and tests never touch it. `web/` is likewise wasm32-only (ADR-0024).
+exclude  = ["fuzz", "web"]
 resolver = "2"
 
 [workspace.package]

core/Cargo.toml

@@ -13,9 +13,16 @@ categories.workspace   = true
 [dependencies]
 midly      = { workspace = true }
 thiserror  = { workspace = true }
-guitarpro  = { version = "0.3", default-features = false }
+guitarpro  = { version = "0.3", default-features = false, optional = true }
 serde      = { workspace = true }
 
+[features]
+default = ["gp"]
+# Guitar Pro import. Pulls `guitarpro`/`zip` (and a `wasm-bindgen` subtree via
+# `time`/`getrandom`); disable it (`default-features = false`) for lean,
+# import-free wasm builds that only need MIDI — see ADR-0024.
+gp = ["dep:guitarpro"]
+
 [dev-dependencies]
 serde_json = { workspace = true }
 proptest   = { workspace = true }

core/src/import.rs

@@ -4,8 +4,9 @@
 //! content, so the product accepts either a `.gp3/.gp4/.gp5/.gpx` tab or a
 //! `.mid` file through one entry point.
 
+#[cfg(feature = "gp")]
+use crate::gp::{self, GpImportError};
 use crate::{
-    gp::{self, GpImportError},
     midi::{self, MidiError},
     score::Score,
 };
@@ -14,6 +15,7 @@ use crate::{
 #[derive(Debug, thiserror::Error)]
 pub enum ImportError {
     /// The bytes looked like Guitar Pro, but the Guitar Pro adapter failed.
+    #[cfg(feature = "gp")]
     #[error("Guitar Pro import failed: {0}")]
     Gp(#[from] GpImportError),
     /// The bytes were not Guitar Pro, and the MIDI adapter failed.
@@ -26,13 +28,15 @@ pub enum ImportError {
 /// Guitar Pro is tried first (it has a recognisable header); anything its
 /// detector rejects falls through to the MIDI importer. A Guitar Pro *parse*
 /// failure surfaces as [`ImportError::Gp`] rather than being masked by the MIDI
-/// fallback.
+/// fallback. Without the `gp` feature only MIDI is recognised.
 pub fn import_score_auto(data: &[u8]) -> Result<Score, ImportError> {
-    match gp::import_gp_score(data) {
-        Ok(score) => Ok(score),
-        Err(GpImportError::UnsupportedFormat) => {
-            midi::import_score(data).map_err(ImportError::Midi)
+    #[cfg(feature = "gp")]
+    {
+        match gp::import_gp_score(data) {
+            Ok(score) => return Ok(score),
+            Err(GpImportError::UnsupportedFormat) => {} // fall through to MIDI
+            Err(other) => return Err(ImportError::Gp(other)),
         }
-        Err(other) => Err(ImportError::Gp(other)),
     }
+    midi::import_score(data).map_err(ImportError::Midi)
 }

core/src/lib.rs

@@ -15,6 +15,7 @@ pub mod feature;
 pub mod fretboard;
 pub mod generate;
 pub mod gesture;
+#[cfg(feature = "gp")]
 pub mod gp;
 pub mod import;
 pub mod midi;

docs/adr/0024-web-wasm-frontend-for-mobile.md

@@ -0,0 +1,100 @@
+# ADR 0024: Ship the egui frontend to the browser (WASM) for mobile testing
+
+Date: 2026-06-16
+Status: Proposed
+
+## Context
+
+griff today runs only as a desktop CLI and a `ratatui` terminal preview (S8) —
+both tied to a computer terminal. The primary author/tester works almost
+entirely from a phone, so iterating on generation (tweaking seed / mode /
+variation and *hearing* the result) is impractical: every test means getting to
+a desktop.
+
+The pieces for a browser build are already in place:
+
+- **`griff-core` is WASM-clean.** It is pure compute — no filesystem, threads,
+  wall-clock, or the `rand` crate (the seeded PRNG is a hand-rolled `SplitMix64`
+  finalizer); all file I/O lives in the CLI. It compiles to
+  `wasm32-unknown-unknown` today (verified 2026-06-16), `serde` and collections
+  included.
+- **ADR-0016 already chose `egui`** as the GUI renderer over a shared UI core
+  (view-model → interaction core → scene → renderers), and **`eframe` builds the
+  *same* egui app to native desktop and web/WASM**. A browser build is therefore
+  not a new frontend — it is the planned egui renderer targeting the browser.
+- **S8 already lists** `eframe/egui window` and `MIDI playback` as its remaining
+  items; the pure `PianoRollView` / `Analysis` projections exist.
+
+What the browser changes versus the native plan is narrow: (1) audio — S8 planned
+`midir`, which has no web backend; (2) input — no filesystem; (3) build/hosting.
+
+## Decision
+
+1. **The canonical web frontend is the `eframe`/`egui` app compiled to
+   `wasm32-unknown-unknown`** — the same renderer ADR-0016 specifies. Native and
+   web share one codebase; the browser is a *build target*, not a fork. That is
+   the M2 target.
+
+2. **The M1 MVP is a thin, throwaway front, not egui** — an *import-free*
+   `cdylib` (`web/`, no `wasm-bindgen`, no framework) that exports three C-ABI
+   functions, plus a static `index.html` + `app.js` that loads the `.wasm` with
+   `WebAssembly.instantiate(bytes, {})` and marshals a small JSON result through
+   linear memory. This unlocks phone testing now without the egui/Trunk/
+   wasm-bindgen toolchain. It is disposable, not a second canonical renderer, so
+   it carries no ADR-0016 divergence debt; egui replaces it at M2.
+
+3. **`griff-core` gains a default-on `gp` feature** so the wasm build can drop
+   the Guitar Pro importer (`guitarpro`/`zip` → `time`/`getrandom` →
+   `wasm-bindgen`/`js-sys`). With `default-features = false` the module is
+   genuinely import-free and ~90 KiB; the CLI and tests keep `gp` on and are
+   unchanged.
+
+4. **Audio on web is WebAudio**, not the Web MIDI API (absent on iOS Safari,
+   patchy on mobile) and not `midir` (no web backend). The MVP uses a placeholder
+   oscillator synth fed note events from core; a bundled SoundFont (guitar tone)
+   is a follow-up. The playback *driver* is the one per-target seam.
+
+5. **Input is a fixed in-code sample** for the MVP (a file picker / drag-drop
+   later); the CLI keeps path-based I/O.
+
+6. **Build and host: `cargo build --target wasm32` → copy the `.wasm` beside the
+   static files → GitHub Pages** (`web/build.sh`, `.github/workflows/web.yml`).
+   No Trunk or `wasm-bindgen` for the MVP. A URL, no install.
+
+7. **Determinism is unaffected** (SPEC §6): the same controls yield the same
+   output in the browser too; the engine's seeded PRNG never touches wall-clock
+   or OS randomness.
+
+## Consequences
+
+- The maintainer can run complement — and the `VariationControl` knob — on a
+  phone via a URL. That is the actual ask.
+- The import-free `cdylib` needs no build tooling beyond the stock wasm target:
+  `cargo build --target wasm32-unknown-unknown` then static hosting. Tiny payload
+  (~90 KiB, ~35 KiB gzipped).
+- The `gp` feature gate also benefits any future wasm/plugin target that only
+  needs MIDI; it is a clean, default-on split.
+- At M2 the per-target surface becomes: one egui codebase for desktop + web, with
+  the playback driver (`midir` native / WebAudio web) and input (fs vs picker)
+  behind seams; a SoundFont (license-checked) lands for a real tone.
+- Accepted: the MVP synth is a placeholder (sawtooth + envelope), the roll is a
+  throwaway canvas painter, and the sample part A is fixed — all replaced as M2/M3
+  land.
+- Accepted: mobile browsers require a user gesture before audio starts (a tap to
+  unlock the `AudioContext`); SoundFont licensing/bundling is a real chore.
+- Accepted: the MVP roll is throwaway; the canonical piano-roll still needs the
+  ADR-0016 Scene/Viewport work (S8).
+- Out of scope for the MVP: offline PWA install, and corpus curation /
+  persistence on web (the `preview/design/` curation dock — later).
+
+## Roadmap
+
+Extends ADR-0016 and advances the S8 "egui window + playback" items toward a web
+target. If it grows beyond a playground it earns its own appended stage
+(append-only, per the stage-label audit).
+
+## See also
+
+- [`0016-shared-ui-core-across-frontends.md`](0016-shared-ui-core-across-frontends.md)
+- [`0007-clap-first-plugin-target.md`](0007-clap-first-plugin-target.md)
+- [`../stages/S8-preview-app.md`](../stages/S8-preview-app.md)

docs/adr/README.md

@@ -29,6 +29,7 @@ immutable; supersede it with a new one. New ADRs: copy
 | [0021](0021-property-invariants-over-canonical-score.md) | Property-based invariants over the canonical Score | Proposed |
 | [0022](0022-repeat-unfolding-as-projection.md) | Repeat unfolding is a projection, not a model rewrite | Proposed |
 | [0023](0023-variation-control-for-complement.md) | Control pitch/contour spread of complementary parts | Proposed |
+| [0024](0024-web-wasm-frontend-for-mobile.md) | Ship the egui frontend to the browser (WASM) for mobile testing | Proposed |
 
 See also: [`../SPEC.md`](../SPEC.md), [`../glossary.md`](../glossary.md),
 [`../decisions.log.md`](../decisions.log.md).

web/.gitignore

@@ -0,0 +1,3 @@
+/target
+/dist
+Cargo.lock

web/Cargo.toml

@@ -0,0 +1,31 @@
+# Excluded from the root workspace (see root Cargo.toml `exclude`): this crate
+# only builds for `wasm32-unknown-unknown`, like `fuzz/` only builds on nightly.
+[package]
+name = "griff-web"
+version = "0.0.0"
+edition = "2021"
+publish = false
+description = "Browser playground (WASM) for the griff engine — see docs/adr/0024."
+
+[lib]
+# `rlib` alongside `cdylib` lets the host-side unit tests link the crate; the
+# wasm build still emits the cdylib.
+crate-type = ["cdylib", "rlib"]
+
+# `default-features = false` drops the GP importer (guitarpro/zip/time/getrandom
+# → wasm-bindgen), leaving a lean, import-free wasm module.
+[dependencies]
+griff-core = { path = "../core", default-features = false }
+
+# A pure-compute WASM module: no unwinding (smaller, no import surface), squeezed
+# for mobile download.
+[profile.release]
+panic = "abort"
+opt-level = "z"
+lto = true
+codegen-units = 1
+strip = true
+
+# Own workspace root (like `fuzz/`): isolates the wasm-only target and profile
+# from the stable host workspace.
+[workspace]

web/README.md

@@ -0,0 +1,55 @@
+# griff web playground (WASM)
+
+A browser front for the complement arranger — built so the engine can be driven
+(and *heard*) from a phone, no install. See
+[`docs/adr/0024-web-wasm-frontend-for-mobile.md`](../docs/adr/0024-web-wasm-frontend-for-mobile.md).
+
+This is the **MVP** (ADR-0024 §2): a deliberately thin, throwaway front — no
+`wasm-bindgen`, no framework. `griff-web` is an *import-free* `cdylib` that
+exports three C-ABI functions; the page (`static/`) loads the `.wasm` with
+`WebAssembly.instantiate(bytes, {})` and marshals a small JSON result through
+linear memory. The canonical `egui` frontend (ADR-0016) replaces it at M2.
+
+## What it does
+
+Builds a fixed sample lead (part A) and a generated complement (part B) entirely
+in the browser, with live controls for **mode**, **seed**, **register offset**,
+and **pitch spread** (the ADR-0023 `VariationControl`, audible on the grid-locked
+modes). Deterministic: the same controls always produce the same result.
+
+## Build & run locally
+
+```sh
+./web/build.sh                              # → web/dist/ (wasm + static)
+python3 -m http.server -d web/dist 8080     # open http://localhost:8080
+```
+
+The crate is wasm32-only and excluded from the root workspace (like `fuzz/`), so
+stable `--workspace` builds/clippy/tests never touch it. It depends on
+`griff-core` with `default-features = false`, dropping the Guitar Pro importer
+(`guitarpro`/`zip`/`time`/`getrandom` → `wasm-bindgen`) — that is what keeps the
+module import-free and ~90 KiB.
+
+## ABI
+
+| export | signature | meaning |
+| --- | --- | --- |
+| `arrange` | `(mode:u32, seed:u32, offset:i32, variation:f32) -> *const u8` | arrange; returns a pointer to JSON in linear memory |
+| `arrange_len` | `() -> usize` | byte length of the last result |
+| `memory` | — | the linear memory JS reads the JSON from |
+
+`mode`: 0 `rhythm_lock`, 1 `register_contrast`, 2 `call_response`,
+3 `support_layer`, 4 `octave_double`, 5 `counter_melody`.
+
+Result JSON: `{ppqn, tempo, realized_spread, error, tracks:[{name, role, notes:[{p,s,d,v}]}]}`.
+
+## Deploy
+
+`.github/workflows/web.yml` builds `web/dist` and publishes it to GitHub Pages on
+pushes to the default branch (enable Pages → "GitHub Actions" in repo settings).
+
+## Notes / next
+
+- Audio is a placeholder WebAudio synth (sawtooth + envelope, A left / B right).
+  A real SoundFont (guitar tone) is a follow-up.
+- Input is a fixed in-code sample; a file picker / drag-drop comes later.

web/build.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Build the griff web playground into web/dist/ (static, deployable anywhere).
+#
+#   ./web/build.sh                              # release build → web/dist
+#   python3 -m http.server -d web/dist 8080     # then open http://localhost:8080
+#
+# No wasm-bindgen / Trunk: griff-web is an import-free cdylib (ADR-0024), so the
+# .wasm is copied next to the static files and loaded with WebAssembly.instantiate.
+set -euo pipefail
+here="$(cd "$(dirname "$0")" && pwd)"
+out="$here/dist"
+
+rustup target add wasm32-unknown-unknown >/dev/null 2>&1 || true
+( cd "$here" && cargo build --release --target wasm32-unknown-unknown )
+
+rm -rf "$out"
+mkdir -p "$out"
+cp "$here"/static/* "$out"/
+cp "$here"/target/wasm32-unknown-unknown/release/griff_web.wasm "$out"/
+
+size=$(wc -c < "$out/griff_web.wasm")
+echo "built web/dist ($((size / 1024)) KiB wasm) — serve it with:"
+echo "  python3 -m http.server -d \"$out\" 8080"