Sparkade

A self-hosted arcade cabinet that generates its own SNES-era games from an optional photo of
the player (their likeness becomes the hero) and a voice prompt. Runs on a dev PC and on its
production target: a Raspberry Pi 3B+ inside a 3D-printed mini cabinet with a 1024×600 display,
USB webcam + mic, and arcade controls on a Zero Delay USB encoder.

Six golden games currently ship preinstalled with curated Muse-generated art packs, so the
cabinet is playable out of the box with no API key. Everything except the AI API calls works fully
offline.

The built-in racer is Spark Token Rally, starring Tom in a blue-and-ivory hover roadster.
Race through Neighborhood Loop, Creator Coast, and Festival Circuit against four friendly rivals,
collect Spark Tokens to bank boost, launch off coastal ramps, and choose a lane in the festival
finale. Its portraits, story scenes, five racers, course panoramas, scenery, and track materials
ship with the game and work offline.

---

Dev quickstart

npm install
npm run demo      # ← start here: full end-to-end flow with the MOCK provider
                  #    (no API key, no network; serves http://127.0.0.1:8080)

Other commands:

npm run dev       # Vite dev server (http://127.0.0.1:5173, HMR) + tsx-watch API server
npm run verify    # typecheck + eslint + unit tests + full build — must pass cleanly
npm run test:e2e  # Playwright at 1024×600 against demo mode (dev/CI only, never on the Pi)
npm run build     # web shell → packages/web/dist · server/cli → single Node bundles
npm run analyze:repairs # aggregate repair + incident patterns from the local data directory
npm run incidents -- list # review the local generation incident catalog

Keyboard controls (default map): arrows = d-pad, X=A, Z=B, A=X, S=Y,
Q=L, W=R, Enter=START, Right-Shift=SELECT. In dev mode the photo step offers a
file-upload fallback and the voice step offers canned transcripts.

Asset review (dev only): http://localhost:5173/?dev=assets (during npm run dev;
http://127.0.0.1:8080/dev/assets redirects there) is a tabbed gallery of the entire built-in
sprite library — heroes/ships, enemies, 12 bosses (four per archetype), NPCs, projectiles/pickups,
and 19 tile families including the default set — plus the bitmap font, all 11 procedural backdrops with live parallax,
the