/tiptap-editor

name: tiptap-editor
description: Tiptap editor API patterns for vmark WYSIWYG development. Use when working with editor commands, node traversal, selection handling, or format operations.

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

1. Identify operation type (format, block, selection, traversal) 2. Check if Tiptap has a built-in command for it 3. Use `editor.commands.xxx()` for single operations 4. Use `editor.chain().focus().xxx().run()` when focus is needed or chaining 5. For node traversal, use `doc.resolve(pos)` to get `$pos` helpers 6. For state queries, use `editor.isActive()` or `editor.getAttributes()`