tiptap-editor

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 58df25c11e9b · 21 Oct 2026Report an issue or request a re-scan

• Publisherxiaolai GitHub userOwner of the repository this skill is read from
• Source folderxiaolai/vmark/.claude/skills/tiptap-editorThe exact folder we audited
• LicenceISCAs the repository states it
• Commit pinned for this verdict58df25c11e9bA new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

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

---
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:**
```typescript
// 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:

```typescript
// 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()`

Excerpt, first 2,918 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-21
   ✓SAFE B 89 / 100

   first audit · source 58df25c11e9b

Questions about tiptap-editor

• github.com/xiaolai/vmark/tree/main/.claude/skills/tiptap-editor — the audited source at commit 58df25c11e9b and every finding aboveObserved · 21 Oct 2026

Spotted something wrong? Report a correction · Methodology