[zurfyx]

Note

Stack, part 10 of 10. Based on #9507 (zurfyx/y-composition-holdback). Review only this PR's own commits.

The @lexical/y fixes touch the same writer, cursor, reader and binding internals, so they are one linear stack: each PR is based on the one below it, each conflict is resolved once, in the PR whose change causes it, and every CI run tests the real combination.

Merge order: bottom first, #9509 → #9523 → #9522 → #9505 → #9508 → #9502 → #9504 → #9527 → #9507 → #9510. With squash merges, rebase the next PR onto main before merging it (git rebase --onto main <old base branch>).

The stack

#	PR	Branch	Base
1	#9509	zurfyx/update-error-rollback	main
2	#9523	zurfyx/write-before-unread-change	#9509
3	#9522	zurfyx/y-keep-chars-at-format-boundary	#9523
4	#9505	zurfyx/y-undo-member-closer	#9522
5	#9508	zurfyx/y-initial-state-binding	#9505
6	#9502	zurfyx/y-reorder-intent	#9508
7	#9504	zurfyx/y-preserve-unknown-attrs	#9502
8	#9527	zurfyx/y-move-keeps-unknown-fields	#9504
9	#9507	zurfyx/y-composition-holdback	#9527
10	#9510 (this PR)	zurfyx/y-incremental-read-marks	#9507

Follow-ups for after the stack (not in it):

• One "seen of Yjs" view. [lexical-y] Bug Fix: Write a local update made before an unread remote change on the document it was made on #9523's Unread (changes Yjs applied that the binding has not read) and [lexical-playground][lexical-website][lexical-y] Bug Fix: Hold back remote changes to the line being composed until the composition ends #9507's Hidden (changes held back while a line is composed) answer one question, and call sites combine them by hand. One owner module (isGone, isShown, attrOf/attrsOf and the write primitives), an item-level held overlay instead of the was/now maps, and a lint or grep test that allows raw .deleted/getAttr(s) only in the Reader and in named provenance scans. [lexical-website][lexical-y] Bug Fix: Stop a format, comment or link from spreading to the end of the document after an undo or delete races an edit inside it #9505's run-opener scans (liveItemBefore, runOpener, restatedEnd) still read raw deletedness and move there too.
• B-2 at the end of a line. Enter at the very end of a line being composed, while a collaborator's alignment change is held back, leaves that alignment off the new line Lexical copies it to. Enter inside the line keeps it on both halves. It needs a per-key "inherits on split" rule, or a Limit in y.md.
• [lexical-website][lexical-y] Bug Fix: Keep the fields an older client does not know in a block it moves #9527's group fallback chain. A moved item takes its group's fields from a chain of four lookups ($groupReference, $priorGroupItem, the nearest neighbour's marker before the write, priorGroupMarker), with separate predecessor stores for markers and nodes. One stored-predecessor lookup would replace it.

Schema version gate (new, October 29)

Important

New on top of this PR: commit e19f32430. It sits on the same read-only and fail-closed path as the commits below, so it lands here rather than as its own PR. It changes the public API of the unreleased @lexical/y.

What it does. An app declares the version of its document schema. The document records the highest version that ever wrote to it, and a client older than that record opens the document read only, with a typed warning (the "Google Docs" rule). Before, an older client kept editing with fields and node types it does not know. #9504's preservation of unknown fields stays as defense in depth, for fields a newer version removes and for apps that do not bump.

