[zurfyx]

Description

The docs give an agent two recipes that pull in opposite directions, and
neither covers the combination a server-side agent needs:

• extensions/block-ids.md "Addressing blocks" applies a model's edit with
  block.replace(node), while collaboration/y.md "Edits made by code" says
  a replaced block is a delete and an insert that loses what a collaborator
  types in it.
• collaboration/y-server.md tells an agent to run editYState on seen
  (the state it read) and merge. On seen every block the agent read still
  exists, so $getBlockById finds a block a collaborator deleted since, and
  the agent's text then survives the merge without its block, glued to a
  neighboring line. Nothing says so, and nothing says to check targets on
  the latest state.
• The server config example says to register "every node type the clients
  use", which reads as if BlockIdExtension (not a node type) may be left
  out; a server config without it writes new blocks without ids.

This adds an "Edits by block id" section to y-server.md: read blocks with
ids from seen, look the answer's ids up on the latest state and send the
gone ones back to the agent (best effort: a delete that reaches the stored
state after the check still lands), apply the rest on seen with
editYState, splicing only what changed (one splice for one contiguous
change; blocks the sketch does not handle are reported back too, not
skipped silently), and merge. "One edit at a time per document" now says
that an agent's planned edit is the exception to running on the latest
state. The config comment
now names BlockIdExtension as part of the clients' extensions, and
block-ids.md says that under @lexical/y a replaced block loses
concurrent typing, with a link to the new section.

Follow-ups

• 98f7fbc5: the sketches splice only plain text (a tab rejects spliceText; a hashtag or a code token would keep its type around new text), and ServerDocsAgentEdits.test.ts runs them over every kind of text node and block.
• 22234311 (review): the target check also sends back a block a collaborator moved or replaced since the read. A move and a replace keep the id, but @lexical/y stores either as a delete and an insert, so the found block was the deleted original and the agent's text was glued to the next line ("Move me now." for a block moved below "Last line." gave " nowLast line."). $placeOf compares where the target is (the path from the root, through the hosts of named slots, each node by its id or, without one, its type, and its slot name or index) and its text between seen and the latest state; a target that is gone or differs goes back (an id that exists only on the latest state too). The check is conservative and best effort, as the bullet says. collaboration/y.md no longer says that typing in a replaced block is lost, and the three pages say that typing at the end of a replaced line can also stay at the end.

Test plan

Before

A scratch script on the published 0823b74 build (seedYState with
RichTextExtension and BlockIdExtension; the agent reads three blocks; a
person deletes the second block and types " Jumps!" at the end of the first;
the agent's answer rewrites both; editYState on seen, merged into the
latest state), applying the answer the way the docs show today
($getBlockById on seen, whole-text replace):

unchecked [ 'The quick red fox.Rewritten. Jumps!', 'Last line.' ]

The rewrite of the deleted block is glued into the first paragraph, and
nothing reported it.

After

The same scenario with the new section's code:

agent reads [
  { id: 'yV2Q4QYdu_-lckETHqioD', text: 'The quick brown fox.' },
  { id: 'Xsr0UCPa1MszTSHCeLISW', text: 'Delete me.' },
  { id: 'eZKtmH7okgYtxEmeV-OPP', text: 'Last line.' }
]
gone [ true ]
final [
  [ 'yV2Q4QYdu_-lckETHqioD', 'The quick red fox. Jumps!' ],
  [ 'eZKtmH7okgYtxEmeV-OPP', 'Last line.' ]
]

The op on the deleted block is reported back, and the in-place rewrite of
the first block keeps the person's concurrent " Jumps!". With the follow-ups, ServerDocsAgentEdits.test.ts passes 7/7: steps 3 and 4 as written against a collaborator who leaves the target alone, moves it, replaces it, types in it or deletes it, a block added after the read, a target moved to the next table cell, one in a table that was moved and one moved to another named slot, and where concurrent typing lands when a line is replaced (12 rounds, both client-id orders). With step 3 as it was before the follow-up, the move case fails (moved: expected [] to deeply equal [ '<id>' ]). The section's code
block type-checks as written (tsc --strict, moduleResolution: bundler,
against the published typings).

$ pnpm run ci-check
Found 0 errors

Docs only; no browser checks apply.

[vercel]

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

Project	Deployment	Actions	Updated
lexical	Ready	Preview	Oct 30, 2026 2:36pm UTC
lexical-playground	Ready	Preview	Oct 30, 2026 2:36pm UTC

[pkg-pr-new]

lexical

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

@lexical/a11y

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

@lexical/clipboard

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

@lexical/code

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

@lexical/code-core

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

@lexical/code-prism

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

@lexical/code-shiki

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

@lexical/compiler

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

@lexical/devtools-core

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

@lexical/dragon

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

