> 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-session06-g7-player-animation/spec.md).

# Session Specification

**Session ID**: `phase37-session06-g7-player-animation` **Phase**: 37 - AI Rogue Visual Asset Finishing **Status**: Not Started **Created**: 2026-06-29

***

## 1. Session Overview

This session closes Phase 37 by deciding whether the generated G7 player animation source can ship at AI Rogue's 16x16 runtime footprint. It is next because the analysis script reports Phase 37 as current, no active session, Sessions 01 through 05 complete, and Session 06 as the only unfinished current-phase candidate.

The work is intentionally conditional. The implementation must review the G7 side-facing, idle, movement, Strike, Surge cast, hurt, recovery, and optional low-HP candidates at runtime scale before wiring them. If the generated frames are readable, they can be cropped, packed, typed, and animated. If they are not readable, the correct product outcome is to record G7 as redraw reference and leave the existing player frame family unchanged.

The session must preserve AI Rogue's simulation behavior, player footprint, collision, input rules, combat balance, browser-local state, production default posture, public-demo boundary, no remote loading, reduced-motion behavior, and the existing two-atlas model unless size evidence proves a scoped change is needed.

***

## 2. Objectives

1. Produce a documented 16x16 G7 downscale review with visual evidence and a clear ship-or-redraw decision.
2. Record accepted or rejected G7 crop-manifest decisions with source, footprint, alpha, and readability notes.
3. If accepted, add typed player frame contracts, required atlas validation, and renderer animation that is presentation-only and simulation-independent.
4. Prove the final outcome with focused tests, asset validation, docs, and desktop/mobile runtime evidence showing either readable G7 animation or a deliberate no-op runtime decision.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase37-session01-g8-runtime-fx` - Provides runtime FX, status overlay, reduced-motion, high-contrast, atlas validation, and browser proof patterns.
* [x] `phase37-session02-g4-status-equipment` - Provides stable UI frame contract patterns and post-G4 atlas validation.
* [x] `phase37-session03-g5-boss-presentation` - Provides multi-frame entity presentation patterns and renderer animation guardrails.
* [x] `phase37-session04-g3-theme-decals` - Provides current gameplay atlas growth evidence and theme visual proof.
* [x] `phase37-session05-g6-ui-cinematics` - Provides latest atlas counts, browser evidence workflow, and final visual-docs context before G7.

### Required Tools Or Knowledge

* Python visual packer: `scripts/extensions/ai-rogue/pack-visual-assets.py`.
* G7 source and alpha derivative: `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/source/ai-rogue-player-animation-source.png` and `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/alpha/ai-rogue-player-animation-alpha.png`.
* Current crop manifest: `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json`.
* Current player render path: `src/extensions/ai-rogue/runtime/types-assets.ts`, `src/extensions/ai-rogue/runtime/assets.ts`, `src/extensions/ai-rogue/runtime/render-model.ts`, `src/extensions/ai-rogue/runtime/renderer-sprites.ts`, and `src/extensions/ai-rogue/runtime/renderer.ts`.
* 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`.

### Environment Requirements

* Dependencies installed with Bun.
* Python environment can run the Pillow-backed visual packer.
* Browser checks can run AI Rogue Play at desktop and mobile viewport sizes.
* Current player rendering tests and runtime smoke checks should pass before edits, or any pre-existing failure must be recorded before changing G7 files.

***

## 4. Scope

### In Scope (MVP)

* Player can benefit from readable idle, walk, Strike, Surge cast, hurt, recovery, and optional low-HP animation frames only if G7 downscale evidence proves they work at the 16x16 runtime footprint.
* Maintainer can inspect a docs-only G7 downscale review image and manifest notes that explain which frames ship and which become redraw reference.
* If accepted, renderer animation cycles presentation frames from clock and movement/tween state while simulation state remains the owner of player position, facing, health, commands, combat events, and rules.
* If rejected, existing `player_*` atlas frames and runtime projection remain unchanged, and tests prove no weak visual replacement shipped.
* User-facing runtime surfaces preserve explicit loading, mount failure, error, reduced-motion, compact-input, mobile, and product-copy behavior.

