docs(badapple): current MAME demo quick start

bad-apple/README.md

@@ -13,6 +13,35 @@ Design: [`../docs/superpowers/specs/2026-10-31-bad-apple-vector-design.md`](../d
 Plan: [`../docs/superpowers/plans/2026-11-01-bad-apple-vector.md`](../docs/superpowers/plans/2026-11-01-bad-apple-vector.md)
 Measurements and gaps: [`REPORT.md`](REPORT.md)
 
+## Quick start — current MAME demo
+
+From the repository root:
+
+```sh
+# 1. video -> data/movie.bin
+cd bad-apple
+python3 -m pipeline.build \
+    --video /tmp/opencode/badapple-real/hd60.mp4 \
+    --out data --duration 30
+cd ..
+
+# 2. payload
+bad-apple/player/build.sh
+
+# 3. watch it
+bad-apple/tools/run_mame_gui.sh
+```
+
+`run_mame_gui.sh` starts MAME with `VT1200_SKIP_LEVEL1=1`, boots the OS, loads
+the payload at frame 2500, lets it take over, writes the movie into low RAM,
+and plays it in a window. Expect the 30 s clip at full screen, upright.
+`BA_END` (default 8000) is the MAME frame at which the loader script exits;
+raise it if your run is slower.
+
+The **network path is currently disabled in practice**: the OS heap cannot
+provide one contiguous 2.4 MB `malloc_` block, so `tools/load.sh` stops before
+it binds UDP. Use the debugger path above. See `REPORT.md`.
+
 ## Build the 30 s stream
 
 ```sh
@@ -47,21 +76,24 @@ The 1987 TI TMS34010 SDK runs under DOSBox. The C sources are K&R C: the
 
 ## Run in MAME (debugger path)
 
+For a window, use `tools/run_mame_gui.sh` (above). For scripted/headless
+checks:
+
 ```sh
 # one frame, then dump VRAM at MAME frame 2700
 VT1200_DUMP_VRAM_FRAMES=2700 VT1200_DUMP_DIR=/tmp/ba-one \
     bad-apple/tools/run_mame.sh one
 
-# 5 s slice, paced
+# 5 s slice, paced (headless)
 BA_MOVIE=bad-apple/data5/movie.bin BA_START=0 BA_COUNT=300 \
     bad-apple/tools/run_mame.sh play
 
-# full 30 s, paced
+# full 30 s, paced (headless)
 BA_MOVIE=bad-apple/data/movie.bin BA_MOVIE_BASE=0x00080000 \
     BA_WAIT=1 BA_PACE=1 bad-apple/tools/run_mame.sh play
 ```
 
-`run_mame.sh` exits when the payload sets its status marker. The debugger
+`run_mame.sh` runs with `-video none`; it exits at `BA_END`. The debugger
 loader writes the movie into high RAM (`0x01D00000`) for small slices; for the
 full 30 s it uses `BA_WAIT=1`, lets the payload take over, then writes low RAM
 at `0x00080000` — the same ordering as the real delivery path.
@@ -76,9 +108,10 @@ disables interrupts and plays.
 bad-apple/tools/load.sh --host <unit-ip> --movie bad-apple/data/movie.bin
 ```
 
-This path is implemented but **not yet verified on the unit or over MAME's
-tap** in this worktree: the tap was down. The OS socket API it uses is the one
-already proven by `harness/udpstream/udpstream.c`. See `REPORT.md`.
+**This path is currently blocked** at `malloc_(2401942)`: the OS heap does not
+give one contiguous 2.4 MB block, so the payload never binds UDP. The debugger
+path above is the working demo. A fixed low-RAM staging receive or raw-LANCE
+loader is the next step. See `REPORT.md`.
 
 ## Data format
 

bad-apple/REPORT.md

@@ -83,9 +83,11 @@ refuses to jump unless the whole-file checksum matches. Out-of-range packets
 are dropped without reading or writing outside the buffer.
 
 Status: the packet format, header offset, checksum path and sender are
-unit-tested; the MAME tap was down in this worktree, so the UDP receive was
-not exercised end-to-end. The same OS socket API is already proven on the unit
-by `harness/udpstream/udpstream.c`. This is the one delivery-path gap.
+unit-tested. The live MAME tap test reaches the payload but stops before UDP
+bind: the marker shows `status=0x20` and no socket is open. The suspect is
+`malloc_(2401942)` — the OS heap does not provide one contiguous block that
+size. The debugger path is the working demo. A fixed low-RAM staging receive
+or raw-LANCE loader is the next step. This is the one delivery-path gap.
 
 ## Regression
 

bad-apple/tools/run_mame_gui.sh

@@ -0,0 +1,39 @@
+#!/bin/sh
+# Run the current debugger-path demo in a MAME window.
+#
+#   bad-apple/tools/run_mame_gui.sh
+#   M=/path/to/vt1200 BA_MOVIE=/path/to/movie.bin bad-apple/tools/run_mame_gui.sh
+#
+# The payload is loaded at frame BA_AT, takes over, and plays the full movie.
+# Close the window or let it exit at BA_END.  Recovery after takeover is a
+# power cycle (in MAME: Shift+F3 or close the window).
+set -eu
+
+HERE=$(cd "$(dirname "$0")" && pwd)
+ROOT=$(cd "$HERE/../.." && pwd)
+M=${M:-/home/arti/code/k-space/mame0289/vt1200}
+BA_MOVIE=${BA_MOVIE:-$ROOT/bad-apple/data/movie.bin}
+BA_AT=${BA_AT:-2500}
+BA_END=${BA_END:-8000}
+
+if [ ! -x "$M" ]; then
+    echo "run_mame_gui.sh: no MAME binary at $M" >&2
+    exit 1
+fi
+if [ ! -f "$BA_MOVIE" ]; then
+    echo "run_mame_gui.sh: no movie at $BA_MOVIE" >&2
+    echo "  build it with: cd bad-apple && python3 -m pipeline.build ..." >&2
+    exit 1
+fi
+if [ ! -f "$ROOT/bad-apple/player/build/player.bin" ]; then
+    echo "run_mame_gui.sh: no payload; run bad-apple/player/build.sh" >&2
+    exit 1
+fi
+
+cd "$ROOT"
+VT1200_SKIP_LEVEL1=1 \
+BA_MOVIE="$BA_MOVIE" BA_MOVIE_BASE=0x00080000 BA_WAIT=1 BA_PACE=1 \
+BA_AT="$BA_AT" BA_END="$BA_END" \
+"$M" vt1200 -rompath harness/mame/roms -sound none -skip_gameinfo -window \
+    -debug -debugger none \
+    -autoboot_script "$ROOT/bad-apple/tools/load_mame.lua" -autoboot_delay 0