@lexical/eslint-plugin

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

@lexical/extension

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

@lexical/fast-check

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

@lexical/file

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

@lexical/hashtag

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

@lexical/headless

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

@lexical/history

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

@lexical/html

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

@lexical/internal

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

@lexical/link

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

@lexical/list

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

@lexical/mark

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

@lexical/markdown

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

@lexical/mdast

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

@lexical/offset

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

@lexical/overflow

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

@lexical/plain-text

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

@lexical/react

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

@lexical/rich-text

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

@lexical/selection

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

@lexical/table

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

@lexical/tailwind

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

@lexical/text

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

@lexical/utils

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

@lexical/y

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

@lexical/yjs

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

commit: 2223431

[meta-code-review]

Thanks for the update: the deleted-block case now behaves exactly as the test plan shows, the new replace wording matches what happens to a paragraph and to a table, and ServerDocsAgentEdits.test.ts keeps the two helpers identical to the page. One blocking point and a few smaller ones on the new text.

1. A block a collaborator moved or replaced still passes the check (packages/lexical-website/docs/collaboration/y-server.md L367-376; steps 3-4 at L448-473)

A move keeps the block's id (extensions/block-ids.md, “How ids follow edits”: drag and drop, insertAfter of an existing node), and so does replace, but @lexical/y stores a move as a delete and a re-insert (collaboration/y.md, Limits, Moves). So $getBlockById(op.id) finds the id on latest, nothing goes to gone, and the splice applied on seen edits the deleted original. With the section's code: seed “First line.” / “Move me.” / “Last line.”, move the second block below the third in latest, and answer {id: <its id>, text: 'Move me now.'}. Whatever the client ids, gone is empty, the moved block still reads “Move me.”, and “ now” is glued to the start of the next line (“ nowLast line.”). A collaborator's replace of the target with “A slow brown dog.” gives “redA slow brown dog.” for the answer “The quick red fox.”. That is the outcome the bullet says the check prevents, while the caveat at L374-376 names only a delete that arrives after the check. Suggest naming moves and rewrites in the caveat, and catching moves, for example by also sending back a target whose parent or previous sibling differs between seen and latest (conservative: an insert or delete next to the target sends it back too).

2. collaboration/y.md still says the opposite of the new wording (packages/lexical-website/docs/collaboration/y.md L655-658)

“A replaced block is a delete and an insert, so what collaborators type into it at the same time is lost” contradicts the corrected sentences at y-server.md L318-322 and L379-383 and extensions/block-ids.md L110-115, and y-server.md L313-314 tells readers to follow that bullet. The new wording is the accurate one; giving y.md the same sentences would make the three pages agree.

3. Nit: typing at the end of a replaced line can stay after the new text (y-server.md L319 and L380, extensions/block-ids.md L112)

Replacing a paragraph while a collaborator types “ Jumps!” at its end gives “The quick red fox. Jumps!” or “ Jumps!The quick red fox.” depending on the client ids; typed at the start or in the middle, it does land before the new text. Something like “lands at the start of the new text (typed at its end, it can also stay at the end)” would match.

4. Nit: an op whose id exists only on latest is dropped silently (y-server.md L463-469)

For an id that appeared after the read, live.has(op.id) is true but $getBlockById(op.id) is null on seen, and else if (block !== null) skips it, so it is in neither gone nor unsupported. else if (live.has(op.id)) would report it, as the description intends.

5. Nit: the guard comment (y-server.md L347-348 and L424-426, repeated in the test)