### Out Of Scope (Deferred)

* Changing player footprint, source tile size, collision, pathing, movement rules, input rules, combat balance, command timing, status effect rules, or progression rewards - Reason: Session 06 is a visual decision and wiring pass only.
* Shipping unreadable downscaled frames because they are available in source - Reason: Phase 37 requires real runtime readability over typed scaffolding.
* Adding a third atlas or remote asset loading - Reason: the current two-atlas model and no remote-loading boundary remain preferred.
* Changing persistence schemas, localStorage or IndexedDB keys, public-demo fixture behavior, hosted writes, collectors, analytics, workers, or WebGPU requirements - Reason: Phase 37 preserves the approved production posture.
* Adding debug UI or route-visible frame names - Reason: proof belongs in tests, screenshots, docs, and implementation notes, not product surfaces.

***

## 5. Technical Approach

### Architecture

Start with evidence, not wiring. Generate a docs-only G7 downscale review image from the source and alpha derivative, compare candidate rows at 16x16, and record the ship-or-redraw decision in `implementation-notes.md`, the crop manifest, and `visual-assets.md`.

If the direct-use review passes, add G7 crop-manifest entries from the alpha derivative, run the existing packer, and keep frames in the gameplay atlas. Extend `types-assets.ts` with a narrow G7 player frame contract and include accepted frames in `assets.ts` required frame validation. Use existing player facing and renderer clock/tween state to animate sprites in `renderer-sprites.ts` and `renderer.ts` without writing animation state into the simulation model.

If the direct-use review fails, add rejected manifest entries and docs evidence instead of adding frame contracts or runtime wiring. The existing player frame family remains the runtime source, and focused tests should assert required frame lists and player projection still use the existing stable frames.

### Design Patterns

* Evidence-first visual acceptance: docs-only downscale proof determines whether runtime code changes are allowed.
* Manifest-first asset tracking: accepted and rejected G7 candidates are recorded with source rectangle, target size, atlas, status, category, and notes.
* Typed frame contract: accepted G7 frames become union types and required atlas frames, not ad hoc strings.
* Presentation boundary: renderer animation uses descriptors, textures, clock, and tween context; simulation remains deterministic and state-owned.
* Product-surface discipline: runtime routes stay product-facing and do not expose frame names, debug labels, source paths, or diagnostics.

***

## 6. Deliverables

### Files To Create

| File                                                                               | Purpose                                                      | Est. Lines |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------- |
| `.spec_system/specs/phase37-session06-g7-player-animation/implementation-notes.md` | G7 downscale review, ship-or-redraw decision, and validation | \~160      |
| `docs/extensions/ai-rogue/generated/ai-rogue-g7-player-downscale-review.png`       | Docs-only 16x16 review evidence for G7 candidates            | Binary     |

### Files To Modify

