> 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/archive/sessions/phase02-session04-battlefield-state-and-interaction-polish/tasks.md).

# Task Checklist

**Session ID**: `phase02-session04-battlefield-state-and-interaction-polish` **Total Tasks**: 21 **Estimated Duration**: 3-4 hours **Created**: 2026-05-29

***

## Legend

* `[x]` = Completed
* `[ ]` = Pending
* `[P]` = Parallelizable (can run with other \[P] tasks)
* `[SNNMM]` = Session reference (NN=phase number, MM=session number)
* `TNNN` = Task ID

***

## Progress Summary

| Category       | Total  | Done   | Remaining |
| -------------- | ------ | ------ | --------- |
| Setup          | 3      | 3      | 0         |
| Foundation     | 5      | 5      | 0         |
| Implementation | 9      | 9      | 0         |
| Testing        | 4      | 4      | 0         |
| **Total**      | **21** | **21** | **0**     |

***

## Setup (3 tasks)

Initial verification and battlefield evidence capture.

* [x] T001 \[S0204] Verify Session 01, Session 02, and Session 03 prerequisites plus baseline focused battlefield tests (`.spec_system/PRD/phase_02/session_04_battlefield_state_and_interaction_polish.md`)
* [x] T002 \[S0204] Create implementation notes with baseline commands, source audit, decisions, and open-risk log (`.spec_system/specs/phase02-session04-battlefield-state-and-interaction-polish/implementation-notes.md`)
* [x] T003 \[S0204] Audit current battlefield state, interaction, fallback, reduced-motion, and documentation contracts against PRD, UX PRD, and gap matrix (`docs/battlefield.md`)

***

## Foundation (5 tasks)

Core state helpers, CSS hooks, and focused test scaffolding.

* [x] T004 \[S0204] \[P] Refine battlefield coordinate and label-placement helper coverage with clamped, missing, non-finite, and edge-position cases (`apps/web/tests/battlefield2d.test.ts`)
* [x] T005 \[S0204] \[P] Extend achievement celebration helper coverage for fresh unlock ordering, deterministic tones, concurrent caps, and cleanup assumptions (`apps/web/tests/achievementCelebration.test.ts`)
* [x] T006 \[S0204] Define battlefield token state-label, fallback, and accessible-name decisions with types matching declared contract and exhaustive enum handling (`apps/web/src/components/battlefield/Battlefield.tsx`)
* [x] T007 \[S0204] Harden board-level selection clearing and token activation boundaries with platform-appropriate accessibility labels, focus management, and input support (`apps/web/src/components/battlefield/Battlefield.tsx`)
* [x] T008 \[S0204] Establish focused battlefield interaction test scaffolding for all hero states, selected state, fallbacks, and reduced-motion fixtures (`apps/web/tests/BattlefieldInteraction.test.tsx`)

***

## Implementation (9 tasks)

Main battlefield state, interaction, fallback, reduced-motion, and docs work.

* [x] T009 \[S0204] Update hero token accessible names, `aria-pressed`, active mission context, and selected label synchronization with state reset or revalidation on re-entry (`apps/web/src/components/battlefield/Battlefield.tsx`)
* [x] T010 \[S0204] Add static state labels or badges for active, awaiting input, verifying, error, spawning, dismissed, selected, and idle heroes so state meaning does not rely on color alone (`apps/web/src/components/battlefield/Battlefield.tsx`)
* [x] T011 \[S0204] Refine battlefield token CSS rings, halos, state marks, dismissed treatment, and focus-visible styling with reduced-motion-safe static indicators (`apps/web/src/index.css`)
* [x] T012 \[S0204] Harden background fallback and hero asset fallback rendering with explicit loading, empty, error, and offline states (`apps/web/src/components/battlefield/Battlefield.tsx`)
* [x] T013 \[S0204] Refine label placement and board positioning behavior for top, bottom, missing, and outlying coordinates with bounded positioning behavior (`apps/web/src/lib/battlefield2d.ts`)
* [x] T014 \[S0204] Harden achievement burst lifecycle with cleanup on scope exit for all acquired resources and concurrent cap enforcement (`apps/web/src/components/battlefield/Battlefield.tsx`)
* [x] T015 \[S0204] Refine achievement burst helper behavior for deterministic diffing and tone output without introducing new asset or sound dependencies (`apps/web/src/components/battlefield/achievementCelebration.ts`)
* [x] T016 \[S0204] Document completed app-side battlefield interaction, state, fallback, and reduced-motion behavior plus Session 05 asset and public-demo boundaries (`docs/battlefield.md`)
* [x] T017 \[S0204] Update web package README battlefield contract and deferred public-demo parity boundary (`apps/web/README_web.md`)

***

## Testing (4 tasks)

Focused verification and quality gates.

* [x] T018 \[S0204] \[P] Write component tests for battlefield selection, empty-board clear, token accessible names, selected state, and roster/detail synchronization (`apps/web/tests/Battlefield.test.tsx`)
* [x] T019 \[S0204] \[P] Write component tests for all battlefield hero states, static indicators, failed background, failed hero art, and reduced-motion behavior (`apps/web/tests/BattlefieldInteraction.test.tsx`)
* [x] T020 \[S0204] \[P] Write fake-timer tests for achievement burst cap, lifetime removal, reduced-motion static output, and unmount cleanup (`apps/web/tests/Battlefield.test.tsx`)
* [x] T021 \[S0204] Run focused battlefield tests, existing hero workflow tests, `npm --workspace apps/web run typecheck`, relevant Biome checks, ASCII validation, and manual battlefield smoke notes (`apps/web/package.json`)

***

## Completion Checklist

Before marking session complete:

* [x] All tasks marked `[x]`
* [x] All tests passing
* [x] All files ASCII-encoded
* [x] `implementation-notes.md` updated
* [x] Ready for the validate workflow step

***

## Next Steps

Run the validate workflow step to verify session completeness.


---

# 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/archive/sessions/phase02-session04-battlefield-state-and-interaction-polish/tasks.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.