# Neon Nexus integration

## Ownership

| Concern | Authority |
|---------|-----------|
| Visuals, symbols, audio, cabinet, intro, win tiers, 5×4 / 5×5 layout, payline geometry | Neon Nexus artifact |
| Session bootstrap, wallet debit/credit, round IDs, Activity outbox, widget, localization shell | PlayerPal / Orbit Games host |
| Immutable outcome (stops, grid, wins, feature steps, total win) | Server (`POST /v1/rounds`) |

Do not replace production wallet or round APIs with the artifact’s demo balance or client-only RNG.

## Round contract

Server returns an immutable outcome containing at least:

- `round_id`, `bet`, `status`, `balance`
- `outcome.grid`, `outcome.win`, `outcome.tier`, `outcome.model_version`
- `outcome.base` (5×4 step with stops and wins)
- `outcome.feature` (null, or `{ steps }` of 5×5 nexus spins with rising `path_multiplier`)

The client animates that result and must not regenerate it.

## Lifecycle (client)

`READY → REQUESTING_RESULT → SPINNING → STOPPING → EVALUATING → PRESENTING_WIN → READY`

Feature presentation may insert explicit feature states; transitions stay named and ordered.

## Embedding

1. Launch via Bucks / Orbit provider launch session (play session token in memory only).
2. Host `demos/apps/provider-game-demo` (Vite) or its production build under the provider origin.
3. Assets resolve from `/neon-nexus/...` (no CDN Pixi runtime).
4. Optional PlayerPal widget uses `game-id=orbit-breaker` and `allowed-integration=pp_int_ORBIT_BUCKS` (platform ids unchanged).

## Commands

```bash
# Dev
task demos:provider-game
# or
cd demos/apps/provider-game-demo && npm run dev

# Test / build / export
cd demos/apps/provider-game-demo && npm test && npm run build
# Output: demos/apps/provider-game-demo/dist

# Math simulation (≥1e6 recommended)
cd services/orbit-games && SPINS=1000000 SEED=42 npm run simulate:rtp
cd demos/apps/provider-game-demo && npm run simulate
```

## Adapter surface

Initialize with session token (Authorization bearer), fixed bet ladder, and currency EUR. Spin requests `{ client_round_id, bet, rtp_profile? }` and presents `outcome`. `rtp_profile` is a development-only prototype control; production forces the reference profile unless the host explicitly enables demo profiles. Interrupt recovery uses `GET /v1/rounds/current` plus idempotent `POST /v1/rounds` with the same `client_round_id`.