• API change: schemaVersion: number is required on YCollabExtension, YBindingOptions (new YBinding(editor, doc, {schemaVersion})) and the @lexical/y/headless config. A config key cannot be required by type, so the extension throws without one, with the fix in the message: YCollabExtension needs schemaVersion (got none): start at 1 and increase it whenever a node's stored fields or node types change. YBinding and the headless helpers require it in their TypeScript and Flow types too. @lexical/y has never been published, so no released API breaks. Every caller in the repo passes it: tests, the playground and the docs.
• Record. lexical-y-schema:<n> = true on the root, one key per version, grow-only like the layout record. The document's version is the highest n. Two versions that write at once both record theirs, and undo never removes one.
• Write. A client records its version in the same transaction as its first write: a local edit, initialize() of a new document, seedYState or editYState. Opening records nothing. Follow-ups (block id naming, refreshes) record nothing. A write the app's own transaction makes to another shared type does not count.
• Gate. A client older than the record goes read only through the sticky read-only path. Its local edits are refused and read again (UNSUPPORTED_EDIT_WARNING). It reports the new UNSUPPORTED_SCHEMA_WARNING (@lexical/y/unsupported-schema) with {reason: 'newer', found, supported}, or 'malformed'. This also happens mid-session, when a newer client's first write arrives:
  • Local updates made before the change was read are written first. That covers updates that were pending and the update that was running when the change arrived.
  • An update made on the newer record is refused. That covers updates from the app's Yjs observers and updates after a read that recovered.
  • An older client never initializes a document a newer one recorded.
  • Headless: an older editYState or readYState throws a 'read-only' YHeadlessError carrying the warning, and writes nothing.
• Equal or higher version edits as before and keeps fields it does not declare. That is what lets a newer version remove a field.
• Docs and playground. y.md has a new section, "Versioning your schema": when to bump, what older clients see, and how to render the warning. The option and the warning are in y.md's tables. The "Older app versions" limit (including the split case) now applies only between equal versions. y-server.md and the README's wire format describe the record. The playground's read-only notice shows the new reason ("edited with a newer version of the playground. Reload the page"), and ?collabYSchemaVersion=<n> overrides the playground's version.
• Changeset: .changeset/lexical-y-schema-version.md ([feature], patch, with Verify:).

Tests. SchemaVersion.test.ts has 21 cases:

• the gate on open and its warning data, and refused local edits;
• opening writes nothing, and the first write carries the record in the same update;
• mid-session gating that keeps what is shown, and a pending local edit written before the gate;
• concurrent versions: the max wins on every client;
• undo and redo never remove the record;
• malformed records, and no initialize under a newer record;
• a recovery after 20 queued listener updates still gates;
• a record that arrives alone, both inside a running update and with nothing pending;
• an observer's update on the newer record is refused, with or without a pending local update;
• a deferred gate is dropped on dispose();
• writes in the app's own transaction;
• headless: seedYState and editYState record the version, and an older editYState refuses;
• the required config, both at runtime and as @ts-expect-error type tests;
• a newer client editing a field it no longer declares.

Every other suite changes only by passing schemaVersion. A collab e2e case covers the playground notice. A gpt-6.1-sol review found 7 issues over two rounds, all fixed with regression tests above.

Before / after

