- commit
- 42748992a868a2380d217c03e8c90a6545e3154e
- parent
- 40959f5f1070b2d96ff5aa6a37a83df09f02d73e
- author
- Dami <dami.etoile@gmail.com>
@@ -0,0 +1,49 @@
1+## Context2+3+Death effects are generated from settled destruction events while Undo restores the engine's prior state. The reported mobile failure indicates that the restored state does not fully replace the presentation snapshot: a red death shadow remains while the restored controlled glyph is absent. The fix must keep engine state authoritative and make the visual timeline converge on the restored state before the next frame.4+5+## Goals / Non-Goals6+7+**Goals:**8+9+- Reconcile board entities, facing, control markers, and active juice effects after Undo.10+- Remove stale destruction shadows and death animations from the undone turn.11+- Keep recovery independent of whether Undo arrived through keyboard, touch, or gamepad input.12+- Verify the focused proof 05 death/Undo path and reset behavior.13+14+**Non-Goals:**15+16+- Changing SINK or DEFEAT semantics, undo history rules, or proof 05 layout.17+- Adding a new animation or changing the designer's death-effect treatment.18+- Changing pack, mod, or URL behavior.19+20+## Decisions21+22+### Reconcile presentation from the restored engine snapshot23+24+After Undo, reconcile presentation entities by stable ID from the returned engine state and restore the entity's noun, coordinates, facing, and control marker together. This keeps coordinates and entity existence engine-owned. Patching only the missing MIAU glyph was rejected because it would leave stale effects or fail for other destroyed entities.25+26+### Clear stale death presentation state on Undo27+28+When Undo restores a state after death, clear the stale SINK/DEFEAT effect, tween, and shake state associated with the undone turn before the next frame. A new turn-epoch tagging scheme was rejected because the focused fix already has stable-ID reconciliation and explicit stale-effect cleanup; broad effect history is outside this bug.29+30+### Exercise the real mobile path in browser coverage31+32+Use the authored proof 05 route and mobile viewport with the existing input adapter, then assert restored board state immediately and after the delayed presentation frame. A unit-only fixture was rejected because the defect depends on stage, juice, and rendering state together; a pixel assertion remains a separate acceptance gate.33+34+## Risks / Trade-offs35+36+- [Risk] An effect can be created while Undo is pressed during a transition. → Clear stale sink/defeat effect, tween, and shake state before applying the restored snapshot.37+- [Risk] Reconciliation by ID can retain an entity with changed noun state. → Copy noun, coordinates, facing, and control status from the restored engine state together.38+- [Risk] Mobile timing differs from desktop. → Check the focused immediate and delayed mobile presentation states and retain the existing input contract.39+40+## Migration Plan41+42+1. Reconcile stable-ID entities and clear stale death presentation state on Undo.43+2. Add focused Node and mobile browser regressions.44+3. Run the full Node suite, production build, and focused mobile checks.45+4. Roll back by reverting presentation changes; no persisted data migration is required.46+47+## Open Questions48+49+None for the focused bug fix.@@ -0,0 +1,26 @@
1+## Why2+3+On mobile, proof 05 can leave the red YOU death shadow visible after Undo while the restored MIAU glyph is missing. This makes the engine state and the presentation disagree at the exact moment the player needs to continue, and repeated death/undo cycles can preserve stale effects.4+5+## What Changes6+7+- Restore the complete visual entity snapshot immediately after Undo, including the controlled glyph and its facing.8+- Clear or replace stale death effects when Undo restores the prior turn.9+- Keep reset, repeated death/undo, reduced-motion, keyboard, touch, and gamepad behavior deterministic.10+- Add focused engine, juice, scene, and browser regression coverage for the proof 05 path.11+12+## Capabilities13+14+### New Capabilities15+16+None.17+18+### Modified Capabilities19+20+- `game-presentation`: require visual entity and effect recovery after Undo and reset.21+22+## Impact23+24+- Affected presentation state and event timeline handling in `src/juice.js`, `src/stage.js`, and board rendering.25+- Affected proof 05 browser acceptance and focused presentation tests.26+- No rule semantics, pack data, input contract, or persistence schema changes.@@ -0,0 +1,24 @@
1+## ADDED Requirements2+3+### Requirement: Undo SHALL restore the complete visual entity state4+After a successful Undo, the presentation SHALL reconcile visible entities from the restored engine snapshot by stable ID, including existence, noun or glyph, grid position, facing, control marker, and active visual effects. Effects created by the undone death turn SHALL not remain visible after reconciliation.5+6+#### Scenario: Proof 05 death then Undo restores MIAU immediately7+- **WHEN** MIAU dies in proof 05 and the player invokes Undo on a mobile viewport8+- **THEN** the restored MIAU glyph and its control marker are visible at the prior position on the next presentation frame, and the red death shadow from the undone turn is absent9+10+#### Scenario: Repeated death and Undo does not accumulate stale effects11+- **WHEN** the player repeats a death followed by Undo multiple times12+- **THEN** each restored snapshot shows exactly the engine entities for that turn and no prior death shadow or missing glyph persists13+14+#### Scenario: Reset clears death presentation state15+- **WHEN** the player resets after a death or after an Undo16+- **THEN** the board shows the native initial entities and facing, with no stale destruction effect or missing controlled glyph17+18+#### Scenario: Reduced motion restores without a transition gap19+- **WHEN** reduced motion is enabled and the player invokes Undo after death20+- **THEN** the restored entities and controls appear immediately with no intermediate death animation frame21+22+#### Scenario: Input paths share the same recovery23+- **WHEN** Undo is invoked by keyboard, touch, or Standard gamepad after a death24+- **THEN** each input path produces the same restored visual state and unchanged engine move history@@ -0,0 +1,12 @@
1+## 1. Presentation recovery2+3+- [x] 1.1 Reconcile visible entities by stable ID from the restored engine snapshot, including glyph, facing, and control markers.4+- [x] 1.2 Clear stale SINK/DEFEAT effect, tween, and shake state when Undo restores the prior turn.5+- [x] 1.3 Verify reset restores native entities/facing and clears stale effects after both death and Undo.6+7+## 2. Regression coverage8+9+- [x] 2.1 Add focused Node tests for death, Undo, entity restoration, facing/control markers, and effect cleanup; the 149-test Node suite is green.10+- [x] 2.2 Verify the focused mobile proof 05 death→Undo state immediately and after the delayed presentation frame, with screenshots/state evidence and no console errors.11+- [x] 2.3 Add a real mobile visual pixel assertion proving the restored MIAU glyph is present and the stale red death shadow is absent.12+- [x] 2.4 Run the production build and record the focused browser regression result.@@ -75,3 +75,26 @@ The presentation SHALL maintain facing per entity ID as visual state separate fr
7575 - **WHEN** reduced motion is enabled and a qualifying horizontal self-move changes facing7676 - **THEN** the glyph changes facing immediately without the 70ms squash animation7777 78+### Requirement: Undo SHALL restore the complete visual entity state79+After a successful Undo, the presentation SHALL reconcile visible entities from the restored engine snapshot by stable ID, including existence, noun or glyph, grid position, facing, control marker, and active visual effects. Effects created by the undone death turn SHALL not remain visible after reconciliation.80+81+#### Scenario: Proof 05 death then Undo restores MIAU immediately82+- **WHEN** MIAU dies in proof 05 and the player invokes Undo on a mobile viewport83+- **THEN** the restored MIAU glyph and its control marker are visible at the prior position on the next presentation frame, and the red death shadow from the undone turn is absent84+85+#### Scenario: Repeated death and Undo does not accumulate stale effects86+- **WHEN** the player repeats a death followed by Undo multiple times87+- **THEN** each restored snapshot shows exactly the engine entities for that turn and no prior death shadow or missing glyph persists88+89+#### Scenario: Reset clears death presentation state90+- **WHEN** the player resets after a death or after an Undo91+- **THEN** the board shows the native initial entities and facing, with no stale destruction effect or missing controlled glyph92+93+#### Scenario: Reduced motion restores without a transition gap94+- **WHEN** reduced motion is enabled and the player invokes Undo after death95+- **THEN** the restored entities and controls appear immediately with no intermediate death animation frame96+97+#### Scenario: Input paths share the same recovery98+- **WHEN** Undo is invoked by keyboard, touch, or Standard gamepad after a death99+- **THEN** each input path produces the same restored visual state and unchanged engine move history100+