clone

a browser grid puzzle game where you push words around to rewrite the rules of each level

main
miau-is-true / openspec / changes / archive / 2026-09-24-fix-undo-death-visual / design.md
design.md 3.0K source

Context

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.

Goals / Non-Goals

Goals:

  • Reconcile board entities, facing, control markers, and active juice effects after Undo.
  • Remove stale destruction shadows and death animations from the undone turn.
  • Keep recovery independent of whether Undo arrived through keyboard, touch, or gamepad input.
  • Verify the focused proof 05 death/Undo path and reset behavior.

Non-Goals:

  • Changing SINK or DEFEAT semantics, undo history rules, or proof 05 layout.
  • Adding a new animation or changing the designer's death-effect treatment.
  • Changing pack, mod, or URL behavior.

Decisions

Reconcile presentation from the restored engine snapshot

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.

Clear stale death presentation state on Undo

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.

Exercise the real mobile path in browser coverage

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.

Risks / Trade-offs

  • [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.
  • [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.
  • [Risk] Mobile timing differs from desktop. → Check the focused immediate and delayed mobile presentation states and retain the existing input contract.

Migration Plan

  1. Reconcile stable-ID entities and clear stale death presentation state on Undo.
  2. Add focused Node and mobile browser regressions.
  3. Run the full Node suite, production build, and focused mobile checks.
  4. Roll back by reverting presentation changes; no persisted data migration is required.

Open Questions

None for the focused bug fix.