Sparkade

# 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

```bash
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:

```bash
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