ttrpg-initiative-tracker/TODO.md

TODO

M4 — Initiative skip bug + dead-participant handling

Dead participants must NOT be skipped in turn order (BUG-3 / M4)

• Current: dead (HP=0) → isActive=false → removed from turn order → skipped
• WRONG. Dead participants still occupy initiative slot.
  • PCs (unconscious): death saves still resolve on their turn
  • Monsters/NPCs: may still have reaction/reaction-like considerations
• Saw this problem in game Saturday.
• Fix: keep dead participants in turnOrderIds; their turn still comes up. Damage/death-save UI already gated on HP=0 so row buttons stay usable.
• Affects: shared/turn.js nextTurn (filters isActive), applyHpChange (sets isActive=false on death), computeTurnOrderAfterRemoval.
• Characterization tests (src/tests/Combat.characterization.test.js) lock CURRENT (buggy) behavior — those tests must be UPDATED to desired behavior, not preserved.
• RED test locked: shared/tests/turn.dead-skip.test.js (4 tests).
  • 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

JUMP_TURN_TO(participantId) manual turn override

• DM clicks participant → cursor jumps → that participant's turn now.
• Future NEXT_TURN continues from jumped position.
• UI button: "Make This Turn"
• Backend action: new endpoint or via generic doc patch.

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)

• 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).

Pipeline

BUG-5: mid-round addParticipant/revive corrupts rotation (deterministic test)

• 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 + togglePause resume rebuilds order via sort but doesn't re-anchor currentTurn to its new position. After several mid-round adds the pointer drifts.
• 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).

Pipeline

• Red test: dead participant still in turnOrderIds, turn still advances to them
• Fix shared/turn.js: don't drop dead from turn order
• Update characterization tests to desired (not preserved) behavior (src/tests/Combat.characterization.test.js, etc)
• JUMP_TURN_TO red test
• JUMP_TURN_TO impl (shared + UI button)
• M5 docker-compose
• M6 undo rework (transactional events table)
• M7 Playwright E2E