> 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_37/prd_phase_37.md). # PRD Phase 37: AI Rogue Visual Asset Finishing **Status**: Complete **Sessions**: 6 (initial estimate) **Estimated Duration**: 3-6 days **Progress**: 6/6 sessions completed and validated (100%) *** ## Overview Phase 37 turns the remaining AI Rogue visual asset plan into executable spec-system sessions. It uses the generated G3-G8 source sheets to select, crop, clean, pack, wire, test, document, and browser-validate the remaining runtime visual improvements: combat/status/fog/accessibility FX, status and equipment icons, Kernel Sentinel and final-defense presentation, sector theme decals, UI/cinematic icons, and the player animation ship-or-redraw decision. The phase preserves AI Rogue's production default posture, browser-local state, static Pages public-demo boundary, no remote game-content loading, deterministic simulation behavior, reduced-motion and high-contrast equivalence, committed asset-size policy, and the existing two-atlas model unless size evidence requires a later reviewed expansion. Proper delivery for this phase means every shipped visual feature proves the user's intended outcome end to end in the product, with real runtime execution, visible results, preference or fallback recovery paths where applicable, and tests. Scaffolding, typed frame names, atlas JSON, or docs that look complete are not enough unless the visuals render in AI Rogue and the acceptance evidence shows the user-facing outcome. *** ## Folded Plan Provenance This PRD and its six session stubs fold the complete remaining-work content from the former ongoing-project visual plan. That old ongoing-project document can be deleted without losing planning details. **Original plan status**: 2026-06-28 remaining visual batches only. Completed source generation and the first G1/G2/G4 runtime finishing pass are recorded in `docs/CHANGELOG.md`. **Original plan created**: 2026-06-28 **Original plan scope**: Visual assets only for `AI Rogue`. Audio asset work remains separate and lives in `docs/ongoing-projects/ai-rogue-audio-asset-opportunities.md` and Phase 36. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | -------------------- | -------- | ---------- | ---------- | | 01 | G8 Runtime FX | Complete | \~12-25 | 2026-06-29 | | 02 | G4 Status Equipment | Complete | \~12-25 | 2026-06-29 | | 03 | G5 Boss Presentation | Complete | \~12-25 | 2026-06-29 | | 04 | G3 Theme Decals | Complete | \~12-25 | 2026-06-29 | | 05 | G6 UI Cinematics | Complete | \~12-25 | 2026-06-29 | | 06 | G7 Player Animation | Complete | 20 | 2026-06-29 | *** ## Completed Sessions * Session 01: G8 Runtime FX - Completed 2026-06-29. * Session 02: G4 Status Equipment - Completed 2026-06-29. * Session 03: G5 Boss Presentation - Completed 2026-06-29. * Session 04: G3 Theme Decals - Completed 2026-06-29. * Session 05: G6 UI Cinematics - Completed 2026-06-29. * Session 06: G7 Player Animation - Completed 2026-06-29. *** ## Upcoming Sessions * None in Phase 37. The next workflow step is `audit` because Phase 37 is complete and the workflow is entering Phase Transition. ## Session 06 Closeout Evidence Session 06 closeout on 2026-06-29 recorded the final Phase 37 visual finishing package: * The 16x16 G7 downscale review image was generated and retained as docs-only evidence at `docs/extensions/ai-rogue/generated/ai-rogue-g7-player-downscale-review.png`. * Direct runtime use of G7 player animation was rejected because the generated side-facing and action frames lose too much silhouette definition at the current player footprint. * `crop-manifest.json` now records 32 rejected G7 player candidates and zero accepted G7 player records. * The visual packer was intentionally skipped for G7 because no frames were accepted; gameplay and UI atlas outputs remain unchanged. * The existing stable player frame contract remains `player_down_0`, `player_left_0`, `player_right_0`, and `player_up_0`. * Full Vitest, focused Vitest, desktop/mobile Playwright, typecheck, lint, scoped Prettier, asset-size, whitespace, JSON, manifest-invariant, ASCII/LF, security, behavioral, and UI product-surface checks passed. * No Phase 37 closeout change introduced remote loading, hosted writes, collectors, analytics, public-demo bridge calls, save schema changes, WebGPU requirements, or deterministic simulation behavior changes. Completed workflow gates: * `creview` reviewed and repaired all uncommitted changes. * `validate` verified session completeness with PASS. * `updateprd` marked Session 06 and Phase 37 complete. *** ## Objectives 1. Pack and wire G8 combat, status, fog, high-contrast, and reduced-motion visual frames that materially improve runtime readability. 2. Finish the remaining G4 status, equipment, reward, loadout, ledger, and settings icon opportunities without disturbing already-wired system-object frames. 3. Upgrade Kernel Sentinel and final-defense presentation while keeping boss logic, footprint, pathing, and win conditions unchanged. 4. Add sector theme identity through additive G3 decals and a small number of tile variants while preserving world-generation rules. 5. Use G6 UI and cinematic icons only where they improve domain-specific readability over standard controls. 6. Review G7 player animation at 16x16 and either wire it with evidence or record it as redraw reference. *** ## Prerequisites * Phase 36 completed and validated before normal sequential execution. * Phase 35 Production Go posture remains intact. * Runtime atlases are generated by `scripts/extensions/ai-rogue/pack-visual-assets.py`. * Crop choices are tracked in `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json`. * Generated visual source files exist under `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/`. * New frame names remain stable, typed, tested, and documented in `docs/extensions/ai-rogue/visual-assets.md`. * Preserve no remote game-content loading, no hosted writes, no collectors, no analytics, no public-demo bridge calls, and no raw private telemetry export. *** ## Baseline For Remaining Work * Runtime atlases are generated by `scripts/extensions/ai-rogue/pack-visual-assets.py`. * Crop choices live in `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json`. * Generated visual source files live under `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/`. * The first runtime pass kept the existing two-atlas model: `src/assets/ai-rogue/gameplay-atlas.png/json` and `src/assets/ai-rogue/ui-atlas.png/json`. * New frame names must remain stable, typed, tested, and documented in `docs/extensions/ai-rogue/visual-assets.md`. *** ## Remaining Source Inputs | ID | Remaining Use | Source | Alpha | Caveat | | -- | ------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | G3 | Sector theme decals and tile variants | `source/ai-rogue-sector-themes-source.png` | `alpha/ai-rogue-sector-themes-alpha.png` | Review lock/stripe pictograms before using them in gameplay. | | G4 | Status pips, equipment icons, and entity overlays | `source/ai-rogue-status-equipment-systems-source.png` | `alpha/ai-rogue-status-equipment-systems-alpha.png` | System-object frames are already wired; only status/equipment/icon candidates remain. Review abstract cross/lock motifs. | | G5 | Kernel Sentinel and final-defense presentation | `source/ai-rogue-boss-final-defense-source.png` | `alpha/ai-rogue-boss-final-defense-alpha.png` | Keep the logical boss footprint unchanged unless pathing changes are explicitly scoped. | | G6 | Cinematic UI and React surface icons | `source/ai-rogue-cinematic-ui-source.png` | `alpha/ai-rogue-cinematic-ui-alpha.png` | Prefer standard UI icons for generic controls when clearer. | | G7 | Player animation review and possible wiring | `source/ai-rogue-player-animation-source.png` | `alpha/ai-rogue-player-animation-alpha.png` | Side-facing frames need 16x16 downscale review before direct runtime use. | | G8 | Combat, status, fog, and accessibility FX | `source/ai-rogue-combat-fog-accessibility-source.png` | `alpha/ai-rogue-combat-fog-accessibility-alpha.png` | Review punctuation-like hazard symbols against the no-baked-text rule. | *** ## Recommended Order 1. G8 combat/status/fog/accessibility FX. 2. G4 remaining status and equipment icons. 3. G5 Kernel Sentinel and final-defense presentation. 4. G3 sector theme decals and tile variants. 5. G6 UI/cinematic icons. 6. G7 player animation, only after footprint/downscale quality is proven. ## Immediate Next Step Continue with: ``` G7 player animation review ``` Review whether generated player animation frames remain readable at 16x16. Wire them only if runtime proof is strong; otherwise record them as redraw reference and keep the existing player frame family. *** ## Remaining Visual Work ### G8 Combat, Status, Fog, And Accessibility FX Highest-priority next batch: * Crop and pack Strike, Surge, Trace Lance, Phase Step, shield block/break, burn/corrupt/leak, jam, root, traced, repair, and cleanse frames where they read clearly at runtime scale. * Add status pips and entity overlays for jammed, burning, shielded, overclocked, leaking, lagged, traced, corrupted, forked, and rooted states. * Add fog corners, explored-memory overlays, reveal shimmer, high-contrast markers, and reduced-motion static impact frames only where they improve readability. * Wire preference-aware frame selection for high-contrast and reduced-motion modes without changing simulation rules. Likely code touchpoints: * `src/extensions/ai-rogue/runtime/types-assets.ts` * `src/extensions/ai-rogue/runtime/assets.ts` * `src/extensions/ai-rogue/runtime/status.ts` * `src/extensions/ai-rogue/runtime/render-model.ts` * `src/extensions/ai-rogue/runtime/render-hud.ts` * `src/extensions/ai-rogue/runtime/effects.ts` * `src/extensions/ai-rogue/runtime/renderer-layers.ts` * `src/extensions/ai-rogue/runtime/__tests__/assets.test.ts` * `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts` * `src/extensions/ai-rogue/runtime/__tests__/status-expanded.test.ts` ### G4 Remaining Status And Equipment Icons Use the accepted G4 source only for the unclaimed status/equipment subset: * UI pips for active statuses. * Equipment icons for `kernel`, `guard`, and `payload`. * Tier language for patched, compiled, vectorized, and kernel-grade equipment that does not rely only on hue. * Optional equipment reward/pickup visuals if the simulation exposes those items on the board. Likely code touchpoints: * `src/extensions/ai-rogue/runtime/equipment.ts` * `src/extensions/ai-rogue/runtime/status.ts` * `src/extensions/ai-rogue/runtime/render-hud.ts` * `src/extensions/ai-rogue/views/reward-icon.tsx` * `src/extensions/ai-rogue/views/loadout-view.tsx` * `src/extensions/ai-rogue/views/ledger-view.tsx` * `src/extensions/ai-rogue/views/settings-view.tsx` * `src/extensions/ai-rogue/runtime/__tests__/equipment.test.ts` * `src/extensions/ai-rogue/runtime/__tests__/status-expanded.test.ts` ### G5 Kernel Sentinel And Final Defense Upgrade the boss/final-defense presentation while keeping logic unchanged: * Boss idle, charge, telegraph, line fire, shielded, hit, and shutdown frames. * Arena marker, compile payload marker, final-defense target marker, objective progress pips, payload activation burst, and win unlock flash. * Event-driven frame overrides for charge, attack, shield, hit, and death windows. Likely code touchpoints: * `src/extensions/ai-rogue/runtime/combat.ts` * `src/extensions/ai-rogue/runtime/render-model.ts` * `src/extensions/ai-rogue/runtime/effects.ts` * `src/extensions/ai-rogue/runtime/effects-cinematics.ts` * `src/extensions/ai-rogue/runtime/renderer-sprites.ts` ### G3 Sector Theme Decals And Tile Variants Turn the five theme IDs into clearer visual identity without replacing the whole tileset: * Cold Cache: coolant shine, frosted conduit, dim blue data floor. * Corrupted Index: magenta corruption cracks, broken index debris. * Firewall: orange hazard vents, warning-striped walls, ember conduit. * Model Vault: violet archive slabs, locked cache motifs, heavier vault doors. * Kernel Core: red core floor, hot machine ribs, boss-sector floor decals. Prefer additive decals and a small number of replacement tiles. Keep world rules unchanged. Likely code touchpoints: * `src/extensions/ai-rogue/runtime/themes.ts` * `src/extensions/ai-rogue/runtime/world-generator.ts` * `src/extensions/ai-rogue/runtime/renderer-layers.ts` * A small `themeVisuals.ts` mapping if direct generator wiring becomes noisy. * `src/extensions/ai-rogue/runtime/__tests__/themes.test.ts` ### G6 UI And Cinematic Icons Use generated UI art only where it improves domain-specific readability: * Sector title-card panels. * Result badges and run-stat icons. * Class, relic, wallet upgrade, shard claim, and save-slot state icons. * Domain-specific audio/control/settings icons where they remain clearer than standard controls. Keep actual text in Pixi/HTML, not baked into images. Likely code touchpoints: * `src/extensions/ai-rogue/runtime/effects-cinematics.ts` * `src/extensions/ai-rogue/views/reward-icon.tsx` * `src/extensions/ai-rogue/views/play-view.tsx` * `src/extensions/ai-rogue/views/ledger-view.tsx` * `src/extensions/ai-rogue/views/loadout-view.tsx` * `src/extensions/ai-rogue/views/settings-view.tsx` ### G7 Player Animation Review before wiring: * Test whether the generated side-facing player rows remain readable at 16x16. * If direct use passes, crop idle, walk, Strike, Surge cast, hurt/recovery, and optional low-HP frames per direction. * If direct use fails, treat G7 as redraw reference and keep the existing player frame family until a tighter sheet exists. * Wire player movement/idle animation separately from simulation state. Likely code touchpoints: * `src/extensions/ai-rogue/runtime/renderer-sprites.ts` * `src/extensions/ai-rogue/runtime/renderer.ts` * `src/extensions/ai-rogue/runtime/effects.ts` *** ## Per-Batch Definition Of Done For each remaining visual batch: * Extend `crop-manifest.json` with accepted and rejected candidates. * Crop from the alpha derivative unless the raw source gives a cleaner edge. * Use nearest-neighbor resizing only. * Remove chroma fringe and harden alpha for sprites/icons. * Keep soft alpha only for fog, glow, vignette, and atmosphere frames. * Preserve stable footprints across animation families. * Rerun `scripts/extensions/ai-rogue/pack-visual-assets.py`. * Update frame-name types and required-frame lists. * Wire runtime or React presentation mappings. * Update focused tests for the new frame expectations. * Regenerate the docs-only atlas preview. * Update `docs/extensions/ai-rogue/visual-assets.md`. * Run validation: * `bun run typecheck` * `bash scripts/check-asset-sizes.sh` * focused Vitest suites touched by the batch * `bunx playwright test tests/e2e/ai-rogue-runtime.spec.ts` * `bunx playwright test tests/e2e/ai-rogue-mobile.spec.ts` *** ## Visual Asset Guardrails * Keep committed runtime image files under the `src/assets` 200 KB cap. * Keep gameplay sprites free of baked text, letters, or readable numbers. * Prefer the existing gameplay/UI atlas model before adding a third atlas. * Preserve 16x16 normal entity and tile footprints unless a larger frame is deliberate. * Keep reduced-motion and high-contrast preferences visually equivalent. * Prefer fewer excellent frames over packing every generated cell. * For themes, prefer additive decals and a small number of tile variants over a full replacement tileset. * For UI, avoid replacing clear Lucide/native controls with less familiar themed icons. * Do not overwrite existing generated files; add a `-v2` suffix if regenerating source art. *** ## Open Decisions * Whether a later visual-expansion atlas is needed; the current two-atlas model is still preferred while sizes remain under policy. * Whether G7 player frames survive 16x16 downscale or should be treated as redraw reference. * Whether G3 and G8 symbolic cells are safe enough for gameplay sprites or should be edited into more abstract marks. * Whether theme visual mapping belongs directly in `world-generator.ts` or in a small `themeVisuals.ts` mapping. *** ## Planning Assumptions And Resolutions ### Working Assumptions * This Phase 37 PRD and its session stubs are the current source of truth for remaining AI Rogue visual work: they contain the six-session split, remaining-source inventory, recommended order, code touchpoints, validation gates, guardrails, and open decisions formerly held in the ongoing-project plan. * Phase 37 should preserve the existing two-atlas model while asset sizes remain under policy: the visual plan names the current gameplay and UI atlases as the baseline and says to prefer the existing model before adding a third atlas. * Visual changes must prove the end-to-end product outcome: the user supplied this as a critical delivery requirement, so every session success criterion includes real runtime visibility, recovery or preference paths where applicable, and tests. ### Conflict Resolutions * The master PRD and state already define Phase 36 as AI Rogue Audio Asset Finishing, while the requested source document defines remaining visual work. The best-supported interpretation is to create Phase 37 as the next sequential visual phase rather than replacing Phase 36, because Phase 36 has audio-specific PRD/session artifacts and the visual plan explicitly says audio work lives in a separate audio opportunity document. State current-phase fields remain on Phase 36 so active audio session work is not disrupted. *** ## Technical Considerations ### Architecture AI Rogue visual assets remain committed local runtime assets. The packer turns reviewed crops into gameplay and UI atlas PNG/JSON files, runtime frame-name types and required-frame lists guard atlas contracts, and Pixi/React surfaces choose frames at presentation boundaries without changing deterministic simulation rules. ### Technologies * Bun scripts and validation commands. * Python visual asset packer at `scripts/extensions/ai-rogue/pack-visual-assets.py`. * PixiJS v8 runtime behind the AI Rogue Play route. * React views for reward, loadout, ledger, settings, and supporting UI surfaces. * TypeScript frame-name contracts and Vitest/Playwright validation. ### Risks * Atlas size growth can break committed asset policy: mitigate by selecting fewer excellent frames, preserving the two-atlas model, and running `bash scripts/check-asset-sizes.sh` after every batch. * Baked text, letter-like marks, or punctuation-like symbols can make gameplay sprites unclear or policy-risky: mitigate through manifest rejections and no-text-safe review before packing. * Visual polish can accidentally change simulation meaning: mitigate by keeping frame selection in presentation layers and using focused simulation/render tests to prove rules are unchanged. * Reduced-motion and high-contrast variants can drift from normal-mode meaning: mitigate by validating all modes in browser checks. ### Relevant Considerations * \[P34-P35] **AI Rogue is production default-enabled**: Visual changes must preserve Production Go and the explicit `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` opt-out path. * \[P31-P35] **Public-demo and AI Rogue gates stay bundled**: Runtime visual changes need asset-size, private-runtime, browser, Pages, route smoke, and playthrough-style gates where touched. * \[P30/P32/P34-P35] **Route-lazy runtime ownership scales**: Keep Pixi behind the Play route/local facade and avoid broad runtime ownership leaks. * \[P30/P34-P35] **Visibility gates catch real issues**: Pair focused tests, asset budgets, browser checks, screenshots, and docs before treating visual work as done. * \[P30/P32/P34-P35] **Do not widen AI Rogue capabilities without review**: This phase adds visual assets only; collectors, WebGPU, workers, remote loading, hosted writes, analytics, and expanded content stay out of scope. *** ## Success Criteria Phase complete when: * [ ] All 6 sessions completed. * [ ] Every accepted visual batch has crop-manifest decisions with rejected candidates recorded where relevant. * [ ] Gameplay and UI atlas outputs are refreshed by the packer and remain under committed asset-size policy. * [ ] Frame-name types, required-frame lists, runtime mappings, and React mappings are updated for accepted visuals. * [ ] Focused unit/browser tests and AI Rogue desktop/mobile Playwright checks prove the visuals render in the real product. * [ ] High-contrast and reduced-motion visual paths remain equivalent in meaning and recover cleanly through preferences. * [ ] `docs/extensions/ai-rogue/visual-assets.md` and related docs are updated with current provenance and usage notes. * [ ] No simulation, privacy, public-demo, remote-loading, hosted-write, or accessibility boundary is widened. *** ## Dependencies ### Depends On * Phase 36: AI Rogue Audio Asset Finishing, for normal sequential workflow completion. * Phase 35: AI Rogue Audit Hardening And Refactor, for Production Go and runtime boundary posture. ### Enables * Future AI Rogue gameplay/content polish that can rely on clearer visual language and documented asset contracts. --- # 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_37/prd_phase_37.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.