feat(plugin-range-decorations): add the range decorations toolkit

[christianhg]

What

The consumer toolkit over the range decoration primitive (#3226), as its own package so the interpreted semantics (event vocabulary, batching, reads, React bindings) evolve on plugin versioning while core's contract stays mechanical facts. Stacked on #3226; merges after it, and @portabletext/plugin-range-decorations@1.0.0 hand-publishes from this branch once the released editor carries the primitive.

import {useRangeDecorationLayer, useRangeDecorations, defineRangeDecoration} from '@portabletext/plugin-range-decorations'

function CommentsLayer(props: {comments: Array<Comment>; store: CommentStore}) {
  const layer = useRangeDecorationLayer({
    rangeDecorations: useMemo(
      () => props.comments.map((comment) => defineRangeDecoration({...})),
      [props.comments],
    ),
    on: (events) => {
      // one batched call per settled change:
      // 'moved' {previousRange, newRange} | 'content-changed' {range} | 'lost' {previousRange}
      for (const event of events) {
        if (event.origin !== 'local') continue // siblings see the edit as remote; one writer
        ...
      }
    },
  })
  const positions = useRangeDecorations(layer) // live reads; re-renders at the settled boundary
  return <CommentsPanel comments={props.comments} positions={positions} />
}

createRangeDecorationLayer(editor, config) is the same layer without React ({update, unregister, current}); useRangeDecorationLayer is its facade hook (stable never-null handle, registration in an effect behind it, the hook owns a hook-created layer's contents); RangeDecorationPlugin is the hook in component form; RangeDecorationWidget is the safe inline anchor for decoration chrome that is not document text (zero-width contentEditable={false}, consumer chrome only, document children stay siblings).

The toolkit folds the primitive's per-operation mappings into the vocabulary: newRange: null becomes lost, reference-changed ranges become moved, contentTouched becomes content-changed, flushed once per settled change with at most one event per decoration per concern, moved before content-changed, lost discarding the others, net-zero movement suppressed, batch order following the layer's array order, listener errors isolated per layer. Event payloads resolve their rangeDecoration at accumulation time, so a same-tick update cannot swap a newer config into an older event (pinned). current is reference-stable when positions are deep-equal and populates for layers created before the editor is ready. Every one of these contracts is pinned in the package's own suite: the vocabulary tests moved here from core with assertions unchanged.

The playground demo

Both packages dogfooded end to end: a comments module (layer factory + hooks, origin-discriminated write-back where only the editor that made the edit persists, live snippets refreshed by content-changed, undo revives orphaned comments) and a presence module (focus-point carets rendered through RangeDecorationWidget in plugin-sdk-value's shape). The Inspector gains a Comments tab and a Decorations tab listing every layer's live positions; the Decorations tab is the only subscriber to presence positions, so the presence owner never re-renders on movement, which is the two-hook split demonstrated. Dialog-close focus hand-off lives in the playground Dialog primitive (focusOnClose, scheduled after react-aria's restore-to-trigger; react-aria lacks a restore-target seam, tracked upstream). The schema's comment annotation is renamed footnote to free the word.

No changeset: new packages hand-publish v1.0.0 before their PR merges.

---

Note

Medium Risk
New public plugin API and non-trivial event batching/reconciliation logic; playground-only state machine changes, but the package will be consumed for collaboration features tied to editor selection and remote edits.

Overview
Introduces @portabletext/plugin-range-decorations, a consumer layer on top of editor.registerRangeDecorations that composes independent decoration stacks (comments, presence, highlights) with batched moved / content-changed / lost events, stable current positions, and React APIs (useRangeDecorationLayer, useRangeDecorations, RangeDecorationPlugin, RangeDecorationWidget).

The playground drops the old PortableTextEditable rangeDecorations prop and demo toolbar button in favor of shared comments and presence plugins wired through the playground machine (comment list, selection sync, layer registration for the inspector). Settings add Collaboration toggles; the inspector gains Comments and Decorations tabs. Schema comment annotations are renamed footnote so “comment” refers to range-based collaboration, not Portable Text marks.

^{Reviewed by Cursor Bugbot for commit 40f570a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
portable-text-editor-documentation	Ready	Preview	Sep 4, 2026 9:49am UTC
portable-text-example-basic	Ready	Preview	Sep 4, 2026 9:49am UTC
portable-text-playground	Ready	Preview	Sep 4, 2026 9:49am UTC

[changeset-bot]

⚠️ No Changeset found

Latest commit: 40f570a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

Bundle Stats

✅ No significant changes.

All scenario measurements (7)

🗺️ @portabletext/editor / @portabletext/editor · @portabletext/editor / @portabletext/editor/behaviors · @portabletext/editor / @portabletext/editor/plugins · @portabletext/editor / @portabletext/editor/selectors · @portabletext/editor / @portabletext/editor/traversal · @portabletext/editor / @portabletext/editor/utils · @portabletext/markdown / @portabletext/markdown · Artifacts

Scenario	Kind	Bundle (raw / gzip)	Gzip change	Import time	Import change
⚪ @portabletext/editor / @portabletext/editor	export	1.10 MB / 256.5 KB	None	62 ms	+1 ms, +1.0%
⚪ @portabletext/editor / @portabletext/editor/behaviors	export	4.0 KB / 1.4 KB	None	2 ms	+0 ms, +3.7%
⚪ @portabletext/editor / @portabletext/editor/plugins	export	5.1 KB / 1.8 KB	None	6 ms	-0 ms, -2.3%
⚪ @portabletext/editor / @portabletext/editor/selectors	export	93.7 KB / 21.3 KB	None	7 ms	-0 ms, -2.2%
⚪ @portabletext/editor / @portabletext/editor/traversal	export	41.7 KB / 10.8 KB	None	5 ms	-0 ms, -0.9%
⚪ @portabletext/editor / @portabletext/editor/utils	export	33.1 KB / 8.7 KB	None	5 ms	-0 ms, -1.7%
⚪ @portabletext/markdown / @portabletext/markdown	export	272.2 KB / 79.6 KB	None	34 ms	+1 ms, +1.5%

Significant means at least 1.0 KB and 1% gzip, or at least 5 ms and 10% import time.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 40f570a. Configure here.}

[cursor]

Stale presence caret after unmount

Medium Severity

The presence effect reports selection but never clears it on unmount. Toggling Presence off stops further updates and unregisters this editor’s layer, while sibling editors keep rendering a frozen caret from the last stored selection.

 

^{Reviewed by Cursor Bugbot for commit 40f570a. Configure here.}