> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase30-session07-play-runtime-integration/spec.md). # Session Specification **Session ID**: `phase30-session07-play-runtime-integration` **Phase**: 30 - AI Rogue Game Extension **Status**: Not Started **Created**: 2026-06-22 *** ## 1. Session Overview This session turns the completed AI Rogue foundations into the first playable run on `/extensions/ai-rogue/play`. Sessions 03, 05, and 06 already provide the lazy PixiJS v8 runtime boundary, browser-local persistence contracts, and pure deterministic dungeon simulation. The next required step is to make the runtime render simulation snapshots with committed pixel art, accept real controls, and surface game state through the React shell. The work replaces the current proof canvas with snapshot-driven sprite rendering. React continues to own routing, coarse controls, persistence UI, and accessible state, while PixiJS owns the canvas, stage lifecycle, textures, sprites, animation frame use, and keyboard/pointer command application. The session also adds the first wallet-backed loadout upgrade. The upgrade must consume browser-local Insight Shards, affect the next run in an obvious way, and remain a single MVP item so Session 08 can expand classes, relics, and progression depth without reworking the first playable slice. *** ## 2. Objectives 1. Render the deterministic simulation with committed gameplay and UI atlas frames instead of proof geometry. 2. Connect start, pause, reset, resume, save, load, win, loss, and run-complete events between the PixiJS runtime and React shell. 3. Add one wallet-backed loadout upgrade that is purchased through browser-local persistence, selected in Loadout, and applied to a run. 4. Apply reduced-motion, high-contrast, input-mode, pause, and focus behavior visibly at runtime with explicit loading, empty, error, offline, and denied states. *** ## 3. Prerequisites ### Required Sessions * [x] `phase30-session03-pixijs-runtime-boundary` - Provides lazy PixiJS v8 WebGL mount, ticker lifecycle, resize, input smoke events, reduced-motion sync, canvas cleanup, and Playwright nonblank canvas proof. * [x] `phase30-session05-persistence-and-save-contracts` - Provides browser-local preferences, wallet, ledger, run history, save-slot contracts, reset scoping, and `useAiRogueSaveState()`. * [x] `phase30-session06-dungeon-simulation-core` - Provides deterministic world generation, command reducer, FOV/fog, enemies, combat, pickups, win/loss snapshots, and fixture seeds. ### Required Tools Or Knowledge * Existing AI Rogue runtime modules in `src/extensions/ai-rogue/runtime/`. * Existing persistence and wallet modules in `src/extensions/ai-rogue/`. * Committed TexturePacker-style atlases in `src/assets/ai-rogue/`. * Play route, Loadout route, and runtime bridge components in `src/extensions/ai-rogue/views/`. * Phase 30 asset and privacy decisions in `docs/extensions/ai-rogue/`. ### Environment Requirements * Bun 1.3.14 project tooling. * PixiJS v8.19.0 remains lazy-loaded from the runtime route only. * Browser APIs are allowed only inside route/runtime/persistence boundaries that already own them; pure simulation modules stay browser-free. *** ## 4. Scope ### In Scope (MVP) * AI Rogue player can start and play one dungeon run - implemented by creating a simulation run inside the runtime controller, applying keyboard or pointer commands, and rendering snapshot changes every tick. * AI Rogue player can see committed art - implemented with gameplay atlas frames for tiles, fog, player, enemies, pickups, hazards, projectile threat feedback, and UI atlas frames for HUD pips, shard icon, run marker, relic, and basic panel pieces. * AI Rogue player can pause, resume, reset, save, load, win, lose, and complete a run without page reload - implemented through runtime events, bounded save slot metadata, run summary persistence, and duplicate-trigger prevention while mutations are in flight. * AI Rogue player can purchase and select one loadout upgrade - implemented as a single wallet-backed upgrade that debits Insight Shards through local persistence, records a privacy-safe ledger entry, and affects the next run. * AI Rogue accessibility preferences affect runtime behavior - implemented for reduced motion, high-contrast tiles, compact input mode, keyboard input mode, pause/focus handling, and visible shell state. ### Out Of Scope (Deferred) * Skill-linked classes, model-flavored resources, relic catalogs, achievements, expanded enemies, boss behavior, deeper floors, and content progression - Reason: Session 08 owns progression depth. * Mobile-first layout, pointer-first polish, optional audio, seed sharing, and final content polish - Reason: Session 09 owns content polish and mobile. * Enabling AI Rogue by default, final documentation, and full quality gate release evidence - Reason: Session 10 owns enablement. * WebGPU, workers, gamepad, pointer lock, remote content, collectors, server endpoints, raw generated-data writes, or hosted storage - Reason: Phase 30 keeps the first slice local, disabled-first, and browser-safe. *** ## 5. Technical Approach ### Architecture Keep the existing boundary shape. `runtime/renderer.ts` remains the only module that imports PixiJS. It should own Pixi application setup, atlas loading, stage containers, sprite pooling, ticker work, and cleanup. Pure helper modules should map simulation snapshots to frame names, draw positions, z-order, HUD state, and accessibility variants without importing PixiJS. Extend `runtime/assets.ts` from validation plus full-atlas proof loading into frame-level texture slicing for both gameplay and UI atlases. The renderer can then draw TexturePacker frames by name while preserving nearest-neighbor sampling and WebGL `preserveDrawingBuffer` verification. Add minimal loadout upgrade and wallet-spend helpers under the existing AI Rogue persistence boundary. Spending must be local, idempotent enough to avoid duplicate clicks while in flight, and recorded as bounded labels, IDs, amounts, and timestamps only. The first upgrade can be a small "Integrity Patch" style effect that increases starting health or shield status for the next run. Save/load should use the Session 05 save-slot contract by storing bounded runtime metadata or a serializable simulation snapshot envelope. It must not persist raw AI OS telemetry, prompts, commands, private paths, logs, Pixi objects, DOM nodes, or provider payloads. ### Design Patterns * Runtime-owned canvas: PixiJS owns sprites and render timing; React owns controls, route lifecycle, accessible labels, and persistence actions. * Snapshot projection: simulation state becomes draw commands before renderer mutation, keeping gameplay rules out of PixiJS objects. * Local transaction boundary: wallet debit, ledger entry, and selected upgrade persistence happen through existing browser-local persistence helpers with duplicate-trigger prevention while in-flight. * State reset on re-entry: route mount, reset, load, and disabled/unavailable transitions clear stale runtime state before accepting new commands. * Bounded browser-safe records: save slots and run summaries store stable IDs, labels, status, depth, turns, shards, and timestamps only. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/extensions/ai-rogue/runtime/render-model.ts` | Pure projection from simulation snapshots and preferences to tile/entity/HUD draw descriptors, z-order, and accessibility variants. | \~220 | | `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts` | Unit coverage for snapshot projection, fog layering, HUD descriptors, high contrast, and deterministic ordering. | \~180 | | `src/extensions/ai-rogue/__tests__/loadout-upgrade.test.ts` | Unit coverage for first upgrade purchase, wallet debit, ledger entry shape, duplicate prevention, and run-effect selection. | \~180 | ### Files To Modify | File | Changes | Est. Lines | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/extensions/ai-rogue/runtime/types.ts` | Add gameplay runtime event, controller, save/load, selected-upgrade, and snapshot metadata types needed by React callers. | \~140 | | `src/extensions/ai-rogue/runtime/assets.ts` | Add gameplay and UI frame texture creation helpers while preserving atlas validation and nearest-neighbor sampling. | \~160 | | `src/extensions/ai-rogue/runtime/renderer.ts` | Replace proof drawing with simulation-driven sprite containers, atlas frames, HUD pips, fog overlays, input application, lifecycle events, and cleanup. | \~420 | | `src/extensions/ai-rogue/runtime/index.ts` | Export new render model and runtime types without importing PixiJS into shared chunks. | \~30 | | `src/extensions/ai-rogue/views/runtime-canvas.tsx` | Wire runtime gameplay events, save/load controls, pause/resume/reset/start states, duplicate-trigger prevention, and accessibility status. | \~260 | | `src/extensions/ai-rogue/views/play-view.tsx` | Replace proof/readiness copy with playable run status, wallet/upgrade state, save slot state, completion feedback, and explicit unavailable/error/offline states. | \~220 | | `src/extensions/ai-rogue/views/loadout-view.tsx` | Add first upgrade purchase/select UI using wallet state, disabled/denied/loading states, and accessible controls. | \~260 | | `src/extensions/ai-rogue/use-save-state.ts` | Expose purchase/save/load helpers needed by Play and Loadout while keeping one mutation in flight. | \~140 | | `src/extensions/ai-rogue/persistence.ts` | Add local wallet spend, upgrade ledger, save-slot update, and run-summary write helpers with transaction boundaries where available. | \~240 | | `src/extensions/ai-rogue/save-schema.ts` | Extend wallet/ledger/save-slot schemas for one upgrade purchase and bounded simulation save metadata. | \~180 | | `src/extensions/ai-rogue/__tests__/client.test.tsx` | Cover Play and Loadout UI behavior for upgrade state, runtime events, and no private text leakage. | \~220 | | `src/extensions/ai-rogue/__tests__/persistence.test.ts` | Cover wallet spend, upgrade ledger records, save-slot writes, run summaries, duplicate prevention, and malformed storage handling. | \~220 | | `src/extensions/ai-rogue/__tests__/use-save-state.test.tsx` | Cover hook mutation sequencing for purchase, save, load, reset, offline, denied, and duplicate in-flight states. | \~200 | | `src/extensions/ai-rogue/runtime/__tests__/assets.test.ts` | Cover frame-level texture slicing for gameplay and UI frames and missing/malformed frame failures. | \~120 | | `tests/e2e/ai-rogue-runtime.spec.ts` | Update Playwright coverage for real atlas rendering, movement/fog feedback, pause/reset/resume, save/load, win/loss, and runtime cleanup. | \~220 | | `tests/e2e/ai-rogue-persistence.spec.ts` | Extend browser coverage for loadout purchase, wallet debit persistence, selected upgrade, run summary, and AI Rogue-only reset. | \~180 | *** ## 7. Success Criteria ### Functional Requirements * [ ] The Play route starts a deterministic run, renders tiles, fog, player, enemies, pickups, hazards, HUD pips, shard icon, run marker, relic icon, and combat feedback from committed atlas frames. * [ ] Keyboard and pointer input move the player through the simulation, reveal fog, trigger combat/pickup/hazard feedback, and do not mutate state while paused, loading, resetting, or unavailable. * [ ] Start, pause, resume, reset, save, load, win, loss, and run-complete events update React-visible state without page reload. * [ ] One wallet-backed loadout upgrade can be purchased once, consumes Insight Shards locally, records a privacy-safe ledger entry, and changes a run. * [ ] Save/load records and run summaries persist bounded game metadata only. ### Testing Requirements * [ ] Unit tests cover render projection, atlas frame slicing, upgrade purchase, wallet debit, save-slot metadata, run-summary writes, hook mutation sequencing, and malformed storage handling. * [ ] Component tests cover Play and Loadout states for loading, empty, error, offline, denied, insufficient funds, in-flight mutation, and success. * [ ] Playwright tests cover nonblank real-art canvas rendering, movement/fog feedback, pause/reset/resume, save/load, win/loss, route cleanup, and reset scoping. ### Non-Functional Requirements * [ ] PixiJS remains lazy-loaded through the runtime boundary and absent from registry, shell, and non-Play route chunks. * [ ] No server endpoint, network call, collector, generated-data write, hosted storage, credential flow, remote loading, worker, WebGPU, audio, gamepad, or pointer-lock surface is introduced. * [ ] Runtime records contain no raw prompts, transcripts, commands, private paths, credentials, logs, provider payloads, DOM nodes, Pixi objects, or browser storage objects. * [ ] Reduced-motion and high-contrast settings visibly affect runtime output. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Focused AI Rogue Vitest suites pass. * [ ] Focused AI Rogue Playwright suites pass. * [ ] `bun run typecheck` passes or any unrelated pre-existing failure is documented with evidence. * [ ] `bash scripts/check-asset-sizes.sh` remains passing because no new runtime media is added. *** ## 8. Implementation Notes ### Working Assumptions * The first upgrade should be a single fixed loadout item, not a general relic catalog: the Session 07 stub asks for one spendable upgrade, while Session 08 owns classes, model-flavored resources, expanded content, and progression depth. Planning can proceed with one bounded upgrade because it satisfies the MVP without preempting Session 08. * Save/load should persist bounded simulation metadata through existing browser-local save slots rather than a new storage surface: Session 05 already created save-slot and run-history contracts, and Phase 30 forbids hosted storage or generated-data writes. Planning can proceed by extending those contracts in place. ### Conflict Resolutions * Phase 30 PRD mentions a future `game/` runtime folder, but the implemented repo uses `src/extensions/ai-rogue/runtime/` and all completed Phase 30 code lives there. The existing repo path wins, so new runtime integration files stay under `runtime/`. * Session 05 deferred full dungeon-state persistence, while Session 07 requires save/load. The chosen interpretation is bounded playable-slice save metadata and serializable simulation state only, because Session 05 already validates safe save envelopes and Phase 30 prohibits raw/private runtime data. ### Key Considerations * Preserve PixiJS import isolation: only `runtime/renderer.ts` should import `pixi.js`; pure tests and route shell tests must not require PixiJS. * Keep wallet spending local and explicitly user-triggered; no automatic debit on route load or run start. * Treat browser storage denial and malformed records as normal degraded states, not fatal page crashes. * Preserve current AI Rogue-only reset scoping and unrelated storage safety. ### Potential Challenges * TexturePacker frame slicing in PixiJS v8: use a small helper and unit tests around frame rectangles before wiring all sprite layers. * Runtime state duplication between React and PixiJS: emit coarse gameplay events and use React for summaries, not per-sprite ownership. * End-to-end win/loss coverage: use Session 06 fixture seeds or a tiny test world path so Playwright does not depend on random exploration. * Wallet purchase transactions: use existing IndexedDB transaction boundaries where available and duplicate-trigger prevention in the hook/UI. ### Relevant Considerations * \[P02] **Static extension registry requires code changes**: Keep AI Rogue as a compile-time extension and avoid dynamic loading, marketplace behavior, eval, or remote code. * \[P02] **Extension payloads and labels stay bounded**: Runtime save/load and run summaries must use bounded browser-safe labels and metadata. * \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, and Cloudflare Worker compatibility constrain runtime imports and tests. * \[P08] **Playwright route interception plus DOM rect checks**: Reuse route interception, canvas pixel checks, and cleanup assertions for AI Rogue. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Runtime lifecycle leaks or stale commands after route exit, reset, load, or disabled transitions. * Duplicate wallet purchase, save, load, or reset actions while a mutation is in flight. * Storage denial, malformed save data, unavailable live data, offline state, or reduced-motion/high-contrast preferences silently leaving the UI inconsistent. *** ## 9. Testing Strategy ### Unit Tests * Test render-model projection for tile ordering, fog overlays, entity visibility, HUD descriptors, combat feedback, high contrast, and reduced motion. * Test atlas frame texture helpers for gameplay/UI frames, missing frames, malformed rectangles, and nearest-neighbor texture configuration. * Test upgrade purchase and wallet spend helpers for balance checks, duplicate attempts, ledger entry labels, and schema parsing. ### Integration Tests * Test `useAiRogueSaveState()` for purchase, save-slot write, load, reset, offline, denied, malformed storage, and one-operation-at-a-time behavior. * Test Play and Loadout components with mocked save state and runtime events for loading, empty, error, denied, insufficient funds, in-flight, and success states. ### Runtime Verification * Run Playwright for `/extensions/ai-rogue/play` to confirm real atlas pixels render, movement changes the canvas, pause blocks mutation, reset restarts the run, save/load restores bounded state, route exit destroys the canvas, and win/loss summaries appear. * Run Playwright for `/extensions/ai-rogue/loadout` to confirm wallet debit, selected upgrade persistence, disabled insufficient-funds state, and AI Rogue-only reset scoping. ### Edge Cases * Storage unavailable or permission denied. * Malformed save slot, wallet, ledger, or preferences records. * Purchase double-click while IndexedDB is in flight. * Load while runtime is running, resetting, hidden, or destroyed. * Reduced-motion preference toggled before and after runtime mount. * High-contrast preference toggled before and after texture layers exist. * Offline browser state with local save metadata available. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase30-session03-pixijs-runtime-boundary`, `phase30-session05-persistence-and-save-contracts`, `phase30-session06-dungeon-simulation-core` * Depended by: `phase30-session08-progression-depth`, `phase30-session09-content-polish-and-mobile`, `phase30-session10-quality-gates-and-enablement` *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase30-session07-play-runtime-integration/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.