Live Preview Completion

The page editor's live preview mode edits plain Markdown while hiding the markup and drawing what it means — the way Obsidian edits. This design finished it so it can be the editor most people use, and made the mode a per-user choice. Status: implemented on main (2026-11-01); full design in the repo at docs/superpowers/specs/2026-11-01-live-preview-completion-design.md. Related: ObsidianBlockReferencesDesign.

The invariant

Both modes edit the same text, so switching is free and lossless. Nothing in live preview may change the document except an explicit user edit — not toggling, not mounting, not moving the caret, not drawing a widget. A round-trip test enforces this and was mutation-tested to confirm it goes red when a widget dispatches a change.

What was added

Construct	Live-preview rendering (off the caret's line)
GFM tables (top-level)	a real table; cells use a text-only inline renderer (no HTML from page text); clicking a row puts the caret on that row's source line
`[{…}]()` plugins, variables, access rules	labelled chips — `⚙ TableOfContents`, a lock chip `view: Admin, Editors`, `$username`
Autolinks and bare URLs	styled as links, `<` `>` hidden
Reference links `[t][r]`	styled as links only when a matching definition exists (CommonMark label rules)
Footnotes `[^1]` / `[^1]: …`	superscript and definition chips (both readers render footnotes)
Backslash escapes, setext headings, HTML blocks	escape hidden; heading styling; HTML shown as muted markup, never rendered

The line under the caret always shows its raw source, so editing a table, chip or diagram means clicking into it.

Editor mode as a preference

Stored as a user-profile attribute (wikantik.editor.mode, source or live) — no migration. GET/PUT /api/auth/profile carries editorMode; null clears it.
Resolution: the account's value, else this browser's remembered choice, else live (the new default). A browser choice made while signed out migrates to the account once; a value mirrored from one account never migrates into another (provenance key).
Preferences → Editor → "Default editing mode". Legacy JSPWiki-syntax pages stay in source and never write the preference.

Lessons

Measure before optimising. The first build regressed typing by ~0.3 ms per keystroke on large pages. Profiling showed one cause: the reference-definition lookup re-walked the whole page every keystroke because its cache was keyed on the (always new) document. Carrying definitions through edits in a StateField, updated only around the edit, restored keystroke cost to within 12% of the baseline.
Widget equality must compare every field. Block widgets are reused when "the same"; the comparison ignored source, so a programmatic edit inside an off-caret fence could leave a stale drawing. Fixed and tested alongside tables.
Lezer's view of footnotes differs by shape — [^1]: word is a link-reference definition, [^1]: two words a paragraph — so footnote handling had to cover both.

Not done (deliberately)

A ProseMirror rich-text mode (the preference is a string enum to leave room for it), table-editing UI, and rendering raw HTML. Phase 2–4 Obsidian syntax (==highlight==, %% %%, inline #tags) will add its own live-preview support.