Web: live serve dashboard, GitHub Pages landing-page deploy, and a browser-version plan

.github/workflows/ci.yml

@@ -43,3 +43,39 @@ jobs:
       uses: codecov/codecov-action@v4
       with:
         fail_ci_if_error: false
+
+  web:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+
+    - name: Regenerate golden-vector fixtures from the real parser
+      run: uv run python scripts/gen_web_fixtures.py
+
+    - name: Fail if committed fixtures drifted
+      run: git diff --exit-code web/fixtures
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: "22"
+        cache: npm
+        cache-dependency-path: web/package-lock.json
+
+    - name: Install web deps
+      run: npm ci
+      working-directory: web
+
+    - name: Typecheck (tsc)
+      run: npm run typecheck
+      working-directory: web
+
+    - name: Parity tests (vitest)
+      run: npm test
+      working-directory: web
+
+    - name: Build studio bundle
+      run: npm run build
+      working-directory: web

.github/workflows/pages.yml

@@ -0,0 +1,52 @@
+name: Deploy landing page
+
+# Publishes the static site/ to GitHub Pages on every push to main that touches it.
+# One-time setup: repo Settings → Pages → Source = "GitHub Actions".
+# URL: https://totalaudiopromo.github.io/audx/
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "site/**"
+      - "web/**"
+      - "src/audx/synth.py"
+      - "src/audx/pattern.py"
+      - "scripts/sync-web-modules.sh"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Sync browser-playground modules from src/
+        run: bash scripts/sync-web-modules.sh
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - name: Build the studio bundle (site/studio.js)
+        run: npm ci && npm run build
+        working-directory: web
+      - uses: actions/configure-pages@v5
+      - name: Upload site/
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v4

.vercelignore

@@ -0,0 +1,15 @@
+.git
+.venv
+node_modules
+**/node_modules
+__pycache__
+**/__pycache__
+marketing
+dist
+build
+*.egg-info
+*.wav
+*.mp4
+.pytest_cache
+htmlcov
+.coverage*

README.md

@@ -31,6 +31,10 @@ audx demo loop.wav
 
 <img src="docs/assets/audx-demo.gif" alt="audx demo session" width="640" />
 
+> **No install? Play it in your browser** — the real pattern language + synth kit run
+> client-side via Pyodide at [`/play.html`](site/play.html) on the landing page
+> (live once GitHub Pages is enabled).
+
 That writes a full multi-track beat — kick, sub, clap, hats, percussion — to
 `loop.wav` using the **built-in synth kit**. Open it and you're listening to
 audx. Then make your own:
@@ -174,7 +178,7 @@ Full walkthrough (kids included): [docs/playing-live.md](docs/playing-live.md).
 | **MIDI** | `export midi` · `midi out\|rec\|list` |
 | **AI (optional extras)** | `ai pattern\|similar\|tag\|groove\|key` |
 | **Bridges** | `plugins scan` · `push2 map\|lights` · `heartmula` · `sadact` · `daemon` |
-| **Live dashboard** | `serve` |
+| **Live dashboard** | `serve` · `open --serve` (host it from the TUI) |
 | **Diagnostics** | `doctor` · `version` |
 
 Run `audx --help` or `audx <command> --help` for details.

docs/README.md

@@ -5,6 +5,7 @@
 - [Pattern language](pattern-language.md) — the full DSL reference
 - [Built-in synth kit](synth-kit.md) — every voice, aliases and the fallback model
 - [Push 2 mapping](push2-mapping.md) — controller MIDI map scaffold
+- [Web version plan](web-version-plan.md) — how audx could run in the browser
 
 For the project overview, install instructions and command list, see the
 [top-level README](../README.md).

docs/handoff-next-session.md

