diff --git a/docs/phase-1-tiptap-strategy.md b/docs/phase-1-tiptap-strategy.md new file mode 100644 index 000000000..a788930e6 --- /dev/null +++ b/docs/phase-1-tiptap-strategy.md @@ -0,0 +1,142 @@ +# Phase 1 — Tiptap Extension Audit & Paragraph Node Strategy + +**Status:** Decision (no production code) +**Tracking issue:** #267 +**Consumed by:** #272 (paragraph + heading + toolbar) +**Supersedes:** Phase 0 finding #4 in `PHASE-0-FINDINGS.md` + +## Purpose + +Phase 0 shipped the editor spike with `@tiptap/react` + `@tiptap/starter-kit` + `@tiptap/extension-link` because it was the fastest path to a working paragraph. `starter-kit` is a meta-package that drags in ~15 extensions, most of which conflict with our block-aware architecture: headings, lists, code blocks, and blockquotes are **blocks** in our system, not ProseMirror nodes living inside a paragraph. Shipping `starter-kit` unchanged means every paragraph's editor can produce document structure our block store cannot represent. + +This document decides (1) which extensions each block-level Tiptap editor actually needs, and (2) whether paragraph's Tiptap instance uses Tiptap's stock `Paragraph` node or a custom `BlockParagraph` node that talks to the Zustand store when the user splits or merges. + +## 1. Starter-Kit Extension Audit + +`@tiptap/starter-kit` bundles the following extensions (v3.22.x). Each row is decided against our architecture: **one Tiptap editor per block instance, containing only inline content for that single block**. Block-level structure (new paragraphs, headings, lists, quotes, code) is owned by the Zustand block store, not by ProseMirror. + +| # | Extension | Kind | Decision | Reasoning | +|---|---|---|---|---| +| 1 | `Document` | node | **Keep** | Required root. Every ProseMirror doc needs it. | +| 2 | `Paragraph` | node | **Replace** (see §2) | Stock node's Enter/Backspace behavior operates on the PM doc; we need it to operate on the block store. Replaced with `BlockParagraph`. | +| 3 | `Text` | node | **Keep** | Required for any text content. | +| 4 | `Heading` | node | **Drop** | Headings are their own block type in our system. A paragraph's editor must never be able to produce an `

`. Heading block uses its own schema (§3). | +| 5 | `BulletList` | node | **Drop** | Lists are a Phase 2 block type. A paragraph editor producing `