memos/docs/superpowers/specs/2026-06-11-markdown-wysiwyg-editor-design.md

# Markdown WYSIWYG Editor — Design

**Date:** 2026-06-11
**Status:** Approved pending user review

## Goal

Replace the plain `<textarea>` memo editor with a modern WYSIWYG editor that renders
markdown syntax live as the user types (Linear / Claude.ai composer style) while keeping
markdown — not HTML — as the only storage and API format. A toggle lets users drop back
to the raw textarea editor at any time.

## Background

The current editor (`web/src/components/MemoEditor/Editor/index.tsx`) is a textarea with
hand-rolled features layered on top: tag suggestions (`#`), slash commands (`/`),
Ctrl+B/I markdown shortcuts, list auto-continuation, URL-paste-to-link, IME composition
plumbing, auto-grow height, and a toolbar that inserts raw markdown strings through an
imperative, character-offset-based `EditorRefActions` API.

Live markdown editing is among the most-requested memos features
(usememos/memos#2216, #3495, #766, #4259).

### Prior art (researched 2026-06)

- **Linear** builds its editor directly on **ProseMirror** (+ y-prosemirror for collab).
- **ChatGPT's composer** is raw **ProseMirror**.
- **Claude.ai's composer** is **Tiptap** (headless framework on ProseMirror).

All three references are ProseMirror-family WYSIWYG editors with markdown input rules.

### Library options considered

| Option | Verdict |
|---|---|
| **Tiptap v3 + `@tiptap/markdown`** | **Chosen.** Claude.ai's stack. Best ecosystem; StarterKit covers the core set with input rules; Suggestion utility replaces hand-rolled tag/slash popups; official bidirectional markdown (early release — gated by a spike). First-class React bindings; best-in-class IME handling via ProseMirror. ~100 KB gzipped. |
| Milkdown | Markdown-first ProseMirror + remark; strongest fidelity by design, but thin UX building blocks, small community, low bus factor. |
| Raw ProseMirror + prosemirror-markdown | Linear's literal approach; maximum control, most engineering effort for the least product difference. |
| Lexical | Non-ProseMirror engine; markdown is a conversion target, historically weaker IME. |
| CodeMirror 6 live-preview (Obsidian style) | Perfect byte fidelity but a different UX than the named references; largely DIY. |

## Decisions (user-confirmed)

1. **Raw mode stays**: a per-editor toggle switches between WYSIWYG and the current
   textarea editor. (Revised from an earlier "full replacement" decision.)
2. **Fidelity contract**: lossless for supported syntax — semantic round-trip for
   everything the editor models; style normalization (e.g. `*` → `-` bullets) is
   acceptable. Unknown/exotic syntax is preserved verbatim, never dropped.
3. **v1 scope — Linear-style core set** rendered live: bold/italic/strike/inline-code,
   headings, ordered/unordered/task lists, links, blockquotes, code blocks, and memos
   `#tags`. Tables, `$…$`/`$$…$$` math, and inline HTML remain literal text in the
   editor (they still render richly in the memo view after save). Mermaid lives in
   ` ```mermaid ` fences, so it is just a code block while editing.

## Architecture

### Editor abstraction

`EditorContent` hosts one of two implementations behind a shared **`EditorController`**
interface:

- `focus()`, `getMarkdown()`, `setMarkdown()`, `insertMarkdown()`, `isEmpty()`
- Formatting **intents**: `toggleBold()`, `toggleItalic()`, `toggleTaskList()`, etc.

The **Tiptap editor** implements intents as ProseMirror commands. The **textarea editor**
implements them exactly as today (wrap selection in `**`). The toolbar dispatches intents
and never knows which editor is mounted. The textarea's existing string-surgery API
(`EditorRefActions`) becomes internal to the textarea implementation rather than the
public contract.

### Mode toggle

- A small icon button in the editor toolbar switches modes mid-edit.
- Switching is a markdown string handoff: WYSIWYG → raw serializes (the same path as
  save, so no new fidelity risk); raw → WYSIWYG parses.
- The preference persists in localStorage (per device). No backend/proto changes; can
  graduate to a server-side user setting later.

### Tiptap editor composition

Built on `@tiptap/react` `useEditor`. Extensions:

- **StarterKit** (configured): headings, bold/italic/strike/code, lists, blockquote,
  code block — all with live input rules (`**bold**` converts as you type).
- **TaskList / TaskItem**, **Link** (includes URL-paste-over-selection → link),
  **Placeholder** (i18n'd), **`@tiptap/markdown`**.
- **`Tag`** (custom): inline node for `#tag`, rendered as a styled token, serialized
  back to `#tag` verbatim. `#` triggers a Suggestion-plugin popup backed by the
  existing tag store.
- **`SlashCommand`** (custom): Suggestion-plugin popup on `/`, replacing
  `SlashCommands.tsx` in WYSIWYG mode.
- **`PreservedBlock`** (custom): the fidelity workhorse — unmodeled constructs
  (tables, math, inline HTML, unrecognized syntax) are captured at parse time into
  nodes carrying their raw source, displayed as literal text (subtle mono styling),
  and re-emitted byte-for-byte on serialize.

Hand-rolled textarea features that become native or config in WYSIWYG mode:
Ctrl+B/I keymaps (StarterKit), list auto-continuation (ProseMirror lists),
auto-grow height (contenteditable), IME composition (ProseMirror — better CJK
behavior than the textarea plumbing).

### Data flow

Unchanged at the boundaries. Memo markdown → `setMarkdown()` on load. On update,
serialized markdown (debounced) flows into the existing state reducer as
`state.content`, so auto-save, the localStorage draft cache (still a plain markdown
string), tag extraction, and the save path are untouched. The backend only ever sees
markdown. File paste/drag wires Tiptap `handlePaste`/`handleDrop` into the existing
`uploadService`.

## Fidelity contract

1. **Supported constructs** round-trip semantically; list-marker style may normalize;
   content never changes meaning.
2. **Unmodeled constructs** round-trip byte-for-byte via `PreservedBlock`.
3. **A round-trip corpus test enforces this permanently** (see Testing). It is written
   first, as a spike, and is the go/no-go gate on `@tiptap/markdown` (early release).
   If the gate fails and custom Marked tokenizers cannot fix it, the fallback is
   swapping only the parse/serialize layer to remark (already a memos dependency)
   while keeping the Tiptap editor — editor and serialization are deliberately
   decoupled for this reason.

## Error handling

- **Load guard (tripwire):** on opening an existing memo, parse → re-serialize →
  compare semantically. If the round-trip would lose content, log it and show a
  notice — "this memo contains syntax the editor can't safely edit" — with a
  one-click switch to raw mode for that memo. Expected never to fire.
- **Draft safety:** the localStorage draft cache stays a markdown string on the same
  debounce as today; drafts are interchangeable between both editor modes.
- **Save path:** reuses already-serialized `state.content`; save never triggers a
  fresh parse, so it gains no new failure mode.

## Testing

- **Round-trip corpus test (the spike, written first):** fixture markdown files
  (GFM, tables, math, mermaid, inline HTML, nested lists, CJK, emoji) → parse →
  serialize → assert semantic equality for supported syntax, byte equality for
  preserved blocks. Runs in the existing vitest/jsdom setup.
- **Extension unit tests:** `Tag` (parse/serialize/suggestion trigger),
  `PreservedBlock` (verbatim round-trip), link-paste.
- **Component tests** (@testing-library): toolbar intents produce expected markdown
  in both modes; slash/tag popups open and insert correctly; mode toggle hands
  content across without loss.
- **Manual QA:** CJK IME composition, mobile Safari/Chrome soft keyboards, focus
  mode, paste-image upload.

## Rollout

Feature branch, PR series:

1. **Spike:** corpus test + `@tiptap/markdown` verdict (throwaway if the gate fails).
2. **Core editor:** Tiptap behind `EditorController`, StarterKit set, markdown in/out,
   wired into the state layer.
3. **Memos features:** `Tag` + suggestions, `SlashCommand`, `PreservedBlock`,
   file paste/drop, toolbar intent conversion.
4. **Toggle + refactor:** mode toggle UI and persistence; textarea editor refactored
   to implement `EditorController` (nothing deleted — it powers raw mode).

Dependency cost: ~100 KB gzipped (`@tiptap/core`, `@tiptap/react`, extensions,
`@tiptap/markdown` + MarkedJS). WYSIWYG is the default mode for all users.

## Out of scope (v1)

- Interactive table editing, live KaTeX/mermaid rendering while editing.
- Collaborative editing (Yjs).
- Server-side persistence of the mode preference.
- Mobile apps (web/PWA only — native apps are separate codebases).