> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/specs/phase24-session08-generated-asset-implementation-handoff/spec.md). # Session Specification **Session ID**: `phase24-session08-generated-asset-implementation-handoff` **Phase**: 24 - Legion II - Live Tier And Combat Playback **Status**: Not Started **Created**: 2026-07-08 **Base Commit**: dd8e2ba81fb2c1bacc9c67f372df354fd55705c9 **Package**: apps/web **Package Stack**: TypeScript *** ## 1. Session Overview This session promotes the three generated Phase 3 visual sheets from manifest-only evidence into typed `apps/web` implementation references. The existing live Legion, combat playback, scrying, and alert focus layers already render product state through DOM and CSS. This session adds a source-owned asset map, media catalog records, fallback labels, reduced-motion pairings, and tests so those layers can prove which generated asset or explicit fallback backs each Phase 24 visual state. It is next because Phase 24 sessions 03, 04, and 05 created the owned surfaces that need the handoff, and sessions 06 and 07 closed the audio/world cue and honesty boundaries. Session 09 depends on this evidence for phase-exit validation and documentation. The implementation must not make browser runtime code discover files directly from `assets/generated/game-design/`. If serving an image becomes necessary, the file must be promoted through an app-owned runtime path. The expected MVP path is typed catalog/reference metadata plus DOM/CSS fallback behavior. *** ## 2. Objectives 1. Add typed Phase 3 generated-asset records for live enemies, strike vocabulary, and reduced-motion static badges. 2. Connect Phase 24 presentation helpers and battlefield layers to direct asset ids or explicit typed fallback labels. 3. Prove with tests that every shipped live enemy, strike, combo/stage, scrying/alert, and static-badge state has asset or fallback coverage. 4. Update asset and media docs so the manifest, app catalog, and session handoff describe the same implementation posture. *** ## 3. Prerequisites ### Required Sessions * [x] `phase24-session03-live-enemy-presentation` - live enemy helpers and `LiveLegionLayer` exist. * [x] `phase24-session04-combat-playback-effects-layer` - linked mission playback helpers and `CombatPlaybackLayer` exist. * [x] `phase24-session05-scrying-and-alert-focus` - scrying posture and single alert focus layer exist. * [x] `phase24-session06-world-cues-and-bark-reuse` - world cues preserve the no-new-recorded-asset boundary. * [x] `phase24-session07-honesty-and-persistence-boundaries` - replay, mock, persistence, privacy, and browser-local erasure boundaries are closed for the new live-tier surfaces. ### Required Tools Or Knowledge * npm workspace scripts for `@factionos/web`. * Vitest focused package tests. * App media catalog pattern in `apps/web/src/data/mediaCatalog.ts`. * Generated asset manifest in `docs/game-design/manifest.md`. ### Environment Requirements * Node 26.2.0+ and npm 11.16.0 per project conventions. * Repository checkout with the three Phase 3 generated PNG sheets present under `assets/generated/game-design/phase03/`. *** ## 4. Scope ### In Scope (MVP) * `apps/web` implementers can reference Phase 3 generated asset ids, source paths, dimensions, usage keys, fallback labels, reduced-motion pairings, and runtime-readiness posture from typed source. * Live Legion helpers and components can expose asset or fallback posture for skirmishers, ram, gremlins, wraiths, and siege states with explicit loading, empty, and reduced-motion behavior preserved. * Combat playback helpers and components can expose asset or fallback posture for strikes, counterattacks, combo/stage treatments, HP drain, assault trim, and verified burn-down states with scoped timer cleanup unchanged. * Scrying and alert focus helpers and components can expose asset or fallback posture for channeling, alert focus, ram, siege, skirmisher, flare, gate, and camp focus states. * Media catalog and docs record the three Phase 3 sheets as implementation references, not release-ready browser runtime files. * Focused tests fail if the generated paths are missing, misspelled, left unmapped, or loaded directly from generated asset paths at runtime. ### Out Of Scope (Deferred) * New art generation or replacement art - Reason: the phase already has the production generated sheets. * Image slicing or sprite extraction - Reason: MVP handoff requires typed references and fallbacks; slicing can follow once UI needs browser-served pixels. * Public-demo mirroring - Reason: Phase 24 owns `apps/web` only unless a later media gate promotes runtime files. * New protocol events, server routes, storage keys, hosted dependencies, XP, loot, banners, titles, Battle Report, War Council, War Tide, seasons, or trusted-erasure claims - Reason: phase guardrails explicitly exclude them. *** ## 5. Technical Approach ### Architecture Create a dedicated `apps/web/src/lib/generatedPhase3Assets.ts` module that exports a small typed catalog for the three generated sheets and the Phase 24 visual states they cover. Presentation helpers will attach asset or fallback metadata to their existing view models. React layers will expose that posture through data attributes, accessibility text, and existing static labels, while continuing to render DOM/CSS visuals instead of loading image URLs from `assets/generated/game-design/`. The app media catalog will add conditional implementation-reference records for the same three sheets. These records will point at repository source paths, record dimensions and fallback posture, and remain blocked from release-ready runtime status until app-owned serving, slicing, metadata, and gates exist. ### Design Patterns * Dedicated typed map: Keeps generated asset ids and fallback posture in one reusable source without broadening protocol or store state. * Thin presentation metadata: Existing pure helpers remain the source for display state and expose asset posture without timers or DOM dependencies. * Component data attributes: Focused tests can assert coverage without adding debug UI or product-facing implementation notes. * Conditional media catalog records: Matches existing media catalog safety posture for generated references and non-release-ready assets. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/src/lib/generatedPhase3Assets.ts` | Typed Phase 3 generated asset ids, paths, dimensions, visual-state coverage, fallback labels, reduced-motion pairings, and runtime posture. | \~180 | | `apps/web/tests/generatedPhase3Assets.test.ts` | Focused tests for generated asset completeness, path existence, fallback coverage, reduced-motion pairings, and no direct runtime generated-path loading. | \~170 | ### Files To Modify | File | Changes | Est. Lines | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/src/data/mediaCatalog.ts` | Add app media catalog group and conditional records for the three Phase 3 generated sheets. | \~100 | | `apps/web/tests/mediaCatalog.test.ts` | Assert Phase 3 records validate, remain blocked from release-ready runtime status, and reference existing paths. | \~60 | | `apps/web/src/lib/mediaCatalog.ts` | Add optional query helper or summary filter support if needed for generated game-design references. | \~30 | | `apps/web/src/lib/liveLegion.ts` | Attach generated asset or fallback posture to live enemy presentation views. | \~45 | | `apps/web/src/components/battlefield/LiveLegionLayer.tsx` | Expose live enemy asset/fallback metadata while keeping product-facing DOM copy. | \~45 | | `apps/web/tests/liveLegion.test.ts` | Assert every live enemy state has generated asset or fallback coverage. | \~45 | | `apps/web/tests/LiveLegionLayer.test.tsx` | Assert rendered live enemy markers expose asset/fallback posture and reduced-motion labels. | \~45 | | `apps/web/src/lib/combatPlaybackEffects.ts` | Attach generated asset or fallback posture to strike, counterattack, combo/stage, HP, assault, and burn-down views. | \~55 | | `apps/web/src/components/battlefield/CombatPlaybackLayer.tsx` | Expose strike vocabulary and static-badge posture without adding image loads. | \~45 | | `apps/web/tests/combatPlaybackEffects.test.ts` | Assert every playback state has generated asset or fallback coverage. | \~50 | | `apps/web/tests/CombatPlaybackLayer.test.tsx` | Assert rendered playback markers expose asset/fallback posture and reduced-motion static twins. | \~50 | | `apps/web/src/lib/scryingAndAlertFocus.ts` | Attach reduced-motion static-badge posture to channeling and alert focus targets. | \~40 | | `apps/web/src/components/battlefield/ScryingAndAlertFocusLayer.tsx` | Expose scrying and alert asset/fallback metadata while preserving exactly one alert focus ring. | \~35 | | `apps/web/tests/scryingAndAlertFocus.test.ts` | Assert scrying and every alert focus kind has generated asset or fallback coverage. | \~45 | | `apps/web/tests/Battlefield.test.tsx` | Add integration coverage for rendered battlefield Phase 24 asset/fallback posture. | \~45 | | `docs/game-design/manifest.md` | Update Phase 3 runtime posture with app implementation reference ids and fallback stance. | \~35 | | `docs/media-assets.md` | Document Phase 3 generated sheets as app implementation references, not release-ready browser runtime files. | \~35 | *** ## 7. Success Criteria ### Functional Requirements * [ ] The three Phase 3 generated asset paths are referenced by `apps/web` source or catalog code, not only Markdown. * [ ] Every Phase 24 live enemy, strike, combo/stage, scrying, alert, and static-badge visual state has a direct asset id or typed fallback label. * [ ] Runtime code does not load or discover files directly from `assets/generated/game-design/`. * [ ] Reduced-motion static twins are paired with the reduced-motion sheet or an explicit fallback state. * [ ] No new protocol event, server route, storage key, hosted dependency, reward, or trusted-erasure claim is introduced. ### Testing Requirements * [ ] Unit tests cover generated asset path existence and mapping completeness. * [ ] Component tests cover rendered asset/fallback posture for live Legion, combat playback, scrying, and alert focus layers. * [ ] Media catalog tests validate the new records and blocked runtime posture. * [ ] Web typecheck passes. ### Non-Functional Requirements * [ ] Generated asset records keep sensitive source data out of normal UI, WebSocket, export, storage, and docs examples. * [ ] Layer metadata does not add visible debug text to product surfaces. * [ ] Existing loading, empty, error, reduced-motion, timer cleanup, and duplicate-trigger protections remain unchanged. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] UI surfaces contain product-facing copy only. *** ## 8. Implementation Notes ### Working Assumptions * App-owned runtime serving is not required for this session: The session stub says to preserve DOM/CSS-first behavior when a sheet is not sliced or app-served yet, and the existing Phase 24 layers already render CSS/DOM state. Planning can proceed by adding typed implementation references, fallback labels, and tests without loading image URLs. * The new asset posture belongs in a dedicated `apps/web` map plus conditional media catalog records: Existing media catalog records distinguish release ready runtime assets from generated references and blocked media. This keeps Phase 3 sheets discoverable without promoting runtime claims. ### Conflict Resolutions * Phase 3 sheets are production generated assets, but phase guardrails prohibit runtime code from discovering or loading directly from `assets/generated/game-design/`: The chosen interpretation is typed source and catalog references with explicit fallback posture. Browser-served copies stay deferred until app-owned paths and media gates exist. ### Key Considerations * Keep product UI copy focused on battlefield state, not implementation details. * Keep reduced-motion equivalence visible through static labels and data posture while avoiding new animation requirements. * Keep generated asset references aggregate and non-sensitive; do not add raw prompts, paths, file contents, provider payloads, terminal output, or scan roots to UI or persisted state. ### Potential Challenges * Asset map could drift from the manifest: Add tests that assert asset ids, source paths, dimensions, and path existence. * Layer metadata could become debug UI: Use data attributes and screen-reader product summaries rather than visible implementation strings. * Media catalog expectations may change counts: Update catalog tests with explicit Phase 3 records and blocked release posture. ### Relevant Considerations * \[P23-apps/web] **Scanner camp projection stays aggregate-only**: Do not add raw issue text, prompts, paths, file contents, provider payloads, scan roots, or secrets to projection or battlefield state. * \[P23-apps/web] **Scanner camps are projection-owned**: New battlefield asset references should read existing selectors and helpers, not create parallel game authority. * \[P22-apps/web] **Do not add parallel game authorities**: Asset posture is metadata on existing presentation views, not new state. * \[P20] **Broad privacy gates are release-critical**: Keep raw commands, terminal output, diffs, file contents, webhook bodies, provider payloads, tokens, secrets, broad paths, and scanner details out of normal surfaces. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Generated asset references could be mistaken for browser-served runtime assets. * Reduced-motion parity could drift if static-badge coverage is not tested. * Battlefield layers could expose implementation/debug copy to normal users. *** ## 9. Testing Strategy ### Unit Tests * `apps/web/tests/generatedPhase3Assets.test.ts` covers ids, dimensions, source paths, path existence, usage coverage, fallback labels, reduced-motion pairings, and no generated-path runtime URL. * `apps/web/tests/liveLegion.test.ts`, `apps/web/tests/combatPlaybackEffects.test.ts`, and `apps/web/tests/scryingAndAlertFocus.test.ts` cover asset/fallback posture on pure presentation output. * `apps/web/tests/mediaCatalog.test.ts` covers catalog record validity, blocked runtime posture, fallback, accessibility, privacy, and path existence. ### Integration Tests * `apps/web/tests/LiveLegionLayer.test.tsx`, `apps/web/tests/CombatPlaybackLayer.test.tsx`, `apps/web/tests/Battlefield.test.tsx`, and related focused layer tests cover rendered data posture, reduced-motion static twins, loading/empty/error preservation, and product-facing copy only. ### Runtime Verification * Run focused Vitest files for generated assets, media catalog, live Legion, combat playback, scrying/alert, and battlefield integration. * Run `npm --workspace @factionos/web run typecheck`. ### Edge Cases * Missing or misspelled generated asset path fails a focused test. * A visual state without asset id or fallback label fails a focused test. * Reduced-motion target without static-badge pairing or fallback fails a focused test. * Runtime URL set to `assets/generated/game-design/` fails a focused test. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase24-session03-live-enemy-presentation`, `phase24-session04-combat-playback-effects-layer`, `phase24-session05-scrying-and-alert-focus`, `phase24-session06-world-cues-and-bark-reuse`, `phase24-session07-honesty-and-persistence-boundaries` * Depended by: `phase24-session09-validation-and-documentation` *** ## 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://faction-os.gitbook.io/faction-os-docs/.spec_system/specs/phase24-session08-generated-asset-implementation-handoff/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.