It says a hashtag or a code token “does not take any text”, but only a tab rejects spliceText; a hashtag or a code token accepts the splice and keeps its type around the new text (#oldtag becomes a hashtag reading Hiag), which is the better reason to skip them.

Checked and fine: the new links and anchors resolve in the website build, and the code block type-checks once seen, latest, ops, config and agent are declared.

[meta-code-review]

A block a collaborator moved keeps its id (extensions/block-ids.md, “How ids follow edits”), and @lexical/y stores the move as a delete and a re-insert (collaboration/y.md, Limits, Moves), so the check finds the id on latest and the splice on seen edits the deleted original: moving “Move me.” below “Last line.” and answering “Move me now.” leaves “ nowLast line.” with nothing sent back. A collaborator's replace, which keeps the id, does the same (“redA slow brown dog.”). Could the caveat name moves and rewrites, and the check also send back a target whose parent or previous sibling differs between seen and latest?

[zurfyx]

Fixed in 2223431: step 3 now compares where each target is ($placeOf: the path from the root, through the hosts of named slots, each node by its id or, without one, its type, and its slot name or index) and its text between seen and the latest state, and sends back the targets that are gone or differ, so a moved or replaced block goes back to the agent. The caveat names what still lands (a change after the check, a block replaced by one with the same text) and that the check is conservative. ServerDocsAgentEdits.test.ts covers move, replace, typing, delete, a block added after the read, a move to the next table cell, a move of the table, and a move to another named slot.

[meta-code-review]

collaboration/y.md L655-658, which L313-314 tells readers to follow, still says what collaborators type into a replaced block “is lost”. This wording is the accurate one; giving y.md the same sentences would make the pages agree.

[zurfyx]

Fixed in 2223431: collaboration/y.md now says the same as this page and extensions/block-ids.md (in a line, concurrent typing survives at the start of the new text; a block stored as a node of its own loses it).

[meta-code-review]

Nit: typed at the end of the replaced line, the collaborator's text can also stay after the new text (“The quick red fox. Jumps!”), depending on the client ids; typed at the start or in the middle, it lands before. The same sentence is at L319 and in extensions/block-ids.md L112.

[zurfyx]

Fixed in 2223431 on all three pages: "at the start of the new text (typed at the end of the line, it can also stay at the end)". Verified over 12 rounds of fresh writers (both client-id orders): typed at the start or in the middle it always lands before the new text; typed at the end, either way.

[meta-code-review]

Nit: an op whose id is live on latest but absent from seen (a block added after the read) gets block === null here and lands in neither gone nor unsupported. else if (live.has(op.id)) would report it.

[zurfyx]

Fixed in 2223431: an id that exists only on the latest state has no place on seen, so the new check sends it back with the other changed targets.

[meta-code-review]

Thanks, this looks good. Moved, replaced, typed-in and deleted targets now go back to the agent, ServerDocsAgentEdits.test.ts keeps the page's helpers in sync with the tests, and collaboration/y.md, collaboration/y-server.md and extensions/block-ids.md now describe a replaced block the same way. Everything below is optional and non-blocking.

1. A move that ends where it started still passes step 3 (packages/lexical-website/docs/collaboration/y-server.md L382-387, the $placeOf comment at L459-461, steps 3-4 at L490-521)

$placeOf compares the target's path and text, so a block that a collaborator moves down and back up, or moves below its neighbour while a block before it is deleted, gives the same string on seen and latest. @lexical/y has still written the move as a delete and a re-insert (collaboration/y.md, Limits, “Moves”), so the splice made on seen lands in the deleted copy. With the section's code, starting from “First line.” / “Move me.” / “Last line.” and the answer “Move me now.” for “Move me.”, the merged document reads “ nowMove me.” (moved down and back) or “ nowLast line.” (moved below “Last line.” while “First line.” is deleted), and gone stays empty.

Step 3 already requires every live target's text on latest to equal what the agent read, so step 4 could run on latest instead of seen: nothing typed in a target since the read is overwritten, the splice always reaches the live block, and these cases (and the same-text replace the caveat names) then give “Move me now.”. The parenthetical in “One edit at a time per document” would change with it. If you prefer to keep seen, naming this case in the caveat, and in the $placeOf comment, which says a move “changes the path”, would make both accurate; a case in ServerDocsAgentEdits.test.ts would pin either choice.

2. Nit: how the place is compared (y-server.md L378-380)

“each node on it by its id or, without one, by its type and place in its parent” reads as if the place counts only for nodes without an id, while $placeOf records every node's place (L473-476), which is what catches a plain move. “each node on it by its id (or, without one, its type) and its place in its parent” would match the code.

3. Nit: the test plan's After output

It comes from the first commit's existence-only check. On the current head the same scenario sends back both ops, since the first block was typed in, and leaves “The quick brown fox. Jumps!” / “Last line.”. AGENTS.md (Commits and Pull Requests) asks the Test plan to carry the real output of what was run, so the 7/7 run of ServerDocsAgentEdits.test.ts, or the script re-run on this head, would fit there.

Website and test changes need no changeset (AGENTS.md, Changesets; CONTRIBUTING.md, Changesets).

[meta-code-review]

Optional: a move that ends where it started still passes this check. A block that a collaborator moves down and back up, or moves below its neighbour while a block before it is deleted, gives the same $placeOf string on seen and latest, but @lexical/y wrote the move as a delete and a re-insert, so the splice on seen lands in the deleted copy: answering “Move me now.” for “Move me.” leaves “ nowMove me.” or “ nowLast line.”, and gone stays empty. Since step 3 already requires each live target's text on latest to equal what the agent read, running step 4 on latest gives “Move me now.” in these cases (and in the same-text replace named here); otherwise this list and the $placeOf comment (“changes the path”) could name the case.

[meta-code-review]

Nit: this reads as if a node's place counts only when it has no id, but $placeOf records every node's place (L473-476), which is what catches a plain move. “each node on it by its id (or, without one, its type) and its place in its parent” would match the code.