> 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-session05-g6-ui-cinematics/spec.md). # Session Specification **Session ID**: `phase37-session05-g6-ui-cinematics` **Phase**: 37 - AI Rogue Visual Asset Finishing **Status**: Not Started **Created**: 2026-06-29 *** ## 1. Session Overview This session adds the generated G6 UI and cinematic art only where it improves AI Rogue readability over standard controls. It is next because the analysis script reports Phase 37 as current, no active session, Sessions 01 through 04 completed, and Session 05 as the first unfinished current-phase candidate. The work is presentation-only. It may add G6 crop decisions, refreshed UI atlas frames, typed UI/cinematic frame contracts, end-screen panel and badge usage, HUD run-stat icons, and React surface icon usage across Play, Ledger, Loadout, and Settings. It must not change simulation rules, persistence schemas, claim or purchase semantics, input rules, public-demo boundaries, hosted runtime behavior, remote loading, or the static Pages safety posture. The product outcome must be visible in real AI Rogue surfaces. Text remains in Pixi or HTML, generated art is used for panels, badges, icons, and markers, and normal user-facing routes must remain product-facing without debug labels, layout shift, text overlap, or unclear control replacement. *** ## 2. Objectives 1. Record accepted and rejected G6 crop decisions for cinematic panels, result badges, run-stat markers, class/relic/wallet/save/shard icons, and domain-specific settings icons. 2. Regenerate atlas outputs and add typed G6 UI/cinematic frame contracts with required-frame validation. 3. Wire accepted G6 frames into end-screen cinematics, runtime HUD descriptors, and AI Rogue Play, Ledger, Loadout, and Settings surfaces without replacing familiar generic controls. 4. Prove the visual outcome with focused tests, asset validation, docs, and desktop/mobile browser evidence covering no layout shift, no text overlap, and no unclear control replacement. *** ## 3. Prerequisites ### Required Sessions * [x] `phase37-session01-g8-runtime-fx` - Provides runtime FX, atlas validation, reduced-motion and high-contrast proof patterns, and browser evidence workflow. * [x] `phase37-session02-g4-status-equipment` - Provides stable UI icon contracts, `RewardIcon` usage, Loadout/Ledger/Settings wiring patterns, and post-G4 UI atlas validation. * [x] `phase37-session03-g5-boss-presentation` - Provides end-screen and final-defense presentation patterns plus cinematic validation. * [x] `phase37-session04-g3-theme-decals` - Provides latest atlas counts, theme visual proof, and current Phase 37 docs state. ### Required Tools Or Knowledge * Python visual packer: `scripts/extensions/ai-rogue/pack-visual-assets.py`. * G6 source and alpha derivative: `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/source/ai-rogue-cinematic-ui-source.png` and `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/alpha/ai-rogue-cinematic-ui-alpha.png`. * Current crop manifest: `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json`. * Current runtime atlas outputs: `src/assets/ai-rogue/gameplay-atlas.png`, `src/assets/ai-rogue/gameplay-atlas.json`, `src/assets/ai-rogue/ui-atlas.png`, and `src/assets/ai-rogue/ui-atlas.json`. * Existing UI/cinematic surfaces: `src/extensions/ai-rogue/runtime/effects-cinematics.ts`, `src/extensions/ai-rogue/runtime/render-hud.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`, and `src/extensions/ai-rogue/views/settings-view.tsx`. ### 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. * Browser checks can run AI Rogue Play, Ledger, Loadout, and Settings at desktop and mobile viewport sizes. *** ## 4. Scope ### In Scope (MVP) * Player can see richer end-screen panels, badges, and result accents while all result title, stat, and prompt text remains Pixi text. * Player can scan HUD run-stat, shard, objective, class, relic, and wallet state using G6 icons where they are clearer than existing generic markers. * User can recognize AI Rogue-specific Ledger, Loadout, save-slot, wallet, storage, audio, and settings states without replacing standard browser, keyboard, gamepad, play, pause, layout, or contrast controls. * Maintainer can rely on typed G6 frame unions, required atlas frame tests, focused view tests, and browser proof to catch missing frames or mapping drift. * User-facing Play, Ledger, Loadout, and Settings surfaces preserve explicit loading, empty, error, storage-unavailable, public-demo, and offline-style recovery states. ### Out Of Scope (Deferred) * Replacing clear Lucide, native, or platform-standard controls - Reason: generated G6 art should improve domain readability, not reduce control familiarity. * Adding baked text, letters, readable numbers, or diagnostic labels to image frames - Reason: text must stay in Pixi or HTML for accessibility and localization safety. * Broad route redesign, marketing-style composition, or debug panels - Reason: this is a visual finishing pass for existing AI Rogue product surfaces. * Changing simulation behavior, combat balance, input rules, claim/purchase persistence, save schemas, localStorage or IndexedDB keys, public-demo boundaries, hosted writes, collectors, analytics, remote loading, workers, or WebGPU-only behavior - Reason: Phase 37 preserves AI Rogue safety posture. * G7 player animation - Reason: that is Session 06 and depends on Session 05. *** ## 5. Technical Approach ### Architecture Use the existing manifest-first asset pipeline. Add reviewed G6 crop decisions to `crop-manifest.json`, run the packer to refresh the atlas files and docs preview, and keep the existing two-atlas model. G6 panel pieces, result badges, run-stat markers, surface icons, save-slot icons, and settings icons should enter the UI atlas unless implementation proves a narrowly scoped gameplay atlas need. Extend `types-assets.ts` with G6 frame-name unions and constants, then include those constants in `assets.ts` required UI frame validation. Extend `RewardIcon` only for icons that are meaningful in React surfaces, with explicit labels and null-safe fallback behavior. Runtime HUD and end-screen usage should use typed frame names already available through atlas validation. Wire visuals through existing presentation boundaries: `effects-cinematics.ts` for the Pixi end screen, `render-hud.ts` and render-model coverage for HUD descriptors, and the existing Play, Ledger, Loadout, and Settings view files for React surfaces. Preserve current mutation guards, loading and error states, storage recovery paths, public-demo copy, reduced-motion and high-contrast behavior, and route cleanup. ### Design Patterns * Manifest-first asset acceptance: every accepted or rejected G6 candidate is recorded with source rectangle, target size, atlas, category, status, and no-baked-text notes. * Typed frame contract: accepted G6 frames are union types and required atlas frames, not ad hoc strings. * Product-surface discipline: UI art supports domain state; diagnostics and proof stay in tests, screenshots, docs, or implementation notes. * Familiar control preservation: standard icons and controls remain standard unless a G6 icon is clearly domain-specific and accessibility remains better. * State-preserving UI wiring: icon upgrades must not change claim, purchase, settings, storage, save-slot, or runtime lifecycle semantics. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------- | | `.spec_system/specs/phase37-session05-g6-ui-cinematics/implementation-notes.md` | G6 candidate review, validation ledger, and browser evidence | \~170 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------- | | `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json` | Accepted/rejected G6 panel, badge, run-stat, shard, save-slot, wallet, and settings icon choices | \~180 | | `src/assets/ai-rogue/ui-atlas.png` | Regenerated UI atlas containing accepted G6 UI/cinematic frames | Binary | | `src/assets/ai-rogue/ui-atlas.json` | Regenerated UI atlas metadata | \~80 | | `src/assets/ai-rogue/gameplay-atlas.png` | Preserve unchanged unless implementation proves a scoped gameplay-atlas need | Binary | | `src/assets/ai-rogue/gameplay-atlas.json` | Preserve unchanged unless implementation proves a scoped gameplay-atlas need | \~0 | | `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` | G6 UI/cinematic frame-name unions, constants, and required frame groups | \~90 | | `src/extensions/ai-rogue/runtime/assets.ts` | Required UI frame names and atlas validation expectations for accepted G6 work | \~40 | | `src/extensions/ai-rogue/runtime/effects-cinematics.ts` | End-screen panel, result badge, and decorative frame usage while keeping text rendered in Pixi | \~90 | | `src/extensions/ai-rogue/runtime/render-hud.ts` | HUD run-stat, shard, class, relic, wallet, and objective icon frame mappings | \~70 | | `src/extensions/ai-rogue/views/reward-icon.tsx` | Accepted G6 React icon names, accessible labels, and null-safe fallback behavior | \~70 | | `src/extensions/ai-rogue/views/play-view.tsx` | Save-slot, run summary, wallet, and readiness icon usage without route-visible diagnostics | \~80 | | `src/extensions/ai-rogue/views/ledger-view.tsx` | Claim, durable ledger, source, and wallet icon usage preserving idempotent claim handling | \~60 | | `src/extensions/ai-rogue/views/loadout-view.tsx` | Class, relic, upgrade, and wallet icon usage preserving duplicate-trigger prevention | \~80 | | `src/extensions/ai-rogue/views/settings-view.tsx` | Domain-specific settings, audio, storage, input-mode, and display icon usage with standard controls preserved | \~90 | | `src/extensions/ai-rogue/runtime/__tests__/assets.test.ts` | Required-frame, atlas count, and TexturePacker metadata coverage for G6 frames | \~55 | | `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts` | HUD descriptor coverage for G6 run-stat icons and layout stability | \~60 | | `src/extensions/ai-rogue/__tests__/client.test.tsx` | React surface coverage for G6 icons, labels, mutation guards, and fallback states | \~120 | | `tests/e2e/ai-rogue-runtime.spec.ts` | Desktop proof for G6 end-screen, Play, Ledger, Loadout, and Settings surfaces | \~90 | | `tests/e2e/ai-rogue-mobile.spec.ts` | Mobile proof for G6 icon readability, no overflow, no layout overlap, and control clarity | \~70 | | `docs/extensions/ai-rogue/visual-assets.md` | Current atlas counts, accepted/rejected G6 decisions, validation evidence, and caveats | \~100 | *** ## 7. Success Criteria ### Functional Requirements * [ ] G6 accepted and rejected candidates are recorded in `crop-manifest.json` with no unresolved entries. * [ ] Runtime UI atlas regenerates successfully and every accepted G6 frame is available through typed frame contracts. * [ ] End-screen panels and result badges render with G6 art while all titles, stats, prompts, and numbers remain Pixi text. * [ ] HUD and React surfaces use G6 art only where it improves AI Rogue domain readability, and standard controls remain familiar. * [ ] Play, Ledger, Loadout, and Settings preserve loading, empty, error, storage-unavailable, public-demo, and recovery states. ### 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, and client tests pass for touched behavior. * [ ] `bunx playwright test tests/e2e/ai-rogue-runtime.spec.ts` passes or records a concrete environment limitation. * [ ] `bunx playwright test tests/e2e/ai-rogue-mobile.spec.ts` passes or records a concrete environment limitation. ### Non-Functional Requirements * [ ] No simulation, combat, input, persistence, save-schema, public-demo, hosted-runtime, collector, analytics, remote-loading, worker, or WebGPU-only behavior changes. * [ ] AI Rogue production default-enabled posture and explicit `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` disable path are preserved. * [ ] Committed runtime image assets remain within media-policy caps. * [ ] UI text does not overlap parent elements and changed icon containers have stable dimensions at desktop and mobile viewports. ### 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 05 is the next executable session: the analysis script reports Phase 37 in progress, `current_session` as null, Sessions 01 through 04 completed, and Session 05 as the first unfinished candidate. Planning can proceed without user arbitration because the dependency chain is explicit and Session 06 depends on Session 05. * G6 is a first-pass manifest batch: the G6 source and alpha derivative exist, and no current crop-manifest entries use `ai-rogue-cinematic-ui-alpha.png`. Planning can proceed by requiring accepted and rejected G6 decisions before atlas regeneration. * The existing two-atlas model remains sufficient: Phase 37 and the media policy preserve the gameplay/UI atlas split, and G6 assets are UI/cinematic surfaces. The plan uses the UI atlas unless implementation proves a narrow gameplay-atlas need. ### Conflict Resolutions * The G6 stub asks for domain-specific settings/control icons, while the stub also excludes replacing clear standard controls. The chosen interpretation is to use generated art for AI Rogue-specific storage, audio, save-slot, wallet, and settings state markers, while preserving familiar platform controls such as play, keyboard, gamepad, contrast, layout, and generic buttons. * The G6 stub asks for title-card panels and result badges while requiring text to stay outside images. The chosen interpretation is to crop panels, frames, and badges only as decorative or semantic art, with all readable titles, numbers, labels, and prompts rendered by Pixi or HTML. ### Key Considerations * Security posture is clean with no open findings, but AI Rogue remains a default-enabled product surface, so visual changes require the bundled runtime, privacy, asset-size, and browser gates. * G6 should not widen the approved local-only media posture or public-demo static boundary. * The UI atlas has room under the configured asset cap, but packer and asset-size evidence must be recorded after every accepted frame batch. ### Potential Challenges * G6 source motifs include familiar control symbols that can overread as generic UI controls. Mitigation: reject or preserve standard controls unless the icon represents an AI Rogue-specific state and has accessible labeling. * Larger panel pieces can cause mobile overflow or text collision. Mitigation: use stable dimensions, responsive constraints, and Playwright proof on desktop and mobile routes. * React views already have storage, loading, and mutation states. Mitigation: wire icons as presentation only and add tests that claim and upgrade actions remain idempotent. ### Relevant Considerations * \[P34-P36] **AI Rogue is production default-enabled**: Preserve production visibility and the explicit disable path while changing visual assets. * \[P31-P36] **Public-demo and AI Rogue gates stay bundled**: Keep asset-size, no-bridge, privacy, browser, playthrough, and product-copy checks together for media/runtime work. * \[P30/P32/P34-P36] **Do not widen AI Rogue capabilities without review**: This session is presentation-only and does not add collectors, remote loading, workers, WebGPU-only behavior, hosted writes, or saved audio state. * \[P30/P32/P34-P36] **PixiJS v8 route, failure, input, and audio tests**: Preserve route cleanup, WebGL/canvas proof, mobile contexts, and reduced motion behavior while changing visual descriptors. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Generated UI art could replace familiar controls and reduce accessibility. * Added panels or icons could cause layout shift, mobile overflow, or text overlap. * Claim, purchase, settings, storage, and runtime state paths could change accidentally while only presentation should change. * Baked text or diagnostic-looking marks could enter committed UI frames. *** ## 9. Testing Strategy ### Unit Tests * Asset tests verify accepted G6 frame counts, required-frame availability, TexturePacker metadata shape, source sizes, and unrotated compact frames. * Render-model tests verify HUD descriptor frame names, stable dimensions, and no simulation-side state changes. * Client tests verify Play, Ledger, Loadout, Settings, and `RewardIcon` labels, fallback states, product-facing copy, and mutation guard preservation. ### Integration Tests * Desktop Playwright runtime tests verify G6 end-screen/HUD visibility and React route surfaces without route-visible diagnostics or private bridge requests. * Mobile Playwright tests verify icon readability, no horizontal overflow, no layout overlap, and familiar control recovery paths on Ledger, Loadout, Settings, and Play. ### Runtime Verification * Run AI Rogue Play through an end-screen-capable scenario or deterministic runtime path and capture proof that G6 panel/badge art appears while the title, stat, and prompt text remains rendered. * Visit Ledger, Loadout, Settings, and Play at desktop and mobile sizes and verify changed surfaces remain product-facing and accessible. ### Edge Cases * Missing G6 atlas frame returns no `RewardIcon` output instead of broken UI. * Storage-unavailable and public-demo states preserve existing copy and disabled actions. * Duplicate claim and upgrade clicks still execute only one write path. * Reduced-motion and high-contrast preferences preserve readability without diagnostic copy. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase37-session01-g8-runtime-fx`, `phase37-session02-g4-status-equipment`, `phase37-session03-g5-boss-presentation`, `phase37-session04-g3-theme-decals`. * Depended by: `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-session05-g6-ui-cinematics/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.