feat(editor): footnotes (reference + definitions, collab-safe) #18

Ghost · 2026-06-20T11:40:36+03:00

Ghost commented

2026-06-20 11:40:36 +03:00

Implements docs/footnotes-plan.md — Variant B (reference + definitions), chosen over the inline-atom-with-sub-editor model specifically for collaboration safety.

What

Footnotes: a superscript marker in the text linked to an editable definition in a "Footnotes" section at the end of the page, with automatic numbering and a read-only hover popover. Survives the Markdown round-trip and the MCP path.

How

editor-ext (packages/editor-ext/src/lib/footnote/): three plain nodes — footnoteReference (inline atom, id), footnotesList (block, trailing), footnoteDefinition (paragraph+, id). renderHTML/parseHTML to sup[data-footnote-ref] / section[data-footnotes] / div[data-footnote-def]; a parse-rule priority makes the empty reference win over the Superscript mark.

Numbering is a decoration-only plugin — a pure function of document order, so every client computes identical numbers with no document mutation (Yjs-safe; no appendTransaction on remote steps).
Sync plugin: single-pass, always SYNC_META-tagged and skipping remote transactions (so it can never re-trigger itself → terminates), idempotent; canonicalizes to one trailing footnotesList (merging duplicates), creates missing definitions, drops orphans, and is TrailingNode-aware. Disabled in read-only.
Commands setFootnote (one tx: reference + definition inserted at the matching index + focus), removeFootnote (cascade, single undo), scrollTo*; slash /footnote.

client: superscript NodeView + floating-ui read-only popover; bottom-list + definition NodeViews; registered in mainExtensions. server: the three nodes registered in tiptapExtensions so collab/save/export keep them. markdown: turndown/marked round-trip to pandoc/GFM [^id]. MCP mirror: schema + converter + commentsToFootnotes rewritten to real footnote nodes + diff marker counting.

Reasoning / decisions

Decoration-based numbering (not stored) is the crux of collab-safety: deterministic from doc state, so two clients never disagree and there's no appendTransaction war.
Parse-priority for the empty reference is load-bearing — without it the server's Superscript mark swallows the sup and the reference is silently dropped on save; guarded by a dedicated server round-trip spec.

Review findings & fixes (two rounds)

Static review found 2 blockers: raw NUL bytes in transforms.ts source (formatters could silently corrupt the sentinel) → rewritten as \u0000 escapes (verified 0 raw NULs in src + build); and the "single trailing footnotesList" invariant wasn't enforced (two lists survived, dropping def ids) → added an idempotent merge/canonicalize pass. Also: a Markdown code-fence guard (so [^id]: inside a code block isn't extracted), the sync plugin disabled in read-only, a misleading comment, and the server round-trip regression test.

Then browser verification caught a hard freeze on insert — an infinite appendTransaction ping-pong between the sync plugin and the TrailingNode extension (each kept repositioning the list), enabled by an un-tagged transaction. Fixed: the sync plugin now does one always-tagged single-pass rebuild and treats the list as correctly placed when only empty paragraphs follow it. Added a real-editor regression test (full Tiptap Editor incl. Superscript + TrailingNode, with a 50-round loop guard) that fails on the old code and passes on the new.

Verification

pnpm --filter @docmost/editor-ext build + server + @docmost/mcp + client — all clean.
Tests: editor-ext 15 pass (incl. the live-editor no-infinite-loop test, multi-list convergence, command cascade, code-fence preservation); MCP 237 pass (JSON↔MD footnote round-trip, commentsToFootnotes→nodes, NUL-sentinel collision); server footnote round-trip-with-Superscript 2 pass.
Browser (headless Chromium, collab on the branch schema): /footnote inserts WITHOUT freezing (responsiveness probe passed); marker + bottom definition appear; hover popover shows the definition; two footnotes number 1/2 in document order; after a reload both markers AND both definitions survive (not stripped on the server save); cascade-deleting a marker removes its definition and renumbers. No real app errors. Screenshots captured.

v2 follow-ups (per plan)

Definition reordering when a reference is moved (cut/paste), id-collision regeneration on paste, multiple references to one footnote.

🤖 Generated with Claude Code

