> 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/phase37-session01-g8-runtime-fx/spec.md). # Session Specification **Session ID**: `phase37-session01-g8-runtime-fx` **Phase**: 37 - AI Rogue Visual Asset Finishing **Status**: Not Started **Created**: 2026-06-28 *** ## 1. Session Overview This session packs and wires the G8 combat, status, fog, high-contrast, and reduced-motion visual frames that most improve AI Rogue runtime readability. It is next because the analysis script reports Phase 37 as current with no active session, and the Phase 37 PRD recommends G8 Runtime FX as the immediate first visual batch. The work is presentation-only. The session may add crop decisions, atlas frames, typed frame contracts, status/overlay/fog mappings, focused tests, and browser proof, but it must not change simulation rules, balance, statuses, public-demo boundaries, remote-loading behavior, or audio assets. The product outcome must be visible in real AI Rogue gameplay. Updated frame names, generated atlas JSON, or docs are not sufficient unless the normal, high-contrast, and reduced-motion paths render clearly in desktop and mobile browser checks. *** ## 2. Objectives 1. Extend the crop manifest with accepted and rejected G8 runtime FX decisions for combat, statuses, fog, reveal, high-contrast, and reduced-motion. 2. Regenerate the existing gameplay/UI atlas outputs and update typed required frame contracts without adding a third atlas. 3. Wire G8 frames into presentation-layer status, combat-feedback, fog, reveal, high-contrast, and reduced-motion paths without changing simulation state. 4. Prove the visuals through focused unit tests, asset-size validation, typecheck, and desktop/mobile AI Rogue browser evidence. *** ## 3. Prerequisites ### Required Sessions * [x] `phase36-session08-final-audio-validation-and-docs` - Phase 36 audio closeout preserved AI Rogue Production Go, asset policy, browser checks, and media/runtime safety boundaries. ### Required Tools Or Knowledge * Python visual packer: `scripts/extensions/ai-rogue/pack-visual-assets.py`. * AI Rogue runtime frame contracts in `src/extensions/ai-rogue/runtime/types-assets.ts` and `src/extensions/ai-rogue/runtime/assets.ts`. * AI Rogue render projection, HUD, effects, and layer ownership under `src/extensions/ai-rogue/runtime/`. * Phase 37 visual guardrails, especially no baked gameplay text, existing two-atlas preference, high-contrast and reduced-motion equivalence, and product-visible proof. ### Environment Requirements * Dependencies installed with Bun. * Python environment can run the visual packer and Pillow dependency already used by the repo. * Playwright Chromium is available through the repo test setup. * Local browser checks can run AI Rogue Play at desktop and mobile viewport sizes. *** ## 4. Scope ### In Scope (MVP) * Player can see clearer Strike, Surge, Trace Lance, Phase Step, shield, repair, cleanse, crash, status, fog, reveal, high-contrast, and reduced-motion presentation during AI Rogue runtime execution. * Operator can review accepted and rejected G8 source cells in `crop-manifest.json`, including punctuation-like hazard symbols rejected unless edited into no-text-safe abstract marks. * Maintainer can rely on typed frame names and required-frame tests to catch missing atlas output. * User-facing Play route remains product-facing while diagnostics and evidence stay in tests, screenshots, or implementation notes. ### Out Of Scope (Deferred) * Simulation rule, balance, enemy, status, objective, pathing, or win-condition changes - Reason: Phase 37 Session 01 is visual presentation only. * Adding a third runtime atlas - Reason: the Phase 37 PRD prefers the existing two-atlas model unless asset-size evidence forces a later reviewed decision. * Audio cues, music, ambience, or stingers - Reason: Phase 36 owns audio and is already closed. * G4 equipment/status icons, G5 boss presentation, G3 theme decals, G6 UI cinematics, and G7 player animation - Reason: these are later Phase 37 sessions. * Remote game-content loading, collectors, hosted writes, analytics, Pages Functions, WebGPU-only behavior, or public-demo bridge calls - Reason: current AI Rogue safety posture must remain unchanged. *** ## 5. Technical Approach ### Architecture Use the existing deterministic asset pipeline. Add reviewed G8 crop decisions to the generated visual asset manifest, run the packer to refresh `src/assets/ai-rogue/gameplay-atlas.png/json`, `src/assets/ai-rogue/ui-atlas.png/json`, and the docs preview, then update TypeScript frame contracts and required-frame lists. Runtime wiring should stay in presentation owners. Status metadata and frame selection belong in `status.ts` or nearby render helpers; tile/fog/entity/HUD projection belongs in `render-model.ts` and `render-hud.ts`; transient impact and static reduced-motion variants belong in `effects.ts` and `effects-transient.ts`; layer fallback and canvas presentation stay in `renderer-layers.ts` and existing renderer owners. The simulation continues to emit the same snapshots and events. ### Design Patterns * Manifest-first asset acceptance: every shipped or rejected G8 candidate is recorded with source rectangle, target size, category, notes, and status. * Typed frame contract: required frame names and union types guard atlas availability before runtime rendering. * Presentation boundary: convert existing statuses, events, preferences, and visibility facts into frames without mutating gameplay state. * Preference equivalence: high-contrast and reduced-motion modes use shape-first or static alternatives that preserve gameplay meaning. * Product-surface discipline: browser proof belongs in tests and implementation notes, not visible Play-route diagnostic copy. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase37-session01-g8-runtime-fx/implementation-notes.md` | G8 manifest review, validation ledger, browser evidence notes | \~180 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- | | `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json` | Accepted and rejected G8 crop decisions for runtime FX, fog, statuses, and accessibility | \~250 | | `src/assets/ai-rogue/gameplay-atlas.png` | Regenerated gameplay atlas containing accepted G8 frames | Binary | | `src/assets/ai-rogue/gameplay-atlas.json` | Regenerated gameplay atlas metadata | \~300 | | `src/assets/ai-rogue/ui-atlas.png` | Regenerated UI atlas if accepted G8 HUD/status frames belong in UI | Binary | | `src/assets/ai-rogue/ui-atlas.json` | Regenerated UI atlas metadata if UI frames change | \~0-120 | | `docs/extensions/ai-rogue/generated/ai-rogue-production-atlas-preview.png` | Regenerated docs-only atlas preview | Binary | | `src/extensions/ai-rogue/runtime/types-assets.ts` | G8 frame-name unions and simulation/accessibility frame group updates | \~80 | | `src/extensions/ai-rogue/runtime/assets.ts` | Required gameplay/UI frame names and atlas validation expectations | \~80 | | `src/extensions/ai-rogue/runtime/status.ts` | Status-to-frame mapping helpers for status pips and entity overlays | \~80 | | `src/extensions/ai-rogue/runtime/render-model.ts` | Combat/status/fog/reveal/high-contrast/reduced-motion projection wiring | \~140 | | `src/extensions/ai-rogue/runtime/render-hud.ts` | HUD descriptor and status-frame presentation updates | \~80 | | `src/extensions/ai-rogue/runtime/effects.ts` | Event-driven G8 impact, repair, cleanse, shield, and static reduced-motion effect routing | \~100 | | `src/extensions/ai-rogue/runtime/effects-transient.ts` | Transient impact frame support and cleanup-safe reduced-motion handling | \~50 | | `src/extensions/ai-rogue/runtime/renderer-layers.ts` | Canvas/layer preference handling if fog or high-contrast frame selection needs layer owner | \~40 | | `src/extensions/ai-rogue/runtime/__tests__/assets.test.ts` | Required-frame, atlas count, and manifest contract coverage | \~60 | | `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts` | Projection coverage for G8 combat, fog, status, high-contrast, and reduced-motion frames | \~140 | | `src/extensions/ai-rogue/runtime/__tests__/status-expanded.test.ts` | Status visual mapping coverage for negative and positive status states | \~80 | | `tests/e2e/ai-rogue-runtime.spec.ts` | Desktop browser proof for visible G8 runtime FX and product-facing copy only | \~80 | | `tests/e2e/ai-rogue-mobile.spec.ts` | Mobile browser proof for visible G8 runtime FX and responsive readability | \~60 | | `docs/extensions/ai-rogue/visual-assets.md` | Current atlas counts, accepted/rejected G8 decisions, validation evidence, caveats | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] G8 accepted and rejected candidates are recorded in `crop-manifest.json` with no unresolved placeholder entries. * [ ] Runtime atlases regenerate successfully and every new required G8 frame is available through typed frame contracts. * [ ] Normal, high-contrast, and reduced-motion render paths use G8 visuals where they improve readability and preserve gameplay meaning. * [ ] AI Rogue Play shows visible G8 runtime FX during real gameplay on desktop and mobile. ### Testing Requirements * [ ] `python3 scripts/extensions/ai-rogue/pack-visual-assets.py` runs successfully. * [ ] `bun run typecheck` passes. * [ ] `bash scripts/check-asset-sizes.sh` passes. * [ ] Focused assets, render-model, status-expanded, effects, and runtime tests pass for touched behavior. * [ ] `bunx playwright test tests/e2e/ai-rogue-runtime.spec.ts` passes or records a concrete environment blocker. * [ ] `bunx playwright test tests/e2e/ai-rogue-mobile.spec.ts` passes or records a concrete environment blocker. ### Non-Functional Requirements * [ ] No simulation rule, balance, pathing, objective, or win-condition snapshots change unexpectedly. * [ ] AI Rogue production default-enabled posture and explicit `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` disable path are preserved. * [ ] No remote loading, hosted write, collector, analytics, public-demo bridge call, WebGPU-only behavior, or new third-party data transfer is introduced. * [ ] Committed runtime image assets remain within the media-policy caps. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Working Assumptions * Session 01 is the next executable Phase 37 session: the analysis script reports `current_phase` 37, no `current_session`, and every Phase 37 candidate unfinished; the Phase 37 PRD recommends G8 as the immediate next batch, while later stubs depend on G8 or atlas-contract stability. * G8 source inputs are available: the repo contains `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/source/ai-rogue-combat-fog-accessibility-source.png`, the matching alpha derivative, and the current crop manifest, so planning can proceed without user arbitration. * The existing two-atlas model should be preserved: Phase 37 names `gameplay-atlas` and `ui-atlas` as the baseline and says to prefer fewer excellent frames before adding a third atlas. * Browser proof must cover product-visible outcomes, not only generated files: the Phase 37 PRD explicitly states atlas JSON and docs are insufficient unless visuals render in AI Rogue. ### Key Considerations * Punctuation-like hazard symbols should be rejected or edited into abstract, no-text-safe marks before runtime use. * High-contrast and reduced-motion variants must preserve meaning; they should not become weaker versions of the normal path. * The G8 work will influence later Phase 37 sessions because G4, G5, G3, G6, and G7 expect stable atlas/frame contracts. ### Potential Challenges * Atlas growth can exceed media policy caps: select fewer excellent frames and run `bash scripts/check-asset-sizes.sh` immediately after packing. * Effects can accidentally imply new mechanics: keep frame selection driven by existing events, statuses, preferences, and snapshots. * Generated symbols may read as punctuation or text at 16x16: reject them in the manifest unless cleanup makes them abstract. * Browser proof can be flaky around runtime timing: use deterministic scenarios and canvas pixel checks already present in AI Rogue e2e tests. ### Relevant Considerations * \[P34-P36] **AI Rogue is production default-enabled**: Visual changes must preserve Production Go and the explicit `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` disable path. * \[P31-P36] **Public-demo and AI Rogue gates stay bundled**: Keep asset-size, provenance, private-runtime, no-remote-loading, no-bridge, browser, mobile, and product-copy checks bundled for runtime/media changes. * \[P30/P32/P34-P35] **Route-lazy runtime ownership scales**: Keep Pixi behind the Play route/local facade and narrow runtime owners. * \[P30/P34-P36] **Visibility gates catch real issues**: Pair typecheck, focused tests, asset-size, browser, mobile, and product-surface checks before widening visibility. * \[P30/P32/P34-P36] **Do not widen AI Rogue capabilities without review**: Production visibility and local media assets are approved; collectors, WebGPU-specific behavior, workers, remote loading, hosted writes, saved audio state, or expanded content require fresh review. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Runtime presentation might update frame contracts without visible gameplay output. * Preference paths could drift so high-contrast or reduced-motion users lose semantic cues. * Presentation code could accidentally mutate simulation state or widen public demo/runtime boundaries. *** ## 9. Testing Strategy ### Unit Tests * Validate atlas metadata, required G8 frame names, and frame-name unions. * Validate status-to-frame mappings for jammed, burning, shielded, overclocked, leaking, lagged, traced, corrupted, forked, rooted, repair, and cleanse presentation. * Validate render-model projection for combat feedback, fog/reveal, high-contrast, reduced-motion, HUD, and deterministic sprite ordering. ### Integration Tests * Run focused runtime tests for assets, render-model, status-expanded, effects, and any touched renderer behavior. * Confirm no simulation snapshots, status mechanics, or event ordering change except for presentation frame names. ### Runtime Verification * Run desktop AI Rogue Play browser proof with a deterministic combat/status scenario and canvas pixel checks. * Run mobile AI Rogue Play browser proof for compact input, visible runtime FX, no horizontal overflow, and product-facing copy only. * Verify normal, high-contrast, and reduced-motion paths. ### Edge Cases * Missing G8 frame falls back explicitly or fails tests before runtime. * Punctuation-like or text-like cells are rejected in the manifest. * Reduced-motion uses static impact frames without leaving stale transient sprites. * High-contrast uses shape-first markers rather than hue-only differences. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase36-session08-final-audio-validation-and-docs`. * Depended by: `phase37-session02-g4-status-equipment`, `phase37-session03-g5-boss-presentation`, `phase37-session04-g3-theme-decals`, `phase37-session05-g6-ui-cinematics`, `phase37-session06-g7-player-animation`. *** ## 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/phase37-session01-g8-runtime-fx/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.