ttrpg-initiative-tracker/TODO.md

# TODO

## Milestone M4 — Initiative rotation bugs + features

Split: bug (rotation corruption) vs feature (dead-participant handling).

### BUG-5: Initiative skip (mid-round add/revive corrupts rotation)
- **Real bug.** Rotation corrupts when participant added/revived mid-round.
- Test: `shared/tests/turn.combat.test.js` (jest, seeded, RED).
- 13 dupes / 100 rounds. First at round 4 (Cleric twice).
- Root cause: `computeTurnOrderAfterAddition` appends id to turnOrderIds
  end. Round wrap re-sorts by initiative. `currentTurnParticipantId` pointer
  stale → nextTurn revisits.
- See full detail below in Confirmed bugs section.

### FEAT-1: Dead participants should stay in turn order (as-designed→change)
- **Feature request, not bug.** Current behavior is as-designed (dead =
  inactive = skipped). User wants change: dead occupy initiative slot,
  PCs get death-save turn.
- Saw Saturday game.
- Desired:
  - dead PC not removed from turnOrderIds
  - dead PC turn still comes up (nextTurn visits them)
  - dead PC on their turn can deathSave
  - dead PC not auto-set isActive=false by applyHpChange
- Affects: `shared/turn.js` `nextTurn` (filters `isActive`), `applyHpChange`
  (sets isActive=false on death), `computeTurnOrderAfterRemoval`.
- Characterization tests (`src/tests/Combat.characterization.test.js`) lock
  CURRENT behavior — UPDATE to desired when implementing.
- RED test locked (desired state): `shared/tests/turn.dead-skip.test.js` (4 tests).

## Confirmed bugs (tests written, NOT fixed)

### BUG-1: addParticipant + pause/resume corrupts turn rotation
- **RESOLVED** as side effect of BUG-2 fix (dup-id rejection broke chain).
- Audit: 0 violations / 100 rounds after BUG-2 fix.
- Replay: 10 rounds clean, no skip/dupe.
- Audit: 128 violations / 100 rounds, 4 symptom faces.
- Symptom chain (one bug family):
  1. pause blocks nextTurn advance → totalTurns stays frozen (e.g. 120)
  2. addParticipant re-adds same `r${totalTurns}` id (BUG-2: no dedup)
  3. togglePause resume rebuilds turnOrderIds → dup id appears x2
  4. nextTurn gets stuck on dup id → rotation breaks
  5. eventually nextTurn throws 'Encounter not running'
- Symptom counts (audit-state.js, 100 rounds):
  62x turnOrder-no-dup, 52x rotation-dupes, 14x nextTurn-throws
- Repro in replay round 10+: current stuck on one participant forever,
  nextTurn returns same id, round never advances.
- Clean minimal repro (shared/tests/turn.pause-add.test.js) PASSES = combo
  needs more state than single add+pause. Audit authoritative repro.
- Clean subsystems (zero violations): HP bounds, isActive, deathSave
  range, conditions, removeParticipant orphans.
- Real repro = `node scripts/audit-state.js` (or audit-rotation.js).

### BUG-2: addParticipant allows duplicate id
- **FIXED** (commit: addParticipant throws on dup id).
- Test: `shared/tests/turn.characterization.test.js` 'addParticipant rejects
  duplicate id' — GREEN.

### BUG-4: hide-player-HP breaks display view (preexisting)
- **Broader than hide-HP**: ALL 5 `storage.setDoc(getPath.activeDisplay(), ...)` calls
  use `{merge:true}` which is IGNORED (setDoc = replace per contract).
  Each write clobbers other fields on activeDisplay/status doc.
  - line 1619: hide-HP toggle → clobbers campaignId+encounterId (display paused)
  - line 1648: start combat → clobbers hidePlayerHp
  - line 1779: end combat → clobbers hidePlayerHp
  - line 1997: deactivate → clobbers hidePlayerHp
  - line 2002: activate → clobbers hidePlayerHp
- Toggle "hide player HP" in admin → display view flips to "Game Session Paused".
- Toggling back does NOT recover. Must re-activate encounter in encounters
  panel to restore display.
- Expected: hide-HP toggle updates one field on activeDisplay/status doc,
  display stays live on current encounter.
- Likely cause: toggle writes to wrong path, or clobbers activeCampaignId/
  activeEncounterId with null (setDoc replace vs updateDoc patch).
- Fix: use updateDoc (patch) not setDoc (replace); or include all existing
  fields when writing.
- Test: render App + DisplayView, toggle hide-HP, assert display still shows
  encounter (not paused).

### BUG-5: mid-round addParticipant/revive corrupts rotation
- Test: `shared/tests/turn.combat.test.js` (jest, seeded RNG, RED).
- 13 rotation-dupes / 100 rounds. First at round 4 (Cleric twice).
- Pattern: Reinforce/Summon added mid-round → appears in rotation same round
  → round wrap re-sorts by initiative → currentTurnParticipantId pointer
  stale → nextTurn revisits.
- Root cause: `computeTurnOrderAfterAddition` appends id to turnOrderIds
  end. Round wrap re-sorts by initiative. currentTurn pointer stale after
  sort → drifts → nextTurn revisits.
- This is the test audit should have been. Mirrors replay-combat.js op
  sequence exactly (damage, heal, conditions, toggleActive, deathSave,
  remove, add, edit, pause/resume, reorder, revive-between-rounds).

### BUG-6: reorderParticipants doesn't update turnOrderIds
- Test: `shared/tests/turn.reorder.test.js` 'reorder updates turnOrderIds' (RED).
- `reorderParticipants(enc, draggedId, targetId)` swaps two same-initiative
  participants in `participants[]` array but leaves `turnOrderIds` unchanged.
- nextTurn rotates via `turnOrderIds` only → reorder has NO effect on combat
  rotation. Mid-encounter drag-drop = pointless.
- replay-combat.js calls reorderParticipants with WRONG signature
  `(enc, reorderedArray)` — swallowed by try/catch, silent no-op. So
  replay never exercised real path either.
- Fix: reorder must also update turnOrderIds to match new participant order
  (within same-initiative tie).

### BUG-7: reorderParticipants has no undo
- Test: `shared/tests/turn.undo.test.js` 'reorderParticipants has no undo' (GREEN doc).
- `reorderParticipants` returns `log: null`. Other ops return `log.undo`.
- Cannot undo drag-drop. Candidate for undo system (M6).

### BUG-8: ws adapter has no reconnect
- Test: `server/tests/ws-reconnect.test.js` (RED).
- WS dies (idle/error/close) → `wsReady=null`, subscribers dead forever.
- Display frozen until full reload.
- Fix: `onclose` → reconnect + re-subscribe existing paths.

## Pipeline
- [ ] BUG-4: fix setDoc→updateDoc for all 5 activeDisplay sites
- [ ] BUG-5: fix computeTurnOrderAfterAddition currentTurn re-anchor
- [ ] BUG-6: reorderParticipants update turnOrderIds
- [ ] BUG-8: ws adapter reconnect
- [ ] FEAT-1: dead participants stay in turn order (update characterization)
- [ ] M5 docker-compose
- [ ] M6 undo rework (transactional events table)
- [ ] M7 Playwright E2E