> 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/phases/phase_30/prd_phase_30.md). # PRD Phase 30: AI Rogue Game Extension **Status**: Complete **Sessions**: 10 (initial estimate) **Estimated Duration**: 6-10 days **Progress**: 10/10 sessions (100%) *** ## Overview Build `AI Rogue`, a repo-local AI OS extension that is a real playable roguelike rather than a demo wrapper. The game mounts a modern PixiJS v8 runtime inside the existing React/TanStack extension host and connects back to AI OS by turning browser-safe agent telemetry into an in-game currency (`Insight Shards`) and progression system. The core loop: use AI OS and local agents, aggregate browser-safe usage/spend/ token/skill/tool metadata, convert bounded daily activity into currency via a manual claim, spend currency on roguelike upgrades and relics, and play short dungeon runs on `/extensions/ai-rogue/play`. Raw spend is a capped signal, not the dominant reward source, so the game makes AI OS feel alive without incentivizing wasteful token burn. This phase delivers the disabled-first extension shell, the lazy PixiJS runtime boundary, the economy/ledger transform, versioned browser-local persistence, the deterministic dungeon simulation, the first integrated playable slice with committed pixel art, AI OS-flavored progression depth, content/mobile polish, and the final quality gates and enablement decision. It follows the durable plan in `docs/extensions/ai-rogue/plan-2026-06-21.md` and the locked asset decisions in `docs/extensions/ai-rogue/visual-assets.md`. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ------------------------------ | -------- | ---------- | ---------- | | 01 | Direction And Asset Readiness | Complete | \~12-25 | 2026-06-22 | | 02 | Extension Shell And Routes | Complete | \~12-25 | 2026-06-22 | | 03 | PixiJS Runtime Boundary | Complete | \~12-25 | 2026-06-22 | | 04 | Economy And Ledger | Complete | \~12-25 | 2026-06-22 | | 05 | Persistence And Save Contracts | Complete | \~12-25 | 2026-06-22 | | 06 | Dungeon Simulation Core | Complete | \~12-25 | 2026-06-22 | | 07 | Play Runtime Integration | Complete | \~12-25 | 2026-06-22 | | 08 | Progression Depth | Complete | \~12-25 | 2026-06-22 | | 09 | Content Polish And Mobile | Complete | \~12-25 | 2026-06-22 | | 10 | Quality Gates And Enablement | Complete | \~12-25 | 2026-06-22 | *** ## Completed Sessions * Session 01: Direction And Asset Readiness - Completed 2026-06-22. Ratified product naming, Insight Shards economy weights, PixiJS renderer posture, committed asset inventory, privacy boundaries, media policy, and later-session handoff anchors. * Session 02: Extension Shell And Routes - Completed 2026-06-22. Registered the disabled-first AI Rogue extension shell with Play, Ledger, Loadout, and Settings views, route and registry coverage, capability declarations, and import-boundary tests while keeping PixiJS/runtime work deferred. * Session 03: PixiJS Runtime Boundary - Completed 2026-06-22. Added the lazy PixiJS v8 runtime boundary, route-scoped React bridge, WebGL nonblank canvas proof, resize/input/reset/visibility lifecycle handling, cleanup coverage, import-boundary tests, Playwright runtime coverage, and bundle-budget evidence. * Session 04: Economy And Ledger - Completed 2026-06-22. Added the deterministic browser-safe Insight Shards economy transform, locked source weights, daily caps, stable redemption keys, manual claim flow, localStorage idempotency guard, privacy-safe Ledger provenance, and unit/component/route/ browser coverage. * Session 05: Persistence And Save Contracts - Completed 2026-06-22. Added versioned browser-local save contracts, localStorage preference persistence, IndexedDB wallet/ledger/run/save storage, legacy claim migration, AI Rogue-only reset scoping, save/load readiness UI, and unit/component/route/ browser coverage. * Session 06: Dungeon Simulation Core - Completed 2026-06-22. Added the deterministic pure TypeScript dungeon simulation with seeded RNG, grid/world generation, field of view and fog projection, movement, two first-slice enemy behaviors, deterministic combat, pointer command helpers, fixture seeds, and focused/full test coverage without widening the PixiJS runtime boundary. * Session 07: Play Runtime Integration - Completed 2026-06-22. Connected the deterministic simulation to the lazy PixiJS runtime with committed atlas rendering, controls, pause/reset/save/load/win/loss lifecycle events, bounded run summaries, save slots, and the first wallet-backed loadout upgrade. * Session 08: Progression Depth - Completed 2026-06-22. Added browser-safe progression derivation, deterministic classes, relics, resources, objectives, expanded enemies and modifiers, local achievement/run-history metadata, Play/Loadout progression states, deferred worker notes, and focused browser coverage. * Session 09: Content Polish And Mobile - Completed 2026-06-22. Added safe seed sharing and replay, compact pointer controls, mobile Play framing, runtime command dispatch, readable combat/reward/hazard/seed descriptors, no-audio documentation, and focused mobile/browser validation using the committed atlas set. * Session 10: Quality Gates And Enablement - Completed 2026-06-22. Closed the phase with passing typecheck, lint, formatting, full and focused Vitest, focused AI Rogue Playwright, production build, bundle budget, asset-size, private-runtime, ASCII/LF, no-audio, and no-remote-loading gates; documented AI Rogue as safe for explicit opt-in without default enablement. *** ## Upcoming Sessions * None. Phase 30 is complete. *** ## Objectives 1. Ship a disabled-first `ai-rogue` extension whose first screen is a real playable roguelike on `/extensions/ai-rogue/play`, with Ledger, Loadout, and Settings as supporting surfaces. 2. Prove a lazy PixiJS v8 (WebGL) runtime boundary that mounts, paints, resizes, and disposes cleanly without leaking the engine into shared app or registry chunks. 3. Derive a bounded, explainable `Insight Shards` economy from browser-safe `LiveData`, with manual claims, daily caps, idempotent redemption, and a "why did I earn this?" breakdown. 4. Persist preferences, wallet, ledger, run history, and saves locally with versioned Zod schemas and safe migration. 5. Build a deterministic, renderer-independent dungeon simulation and integrate it with the renderer, assets, controls, and one spendable upgrade into a complete run. 6. Add AI OS-flavored progression depth, content/mobile polish, and pass all quality gates before deciding on enablement. *** ## Prerequisites * Phase 29 completed. * Extension platform foundation in place (`src/extensions/registry.ts`, `docs/extensions/README_docs-extensions.md`, ADR 0001). * `pixi.js@8.19.0` installed (checked 2026-06-22); `@pixi/react` not installed. * Durable plan `docs/extensions/ai-rogue/plan-2026-06-21.md` and asset decisions `docs/extensions/ai-rogue/visual-assets.md` captured. * First visual-asset batch already generated and committed: `src/assets/ai-rogue/gameplay-atlas.{png,json}` and `ui-atlas.{png,json}` (TexturePacker-style frames, both well under the 200 KB media limit). *** ## Technical Considerations ### Architecture * Standard compile-time extension model: no dynamic plugin loading, no remote game package loading, no separate app runtime. * Layout under `src/extensions/ai-rogue/` with `client.tsx`, `capabilities.ts`, `economy-schema.ts`, `save-schema.ts`, a `game/` runtime folder (runtime, renderer, assets, input, loop, simulation, world, entities, combat, progression, rng), and `views/` (play, ledger, loadout, settings). * Imperative PixiJS ownership for the loop, sprites, textures, and input sampling; React owns routing, menus, coarse state, and accessible UI. * Pure TypeScript modules for simulation, economy, world generation, and save migration so they test without browser APIs. ### Technologies * PixiJS v8 (`pixi.js@8.19.0`), WebGL renderer with `preserveDrawingBuffer: true` for `readPixels` canvas verification. * React 19, TanStack Router/Start, Vite 8, Zod, Vitest, Playwright. * `localStorage` for tiny preferences; IndexedDB for saves, run history, wallet, and ledger. ### Risks * PixiJS lazy chunk size: Measure the runtime chunk; keep it under the 350 KB app budget or extend `is_vendor_chunk` in `scripts/check-bundle-budget.sh` to grant the 450 KB watched-vendor allowance. Total client JS gzip stays under 1250 KB. * WebGPU auto-selection would break the WebGL `readPixels` gate: pin WebGL for the first slice; defer WebGPU and its screenshot-based verification. * Privacy leakage: Economy and ledger must use counts, categories, labels, and capped signals only -- never raw prompts, transcripts, commands, private paths, credentials, or logs. * Asset budget: Committed pixel art must stay under the 200 KB per-file media limit; prefer compact atlases over loose large PNGs. * Scope creep: Inventory, crafting, NPCs, meta-trees, procedural biomes, workers, gamepad, pointer lock, audio wrappers, and collectors stay deferred until profiling or UX evidence justifies them. ### Relevant Considerations * \[P02] **Static extension registry requires code changes**: Registering `ai-rogue` means editing the client registry; no marketplace, dynamic loading, eval, or remote code. * \[P02] **Disabled-first pattern**: The extension ships disabled and gated by `VITE_CLAUDE_OS_ENABLED_EXTENSIONS`; enablement comes only after gates pass. * \[P02] **Extension payloads and labels stay bounded**: Honor the shared 1 MB payload limit and explicit live, fixture, fallback, degraded, and unavailable states for any extension data. * \[P02] **Zod schemas with `.default()` for safe parsing**: Additive defaults keep older saves, ledgers, and preferences parseable across migrations. * \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, and Cloudflare Worker compatibility constrain the lazy PixiJS chunk and budgets. * \[P08] **Playwright route interception plus DOM rect checks**: Reuse the memory-graph nonblank-canvas verification approach for canvas e2e coverage. ### Reference Implementations Two working PixiJS roguelikes are vendored under `EXAMPLES/` as study material. Mine them for proven patterns; do not copy architecture wholesale. * `EXAMPLES/Rotten-Soup/` -- Vue 2 + `rot.js` + PixiJS **4.8.2** roguelike. Strong on turn scheduling, FOV/fog, themed dungeon generation, and a goal-driven enemy AI. Per-session pointers appear in Sessions 01, 03, 06, 07, 08, 09. * `EXAMPLES/frogue/` -- ClojureScript + `rot.js` + PixiJS **5.3.6** roguelike on a small custom ECS (`fae`). Strong on sim/render system separation, cellular map generation, compact grid model, and a stage lifecycle. Per- session pointers appear in Sessions 03, 06, 07, 08, 09. Caveats that apply everywhere these are cited: * Both predate **PixiJS v8** (the v8.19.0 target). `PIXI.Application` now inits async, `Assets.load` replaces `PIXI.loader`, the ticker/renderer surface changed, and there is no global `PIXI.settings.SCALE_MODE`. Treat them as sources of *patterns and algorithms*, not v8 API. * Both **couple simulation to the renderer** (entities hold PIXI graphics; globals reach into the display), which is exactly the coupling the pure- TypeScript simulation mandate forbids. frogue's `state`-vs-`effect` system split is the closest positive model; otherwise borrow the algorithm and leave the wiring behind. * Both lean on **`rot.js`** for scheduler, FOV, and map generation. AI Rogue plans its own seeded RNG and simulation, so `rot.js` is a dependency to weigh against the bundle budget, not an assumed primitive. ### Locked Visual Assets `docs/extensions/ai-rogue/visual-assets.md` is the authoritative, locked art spec, and its first batch is already generated and committed -- treat these as fixed inputs, not open decisions: * **Tile/display scale**: 16x16 source pixels, nearest-neighbor, baseline 2x display (one tile = 32 CSS px); 3x is a roomy-desktop option, not the slice baseline. * **Two committed atlases**: `src/assets/ai-rogue/gameplay-atlas.{png,json}` (player/enemy/boss/tiles/pickups/hazards/projectile/fog, 48 frames) and `ui-atlas.{png,json}` (HUD icons, pips, frame pieces, run marker, reward icons). Footprints are 16x16 for player/standard enemies, 32x32 for bosses. * **First-slice enemy set**: `Errant Process` (16x16 melee chaser), `Firewall Sentry` (16x16 ranged guard with a telegraphed line projectile), and boss `Kernel Sentinel` (32x32, telegraphed area attacks). * **Palette semantics** (locked swatches in the doc): cyan = currency, green = health, orange/red = hostile, magenta or acid yellow-green = hazard, over a dark neutral dungeon base with warm machine-glow accents. * **Playable-space baseline** (E2E-measured): the Play view skips a hero and targets roughly a 30x16 visible-tile room at 1280x720, scaling down to fewer columns on portrait/mobile without changing source art. Per-session pointers into this doc appear in Sessions 01-04 and 06-10. *** ## Success Criteria Phase complete when: * [x] All 10 sessions completed. * [x] `ai-rogue` registers disabled-first, routes to a playable Play view when enabled, and fails gracefully when disabled or data is absent. * [x] The Play route lazily loads PixiJS, paints a nonblank WebGL canvas, resizes, and disposes without leaked listeners or tickers; other routes do not pay the runtime cost. * [x] A user can start a run, move, fight, reveal fog, reach win/loss, and reset or resume without page reload, using committed pixel art. * [x] Claims are deterministic per snapshot, cannot double-credit after refresh, and show a privacy-safe provenance breakdown. * [x] Preferences, wallet, ledger, run history, and saves survive refresh, handle malformed data safely, and reset clears only AI Rogue local state. * [x] All quality gates pass: `bun run typecheck`, `bun run lint`, `bun run format:check`, focused Vitest and Playwright suites, `bun run build`, `bun run budget:check`, `bash scripts/check-asset-sizes.sh`, and `bun run runtime:check-private`. * [x] No non-goal slipped in (remote loading, unbounded token-burn rewards, unreviewed large media, or raw private telemetry exposure). *** ## Dependencies ### Depends On * Phase 29: Trend Finder TrendingAI Comparison Adoption (latest completed baseline and extension platform conventions). ### Enables * Phase 31: Future AI Rogue content, collectors, WebGPU verification, worker protocol, or expanded progression (captured as follow-up in Session 10). --- # 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/phases/phase_30/prd_phase_30.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.