Every editing surface in the workbench falls into exactly one of four classes. The class decides what ⌘Z does there, what survives a killed tab, and why. If you add a surface, add it to a table below — a surface missing from this document is a review finding, not a default.
The rules the classes share#
- Undo depth. The solo command stack refuses construction below 50 entries
(
MINIMUM_UNDO_DEPTH) and defaults to 100; the CRDT undo manager is unbounded. Both clear the checklist floor of 50. - Shortcut scope. ⌘Z / ⇧⌘Z / Ctrl-Y are bound per editor region
(
useUndoRedoShortcutsreturns props the editor spreads on its root), never onwindow. The develop ladder mounts over a dozen editors at once; a global listener per editor would undo something in every one of them on a single keystroke. The editor that responds is the one holding focus; with focus outside every editor the keys do nothing, and the history bar's buttons remain. - Text fields. A field whose edits are recorded in the command stack carries
data-history-managedand routes ⌘Z to the stack. A field without it (search boxes, staging forms) keeps the browser's native undo. Both by design. - Drafts mirror unsaved edits, not the buffer. Autosave (800 ms debounce, localStorage, 7-day cap) writes only after a real edit; a session that only looked writes nothing, and a completed save discards the draft. A recovered draft is offered with its age, never applied — restore and discard get equal visual weight.
- The kill test. The recovery contract is stated as a test: kill the tab
mid-edit, reopen, the draft is offered. It is exercised in
src/lib/use-editor-history.spec.tsx("offers a draft after the tab is killed…") by ripping the container out with no unmount, no effect cleanup and no unload handler, then mounting fresh.
Class 1 — solo editors: command stack + local drafts#
Buffer edited locally until an explicit Save; a killed tab would lose minutes of
composition. Each uses useEditorHistory (stack, drafts, region shortcuts) and
renders EditorHistoryBar (undo/redo + the recovery prompt).
| Surface | Component | Draft key (surface · id) |
|---|---|---|
| Quick capture modal | QuickCapture |
quick-capture · global |
| Design pillars | PillarEditor |
pillars · idea id |
| Core loop | CoreLoopDesigner |
core-loop · idea id |
| Comps & positioning | PositioningPanel |
positioning · idea id |
| Systems sketch | SystemsSketchPanel |
systems-sketch · idea id |
| Blockout brief | BlockoutBriefPanel |
blockout-brief · idea id |
| Kit sheets | KitSheetEditor |
kit-sheet · idea id |
| Prototype brief | PrototypeBriefPanel |
prototype-brief · idea id |
| Scope inputs | ScopeEstimatePanel |
scope-estimate · idea id |
| Format decision | FormatDecisionPanel |
format-decision · idea id |
| Series bible | SeriesBiblePanel |
series-bible · idea id |
| Episode grid | EpisodeGridPanel |
episode-grid · idea id |
| Breaking board | BreakingBoardPanel |
breaking-board · idea id |
| Casting sheets | CastingSheetPanel |
casting-sheets · idea id |
| Mood board composer | MoodBoardComposer |
mood-board · composer |
| Sonic board composer | SonicBoardComposer |
sonic-board · composer |
| Corkboard arrangement | Corkboard |
corkboard · beat-outline version id |
Canvas operations are first-class commands: a card drag coalesces into one undo step per gesture (per-gesture coalesce keys, so back-to-back drags never merge), add/remove are discrete steps, and compound edits (remove a loop node and its edges; remove a comp and its matrix column) are one command so one undo restores both halves.
Corkboard notes: the board is keyed by beat-outline version id, and a saved arrangement creates a new version — so a draft only resurfaces for the exact version it was made against, and drafts for superseded versions age out without ever being offered.
The panels' load-from-server effect is guarded by their dirty flag, and a
restored draft marks the editor dirty (onRestore); without that, the next
background refetch would reset the buffer and silently destroy the draft the
user just chose to keep.
Class 2 — collaborative surfaces: CRDT history, no local drafts#
| Surface | Component |
|---|---|
| Shared idea board | IdeaBoard |
The board is a Yjs document (P7.1), so history is Y.UndoManager via
useCrdtHistory, tracking only transactions tagged with this client's origin —
undo reverts your change and never a colleague's. Every mutation goes through
withLocalOrigin; an untagged change would be silently un-undoable, so there is
deliberately no second write path. Drag gestures close their undo step on
pointer-up (endStep), so two quick drags are two undos.
No local drafts here, on purpose: the CRDT document is the store and survives a killed tab by construction. Layering localStorage drafts on top would create a second source of truth that disagrees the moment a remote edit lands.
Class 3 — immediate-commit surfaces: no local stack, by design#
Every action is a server write the moment it happens; there is no local buffer for a killed tab to lose, and "undo" would mean reversing a persisted, sometimes audited, act — a different feature (versioning / revert) than an editor stack, and pretending otherwise would revert things colleagues may already have seen.
| Surface | Where | The transient state at risk |
|---|---|---|
| Quests page | pages/Quests.tsx |
a 2-field create form |
| Dialogue trees | pages/Dialogues.tsx |
one node's line before "Save node" |
| Story graphs | pages/StoryGraphs.tsx |
walkthrough save-states are domain saves, not editor state |
| Relationship web | pages/RelationshipWeb.tsx |
none — edge edits commit per action |
| Cultures | pages/Cultures.tsx |
none — trait edits commit per action |
| Ideation inbox / triage | pages/IdeationInbox.tsx |
none — keep/park/kill are decisions |
| Tournament voting | pages/Tournament.tsx |
none — votes are recorded judgments |
| Stage gates | StageGatePanel |
a one-line note; the decision is audited |
| Product routing | ProductRoutingPanel |
a one-line reason; routing is a decision |
The residual loss window is a single short field typed seconds before the act. Browser-native undo covers typing there; nothing else exists to recover.
Class 4 — read-only / generated panels: nothing to undo#
OnePagerPanel, TableReadPanel, NotesDashboardPanel, TitleClearancePanel,
GeneratorScoreboard, the attribution panel and the diagnostics read-outs
render server-derived documents. They hold no editable buffer; their inputs (if
any) are filters.
ScriptEditor predates this checklist and is a controlled library component —
value/onChange belong to whoever mounts it, so history belongs to the
mounting surface, and it ships its own useScriptEditorAutoSave for the one
consumer that wants it.