initiative/specs/037-undo-redo/quickstart.md

Quickstart: Undo/Redo

Feature: 037-undo-redo Date: 2026-03-26

Overview

This feature adds undo/redo to all encounter state changes using the memento (snapshot) pattern. Each action captures the pre-action encounter state onto an undo stack. Undo restores the previous state; redo re-applies an undone state.

Implementation Layers

Domain (packages/domain/src/undo-redo.ts)

Pure functions for stack management:

• pushUndo(state, snapshot) — push snapshot, cap at 50, clear redo
• undo(state, currentEncounter) — pop undo, push current to redo
• redo(state, currentEncounter) — pop redo, push current to undo
• clearHistory() — reset both stacks

All functions take and return immutable data. No I/O.

Application (packages/application/src/)

Use cases that orchestrate domain calls via store ports:

• undoUseCase(encounterStore, undoRedoStore) — execute undo
• redoUseCase(encounterStore, undoRedoStore) — execute redo

New port interface UndoRedoStore in ports.ts:

• get(): UndoRedoState
• save(state: UndoRedoState): void

Web Adapter (apps/web/src/)

Hook (use-encounter.ts): Wraps every action callback to capture pre-action snapshot. Exposes undo(), redo(), canUndo, canRedo.

Persistence (persistence/undo-redo-storage.ts): Save/load undo/redo stacks to localStorage keys "initiative:encounter:undo" and "initiative:encounter:redo".

UI (components/turn-navigation.tsx): Undo/Redo buttons in the top bar, inboard of the turn step buttons, disabled when stack is empty.

Keyboard (hooks/use-undo-redo-shortcuts.ts): Global keydown listener for Ctrl+Z / Ctrl+Shift+Z (Cmd on Mac). Suppressed when text input has focus.

Key Design Decisions

1. Memento over Command: Full encounter snapshots, not inverse events. Simpler at encounter scale (~2-5 KB per snapshot).
2. Capture in hook, not domain: Snapshot capture happens in the adapter layer. Domain and application layers are unaware of undo/redo.
3. React state for stacks: Enables reactive button disabled states without manual re-render triggers.
4. Clear is not undoable: Both stacks reset on encounter clear (per spec).

Testing Strategy

• Domain tests: Pure function tests for stack operations (push, pop, cap, clear, undo/redo roundtrip).
• Application tests: Use case tests with mock stores.
• Integration: Spec acceptance scenarios mapped to test cases (undo restores state, redo reapplies, new action clears redo, keyboard suppression during input focus).