Implements `docs/footnotes-plan.md` — **Variant B (reference + definitions)**, chosen over the inline-atom-with-sub-editor model specifically for collaboration safety. ## What Footnotes: a superscript marker in the text linked to an editable definition in a "Footnotes" section at the end of the page, with automatic numbering and a read-only hover popover. Survives the Markdown round-trip and the MCP path. ## How **editor-ext** (`packages/editor-ext/src/lib/footnote/`): three plain nodes — `footnoteReference` (inline atom, `id`), `footnotesList` (block, trailing), `footnoteDefinition` (`paragraph+`, `id`). `renderHTML`/`parseHTML` to `sup[data-footnote-ref]` / `section[data-footnotes]` / `div[data-footnote-def]`; a parse-rule **priority** makes the empty reference win over the Superscript mark. - **Numbering** is a **decoration-only** plugin — a pure function of document order, so every client computes identical numbers with no document mutation (Yjs-safe; no `appendTransaction` on remote steps). - **Sync plugin**: single-pass, **always SYNC_META-tagged** and skipping remote transactions (so it can never re-trigger itself → terminates), idempotent; canonicalizes to one trailing `footnotesList` (merging duplicates), creates missing definitions, drops orphans, and is **TrailingNode-aware**. Disabled in read-only. - Commands `setFootnote` (one tx: reference + definition inserted at the matching index + focus), `removeFootnote` (cascade, single undo), `scrollTo*`; slash `/footnote`. **client**: superscript NodeView + floating-ui read-only popover; bottom-list + definition NodeViews; registered in `mainExtensions`. **server**: the three nodes registered in `tiptapExtensions` so collab/save/export keep them. **markdown**: turndown/marked round-trip to pandoc/GFM `[^id]`. **MCP mirror**: schema + converter + `commentsToFootnotes` rewritten to real footnote nodes + diff marker counting. ## Reasoning / decisions - **Decoration-based numbering** (not stored) is the crux of collab-safety: deterministic from doc state, so two clients never disagree and there's no appendTransaction war. - **Parse-priority** for the empty reference is load-bearing — without it the server's Superscript mark swallows the sup and the reference is silently dropped on save; guarded by a dedicated server round-trip spec. ## Review findings & fixes (two rounds) Static review found **2 blockers**: raw NUL bytes in `transforms.ts` source (formatters could silently corrupt the sentinel) → rewritten as `\u0000` escapes (verified 0 raw NULs in src + build); and the "single trailing footnotesList" invariant wasn't enforced (two lists survived, dropping def ids) → added an idempotent merge/canonicalize pass. Also: a Markdown code-fence guard (so `[^id]:` inside a code block isn't extracted), the sync plugin disabled in read-only, a misleading comment, and the server round-trip regression test. Then **browser verification caught a hard freeze on insert** — an infinite `appendTransaction` ping-pong between the sync plugin and the `TrailingNode` extension (each kept repositioning the list), enabled by an un-tagged transaction. **Fixed**: the sync plugin now does one always-tagged single-pass rebuild and treats the list as correctly placed when only empty paragraphs follow it. Added a **real-editor regression test** (full Tiptap Editor incl. Superscript + TrailingNode, with a 50-round loop guard) that fails on the old code and passes on the new. ## Verification - `pnpm --filter @docmost/editor-ext build` + `server` + `@docmost/mcp` + `client` — all clean. - Tests: editor-ext **15 pass** (incl. the live-editor no-infinite-loop test, multi-list convergence, command cascade, code-fence preservation); MCP **237 pass** (JSON↔MD footnote round-trip, `commentsToFootnotes`→nodes, NUL-sentinel collision); server footnote round-trip-with-Superscript **2 pass**. - Browser (headless Chromium, collab on the branch schema): `/footnote` inserts WITHOUT freezing (responsiveness probe passed); marker + bottom definition appear; hover popover shows the definition; two footnotes number 1/2 in document order; **after a reload both markers AND both definitions survive** (not stripped on the server save); cascade-deleting a marker removes its definition and renumbers. No real app errors. Screenshots captured. ## v2 follow-ups (per plan) Definition reordering when a reference is moved (cut/paste), id-collision regeneration on paste, multiple references to one footnote. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Ghost added 2 commits 2026-06-20 11:40:36 +03:00

feat(editor): footnotes (reference + definitions model) 4d17befb0d

Adds footnotes: a superscript marker in the text linked to an editable
definition in a Footnotes section at the end of the page, with auto-numbering
and a read-only hover popover. Chose the reference+definitions model (3 plain
nodes) over an inline atom with a sub-editor specifically for collaboration
safety.

editor-ext (packages/editor-ext/src/lib/footnote/):
- footnoteReference (inline atom, id), footnotesList (block, last child),
  footnoteDefinition (paragraph+, id). renderHTML emits sup[data-footnote-ref]
  / section[data-footnotes] / div[data-footnote-def]; parse-rule priority makes
  the empty reference win over the Superscript mark (else it is dropped on the
  server save).
- numbering: a decoration-only plugin (pure function of doc order) -> every
  client computes identical numbers, no document mutation, Yjs-safe.
- sync plugin: single-pass, always SYNC_META-tagged and skipping remote txns
  (terminates, no loop), idempotent; canonicalizes to one trailing footnotesList
  (merging duplicates), creates missing definitions, drops orphans, and
  coexists with TrailingNode. Disabled in read-only.
- commands setFootnote (one tx: reference + definition at the matching index +
  focus) / removeFootnote (cascade, one undo) / scrollTo*. slash /footnote.

client: superscript NodeView + floating-ui read-only popover; bottom-list and
definition NodeViews; registered in mainExtensions.

server: the three nodes registered in tiptapExtensions so collab/save/export
keep them. Round-trip regression spec guards the Superscript parse-priority.

markdown: turndown/marked round-trip to pandoc/GFM [^id] (+ a code-fence guard
so footnote-like lines inside code blocks are not extracted).

MCP mirror: schema + markdown-converter + commentsToFootnotes rewritten to real
footnote nodes + diff marker counting; NUL sentinels written as \u0000 escapes.

