tiptap-editor

Tiptap Editor API Patterns Overview This skill documents proper Tiptap API usage patterns for vmark development. It helps distinguish when to use Tiptap's high-level API vs direct ProseMirror access. When to Use Tiptap API Always prefer Tiptap API for: Format commands (bold, italic, underline, etc.) Block type changes (heading, paragraph, code block) List operations (bullet, ordered, toggle, indent/outdent) Table operations via Tiptap table extension Content insertion and replacement Editor state queries ( isActive , getAttributes ) Tiptap patterns to use: // Direct commands editor . commands . toggleBold ( ) editor . commands . setHeading ( { level : 2 } ) editor . commands . setContent ( doc , { emitUpdate : false } ) // Chained commands (for multiple operations) editor . chain ( ) . focus ( ) . setHeading ( { level : 2 } ) . run ( ) editor . chain ( ) . focus ( ) . toggleMark ( "underline" ) . run ( ) // State queries editor . isActive ( "blockquote" ) editor . isActive ( "heading" , { level : 2 } ) editor . getAttributes ( "link" ) When Direct ProseMirror is Appropriate Use ProseMirror directly for: Markdown conversion layer ( proseMirrorToMdast.ts , mdastToProseMirror.ts ) Multi-cursor/selection subclassing ( MultiSelection.ts ) Custom node views Low-level transaction manipulation Schema-level operations Known Issues in vmark 1. cursorHandlers.ts Block Boundary Issue src/hooks/mcpBridge/cursorHandlers.ts uses doc.textContent which flattens the document and loses block boundaries. The correct approach is to use $pos helpers: // WRONG - loses block structure const text = doc . textContent ; // RIGHT - respects block boundaries const $pos = doc . resolve ( from ) ; const currentNode = $pos . parent ; const blockStart = $pos . before ( $pos . depth ) ; const blockEnd = $pos . after ( $pos . depth ) ; 2. Cursor Sync Drift After WYSIWYG Edits sourceLine attributes are only set on initial parse. After WYSIWYG edits that add/remove blocks, line numbers no longer match the source. This is a known limitation. 3. HtmlNodeView.ts Store Issue src/plugins/markdownArtifacts/HtmlNodeView.ts writes cursor info to wrong store. References references/patterns.md - Detailed API patterns and $pos usage references/examples.md - Real code examples from vmark codebase Workflow Identify operation type (format, block, selection, traversal) Check if Tiptap has a built-in command for it Use editor.commands.xxx() for single operations Use editor.chain().focus().xxx().run() when focus is needed or chaining For node traversal, use doc.resolve(pos) to get $pos helpers For state queries, use editor.isActive() or editor.getAttributes()