> 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-session04-g3-theme-decals/spec.md). # Session Specification **Session ID**: `phase37-session04-g3-theme-decals` **Phase**: 37 - AI Rogue Visual Asset Finishing **Status**: Not Started **Created**: 2026-06-29 *** ## 1. Session Overview This session adds readable sector identity to AI Rogue by using the generated G3 sector-theme sheet for additive decals and a small number of tile variants. It is next because the analysis script reports Phase 37 as current, no active session, Sessions 01 through 03 completed, and Session 04 as the first unfinished current-phase candidate. The work is presentation-only. It may add G3 crop decisions, refreshed gameplay atlas frames, typed theme visual contracts, rule-preserving world tile frame selection, render-model decal overlays, theme-aware atmosphere, tests, docs, and browser proof, but it must not change topology, room partitioning, enemy rules, pickup placement, rewards, difficulty, persistence, audio, public-demo boundaries, or hosted/runtime capability. The product outcome must be visible in real AI Rogue play. Each of Cold Cache, Corrupted Index, Firewall, Model Vault, and Kernel Core should have a distinct visual identity at normal tile scale while normal, high-contrast, and reduced-motion presentations remain readable and product-facing. *** ## 2. Objectives 1. Extend the crop manifest with accepted and rejected G3 tile/decal decisions for the five sector themes, including no-text-safe review notes. 2. Regenerate gameplay atlas outputs and add typed G3 theme frame contracts and required-frame validation. 3. Wire theme-specific tile variants, sparse decals, and atmosphere through deterministic presentation logic without changing generated world rules. 4. Prove distinct sector identity through focused assets, theme, world, render-model, asset-size, typecheck, desktop browser, and mobile browser validation. *** ## 3. Prerequisites ### Required Sessions * [x] `phase37-session01-g8-runtime-fx` - Provides runtime FX, fog, reveal, high-contrast, reduced-motion, atlas regeneration, and visual proof workflow. * [x] `phase37-session02-g4-status-equipment` - Provides stable UI icon contracts and post-G4 atlas validation patterns. * [x] `phase37-session03-g5-boss-presentation` - Provides completed boss and final-defense presentation, post-G5 atlas counts, and browser proof patterns. ### Required Tools Or Knowledge * Python visual packer: `scripts/extensions/ai-rogue/pack-visual-assets.py`. * G3 source and alpha derivative: `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/source/ai-rogue-sector-themes-source.png` and `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/alpha/ai-rogue-sector-themes-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 sector theme, world-generation, render-model, renderer-layer, and atlas contract files under `src/extensions/ai-rogue/runtime/`. ### 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 with deterministic depth/theme scenarios. *** ## 4. Scope ### In Scope (MVP) * Player can distinguish Cold Cache, Corrupted Index, Firewall, Model Vault, and Kernel Core sectors through additive decals, tile variants, and atmosphere without relying on debug copy. * Maintainer can rely on typed G3 theme frame names, required-frame tests, and theme visual helper tests to catch missing atlas output or mapping drift. * World generation keeps the same dimensions, start/exit positions, tile kinds, passability, sight blocking, hazard damage, enemy placement, pickup placement, and objective behavior for the same seed/depth. * Renderer output projects sparse, deterministic theme decals and theme-aware background treatment from existing `snapshot.theme` and tile facts. * User-facing Play route remains product-facing; diagnostics and evidence stay in tests, screenshots, docs, or implementation notes. ### Out Of Scope (Deferred) * Replacing the whole tileset - Reason: the session calls for additive decals and a small number of variants, not a complete art rebase. * Changing topology, room rules, enemy rules, rewards, difficulty, objective rules, input, combat, persistence, or save schema - Reason: G3 is a visual finishing pass. * Using lock, stripe, pictogram, letter-like, number-like, or punctuation-like cells that fail no-text-safe review - Reason: committed gameplay image frames must not carry baked text or misleading control/state semantics. * G6 UI/cinematic icons and G7 player animation - Reason: those are later Phase 37 sessions. * Remote game-content loading, collectors, hosted writes, analytics, Pages Functions, public-demo bridge calls, WebGPU-only behavior, or new third-party data transfers - Reason: AI Rogue safety posture remains local-only and static-demo-safe. *** ## 5. Technical Approach ### Architecture Use the existing manifest-first asset pipeline. Add reviewed G3 crop decisions to `crop-manifest.json`, run the packer to refresh `src/assets/ai-rogue/gameplay-atlas.png/json` and the docs preview, and leave the UI atlas unchanged unless implementation finds a concrete UI-atlas need that still fits this session's scope. Create a small `theme-visuals.ts` runtime helper because five sector themes need shared mapping across world generation, render projection, tests, and background atmosphere. The helper should map each `AiRogueSectorThemeId` to typed tile variants, sparse decal frames, and atmosphere colors. The world generator should use this helper only to select equivalent tile frame names for already-created floor, wall, hazard, door, vault, and terminal positions. The render model should add sparse decal overlay sprites from `snapshot.theme` and tile coordinates, with deterministic placement, bounds-safe dimensions, and visibility/exploration alpha behavior. Keep all behavior presentation-owned. Existing world geometry, tile kind, passability, sight-blocking, hazard damage, enemy/pickup counts, objective progress, audio routes, public-demo boundaries, and save contracts must remain unchanged. High-contrast and reduced-motion modes should keep theme identity legible by adjusting tints, frame choice, or alpha without adding route-visible diagnostics. ### Design Patterns * Manifest-first asset acceptance: every accepted or rejected G3 candidate is recorded with source rectangle, target size, atlas, category, status, and notes. * Typed frame contract: G3 theme tile and decal frame names are union types and required atlas frames, not ad hoc strings. * Presentation boundary: theme visuals derive from existing `snapshot.theme`, tile kind, tile position, and preferences without mutating simulation state. * Deterministic sparse overlays: decals use stable tile coordinate hashing so repeated renders do not flicker or alter generated world output. * Product-surface discipline: browser proof belongs in tests and notes, not debug copy mounted into normal routes. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------ | ------------------------------------------------------------ | ---------- | | `.spec_system/specs/phase37-session04-g3-theme-decals/implementation-notes.md` | G3 candidate review, validation ledger, and browser evidence | \~170 | | `src/extensions/ai-rogue/runtime/theme-visuals.ts` | Typed sector theme visual mapping and deterministic helpers | \~160 | | `src/extensions/ai-rogue/runtime/__tests__/theme-visuals.test.ts` | Focused mapping, deterministic decal, and fallback coverage | \~140 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------- | | `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json` | Accepted/rejected G3 tile, wall, hazard, conduit, vault, core, crack, coolant, and decal choices | \~170 | | `src/assets/ai-rogue/gameplay-atlas.png` | Regenerated gameplay atlas containing accepted G3 theme tile and decal frames | Binary | | `src/assets/ai-rogue/gameplay-atlas.json` | Regenerated gameplay atlas metadata | \~100 | | `src/assets/ai-rogue/ui-atlas.png` | Preserve unchanged unless implementation proves a scoped UI-atlas need | Binary | | `src/assets/ai-rogue/ui-atlas.json` | Preserve unchanged unless implementation proves a scoped UI-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` | G3 theme tile/decal frame-name unions, constants, and simulation frame lists | \~90 | | `src/extensions/ai-rogue/runtime/assets.ts` | Required gameplay frame names and atlas validation expectations for accepted G3 work | \~45 | | `src/extensions/ai-rogue/runtime/themes.ts` | Sector theme visual metadata references if needed for local clarity | \~30 | | `src/extensions/ai-rogue/runtime/world-generator.ts` | Rule-preserving theme tile frame selection through `theme-visuals.ts` | \~90 | | `src/extensions/ai-rogue/runtime/renderer-layers.ts` | Theme-aware atmosphere colors while preserving reduced-motion behavior | \~70 | | `src/extensions/ai-rogue/runtime/renderer.ts` | Pass `snapshot.theme` into background rendering | \~10 | | `src/extensions/ai-rogue/runtime/render-model.ts` | Sparse G3 decal overlay sprites and high-contrast/reduced-motion presentation handling | \~120 | | `src/extensions/ai-rogue/runtime/__tests__/assets.test.ts` | Required-frame, atlas count, and TexturePacker metadata coverage for G3 frames | \~45 | | `src/extensions/ai-rogue/runtime/__tests__/themes.test.ts` | Theme visual coverage tied to existing sector theme IDs and ambience routes | \~45 | | `src/extensions/ai-rogue/runtime/__tests__/world.test.ts` | Seed/depth rule stability tests proving only frame names vary by theme | \~80 | | `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts` | Theme decal sprite, ordering, alpha, high-contrast, and reduced-motion coverage | \~120 | | `src/extensions/ai-rogue/runtime/__tests__/biome-final.test.ts` | Theme pressure and final-depth stability checks after G3 visual mapping | \~35 | | `tests/e2e/ai-rogue-runtime.spec.ts` | Desktop proof that each theme projects distinct in-bounds G3 visuals | \~80 | | `tests/e2e/ai-rogue-mobile.spec.ts` | Mobile proof for theme readability, no horizontal overflow, and no layout overlap | \~60 | | `docs/extensions/ai-rogue/visual-assets.md` | Current atlas counts, accepted/rejected G3 decisions, validation evidence, and caveats | \~90 | *** ## 7. Success Criteria ### Functional Requirements * [ ] G3 accepted and rejected candidates are recorded in `crop-manifest.json` with no unresolved placeholder entries. * [ ] Runtime gameplay atlas regenerates successfully and every accepted G3 frame is available through typed frame contracts. * [ ] Each of the five sector themes has at least one distinct tile variant and one distinct additive decal or equivalent presentation marker. * [ ] Generated worlds for the same seed/depth preserve tile kinds, passability, sight blocking, hazard damage, start/exit positions, enemy spawns, pickup spawns, and objective behavior while frame names vary by theme. * [ ] Normal, high-contrast, and reduced-motion presentations keep sector identity readable without route-visible diagnostics. ### 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, theme-visuals, themes, world, render-model, and biome-final 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 topology, enemy-rule, pickup-rule, objective-rule, combat, audio, persistence, save-schema, public-demo, hosted-runtime, or collector behavior changes. * [ ] AI Rogue production default-enabled posture and explicit `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` disable path are preserved. * [ ] No remote loading, hosted write, analytics, public-demo bridge call, WebGPU-only behavior, or new third-party data transfer is introduced. * [ ] Committed runtime image assets remain within 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 04 is the next executable session: the analysis script reports Phase 37 as current, no active session, Sessions 01 through 03 completed, and `phase37-session04-g3-theme-decals` as the first unfinished candidate; the Phase 37 PRD also recommends G3 after G8, G4, and G5. * G3 work can proceed from existing source inputs: the repo contains the G3 source sheet, alpha derivative, crop manifest, gameplay/UI atlases, and visual packer, so planning does not need user arbitration. * G3 is expected to be gameplay-atlas-only: the session stub describes sector decals and tile variants, the current UI atlas has no G3 entries, and the G3 source file is the sector-theme sheet rather than a UI/cinematic sheet. * A small `theme-visuals.ts` helper is warranted: five sector themes need the same visual mapping in world generation, render projection, renderer-layer atmosphere, and tests, and a typed helper keeps those mappings exhaustive. ### Conflict Resolutions * Master PRD phase table says Phase 37 is "Not Started", while the analysis script and `.spec_system/PRD/phase_37/PRD_phase_37.md` say Phase 37 is in progress with Sessions 01 through 03 complete. The script and phase PRD win because they are current generated state for the active phase and list the completed session IDs. ### Key Considerations * The manifest currently has 176 frame records, 159 accepted and 17 rejected, with no existing entries from the G3 sector-theme source file. * Current post-G5 gameplay atlas is 214 frames and 87,737 bytes, leaving room under the 200 KB per non-logo committed asset cap for a focused G3 pass. * Existing `themes.ts` already owns sector IDs, labels, pressure, palette hints, and theme ambience routes; G3 should add visual identity without reworking those gameplay semantics. * Existing render projection already supports high-contrast and reduced-motion preferences; G3 decals must join that preference path rather than bypass it. ### Relevant Considerations * \[P34-P36] **AI Rogue is production default-enabled**: preserve the current production posture and explicit disable path while adding visual polish. * \[P31-P36] **Public-demo and AI Rogue gates stay bundled**: keep asset-size, provenance, browser, no-remote-loading, no-bridge, and playthrough checks part of media/runtime validation. * \[P30/P34-P36] **Validation before expansion**: prove visual changes with focused evidence before widening runtime presentation. * \[P31-P35] **Do not let public demo become live runtime**: G3 must not add hosted writes, bridge calls, collectors, analytics, or runtime loading. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Theme visual mapping could accidentally change world rules instead of only frame names and presentation overlays. * High-contrast or reduced-motion preferences could hide theme identity or make decals visually noisy. * Browser proof could drift into route-visible diagnostics instead of keeping evidence in tests and notes. *** ## 9. Testing Strategy ### Unit Tests * `theme-visuals.test.ts` should prove exhaustive theme mappings, deterministic decal selection, valid fallbacks, and preference-aware frame choices. * `assets.test.ts` should prove every accepted G3 frame is present in the gameplay atlas, required frame lists, and TexturePacker metadata. * `themes.test.ts`, `world.test.ts`, and `biome-final.test.ts` should prove existing theme order, pressure, ambience, final-depth, and generation rule behavior still hold. * `render-model.test.ts` should prove G3 decals project in deterministic order, stay in bounds, use product-facing labels, and adjust for high-contrast and reduced-motion preferences. ### Integration Tests * Focused Vitest command should cover assets, theme-visuals, themes, world, render-model, and biome-final tests together. * Typecheck should prove frame-name unions, render model output, and renderer call-site changes stay aligned. ### Runtime Verification * Desktop Playwright proof should render deterministic scenarios for depths mapped to all five themes and assert distinct G3 frame names are present and in bounds. * Mobile Playwright proof should assert theme decals remain readable with compact input, no horizontal overflow, no incoherent overlap, and no diagnostics mounted into product UI. ### Edge Cases * G3 pictogram-like, stripe-like, lock-like, letter-like, or punctuation-like cells should be rejected or cropped into abstract marks before runtime use. * Unknown or malformed theme IDs should fall back to stable baseline visuals in helper tests, even though production theme IDs are typed. * Reduced-motion mode should avoid animated or flickering theme effects. * High-contrast mode should preserve core readability even when theme tints are muted or overridden. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase37-session01-g8-runtime-fx`, `phase37-session02-g4-status-equipment`, `phase37-session03-g5-boss-presentation`. * Depended by: `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-session04-g3-theme-decals/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.