ContextQMD
Back to Plate

Slate v2 overlay architecture cuts

docs/research/decisions/slate-v2-overlay-architecture-cuts.md

53.0.62.2 KB
Original Source

Slate v2 overlay architecture cuts

Question

What architecture conclusions are strong enough to lock for Slate v2 after the full decorations / annotations research pass?

Decision

Accept the following cuts and design direction:

  • split the overlay system into Decoration, Annotation, and Widget lanes
  • cut legacy decorate as architecture
  • make Bookmark the preferred durable public anchor noun
  • demote RangeRef to lower-level runtime machinery
  • allow canonical annotation metadata to stay in app-, collab-, or service-owned stores while slate-react mirrors/indexes anchors
  • keep generic widget registration, public WidgetPlacement, and public bookmark registries out of the early public API
  • reject public path-based widget anchors
  • reject callback/array-first public APIs where store/controller surfaces are more honest

Why

  • ProseMirror proves mapped decoration data and bookmark durability are real, not aesthetic preferences.
  • Lexical proves id-bearing marks, comment stores, and decorator UI want separate ownership.
  • Tiptap proves product-layer comments, suggestions, and floating menus do not collapse into one engine primitive cleanly.
  • VS Code proves typed visual channels and comment controllers scale better than one generic overlay bucket.
  • TanStack DB proves annotation metadata wants normalized stores and stable subscriptions.
  • local Slate v2 proof already supports runtime ids, projection slices, bookmarks, and DOM-bridge separation.

What this overrules

  • compatibility-first protection of legacy decorate
  • equal-peer public RangeRef + Bookmark
  • public path-based widget anchors
  • forcing canonical thread/comment metadata into the editor runtime
  • one derive(snapshot) callback as the only serious decoration-source shape
  • render-time array replacement as the default annotation integration story

Practical consequence

The best next implementation work is not “make old Slate decorations survive”.

It is:

  • harden the overlay kernel
  • connect store/controller-style annotation inputs
  • expose the smallest honest public surface
  • keep legacy baggage out unless real adoption pain later proves it is worth it