fix: emit reliable patches after clearing the editor

[christianhg]

Clearing a Portable Text field and typing into it again could silently lose the new text, or crash the consumer applying the emitted patches (Cannot apply deep operations on primitive values): the retype flush emitted only diffMatchPatches against a field the same patch stream had just unset([]). It reproduces with any host that mirrors mutation.value back into update value, which is the documented wiring (the playground uses it), and it is live in the playground on main.

The editor tells a synced-in pristine block (persisted content) apart from its own local placeholder by remembering the last synced value. Two paths let the placeholder itself become that evidence. First, the sync machine recorded every completed sync, including no-op syncs whose value the engine already embodied, so the mirror's echo after a single-flush clear recorded the placeholder directly. Second, and surviving any recording guard: when a clear spans several flushes (character-by-character backspace), the mirrored echoes lag the ongoing edits, so each stale echo differs from the engine by the time it syncs, writes as a genuine remote change, and the last one legitimately records the cleared state.

Two mechanisms, one per path. Recording now happens only when a sync actually wrote into the engine, since an echo of the editor's own state asserts nothing about persistence. And patch generation tracks its own field-level statement: after it emits the became-empty unset([]), the next content-producing edit always rebuilds the field, regardless of what lagging syncs recorded in between. Rebuilding over a recorded value equal to the placeholder also clears the recording (the rebuild proves it was a stale echo), so a repeated clear unsets the field again instead of leaving an empty block behind. The emitted stream stays self-consistent: destroy, then rebuild, never text diffs into the void.

One narrow trade rides along, disclosed in the changeset: a genuine empty block arriving through update value in the window between the editor's own unset and its next keystroke is now rebuilt (re-inserting a block the document already holds) where value sync previously suppressed correctly; the same window reached through remote patches misbehaved identically before this change. A stale echo and a genuine pristine block are indistinguishable by value in that window; distinguishing them takes provenance metadata, which is follow-up work. Both regression scenarios from the persisted-content fix this builds on remain pinned and green; the two new scenarios were proven red five-for-five without each mechanism and stable across twenty runs with them.

---

Note

Medium Risk
Changes patch emission and value-sync bookkeeping on the critical clear→retype path; behavior is narrow but affects how hosts apply local patches.

Overview
Fixes a bug where clearing the editor and typing again could emit only diffMatchPatch patches against a field the same stream had just removed with unset([]), so consumers lost the new text or threw when applying patches. This showed up with the common host pattern that mirrors mutation.value back into update value.

Patch generation now tracks valueUnsetEmitted after a became-empty unset([]). The next local edit that produces patches always re-materializes the field (setIfMissing, block insert, then text diffs), even if a lagging mirrored sync made the placeholder look like persisted content. Rebuilding over a recorded value equal to that placeholder clears lastSyncedValue so a second clear still emits unset([]).

Value sync only updates lastSyncedValue when a completed sync actually wrote into the engine (done syncing carries a changed flag), so no-op echoes of the editor’s own state are not treated as host persistence claims.

Regression coverage adds scenarios for single-flush and character-by-character clears with mirrored values.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 946c2ca

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 14 packages

Name	Type
@portabletext/editor	Patch
@portabletext/plugin-character-pair-decorator	Patch
@portabletext/plugin-dnd	Patch
@portabletext/plugin-emoji-picker	Patch
@portabletext/plugin-input-rule	Patch
@portabletext/plugin-list-index	Patch
@portabletext/plugin-markdown-shortcuts	Patch
@portabletext/plugin-one-line	Patch
@portabletext/plugin-paste-link	Patch
@portabletext/plugin-sdk-value	Patch
@portabletext/plugin-table	Patch
@portabletext/plugin-typeahead-picker	Patch
@portabletext/plugin-typography	Patch
@portabletext/toolbar	Patch

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

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

Project	Deployment	Actions	Updated
portable-text-editor-documentation	Ready	Preview	Sep 8, 2026 6:29am UTC
portable-text-example-basic	Building	Preview	Sep 8, 2026 6:29am UTC
portable-text-playground	Ready	Preview	Sep 8, 2026 6:29am UTC

[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.09 MB / 254.4 KB	+68 B, +0.0%	67 ms	-0 ms, -0.3%
⚪ @portabletext/editor / @portabletext/editor/behaviors	export	4.0 KB / 1.4 KB	None	2 ms	-0 ms, -2.6%
⚪ @portabletext/editor / @portabletext/editor/plugins	export	5.1 KB / 1.8 KB	None	7 ms	-0 ms, -1.0%
⚪ @portabletext/editor / @portabletext/editor/selectors	export	94.8 KB / 21.7 KB	None	8 ms	+0 ms, +0.7%
⚪ @portabletext/editor / @portabletext/editor/traversal	export	42.8 KB / 11.2 KB	None	6 ms	+0 ms, +0.6%
⚪ @portabletext/editor / @portabletext/editor/utils	export	34.0 KB / 9.1 KB	None	6 ms	+0 ms, +2.3%
⚪ @portabletext/markdown / @portabletext/markdown	export	292.1 KB / 86.0 KB	None	40 ms	-1 ms, -1.7%

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 677a27b. Configure here.}