@@ -0,0 +1,65 @@
+# Handoff — next session
+
+_Last updated: 2026-06-21. Branch: `claude/audx-team-launch-wyajz5` is the configured
+dev branch, but **all of this session's work lives on `claude/audx-web-and-serve` (PR #5)**
+to keep that PR coherent. Latest commit: `ef30c66`._
+
+## TL;DR
+A full **browser version of audx** ("audx studio") was built this session on top of the
+existing CLI, plus `audx serve` and a GitHub Pages landing site. Everything is verified
+locally (108 web tests, full Python suite, ruff/mypy, `tsc`, esbuild build). **Two things
+are blocked on the user, not on code.**
+
+## ⚠️ Blockers for the user (do these first)
+1. **CI is not triggering.** Despite "Actions sorted", pushes to `claude/audx-web-and-serve`
+   produce **zero** workflow runs (last repo run was 10:52Z on `main`, before PR #5 existed;
+   my 20:28Z push triggered nothing). `ci.yml` fires on `pull_request` (needs a push) and
+   `push` to `main`. Evidence points to an **Actions usage/billing cap** (CI ran fine for
+   `claude/audx-team-launch-wyajz5` in the morning, then stopped ~10:52). 
+   → Check **Settings → Billing → Actions minutes / spending limit**, not just the on/off
+   toggle. If not billing, **close + reopen PR #5** to force a fresh `pull_request` event.
+   Until CI runs, the `web` + Python CI jobs have never validated on a clean checkout — but
+   they pass locally.
+2. **GitHub Pages**: enable once at **Settings → Pages → Source = "GitHub Actions"** to
+   publish `site/` → https://totalaudiopromo.github.io/audx/ (studio at `/studio.html`,
+   DSL playground at `/play.html`).
+
+## What shipped (all on PR #5)
+- `audx serve` live dashboard, and `audx open --serve` to host it from the TUI.
+- Pages landing site (`site/`) + Pyodide DSL playground (`site/play.html`).
+- **audx studio** (`site/studio.html` + `web/` TypeScript, bundled to `site/studio.js`):
+  native synth, live Web Audio scheduler, velocity/accents, multi-bar, pan, mute/solo,
+  share links + WAV + **stems** export, **your-own-samples** (IndexedDB), **Web MIDI +
+  Push 2 LEDs**, and **CLI-interop songs** with **live song playback**.
+
+## Verification model (important context)
+The `web/` code mirrors Python and is **golden-vector tested** against it: fixtures are
+generated by `scripts/gen_web_fixtures.py` → `web/fixtures/*.json`, guarded by
+`tests/test_web_fixtures.py` (Python) and the CI `web` job. Parity covered: DSL parser,
+all 20 synth voices, Push 2 LED bytes, song timeline.
+**Not verifiable here (no browser):** visual look/feel, live audio timing, `decodeAudioData`,
+IndexedDB, File drag-drop, Web MIDI. These need a human in a browser → **ask the user to
+open `studio.html` and report** spacing/timing/levels.
+
+## Web app file map (`web/src/`)
+- `dsl.ts` — pattern DSL parser (port of `pattern.py`).
+- `synth.ts` — 20 voices (port of `synth.py`).
+- `types.ts` — Track/ProjectState, pan/velocity helpers.
+- `project.ts` — v3 URL/share + localStorage encoding (sample ref/name only).
+- `render.ts` — offline render: `renderProject` / `renderStems` / `renderSong`.
+- `samples.ts` — IndexedDB sample store + decode (CLI precedence: sample > synth).
+- `zip.ts` — store-only ZIP (stems bundle).
+- `song.ts` — Scene/Song, `timeline`, `songStepPlan`, CLI Song JSON interop.
+- `push2.ts` / `midi.ts` — Push 2 LED bytes + Web MIDI glue.
+- `studio.ts` — the app (scheduler, grid UI, transport, song panel).
+Build: `cd web && npm ci && npm run build` (esbuild → `../site/studio.js`).
+Test: `npm test` (vitest, 108) + `npx tsc --noEmit`. Python: `uv run pytest -q`.
+
+## Suggested next work (optional, not started)
+- Euclidean quick-fill per track (export `euclideanGrid` from `dsl.ts`), per-track
+  copy/clear/shift, computer-keyboard finger-drumming.
+- Once CI is green: confirm the `web` job passes on a clean checkout (npm ci/lockfile,
+  node setup, the `git diff --exit-code web/fixtures` drift gate).
+- Consider merging PR #5 once CI is green and the user has eyeballed the studio.
+
+Plan doc with full scope/parity detail: `docs/web-version-plan.md`.

docs/playing-live.md

@@ -145,6 +145,17 @@ audx song render track.json -o track.wav
 
 ---
 
+## Watch it on a second screen
+
+Host the live dashboard from the TUI and open it on a phone or tablet on the same
+Wi-Fi — handy for kids to watch the grid light up while someone else plays:
+
+```bash
+audx open --serve                 # then visit http://<this-computer>:8080/
+```
+
+The dashboard is read-only (a sequencer grid + meters that follow the session).
+
 ## Troubleshooting
 
 **No sound when I hit pads**

docs/releases/v0.3.0.md

@@ -0,0 +1,28 @@
+# audx v0.3.0 — make sound in ten seconds
+
+The release where audx makes music the moment you install it — no samples, no setup.
+
+## ✨ Highlights
+- **Zero-config sound** — a built-in 20-voice synth kit (drums + melodic: bass,
+  pluck, stab, keys, saw, sine). `audx render "kick 4/4"` and `audx demo loop.wav`
+  just work, with no sample library.
+- **Play it live** — `audx jam` turns any MIDI controller into an instrument
+  (drums, or `--chromatic` for melodies); the TUI also has computer-keyboard pads.
+- **Push 2 pads light up** — audx paints the drum kit on the pads and flashes each
+  one as you hit it (`audx push2 lights` for a quick check). Built to Ableton's spec.
+- **Songs** — `audx song render` builds multi-section tracks (intro/verse/drop/outro).
+- **Runs anywhere** — offline features (render, export, demo, diff) need no system
+  libraries; `python-rtmidi` is bundled so MIDI works out of the box.
+
+## Added
+- Built-in synth kit (14 drums + 6 melodic voices), `audx demo`, `audx synths`
+- `audx jam` live MIDI play; computer-keyboard TUI finger-drum pads
+- Push 2 pad LED control + `audx push2 lights`
+- `audx song render` / `song info` multi-section arrangements
+- Sample-less `render`; PortAudio now optional for offline use
+- Live `audx serve` dashboard (sequencer grid + meters)
+
+## Quality
+- Test suite 30 → 200+; type-checking clean across the whole package; uv-based CI
+
+Full details: [CHANGELOG.md](../../CHANGELOG.md).