Concurrent editing
What people see when they delete, undo, split, merge and move the same content at the same time.
Edytor merges concurrent edits without conflicts. Two people typing in different blocks, or in the same paragraph, both keep their text, and every replica ends with the same document.
When two people touch the same content, edytor follows one principle: keep what nobody removed, and never duplicate what both did. This page shows each rule users run into as an Alice and Bob table. “At the same time” means before either has seen the other’s edit, whether because of latency or because one of them was offline. Each table reads top to bottom; a row shows what each person does, then what they see.
Undo is your own
Undo and redo revert only your own edits.
| Alice | Bob | |
|---|---|---|
| 1 | Deletes the “Draft” block. | Types “!” in another block, “Notes”. |
| 2 | Undoes. “Draft” comes back. | “Notes!” keeps Bob’s edit. |
See History for undo steps in the editor.
Concurrent deletes and undo
Each person’s delete of a piece of text is recorded as theirs. A character is visible only while no one’s delete of it is in effect.
| Alice | Bob | |
|---|---|---|
| 1 | Deletes “ world” from “hello world”. | Deletes “ world” from “hello world”. |
| 2 | Undoes. The text stays deleted: Bob’s delete still holds. | |
| 3 | Undoes. “ world” comes back, once. |
Both see hello after step 2 and hello world after step 3, never hello world world.
Edge cases
- An undo shows the very text that was deleted, where it was, never a copy: a caret, a selection or a comment anchored in it is where it was.
- An undo made before a peer’s concurrent delete arrived shows the text until that delete arrives, then the text is hidden again: it is the peer’s delete too, and the peer’s undo brings it back.
- Text typed and deleted within one undo step leaves no trace; no undo can bring it back.
- An undo step that leaves your history (past its limit, or dropped by a new edit after an undo) makes its deletes permanent: the deleted text is removed from the document, and another person’s undo of the same delete brings nothing back.
- Deletes are kept for 30 days, then purged by the room (
purgeAfterDays): after that, an undo of the delete restores nothing, and nobody’s delete record is left to hold the text. A version of the document restores anything within those 30 days.
An explicit delete wins over concurrent typing
| Alice | Bob | |
|---|---|---|
| 1 | Deletes the “Draft” block. | Types “ v2” in “Draft”, without having seen the delete. |
| 2 | “Draft” is gone. | “Draft” is gone, with “ v2”; Bob’s caret moves to where the block was. |
This applies to text in the deleted block. A block Bob adds under it, or splits off inside it, is kept in its place (see Deleting a block keeps its children). It also applies to deletes only: undoing a block’s creation is not a delete (see Undoing a new block keeps a peer’s text).
Deleting a block keeps its children
Deleting a block removes only that block. A block selection holds exactly the blocks selected: clicking a block’s handle selects that block, not its children.
| Alice | Bob | |
|---|---|---|
| 1 | Selects the “Tasks” block by its handle and deletes it. | Types in “Buy milk”, a child of “Tasks”. |
| 2 | “Buy milk” and its sibling take the place of “Tasks”, with their own children. | Bob’s typing is kept in “Buy milk”. |
| 3 | Undoes: “Tasks” returns with both children nested under it. |
The same holds for whatever Bob puts under “Tasks” without having seen the delete: nothing that Alice did not delete is hidden with it.
| Bob, at the same time | Result after both sync |
|---|---|
| Presses Enter in the middle of “Buy milk”, which has children | Both halves of “Buy milk” take the place of “Tasks”, in order; the children stay under the second half, as the split put them. |
| Types in the second half after that Enter | The text is kept. |
| Adds a new child under “Tasks”, or moves a block into it | It takes the place of “Tasks” too, among the children, in the order Bob placed it. |
| Deletes “Buy milk” (keeping its children) | Both deletes hold; the children of “Buy milk” take the place of “Tasks”. |
Alice’s undo puts all of it back under “Tasks”.
To delete a whole subtree from code, pass keepChildren: false. Every block in the subtree is deleted; a block Bob adds inside it at the same time takes the subtree’s place:
edytor.document.deleteBlock('tasks', { keepChildren: false });
Undoing a new block keeps a peer’s text
Undoing the creation of a block (inserting it, pasting it, pressing Enter at the end of a line) removes your part only. The block stays while it holds someone else’s text or a child.
| Alice | Bob | |
|---|---|---|
| 1 | Presses Enter at the end of “Agenda”, creating an empty line. | |
| 2 | Types “Budget review” in the new line. | |
| 3 | Undoes. The line stays, with Bob’s “Budget review”. |
This holds even when Bob’s text arrives after Alice’s undo. If Bob later deletes his text, the empty line goes away; Alice’s redo brings her part back beside Bob’s.
| Alice | Bob | |
|---|---|---|
| 1 | Splits “hello world” after “hello”. | |
| 2 | Types “!” at the end of “ world”. | |
| 3 | Undoes. One line: “hello world!”. |
An emptied document shows a virtual paragraph
A document can end up with no blocks, for example when two people delete its last two blocks at the same time. Each view then shows one empty paragraph with the caret in it. Nothing is written for it.
| Alice | Bob | |
|---|---|---|
| 1 | Deletes block A (a block selection). | Deletes block B, the only other block. |
| 2 | Sees an empty paragraph; types “Hi”. | Sees an empty paragraph; types “Hello”. |
| 3 | Two lines: “Hi” and “Hello”. | The same two lines. |
The first edit in the virtual paragraph (typing, pasting, Enter, turning it into a heading) creates a real block in the same update. Nobody writes a placeholder block for having seen an empty document, so no empty paragraphs are duplicated. A read-only view shows the virtual paragraph but cannot create it. In a view, its handle is edytor.root.children[0] while the document is empty.
Deleting everything keeps the first block
Selecting all the text and deleting it keeps the first block, emptied, with its id, type and data: a heading stays a heading.
| Alice | Bob | |
|---|---|---|
| 1 | Selects all text and deletes. | Selects all text and deletes. |
| 2 | One empty block. | The same one empty block. |
Two people clearing the document converge on one block, not two. Typing that Bob did in the first block at the same time survives in it; typing in any other block goes with that block. Each person’s delete holds on its own: the first undo leaves the other’s delete in effect, the second brings the document back.
Moves, splits and merges keep identity
A block keeps its id and its CRDT identity when it is moved, nested, split or merged. Edits made concurrently to it land where the block, or its text, ends up.
| Alice | Bob | Both see | |
|---|---|---|---|
| Move | Moves “Notes” to the end. | Types “!” in “Notes”. | “Notes!” at the end. |
| Same block moved twice | Nests “Notes” under “Ideas”. | Moves “Notes” to the top. | One placement, chosen the same way on every replica. “Notes” is never duplicated. |
| Split | Splits “hello world” after “hello”. | Types “!” after “world”. | “hello” and “ world!“. |
| Merge | Joins “world” into the line above, “hello”. | Types “!” after “world”. | “helloworld!”. |
| Merge and split | Joins “world” into “hello” (Backspace at its start). | Splits “hello” after “he”. | “he” and “lloworld”: the joined text follows the piece that ends “hello”, as either order of the two gestures gives it. Bob splits at the end of “hello”: “hello” and “world”. |
| Same new block twice | Adds a block with the id summary (your app picks the id) and types “A”. |
Adds a block with the same id and types “B”. | One block summary, the one of the larger client id (its type, data and place), showing “A” then “B” (or “B” then “A”): the other’s text is not lost, and both can edit it there. Two different templates seeding one id keep one version instead (seeds). |
| Same split twice | Splits “hello world” after “hello”. | Splits it at the same place. | Both new lines exist; the text goes to one and the other stays empty. |
| Two splits | Splits “hello world” after “hello”, or pastes several lines of text there. | Splits it after “he”. | “he”, “llo” and “ world” (with the pasted lines after “hello”), in that order, whatever the client ids. The same when Alice first typed or deleted text before her split point, or typed or deleted after her own split point, before the sync. |
| Split and lift | Splits “hello world”, the paragraph above a list, after “hello”. | Lifts the list’s first item “a” out (Backspace at its start, or Turn into). | “hello”, “ world”, then “a”, whatever the client ids. |
| Two outdents | Outdents “x”, a nested line of “item” (Shift+Tab). | Outdents “y”, the nested line after it. | “x” before “y”, whatever the client ids. |
| New lines after one line | Presses Enter at the end of “x” and types three lines, “a1”, “a2”, “a3”. | Does the same: “b1”, “b2”, “b3”. | Each person’s lines together: “x”, “a1”, “a2”, “a3”, “b1”, “b2”, “b3”, or Bob’s lines first. Which person’s lines come first depends on the client ids; they never interleave. |
| Merge into a deleted line | Joins “item”, which has nested lines, into “hello” above (Backspace at its start). | Deletes “hello”. | “item” is back in its place, its former nested lines right after it, in order. |
mergeFrom into a deleted block |
Calls hello.mergeFrom(item): the nested lines of “item” become the last children of “hello”. |
Deletes “hello”. | “item” is back in its place, with its nested lines still under it. |
| A cycle | Moves “A” under “B”. | Moves “B” under “A”. | Resolved the same way on every replica: no block becomes unreachable. Moving a block into its own subtree is refused outright. |
Which races keep the text order
The rows above that say “whatever the client ids”, and the list races below, are part of a wider rule: when two people restructure the same place at the same time, both see the lines in the order one of the two gestures made first would give, whatever their client ids. It holds when each person makes one or several of these gestures between two syncs, and tests run each race on up to 240 pairs of client ids and check the order on every one:
- Enter inside a line, and a paste of several lines of text into a line, also when the person first typed or deleted text in that line, before or after the split point.
- A new block next to a line: Enter at the start or end of a line (at the end of a line with nested lines that is no toggle, callout or quote, it splits), Duplicate, a kind picked from the handle’s + button (the + alone adds nothing), a paste at the start of a line whose first pasted line is a list, a code block, a divider or an image, and Enter inside the first line of an open toggle, or of a callout or quote with nested lines (the text after the caret becomes a new first nested line).
- A paste of whole blocks copied with a block selection (or their drop), which lands after the caret’s line, and a paste or typing over selected blocks, which takes their place.
- Backspace at the start of a list’s first item or of a block with nested lines, Turn into on one list item, Turn into over several blocks at once, and Shift+Tab on one line, on adjacent lines, or on lines with an unselected one between them (one outdent per group of adjacent items).
- Tab on a line, against a new line added after the last nested line of the block it nests under.
- Several gestures by one person before a sync, where the tests run them: two Enters, or a new line or a duplicate and then Enter inside it, against a split or a lift next to them.
The lines one person adds one after another stay together: a line added right after a line the same person added extends that person’s run there, so nobody else’s line lands inside it. Two people adding lines at the same place each keep their own lines together, and whose come first depends on the client ids, as either order is one the two gestures can give (the New lines after one line row above).
Other moves (a drag, the block handle’s Alt+↑, Alt+↓ and Alt+→, Mod+Shift+↑/↓, the block menu’s Move up and Move down) against another person’s edit next to the moved block converge as well; the sweeps do not run them on every pair of client ids. (The handle’s Alt+← is the outdent, which keeps the order like Shift+Tab.)
Two races still order lines by client id. Both people see the same document and no text is lost:
| Case | Alice | Bob | What can happen |
|---|---|---|---|
| Two pastes into one gap | Pastes a list at the start of the line “body”, after “hello world”. | Pastes a list at the end of “hello world”. | Alice’s list can show before Bob’s, where either order of the two pastes puts Bob’s first. |
| One outdent call over lines that are not adjacent | Calls unNestBlocks(['a', 'c']) (on the document or the view) on the list items “a” to “e”, “b” not included. |
Outdents “d”. | “a” can stay before “b”, where the call alone puts “b” first. Shift+Tab and edytor.moveBlocks with direction: 'out' outdent one run of adjacent lines at a time, and keep the order. |
Splits and joins next to a moved block
A split or a join racing a move of the same block keeps every piece of text, but not always next to the block it came from.
| Alice | Bob | Both see | |
|---|---|---|---|
| Split, then a move | Presses Enter in a block, or pastes several lines into it. | Outdents or lifts that block, splits its list at a later item, presses Enter in its parent (which moves it under the new line), or outdents an earlier nested line of its parent (Shift+Tab, which takes it along as a nested line). | Alice’s new line stays where she made it, beside the block’s old place: it shows before or after the block’s text instead of right after it. |
A split and a join of the same line are the Merge and split row of Moves, splits and merges keep identity, and two splits of one block after a typed edit are under Which races keep the text order. Earlier releases put a joined line after the first piece of a split, and a client of one still shows it so until it upgrades: see the upgrade notes.
Conflicting type changes
When two people change the same block’s type at the same time, one change wins, chosen the same way on every replica. Undo never leaves a block without a type.
| Alice | Bob | |
|---|---|---|
| 1 | Turns the paragraph “Plan” into a heading. | Turns it into a quote. |
| 2 | Both see the same one: say Alice’s heading won. | |
| 3 | Undoes. “Plan” is a paragraph again, the type Alice replaced, for both. | |
| 4 | Redoes. “Plan” is a heading again. |
If Bob’s quote had won, Alice’s undo changes nothing: the quote stays. The same holds for block data (a to-do’s checked, a heading’s level) and for an inline atom’s data. lastChangedBy follows the same rule: it returns to the author before Alice.
Void blocks hold no children
Turning a block into a void kind (an image, a divider) moves its nested blocks out, right after it, in order: nothing renders a void block’s children. Undo puts them back under the block. The same holds for whatever Bob puts under the block without having seen the change.
| Alice | Bob | |
|---|---|---|
| 1 | Turns “Plan”, which has a child “Step 1”, into a divider. | Presses Enter in the middle of “Step 1”, and nests “Notes” under “Plan”. |
| 2 | After both sync: the divider, then “Step 1”, its second half, and “Notes”, in that order, for both. | |
| 3 | Undoes. “Plan” is a paragraph again, with the three blocks nested under it. |
The rule reads the kind’s role from the document’s semantics, so every replica needs the same roles: a document with no roles for a kind treats it as any other block and shows its children.
Island blocks
An island block (the code plugin’s code block, for example) seals its content: range deletions and merges never cross its boundary, and blocks cannot be moved into or out of it. See the document model.
Deleting or merging away an island turns its children into ordinary blocks: each takes the default child type of its new parent (a paragraph at the top level), or a paragraph where that type shows no text (a code block’s lines left directly in a columns layout show as paragraphs right after the layout, never as columns). A line Bob adds to the island without having seen the change does the same.
| Alice | Bob | |
|---|---|---|
| 1 | Deletes a code block with one line, “let a”. | Adds a line “let b” to the code block. |
| 2 | After both sync: “let a” and “let b” are paragraphs where the code block was, for both. | |
| 3 | Turns “let b” into a heading, moves it, or presses Enter or Tab in it. It stays a heading or a paragraph, never a code line outside a code block. | |
| 4 | Undoes back to the delete. The code block is back with both lines as code lines. |
A code line holds no nested blocks, and a code block holds only code lines: the code kind declares lines: true (block options). Other islands, such as a table of rows of cells, keep their nesting. When Alice’s undo brings a code block back while Bob has changed one of its former lines, both rules keep Bob’s work visible:
| Bob, after the delete and before Alice’s undo | After Alice’s undo |
|---|---|
| Nests the paragraph below under “let a” (Tab) | The paragraph shows right after the code block, where it can be edited and moved. |
| Turns “let a” into a heading | “let a” shows as a code line in the code block. If Alice redoes, it is a heading again. |
Edge cases
- If someone later deletes “let a”, the paragraph Bob nested under it stays right after the code block; it never moves into the code block as a code line.
- When Bob turns a code block into a paragraph while Alice adds a line to it, both lines show as paragraphs under it, whether or not another code block exists in the document.
- Only a code block’s lines change kind this way: a table turned into another kind keeps its rows as rows, and so does a row Alice adds meanwhile.
- Nothing merges into a code block from outside it:
mergeFromrefuses the merge andcanMergeanswersfalse. Its first line does not merge into it either, because a code block shows no text of its own.
Lists and other containers
A block that renders no content of its own (a list, a code block, a table row) never takes text by a merge: the first item of a list and the first cell of a table row never merge into their container, and a list or a row never merges as a whole.
| Gesture | What happens |
|---|---|
| Delete at the end of the block above a list | The first item’s text comes up; the rest of the list stays in place. |
Backspace (mergeBackward) at the start of a list’s first item |
The item moves out of the list as a paragraph, unless it stays inside an outer list of that kind: the first item of a nested list stays a list item of its parent item. |
| Backspace at the start of a table row’s first cell | The cell stays where it is. |
| A merge, delete, outdent or paste that would leave a paragraph in a list | The paragraph becomes a list item. A move of one into a list is refused, and Tab after a list nests under its last item. |
| The same for any other block (an image, a code block, a heading, a to-do) | A merge, delete or paste keeps its kind and data where it leaves it in a list; an outdent or move that would place one directly in a list is refused. |
| A list loses its last item | The list is removed. |
| A text selection that starts above a list is deleted | The list keeps its remaining items. |
| Shift+Tab on a middle item | The list splits around it: the list keeps the items after it. |
When two people edit one list at the same time:
| Alice | Bob | Both see | |
|---|---|---|---|
| The only item goes | Deletes, lifts or moves the list’s only item. | Adds an item to the list. | Bob’s item stays, shown as a paragraph where the list was. Alice’s undo puts it back in the list. |
| A split under a deleted item | Deletes an item. | Splits a paragraph under that item. | The new paragraph shows in the list, as an item. |
| An outdent and an append | Outdents a middle item (Shift+Tab). | Appends an item (Enter at the end of the last item). | Bob’s item stays at the end of the list that keeps the items after Alice’s. |
| An outdent and an insert before it | Outdents a middle item. | Adds an item among the items before it. | Bob’s item ends up after Alice’s. |
| One item each | Outdents, lifts (Backspace at the start of the first item) or turns into another kind one item. | Does the same to another item of the same list. | The text keeps its order whatever their client ids (which races keep it). A list left empty is removed by the next key next to it. |
| A middle item and the one above it | Outdents a middle item. | Lifts or outdents the item above it, or undoes a Turn into. | A paragraph never shows directly in a list: on every replica it shows as a list item, and it leaves the list as a paragraph like any other item. |
Edge cases
| Alice | Bob | What can happen | |
|---|---|---|---|
| Nested lists | In a list nested directly in a list, moves an item of the inner list into the outer one (Shift+Tab) or lifts it out of both lists. | Lifts a later item of the inner list out of both (Turn into a heading, a divider or a code block). | Alice’s item can end up after Bob’s. |
| A divider after an item | Inserts a divider or code block after an item (Turn into on an item with text). | Outdents, or turns into another kind, a later item of the same list, and his client id wins. | Alice’s divider or code block can show above her item; the text keeps its order. |
| A retype and an outdent | Outdents an item. | Turns the item above into a heading or a to-do (Turn into, the slash menu, # ). |
The heading may stay in the list Alice’s outdent splits off. It keeps its kind, data and place, as a heading a merge leaves in a list does. |
The editor, a headless document and the room’s transact apply the same rules.
Layouts
A columns layout is shown by its role, on every replica, whatever the race left in the stored tree: a layout shows only its columns (any other block stored in it shows right after it), an empty column does not show, a layout showing one column shows as that column’s blocks, and a column outside a layout shows as its blocks. The edits write the same result, so a replica that applied an edit and one that only saw a collaborator’s agree.
| Alice | Bob | |
|---|---|---|
| 1 | Deletes the only block of column 2 in a two-column layout. Column 2 goes, and the layout, left with one column, shows as column 1’s blocks. | Adds a line under that block, in column 2. |
| 2 | After both sync: column 1’s blocks where the layout was, then Bob’s line, for both. |
Edge cases
- Two people dragging blocks beside the same block at once each wrap it in a layout: the block ends in one of them, and the other, left with one column, shows as its blocks. Which one keeps the block is not claimed.
- A block a collaborator adds to a column another person deletes shows right after the layout; a column a collaborator adds to a layout another person deletes shows as its blocks, after the layout’s.
- A move racing a dissolve, or a merge across columns racing a new block in the emptied column, leaves no empty column and no one-column layout on screen.
- Two resizes at once keep each column’s latest weight: weights are per column, so the row stays filled.
- Undoing a new layout withdraws it, its columns too: a block a collaborator put in one of its columns meanwhile stays, in the layout’s place.
- No layout is shown inside a column by any gesture, but a race (Alice drags a layout into a toggle while Bob drags the toggle into a column) can put one there: it shows as it is.
The rules read the layout role from the document’s semantics, so every replica needs it: the columns plugin in every view, and defaultSemantics on a headless document, which holds it by default. The room holds it too.
Mixed versions
Clients must run compatible edytor versions. A client of another document generation is refused by the providers and the room. Older clients of the same generation ignore the per-person delete and undo records described above and fall back to plain undo; see Limitations.