Record the alternatives the editor substrate decision was chosen over

[Azganoth]

Question

Was ProseMirror, through Milkdown Kit, the right document model for Leafdown's hybrid editor, and what alternatives was it chosen over?

Use temporary source projection establishes why projection is the correct approach within a ProseMirror document model, and records what it beat there: decorations and widgets cannot make synthetic markers natively editable without recreating selection, deletion, clipboard, IME, and keyboard behavior, and a permanent Markdown-token schema would conflict with Milkdown's CommonMark/GFM model. Those alternatives are settled and are not reopened here.

The open question sits one level below: projection exists because the document model renders semantic content and does not natively carry Markdown syntax as editable text. A source-first model inverts that — source is the document, and regions are decorated to render richly. Use Milkdown Kit records no alternatives, so whether that inversion was considered, and why it was not chosen, is unrecorded.

Context

The editor is the largest subsystem in the project: 10,903 source lines and 8,230 test lines across 15 plugins and 12 command modules, of which source projection is roughly 4.0k lines across 8 source files, two of them over a thousand lines each.

Use Milkdown Kit carries a rationale but no rejected alternatives, which means the most consequential technical decision in the project cannot be revisited on its merits — any future doubt restarts the evaluation from nothing. The projection decision demonstrates the standard worth meeting: it names what it rejected and why, and remains useful precisely because it does.

Confirming Milkdown is an expected outcome, and a confirmation that records what it beat is the deliverable either way. Cost is the reason to answer now rather than later: the editor grows, and every month makes both the evaluation and any change that follows more expensive.

Related context

• Related issues or pull requests: #44, #46, #63, #64 — the origin and generalization of source projection.
• Documentation, decisions, or prior investigation:
  • docs/decisions.md, "Editor Decisions" — Use Milkdown Kit, Accept Milkdown GFM preset behavior, Do not use Crepe, Use temporary source projection. Per docs/README.md, Decisions has authority over Architecture and Specification.
  • docs/decisions.md, Gate on defect classes automation can reach — already characterizes this project's substantive defects as boundary-semantics failures. Use that characterization rather than re-deriving it.
  • docs/architecture.md, "Editor Architecture" — Milkdown responsibilities, Leafdown responsibilities, clipboard ownership, source projection.
  • docs/specification.md — editor behavior, clipboard semantics, and save output rules that any substrate must preserve.

Validate

1. Establish whether the difficulty is model-rooted. Group the projection and editor clipboard fixes in git log by root cause rather than symptom, and determine whether each traces to the document model rendering semantic content rather than source, or to complexity inherent in the hybrid-editing goal that any substrate would carry. Treat the reasoning already recorded in Use temporary source projection as established. If the causes are inherent rather than model-rooted, the question is answered: record that conclusion and stop before step 2.

2. Evaluate substrates against the product goal in docs/specification.md — one hybrid surface, no source/preview split, no separate modes, local raw-source editing for inline and source-oriented constructs, Markdown semantics preserved on save:

   • Staying on Milkdown. The baseline every alternative must beat, evaluated as seriously as the rest.
   • CodeMirror 6, as the source-first inversion. Assess how far Obsidian's Live Preview is relevant prior art for reaching this product goal on that model.
   • Lexical.
   • ProseMirror-based alternatives such as TipTap. Reason explicitly about whether changing the abstraction over an unchanged document model could address a model-rooted cause, rather than listing them as if they were a different substrate.

   For each: how naturally it expresses local raw-source editing, Markdown round-trip fidelity and what owns it, GFM and footnote support, Shiki integration, table editing, clipboard control at the fidelity documented in Clipboard Ownership, extension model maturity, maintenance health, and license compatibility with GPL-3.0-or-later.

3. Quantify migration cost for any recommended change: what carries over, what is rewritten, and which behavior specified in docs/specification.md is at risk. A migration that silently drops specified behavior is not a migration.

Exit criteria

• The question is answered, with the model-rooted determination supported by evidence from the fix history.
• The outcome records the conclusion, tradeoffs, and supporting evidence links.
• Use Milkdown Kit in docs/decisions.md gains the alternatives it was chosen over and the reasons, in the repository's Decision, Rationale, Consequences format — regardless of which way the spike lands.
• Follow-up issues are created only for selected work. A migration is accepted only as a staged path where each stage ships and is verifiable independently.
• Owning documentation updates are identified when the outcome changes durable direction.

Outcome

To be completed when the spike concludes.