# Ink

The editing feel: there is no edit mode. One ProseMirror-backed primitive for every text seat — line/text/prose — with continuous save, real undo, Esc burst-revert, and [[ mentions.

Install: `npx candlelight-ds add ink`

Category: primitive · Grammar: G8

## Use when

Any text the user owns — titles, names, descriptions, documents.

## Don't use when

Genuine configuration (URLs, keys — forms stay forms) or search fields (queries, not documents). Create-inputs and renames under navigating links (InlineEdit).

## States

- reading (identical to writing)
- writing (caret only)
- empty (placeholder)
- read-only (same face)
- mention popup open

## Keyboard

- `Enter (line)` — commits and blurs — Enter stays sacred to the commit key
- `Esc` — reverts the current burst since the last save
- `⌘Z` — real undo, alive across saves
- `⌘B/⌘I (prose)` — bold/italic; markdown shortcuts free
- `[[ (prose)` — opens the mention popup; ↑↓ walk, Enter picks, Esc closes

## Traps (shipped once — do not re-learn)

- Suggestion-popup key priority: popup keys MUST be handled in editorProps.handleKeyDown — a React wrapper's onKeyDown runs after ProseMirror's keymaps, so Enter splits the paragraph instead of picking.

## Acceptance tests

- The squint test: a screenshot of editing vs reading is identical but the caret.
- The keystroke test: typing is indistinguishable from a bare textarea (zero React renders per keystroke).
- The crash test: kill the tab mid-word, lose at most one debounce window of words.
- The undo test: ⌘Z works across saves because the editor never unmounts.
- The menu test: no seat without a right-click menu.
- The one-feel test: a stranger can't tell any two seats were different components.

## Files

- components/ui/Ink.tsx

npm dependencies: @candlelight-ds/tokens, @tiptap/react, @tiptap/starter-kit, @tiptap/core, @tiptap/extension-document, @tiptap/extension-paragraph, @tiptap/extension-text, @tiptap/extensions, tiptap-markdown, clsx, tailwind-merge

Rendered twin: https://candlelight-docs.vercel.app/components/ink · Full spec: https://candlelight-docs.vercel.app/spec.md