Skip to content

Generalize and rename the source-projection session engine #63

Description

@Azganoth

Summary

Generalize Leafdown’s existing inline source-projection plugin into a reusable source-projection session engine and rename the capability from inlineSourceProjection to sourceProjection.

This is a behavior-preserving enabling rework for:

The current session representation assumes one text range with a uniform set of marks and reconstructs canonical content from text + marks. It cannot safely represent either a rich inline fragment or an inline atomic node.

Retain the established session lifecycle: projection-local undo/redo, restore-before-commit native history bridging, dirty-state integration, transient Markdown-update suppression, selection preservation, target switching, save-time finalization, and exact literal fallback.

Expected behavior

  • The shared engine owns one active session, its projected range, original ProseMirror content, projected source, local history, transaction metadata, and finalization lifecycle.
  • Sessions preserve the original target as an immutable ProseMirror Slice or equivalent fragment rather than reconstructing it only from uniform marks.
  • Projection entry replaces the complete target with unmarked editable source text.
  • Clean finalization restores the original content exactly.
  • Edited finalization restores the original content before applying the adapter-produced replacement as the native history change.
  • Invalid source commits every projected character as literal document text.
  • Object-specific adapters own target discovery and precedence, source generation, validation and rehydration, presentation spans, and selection mapping.
  • The adapter contract supports rich inline fragments and inline atomic nodes without implementing Mixed-format link labels do not enter source projection #58 or Project footnote-reference source in the editor #60 in this issue.
  • Existing strong, emphasis, strikethrough, inline-code, link, and autolink projection behavior remains unchanged.
  • The plugin, syntax modules, exported symbols, tests, imports, CSS selectors, data attributes, and documentation use sourceProjection terminology.
  • markerPresentation remains a separate capability.
  • The contract allows Mixed-format link labels do not enter source projection #58 to preserve one logical outer link wrapper when a mixed-format link is saved and reopened.

Related docs

Done when

  • The capability consistently uses sourceProjection terminology.
  • Sessions store and restore original ProseMirror slices or fragments.
  • Session lifecycle logic is independent of mark-specific syntax.
  • An adapter boundary exists for discovery, source generation, rehydration, presentation, and selection mapping.
  • Clean entry and exit restore original document content exactly.
  • Edited valid source retains existing native undo/redo behavior.
  • Invalid source retains every projected character as literal text.
  • Existing projection behavior remains unchanged and covered.
  • Projection-local history, dirty tracking, Markdown-update suppression, selection crossing, target switching, paste, and save-time finalization remain covered.
  • Projection documentation and the documentation index use the new capability name.
  • Mixed-format link labels do not enter source projection #58 and Project footnote-reference source in the editor #60 can depend on this issue without depending on each other.

Out of scope

  • Mixed-format link-label projection itself.
  • The serializer behavior required to preserve one logical link wrapper.
  • Footnote-reference projection.
  • Footnote definitions.
  • Raw HTML, images, and tooltip UI.
  • New user-visible source-projection behavior.
  • A permanent Markdown-token schema.

Metadata

Metadata

Assignees

Labels

FeatureNew feature or request

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions