> 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-session03-live-enemy-presentation/implementation-notes.md). # Implementation Notes **Session ID**: `phase24-session03-live-enemy-presentation` **Package**: apps/web **Started**: 2026-07-08 06:15 **Last Updated**: 2026-07-08 09:13 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 20 / 20 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Task Log ### Tasks T001-T002 - Grounding **Completed**: 2026-07-08 06:18 **Notes**: * Reducer event shapes verified: `test_failure {path, message}` spawns via `withLegionSkirmisher` (fold-time sanitized by `normalizeEnemyPathRef`); `build_error`/`build_fix {detail}` set/clear the ram; `ts_errors {count, files}` and `lint_error` drive gremlin pressure; stall trio drives siege levels 1-3; `tool_result` `ok:false` stacks wraiths (cap 3 in `MAX_WRAITH_STACK`). * Grounding correction resolved: the initial event set had no skirmisher clear signal, so this implementation adds a minimal shared `test_pass` protocol event and folds it through the same normalized path boundary to remove the matching skirmisher. * Enemy refs are sanitized at fold time (anchored path scoping, safe token pattern, sensitive redaction) - presentation only bounds display length. ### Tasks T003-T007 - Pure model and CSS **Completed**: 2026-07-08 06:22 **Notes**: * `apps/web/src/lib/liveLegion.ts`: constants (`LIVE_LEGION_SKIRMISHER_VISIBLE_LIMIT` 6, wraith cap 3, keep anchor 50/84, gremlin anchor 60/80, siege anchor 40/80, top-edge skirmisher spread 22-78 at 9), `liveLegionPresentation` (caps, overflow, ordering: skirmishers oldest-first, wraiths stack-desc-then-heroId), gremlin totals hiding at zero, ram/siege views, `threatCount`, `wraithDarkeningTier`. * Motion CSS appended to the battlefield block in `index.css`: skirmisher pulse, ram slow-rock, gremlin jitter, wraith drift - all disabled under `.battlefield2d-reduce-motion` (same pattern as camp/token rules). ### Tasks T008-T015 - Layer and mount **Completed**: 2026-07-08 06:26 **Notes**: * `LiveLegionLayer.tsx`: pointer-events-none layer at z-\[16] (camps 15, heroes 20), sr-only threat summary, exported test-id helpers; skirmisher edge markers with title + sr path text and "+N more" overflow chip; ram at the keep anchor with motion class and cracked-gate static chip; gremlin chip (unicode-escaped gear) with pressure breakdown sr text; wraith buttons beside hero coordinates (offset +4/-7) that select the hero, darkening tiers 1-3; siege banner with level + stalled count. * Battlefield mounts the layer after `ScannerStateLayer` with memoized presentation, hero coordinate/name records (visible heroes only), and the existing `setSelectedHeroId`. * Off-board heroes: wraiths counted in the summary, never positioned. ### Tasks T016-T020 - Tests and gates **Completed**: 2026-07-08 06:30 **Notes**: * `liveLegion.test.ts` (8 tests): zero states, caps/overflow/ordering, gremlin totals, bounded labels, threat counting, darkening tiers. * `LiveLegionLayer.test.tsx` (7 tests): per-kind rendering, reduced-motion static twins, wraith click-to-select, off-board skip, siege banner, hostile-detail bounding. * `Battlefield.test.tsx` (+2 tests): real `test_failure`/`test_pass`/`build_error` events through `applyEvent` render markers, `build_fix` clears the ram, `test_pass` clears the skirmisher, wraith click selects the hero, layer z-order below tokens. * Gates: full repo tests 3321/3321 with 1 skipped, workspace typecheck, Biome, root format:check, ASCII/LF all clean. **Files Changed**: * `apps/web/src/lib/liveLegion.ts` (new) * `apps/web/src/components/battlefield/LiveLegionLayer.tsx` (new) * `apps/web/src/components/battlefield/Battlefield.tsx` * `apps/web/src/index.css` * `apps/web/tests/liveLegion.test.ts` (new) * `apps/web/tests/LiveLegionLayer.test.tsx` (new) * `apps/web/tests/Battlefield.test.tsx` * `packages/protocol/src/events.ts` * `packages/protocol/tests/events.test.ts` **BQC Fixes**: * Bounded rendering under storms: caps enforced in the pure model, tested with oversize inputs. * Accessibility: only wraiths are interactive (pointer-events-auto buttons); informational markers are aria-hidden visuals + sr text, so the hero tab order is not polluted by transient threat markers. ### Resume Correction - Presentation Boundary And Pass-Clear Contract **Completed**: 2026-07-08 09:13 **Notes**: * Tightened `liveLegionPresentation` so skirmisher display refs and ram labels are derived through `normalizeLegionIssuePathSegments` plus `sanitizeLegionSectorLabel`, matching T004's display-boundary requirement even if a direct model input bypasses reducer normalization. * Strengthened pure and component privacy tests so raw absolute paths, secret-shaped segments, query strings, and long ram details do not leak through labels or DOM attributes. * Added the minimal `test_pass {path}` shared protocol event and reducer handling so `test_failure -> marker -> test_pass -> cleared` is covered by the normal store path rather than leaving the criterion unresolved. **Files Changed**: * `apps/web/src/lib/liveLegion.ts` - added camp sanitizer reuse for live enemy display labels/refs. * `apps/web/tests/liveLegion.test.ts` - added hostile path/detail presentation-boundary assertions. * `apps/web/tests/LiveLegionLayer.test.tsx` - added DOM-level privacy assertions for skirmisher refs and ram details. * `.spec_system/specs/phase24-session03-live-enemy-presentation/tasks.md` - checked the completion checklist and corrected the handoff to `creview`. * `packages/protocol/src/events.ts` - added the `TestPassEvent` contract. * `packages/protocol/tests/events.test.ts` - added `test_pass` to event type coverage. * `apps/web/src/lib/gameProjection.ts` - removes normalized skirmisher refs on `test_pass`. * `apps/web/tests/gameProjection.test.ts` - covers pass-clearing and idempotent duplicate passes. * `apps/web/tests/Battlefield.test.tsx` - covers pass-clearing through `useGameStore.applyEvent`. * `docs/api/event-api-hook-contracts.md` - lists `test_pass` with the dev-health event family. * `docs/game-design/02-core-gameplay-and-player-verbs.md`, `docs/game-design/07-content-audio-and-feature-inventory.md`, `docs/game-design/08-production-roadmap-and-phase-a-spec.md`, `docs/game-design/10-technical-design-and-game-projection.md`, `docs/game-design/11-open-questions-and-change-log.md`, `docs/game-design/13-implementation-phase-outline.md`, and `docs/game-design/15-phases-yet-to-be-implemented.md` - aligned skirmisher event inventories with `test_failure`/`test_pass`. **Verification**: * Command/check: `npm test -- apps/web/tests/liveLegion.test.ts apps/web/tests/LiveLegionLayer.test.tsx apps/web/tests/Battlefield.test.tsx` * Result: PASS - 3 files, 45 tests. * Command/check: `npm test -- packages/protocol/tests/events.test.ts apps/web/tests/gameProjection.test.ts apps/web/tests/liveLegion.test.ts apps/web/tests/LiveLegionLayer.test.tsx apps/web/tests/Battlefield.test.tsx` * Result: PASS - 5 files, 95 tests. * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS - web TypeScript build check completed. * Command/check: `npm run typecheck` * Result: PASS - all workspaces, including protocol and web. * Command/check: `npm test` * Result: PASS - 282 files passed, 1 skipped; 3321 tests passed, 1 skipped. * Command/check: `npm run format:check` * Result: PASS - 780 files checked, no fixes applied. * Command/check: `npm run lint` * Result: PASS - 782 files checked, no fixes applied. * Command/check: ASCII/LF validation over changed session, protocol, and web files * Result: PASS - no non-ASCII or CRLF found. * UI product-surface check: PASS - live markers render safe product threat labels only; no debug/runtime/scaffolding copy added. * UI craft check: PASS - existing battlefield layer ordering, reduced-motion twins, sr-only summary, and native wraith button behavior preserved. **BQC Fixes**: * Trust boundary/error information boundaries: presentation layer now sanitizes direct live-enemy display values before they enter labels or DOM attributes (`apps/web/src/lib/liveLegion.ts`). * Contract alignment: shared `ServerEvent` now includes `test_pass`, and the web reducer/integration tests consume that event through the normal store path (`packages/protocol/src/events.ts`, `apps/web/src/lib/gameProjection.ts`). **Out-of-Scope Files**: * `packages/protocol/src/events.ts` - required shared event contract for the apps/web pass-clearing success criterion. * `packages/protocol/tests/events.test.ts` - required protocol coverage for the shared event contract. * `docs/api/event-api-hook-contracts.md` and `docs/game-design/*.md` files - required contract/design documentation alignment for the new shared event. *** ## Design Decisions ### Decision 1: Skirmishers are informational, wraiths are interactive Skirmisher inspect-through is the visible safe test path (title + sr text); adding buttons for every failing test would flood the tab order during test storms. Wraiths are buttons because their real source is the hero, and selecting the hero is the existing inspection affordance. ### Decision 2: Skirmisher clearing uses an explicit pass event Skirmishers clear only on the explicit `test_pass {path}` event using the same normalized path boundary as `test_failure`. Aging markers out on a timer would fabricate "fixed" state and violate Fun Law 1. ### Decision 3: Keep anchor constants exported from liveLegion.ts `LIVE_LEGION_KEEP_ANCHOR` (50, 84) is the stable gate anchor for Session 04 ram-break effects and design Phase 9 set pieces. --- # 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-session03-live-enemy-presentation/implementation-notes.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.