Before (the new test file run on this PR's previous head, 66bb2a79e):

$ npx vitest run --project unit packages/lexical-y/src/__tests__/unit/SchemaVersion.test.ts
 FAIL  |unit| packages/lexical-y/src/__tests__/unit/SchemaVersion.test.ts > schema version gate > an older client opens a newer document read only, with the warning
AssertionError: expected 'active' to be 'readonly' // Object.is equality
 Test Files  1 failed (1)
      Tests  20 failed | 1 passed (21)

After:

$ npx vitest run --project unit packages/lexical-y/src/__tests__/unit/SchemaVersion.test.ts
 Test Files  1 passed (1)
      Tests  21 passed (21)

$ npx vitest run --project unit packages/lexical-y packages/lexical/
 Test Files  265 passed | 2 skipped (267)
      Tests  9824 passed | 46 expected fail | 4 skipped (9874)

$ pnpm run ci-check
Changeset check passed: 20 pending changeset(s) valid.
Found 0 errors
(exit 0: tsc, Flow, Prettier, ESLint)

The collab e2e specs could not run locally. The machine's sandbox lets Chromium start only with --single-process, which cannot open the second browser context the collab specs need. The existing layout-gate spec fails the same way there. CI runs them.

Description

Every read here goes through #9504's guardedRead, and the read-only rules build on its fail-closed state. Five commits keep a client's bound editor showing what a fresh read of the document shows. Each commit message carries its own description and before/after output.

1. Bind only documents from createYDoc. Yjs cleans up formats by default (doc.cleanupFormatting). A client that applied a stored state to a plain new Y.Doc() before binding had already deleted format items the binding keeps. An edit typed inside a commented word that another client deleted then showed without the comment on that client (paragraph("015")) and with it everywhere else (paragraph("015"[c3])).
   • createYDoc(state?, options?) is now exported by @lexical/y too. It turns the cleanup off before anything is applied and returns a branded YDoc.
   • YCollabExtension's doc and new YBinding take only a YDoc (TypeScript and Flow).
   • At runtime, a document with the cleanup on makes the binding read only, with UNSUPPORTED_CONFIG_WARNING (reason: 'cleanup-formatting').
   • The docs and the playground create bound documents with createYDoc.
   • @lexical/y has not been released, so the narrower doc type breaks no published API.
2. Place what a remote read brings by the blocks around it, never inside a node it moved.
   • A client read only for an unregistered node type showed a paragraph added after such a node at the top of its editor, and kept a line merged away next to one.
   • A remote read into an editor showing an unwritten update could also place a node inside itself, as a child or as a named slot's value. Lexical's walk up the tree then never ended, and the tab hung.
   • The region read now anchors on the node before the old content when the read leaves it in place, and otherwise on the nearest unit before the region that the container still holds.
   • Every placement is checked first. A read that would make a node its own ancestor throws instead, and the binding warns (RECOVERED_READ_WARNING) and reads the document again.
3. Read again what a local update changes while the binding is read only.
   • Code calling editor.update() on a read-only bound editor left the change on screen, unwritten. A remote read into that editor could then misplace blocks or hang.
   • The binding now reads the changed containers again and warns with the new UNSUPPORTED_EDIT_WARNING (reason: 'read-only'). Composition-time changes are read again when the composition ends.
   • Separate updates keep their own re-read budget.
   • Left as before: updates tagged SKIP_COLLAB_TAG, updates while the binding is pending, and updates after the binding went read only to keep showing a change it cannot store (an unstorable slot).
4. Keep a binding read only for good, and warn once about local edits.
   • A change to the layout record made a read-only binding 'active', and editable, while it read the document again, and repeated the cause's warning. setStatus now stays 'readonly' while a lasting cause holds: an unsupported configuration, node types it cannot build, or a change it cannot store.
   • The refusal applies to any status but 'active', and UNSUPPORTED_EDIT_WARNING is reported once each time the binding goes read only.
5. After the binding failed closed ([lexical-website][lexical-y] Bug Fix: An older client keeps the fields and content it cannot read #9504), a local update goes back to what the editor showed.
   • The binding reads nothing more then, so it cannot read the update's change again. Before this change, the editor kept showing it; before reads were guarded, the failing re-read left the editor empty.
   • It now shows the earlier state again, reading nothing, and warns once. Failing closed also keeps the binding read only for good.

Merge order. #9501, #9503 and #9508 add tests that bind new Y.Doc(): TableOnOpen.test.ts, MarkStateBlockType.test.ts and regressions/InitialState.test.tsx. With this PR they need createYDoc() and the YDoc type.

• If they land first, this PR rebases after them and switches those tests (a mechanical change, verified on the combination).
• If this PR lands first, they switch on their rebase.

Restack (October 29)

Rebased onto #9507 (it was based on #9504). One conflict, with #9508 in y.md: both texts combined (synced: true initializes as soon as the binding starts, and createYDoc(stored) is named). The first commit, which brands bound documents, now also moves the tests of PRs below it that bind a plain Y.Doc to createYDoc: #9523's BatchedWrites.test.ts and #9508's regressions/InitialState.test.tsx (N8).

New commits, each with a regression test named after its finding:

• N3: one restore operation, showAgain, for both failClosed and restoreShown: it sets the earlier state whole, or clears the root where that state is empty, and commits it when it runs from a commit's $onUpdate callbacks. A local update after opening the room failed closed no longer throws setEditorState: the editor state is empty and no longer stays shown; this is the unhandled error that turned this PR's CI red (N3: in SchemaSkew.test.ts).
• N7: read only is sticky for a class that throws on stored content too (state.unreadable is in staysReadOnly, the one read-only predicate), and a binding becomes active only at the end of its first full read, once that read found nothing that keeps it read only. Before, a layout-record change flipped such a binding to active and back, and a first open published active before the read (N7: in SchemaSkew.test.ts).
• App updates during a status change (review findings R2-2 to R6-1; one commit): the binding becomes active right after the first read's commit, so nothing an app does when the editor becomes editable (an editable listener's update or command) runs inside the read; a focused editor still gets the read's caret, set ahead of the app's queued replies and not at all where the app set an editor state of its own. One owner, notifyApart, notifies the app apart from the binding's own updates: updates its listeners queue meanwhile are handed back to Lexical's queue right after the binding's update commits, in order, after what the app queued before them and ahead of what it does next, and commit on their own, written or refused like any local edit; dispose() hands them back to the editor; a listener's error is rethrown in a microtask. Failing closed shows the earlier state again before going read only. Before, opening a room such an edit was shown but never stored, a frozen editor kept it for good, and a throwing listener lost it or let its error out through Y.applyUpdate (R2-* to R6-* in SchemaSkew.test.ts and Focus.test.ts). Decision for Gerard: during a freeze nested in the app's own editor.update, an app listener that throws on its reply's commit surfaces from that editor.update (as an app's own queued update would), never from Y.applyUpdate; keeping the reply out of the app's update instead would reopen the ordering problem above. These fixes use Lexical internals (_updates, _updating, _pendingEditorState, _deferred); a Lexical hook for running an update apart from the one in progress would remove that coupling.
• Docs: the UNSUPPORTED_EDIT_WARNING row says that once the document cannot be read, the editor shows again what it showed; the setup notes say the editor is read only until the document has been read and found writable.

Fixed after a randomized soak test of the whole stack:

• R-1: when the binding fails closed, it now ends read only even if an app update listener throws on the restore of what the editor showed; the error is rethrown in a microtask. Before, the throw left the binding active with reads stopped, and its next local edit was written from a stale view, deleting a collaborator's text on every client. A binding opened through the provider's sync also becomes active when an app listener throws on its first read's commit (which skips that commit's $onUpdate callbacks); it used to stay pending (R-1: in regressions/GuardedRead.test.ts).
  Outside this stack: [lexical-table][lexical-y] Bug Fix: Don't throw when a table exists before its DOM #9501's TableOnOpen.test.ts and [lexical-code-prism][lexical-code-shiki][lexical-mark][lexical-website][lexical-y] Bug Fix: Keep comment ids and NodeState when a block change moves or re-creates text #9503's MarkStateBlockType.test.ts bind a plain Y.Doc too. Whichever of those and this PR merges second needs the same createYDoc change in those files.

Changeset

• .changeset/lexical-y-schema-version.md ([feature], the schema version gate above)
• .changeset/lexical-y-create-ydoc.md
• .changeset/lexical-y-region-placement.md
• .changeset/lexical-y-read-only-edits.md

The other three are [fix] patches to @lexical/y.

Test plan

New tests:

• FormatCleanup.test.ts: a stored state loaded before binding, plus a randomized lane against a fresh read.
• UnknownNodeReads.test.ts
• EditorDrift.test.ts, with and without BlockIdExtension:
  • reads into an editor that shows an update tagged SKIP_COLLAB_TAG;
  • local updates on a read-only client, including list numbering, composition, and an unstorable slot.

Before

Abbreviated; full output is in each commit message.

On main, a client that applies the stored state to a plain Y.Doc and binds:

bound: paragraph("015")
fresh: paragraph("015"[c3])
status: active, warnings: 0

UnknownNodeReads.test.ts at the first commit:

Expected: "paragraph("one") / paragraph("two") / paragraph("after")"
Received: "paragraph("after") / paragraph("one") / paragraph("two")"
      Tests  3 failed | 1 passed (4)

EditorDrift.test.ts at the first commit never finishes (killed by timeout 60, exit 124). A production build of the slot case never returns from Y.applyUpdate.

At the second commit, the read-only tests fail:

Expected: "paragraph("one") / quote(paragraph("inner"))"
Received: "paragraph("one" br "x") / paragraph("inner") / quote()"
AssertionError: expected [] to deeply equal [ { reason: 'read-only' } ]
AssertionError: expected [ [ 100, 2 ], [ 101, 2 ], …(4) ] to deeply equal [ [ 1, 2 ], [ 1, 2 ], [ 1, 2 ], …(3) ]
Tests  8 failed | 10 passed (18)

After

FormatCleanup.test.ts        Tests  35 passed (35)   (STORED_STATE_FUZZ_SEEDS=300: 300 passed)
UnknownNodeReads.test.ts     4 passed
EditorDrift.test.ts          Tests  22 passed (22)

$ ./node_modules/.bin/vitest --run --project unit packages/lexical-y
 Test Files  151 passed | 2 skipped (153)
      Tests  5030 passed | 18 expected fail | 2 skipped (5050)
$ pnpm run ci-check
Found 0 errors
$ ./node_modules/.bin/vitest --run --project scripts-unit scripts/__tests__/unit/treeShakingSource.test.ts scripts/__tests__/unit/changesets.test.ts
      Tests  406 passed (406)

The collab Y e2e specs (Collaboration.spec.mjs, CollabY*.spec.mjs) pass in Chromium: 31 passed. Firefox and WebKit were not run.

[vercel]

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

Project	Deployment	Actions	Updated
lexical	Ready	Preview	Oct 29, 2026 8:18pm UTC
lexical-playground	Ready	Preview	Oct 29, 2026 8:18pm UTC

[pkg-pr-new]

lexical

npm i https://pkg.pr.new/lexical@9510

@lexical/a11y

npm i https://pkg.pr.new/@lexical/a11y@9510

@lexical/clipboard

npm i https://pkg.pr.new/@lexical/clipboard@9510

@lexical/code

npm i https://pkg.pr.new/@lexical/code@9510

@lexical/code-core

npm i https://pkg.pr.new/@lexical/code-core@9510

@lexical/code-prism

npm i https://pkg.pr.new/@lexical/code-prism@9510

@lexical/code-shiki

npm i https://pkg.pr.new/@lexical/code-shiki@9510

@lexical/compiler

npm i https://pkg.pr.new/@lexical/compiler@9510

@lexical/devtools-core

npm i https://pkg.pr.new/@lexical/devtools-core@9510

@lexical/dragon

npm i https://pkg.pr.new/@lexical/dragon@9510

@lexical/eslint-plugin

npm i https://pkg.pr.new/@lexical/eslint-plugin@9510

@lexical/extension

npm i https://pkg.pr.new/@lexical/extension@9510

@lexical/fast-check

npm i https://pkg.pr.new/@lexical/fast-check@9510

@lexical/file

npm i https://pkg.pr.new/@lexical/file@9510

@lexical/hashtag

npm i https://pkg.pr.new/@lexical/hashtag@9510

@lexical/headless

npm i https://pkg.pr.new/@lexical/headless@9510

@lexical/history

npm i https://pkg.pr.new/@lexical/history@9510

@lexical/html

npm i https://pkg.pr.new/@lexical/html@9510

@lexical/internal

npm i https://pkg.pr.new/@lexical/internal@9510

@lexical/link

npm i https://pkg.pr.new/@lexical/link@9510

@lexical/list

npm i https://pkg.pr.new/@lexical/list@9510

@lexical/mark

npm i https://pkg.pr.new/@lexical/mark@9510

@lexical/markdown

npm i https://pkg.pr.new/@lexical/markdown@9510

@lexical/mdast

npm i https://pkg.pr.new/@lexical/mdast@9510

@lexical/offset

npm i https://pkg.pr.new/@lexical/offset@9510

@lexical/overflow

npm i https://pkg.pr.new/@lexical/overflow@9510

@lexical/plain-text

npm i https://pkg.pr.new/@lexical/plain-text@9510

@lexical/react

npm i https://pkg.pr.new/@lexical/react@9510

@lexical/rich-text

npm i https://pkg.pr.new/@lexical/rich-text@9510

@lexical/selection

npm i https://pkg.pr.new/@lexical/selection@9510

@lexical/table

npm i https://pkg.pr.new/@lexical/table@9510

@lexical/tailwind

npm i https://pkg.pr.new/@lexical/tailwind@9510

@lexical/text

npm i https://pkg.pr.new/@lexical/text@9510

@lexical/utils

npm i https://pkg.pr.new/@lexical/utils@9510

@lexical/y

npm i https://pkg.pr.new/@lexical/y@9510

@lexical/yjs

npm i https://pkg.pr.new/@lexical/yjs@9510

commit: 459f552