| File                                                                              | Changes                                                                                              | Est. Lines |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- |
| `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json` | Accepted or rejected G7 player crop decisions with explicit downscale notes                          | \~120      |
| `src/assets/ai-rogue/gameplay-atlas.png`                                          | Regenerated only if G7 frames are accepted                                                           | Binary     |
| `src/assets/ai-rogue/gameplay-atlas.json`                                         | Regenerated gameplay atlas metadata only if G7 frames are accepted                                   | \~80       |
| `src/assets/ai-rogue/ui-atlas.png`                                                | Preserve unchanged except for normal packer output ordering if the packer touches both atlases       | Binary     |
| `src/assets/ai-rogue/ui-atlas.json`                                               | Preserve unchanged except for normal packer output ordering if the packer touches both atlases       | \~0        |
| `docs/extensions/ai-rogue/generated/ai-rogue-production-atlas-preview.png`        | Regenerated docs-only atlas preview if the packer runs                                               | Binary     |
| `src/extensions/ai-rogue/runtime/types-assets.ts`                                 | Accepted G7 player frame-name unions and constants, or rejection tests preserving existing contracts | \~60       |
| `src/extensions/ai-rogue/runtime/assets.ts`                                       | Required gameplay frame names and atlas validation expectations for accepted G7 work                 | \~30       |
| `src/extensions/ai-rogue/runtime/render-model.ts`                                 | Player frame selection helper only if G7 is accepted; simulation-independent projection              | \~60       |
| `src/extensions/ai-rogue/runtime/renderer-sprites.ts`                             | Player sprite animation helper only if G7 is accepted, with reduced-motion handling                  | \~80       |
| `src/extensions/ai-rogue/runtime/renderer.ts`                                     | Call accepted player animation helper after sprite sync without changing command or tween semantics  | \~25       |
| `src/extensions/ai-rogue/runtime/effects.ts`                                      | Optional action/hurt presentation hook only if accepted frames need existing event timing            | \~35       |
| `src/extensions/ai-rogue/runtime/__tests__/assets.test.ts`                        | G7 required-frame coverage if accepted, or no-op contract coverage if rejected                       | \~45       |
| `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts`                  | Player facing and frame-selection coverage without simulation-rule changes                           | \~55       |
| `src/extensions/ai-rogue/runtime/__tests__/renderer-lifecycle.test.ts`            | Player animation cycling, reduced-motion behavior, and cleanup coverage if accepted                  | \~55       |
| `src/extensions/ai-rogue/runtime/__tests__/simulation.test.ts`                    | Guard that movement, facing, combat, and player frame state remain deterministic                     | \~35       |
| `tests/e2e/ai-rogue-runtime.spec.ts`                                              | Desktop runtime proof for readable accepted animation or unchanged rejected baseline                 | \~70       |
| `tests/e2e/ai-rogue-mobile.spec.ts`                                               | Mobile proof for 16x16 readability or documented no-op baseline                                      | \~55       |
| `docs/extensions/ai-rogue/visual-assets.md`                                       | G7 decision, atlas counts, accepted/rejected candidates, validation evidence, and redraw caveat      | \~100      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] G7 downscale review evidence exists and documents whether direct runtime use passes or fails.
* [ ] `crop-manifest.json` records accepted or rejected G7 candidates with no unresolved entries.
* [ ] If accepted, player idle/movement/action presentation uses accepted G7 frames at stable 16x16 source footprint without simulation-state changes.
* [ ] If rejected, existing player rendering remains unchanged and G7 is documented as redraw reference.
* [ ] Desktop and mobile AI Rogue runtime proof shows the final product outcome without route-visible diagnostics or frame names.

### Testing Requirements

