Editor document model

Editor Document Model & Commands

Use this skill when designing or modifying the state architecture, schema rules, and mutation commands of a visual editor, block editor, or interactive workspace.

Single Authoritative Document Model (Haverbeke & Ousterhout)

1. Never Let the DOM and Application State Compete as Primary Sources of Truth:
   • Maintain a canonical, serializable document model (an immutable tree or normalized node map) as the single owner of content.
   • The view is a projection of document state, and edits dispatch structured commands / transactions ($\text{State} + \text{Transaction} \to \text{State}'$). Never mutate the DOM directly behind the editor library's back.
2. Strictly Separate the Four Editor State Layers:
   • Document Content State: Blocks, inline nodes, marks, attributes, and hierarchy (persisted and tracked by undo/redo).
   • Selection & Cursor State: Active block/text selection, anchor/head positions, and focus target (ephemeral, bound to document positions).
   • View / UI State: Zoom, pan, collapsed panels, hover guides, active toolbars, and drag indicators (never persisted as document content).
   • Persistence / Save State: clean, dirty, saving, saved, error, conflict, and last-acknowledged revision version.

Schema Rules, Stable IDs & Structural Integrity

• Stable Block Identifiers: Assign every addressable block or canvas element a stable unique ID (id).
• Parent-Child & Content Constraints: Enforce explicit schema rules defining which block types may nest inside which containers, required child nodes, and allowed inline marks.
• Safe Duplication & Deletion:
  • When duplicating or pasting a block subtree, mint fresh IDs for every cloned node and remap internal cross-references within the cloned subgraph.
  • When deleting a node, clean up dangling references and ensure the document keeps at least one valid root block when required by the schema.

Transactional Command Pipeline

• Route every content modification—typing, block insertion, drag-and-drop move, inspector edit, paste, or slash-command transform—through explicit, composable transactions.
• Validate schema invariants before committing a transaction so invalid trees cannot enter editor state.
• Adapt to existing libraries (ProseMirror, Tiptap, Lexical, Slate, BlockNote) via their native extension, node, and command APIs rather than building a custom rich-text engine.

Checklist

• Is there a single authoritative document model separated from selection, view UI, and save state?
• Do all blocks carry stable IDs, with fresh IDs and remapped references generated on duplication?
• Are parent-child nesting rules and schema invariants enforced on every command and transaction?
• Do all edits flow through structured transactions rather than direct DOM or ad-hoc state mutations?