Undo and redo history

Undo/Redo & History

Use this skill when designing or debugging undo/redo stacks, transaction coalescing, history boundaries, and state restoration in visual and block editors.

Human-Meaningful Undo Units (Norman & Haverbeke)

1. Coalesce Continuous Micro-Edits, Separate Distinct Actions:
   • A user pressing Cmd/Ctrl+Z expects to undo a meaningful editing step, not a single character or intermediate drag pixel:
     • Continuous typing: Coalesce consecutive character insertions within a time window (e.g., 300–500 ms) at adjacent positions into one undo group; break the group on pause, cursor jump, or block boundary change.
     • Drag-and-drop / Resize / Slider drag: Record the pre-drag state once on dragStart, preview intermediate frames without pushing to history, and commit a single undoable transaction on drop.
     • Composite commands: Multi-step operations (e.g., "convert block type and migrate children", "paste multi-block fragment", "duplicate section") must execute inside a single transaction or history group so one Undo reverses the entire operation atomically.
2. Exclude Non-Content Events from the Undo Stack:
   • Never record background or metadata-only events in the user's undo history (addToHistory: false):
     • Autosave status updates, server revision acknowledgments, or dirty-flag changes.
     • Viewport pan/zoom, panel collapse/expand, or selection-only changes.
     • Lazy-loaded asset metadata resolution or remote presence/awareness updates.

Selection Restoration & History Integrity

• Restore Selection Alongside Content:
  • Every history entry must store both the inverse document steps and the pre-/post-transaction selection anchor so Undo and Redo place the user's focus and cursor back at the edited location.
• Clear Redo Branch Only on Genuine Content Edits:
  • Navigating, selecting, copying, or autosaving after an Undo must never wipe the Redo stack; only a new history-tracked content transaction clears forward redo entries.
• Bounded History Memory:
  • Cap history depth (e.g., 100–500 groups) and store compact structural deltas/steps rather than cloning full multi-megabyte document snapshots on every keystroke.

Checklist

• Are continuous keystrokes coalesced by time/position while drag/resize gestures commit as a single undo step?
• Do composite multi-block operations undo and redo atomically in a single step?
• Are autosave responses, UI view toggles, and background sync metadata excluded from the undo stack?
• Do Undo and Redo restore both the document structure and the corresponding cursor/block selection?