* [ ] `python3 scripts/extensions/ai-rogue/pack-visual-assets.py` runs if any G7 frames are accepted.
* [ ] `bun run typecheck` passes.
* [ ] `bash scripts/check-asset-sizes.sh` passes.
* [ ] Focused assets, render-model, renderer-lifecycle, and simulation tests pass for the chosen branch.
* [ ] `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.
* [ ] Player source footprint remains 16x16 unless a rejection is recorded.
* [ ] Reduced-motion mode remains readable and avoids unnecessary animation.
* [ ] Runtime image assets remain within media-policy caps.
* [ ] Normal user-facing surfaces contain product-facing copy only.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] `git diff --check` passes.
* [ ] Implementation notes explain the ship-or-redraw decision with evidence.

***

## 8. Implementation Notes

### Working Assumptions

* G7 source review is the gating deliverable, not a formality: the Phase 37 PRD and Session 06 stub both state that side-facing G7 frames need 16x16 downscale review before direct runtime use, and rejection is an acceptable product outcome.
* The current repo is single-package for this session: the analysis script reported `monorepo: null`, no packages, and no active package context, so all paths are repo-root-relative.
* Existing player frame family is the safe fallback: the committed gameplay atlas already contains `player_down_0` through `player_up_2`, and `render-model.ts` currently projects the simulation-provided player `frameName`; planning can proceed with a no-op branch if G7 fails review.

### Key Considerations

* The existing two-atlas model should be preserved while asset-size checks pass.
* G7 must improve the runtime player visually at 16x16; typed frame names or atlas metadata alone are not sufficient.
* Any accepted animation must be presentation-only and must not widen save, command, input, collision, or combat contracts.
* Evidence belongs in generated docs images, implementation notes, tests, and Playwright proof, not in normal AI Rogue product routes.

### Potential Challenges

* Side-facing rows may lose silhouette at 16x16: reject direct runtime use and document the redraw path instead of shipping unclear frames.
* Player action frames may imply mechanics that do not exist: restrict accepted use to existing Strike, Surge, hurt, and recovery events derived from current simulation events.
* Clock-driven animation can drift from deterministic snapshots: keep it in the renderer sprite layer and make reduced-motion fall back to static frames.
* Atlas size can grow unexpectedly: keep accepted G7 frames narrow and rerun `scripts/check-asset-sizes.sh`.

### Relevant Considerations

* \[P34-P36] **AI Rogue is production default-enabled**: Runtime visual changes must preserve the approved default posture and the explicit `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` disable path.
* \[P31-P36] **Public-demo and AI Rogue gates stay bundled**: Media/runtime work must keep asset-size, no-remote-loading, browser proof, mobile proof, and product-copy checks together.
* \[P30/P34-P36] **Visibility gates catch real issues**: Typecheck, focused tests, asset size, browser proof, and visual evidence are part of the session definition, not optional closeout polish.
* \[P30/P32/P34-P35] **Route-lazy runtime ownership scales**: Pixi runtime changes should stay behind the mounted Play route/local runtime facade.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Shipping unreadable player animation because manifest or atlas work looks complete without runtime-scale evidence.
* Accidentally moving animation state into the simulation model and changing deterministic snapshots, saves, or command behavior.
* Breaking reduced-motion, compact mobile play, or mounted-route cleanup while adding renderer-clock animation.

***

## 9. Testing Strategy

### Unit Tests

* Verify accepted G7 frame metadata and required-frame membership, or verify unchanged required-frame contracts if G7 is rejected.
* Verify player frame selection preserves facing, footprint, and product labels without changing simulation-owned state.
* Verify renderer sprite animation cycles accepted player frames, respects reduced motion, and does not leak inactive sprites.
* Verify simulation movement, Strike, Surge, hurt, recovery, and facing behavior remain deterministic.

### Integration Tests

* Run focused AI Rogue runtime test files that cover assets, render-model, renderer lifecycle, and simulation behavior.
* Run the packer only when G7 accepted frames are added and verify atlas output remains valid.

### Runtime Verification

* Desktop AI Rogue Play proof shows accepted animation is readable during idle, movement, and action/recovery moments, or confirms the rejected branch leaves baseline player visuals unchanged.
* Mobile AI Rogue Play proof checks the same branch at compact viewport sizes with no horizontal overflow, no product-copy diagnostics, and stable controls.

### Edge Cases

* G7 source rows are too detailed or ambiguous at 16x16.
* Reduced-motion mode should not keep cycling frames.
* Player damage, low-health, and recovery frames must not conceal health/status overlays.
* Missing accepted textures must fail tests or fall back safely without blank sprites.
* Rejected branch must not leave half-added frame names in types or required atlas lists.

***

## 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`, and `phase37-session05-g6-ui-cinematics`.
* Depended by: Phase 37 closeout through `updateprd`; no later Phase 37 session depends on this plan.

***

## 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-session06-g7-player-animation/spec.md?ask=<question>&goal=<endgoal>
```

`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.