v2 follow-ups (per plan): definition reordering on reference move, id-collision
regeneration on paste, multiple references to one footnote.

Implements docs/footnotes-plan.md (variant B).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs: remove implemented footnotes plan 1c83a8ae15

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Ghost added 1 commit 2026-06-20 13:47:20 +03:00

fix(footnotes): survive duplicate-id definitions without collab divergence ceee2a76ca

Release-cycle red-team found two same-id footnoteDefinition nodes (trivially
produced by markdown import [^d]: first / [^d]: second, or paste/duplicate)
caused silent data loss: scan() used a last-wins Map and the sync rebuild
(addToHistory:false, propagated via Yjs, un-undoable) dropped all but the last.

Fix resolves collisions so BOTH survive, with a DETERMINISTIC id scheme so
collaborators converge:
- deriveFootnoteId(originalId, occurrence, taken): the k-th (k>=2) occurrence of
  id X becomes X__k, bumped with a deterministic alpha suffix only against the
  doc's own id set — a pure function of document state. No Math.random/Date.now
  on the sync or import paths (random uuid stays only in setFootnote, where a
  single user originates a brand-new id).
- footnote-sync.resolveCollisions walks refs+defs in document order, re-ids
  duplicate references via setNodeMarkup and pairs them 1:1 with definitions;
  single SYNC_META-tagged transaction, returns null when canonical (terminates).
- Markdown import (footnote.marked) + MCP mirror (collaboration.ts) dedup with
  the same deterministic scheme + marker rewrite; packages/mcp/build regenerated.
- Paste plugin remaps colliding pasted ids against the current doc.

Tests: two independent editors resolving the same duplicate-id doc produce
IDENTICAL ids (the cross-client determinism guard that the random version would
fail); both definitions survive the first edit; import dedup is deterministic.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Ghost added 1 commit 2026-06-20 15:44:20 +03:00

perf+fix(footnotes): minimal-diff sync (no concurrent-edit loss); cache numbering 587a940959

Release-cycle review found two hardening gaps:
- The sync plugin deleted+rebuilt the WHOLE footnotesList on any reorder/orphan,
  replacing every definition's Yjs subtree -> a collaborator typing in a
  definition could lose in-flight characters on merge. Rework to targeted,
  minimal mutations: attr-only setNodeMarkup for collision re-ids, delete only
  genuine orphans, insert only genuinely-missing definitions (at the list end,
  not shifting existing subtrees), and consolidate multiple lists only in the
  abnormal paste/merge case. An unchanged (correct id, referenced) definition is
  left completely untouched. Numbering is decoration-only, so physical list order
  may drift after a reorder (accepted) while displayed numbers stay correct.
  Invariants preserved (reviewed + tested): one SYNC_META transaction, null when
  canonical (terminates), deterministic deriveFootnoteId, remote-skip -> no
  re-introduced freeze or divergence.
- computeFootnoteNumbers ran per-NodeView-render (O(n^2)/keystroke in big docs).
  The numbering plugin now caches the number map in its state (computed once per
  docChanged); NodeViews read it O(1) via getFootnoteNumber.

Tests: no-rebuild-on-reorder asserts unchanged definition node subtrees are
identity-preserved; isRemoteTransaction skip; enableSync:false read-only; cache
correctness. Browser re-smoke: insert (no freeze), number, persist across reload,
cascade delete all pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Ghost referenced this pull request

2026-06-20 21:02:02 +03:00

[footnotes] Слишком большой промежуток между номером и текстом определения #44

Ghost added 1 commit 2026-06-20 21:29:14 +03:00

fix(footnotes): tighten the gap between a definition's number and text (#44 ) a85dd607bd

The footnote definition number ('1.') sat ~19px from its text because two
spacings stacked: the 1.5em (24px) marker min-width box (wider than the ~15px
glyph) plus a 10px flex gap. Reduce the flex gap to 0.4em (about one space) and
right-align the number within the 1.5em column so the period sits next to the
text and multi-digit numbers (10, 11, ...) stay aligned. Reads like '1. text'.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

vvzvlad added 1 commit 2026-06-20 22:21:19 +03:00

Merge branch 'develop' into feat/footnotes c5f44a6eee

Resolve conflicts at shared registration points by unioning both features
(footnotes + the already-merged html-embed / page-embed work):
- slash-menu/menu-items.ts, editor extensions.ts: keep both imports + configures
- collaboration.util.ts: register footnote nodes and pageEmbed
- editor-ext marked.utils.ts: register footnote + html-embed markdown extensions
- editor-ext package.json/tsconfig.json/vitest.config.ts: union of test config
  (jsdom env for footnote DOM tests + combined test/spec include glob)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Ghost merged commit 692c0abe13 into develop

2026-06-20 22:21:37 +03:00

Ghost referenced this issue from a commit

2026-06-20 22:21:38 +03:00

Merge pull request 'feat(editor): footnotes (reference + definitions, collab-safe)' (#18) from feat/footnotes into develop

vvzvlad referenced this issue from a commit

2026-06-21 05:21:31 +03:00

docs(readme): sync roadmap with develop

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: vvzvlad/gitmost#18