diff --git a/openspec/changes/add-data-node-operations/design.md b/openspec/changes/add-data-node-operations/design.md new file mode 100644 index 00000000..a2e829fd --- /dev/null +++ b/openspec/changes/add-data-node-operations/design.md @@ -0,0 +1,120 @@ +## Context + +The v3 List tool keeps its items in one flat array inside a single block: + +```ts +{ style, start?, counterType?, items: [{ content: Text, depth: number, checked?: boolean }] } +``` + +Every List interaction becomes one of three model calls on that array: `createDataNode('items.N', …)`, `removeDataNode('items.N')`, or `updateValue('items.N.depth' | 'items.N.checked', …)`. The model already supports them. `BlockNode.createDataNode` splices when the parent is an array, `removeDataNode` splices it out, and `ValueNode.update` emits `ValueModifiedEvent` with `{ value, previous }`. What is missing is everything downstream of the event: attribution, operations, transforms and replay. + +Two undo managers consume model events. `core`'s `UndoRedoManager` records raw event payloads and replays their inverse through `EditorJSModel.insertData` / `removeData` / `modifyData`. `collaboration-manager`'s records `Operation`s and cancels core's with `preventDefault()`. Both replay through the same three model methods, and so does `ot-server`'s `DocumentManager`. Fixing those methods once fixes undo in all three places. + +## Goals / Non-Goals + +**Goals** +- Data-node insert/delete and value modify on any block reach peers, are applied by `ot-server`, and can be undone and redone locally. +- Concurrent structural edits in the same array converge, including text edits inside a shifted element. + +**Non-Goals** +- Re-keying model listeners or `InputsRegistry` after an array splice (a separate change, see proposal). +- Grouping several operations into one undo step in collaboration mode. +- Fixing the client/server protocol (revision stamping, in-flight rebasing, explicit transform order). That is `fix-ot-client-convergence`, which this change depends on. + +## Decisions + +### D1. Initialization events are marked, not removed + +`BlockNode#initialize` calls `createDataNode` once per top-level key. The resulting `DataNodeAddedEvent`s are the only signal `BlockToolAdapter` gets to dispatch `KeyAddedEvent`, which tools such as Paragraph use to create their inputs data-first. They must keep flowing. But they duplicate the `BlockAddedEvent` that precedes them. Turning them into operations would make every block insert also send N data-node inserts, and redo would throw `AlreadyExistingKeyError`. + +`DataNodeAddedEvent` therefore gets a boolean marker, `detail.isInitialization`. `BlockNode` sets it for events dispatched from `#initialize`. `CollaborationManager` and core's `UndoRedoManager` skip marked events entirely: no operation, no undo entry and no transform of the undo stacks. `BlockToolAdapter` does not look at the marker. + +The marker is lost today when the event bubbles, because `EditorDocument#listenAndBubbleBlockEvent` and `EditorJSModel#listenAndBubbleDocumentEvents` re-create events as `new ctor(index, data, userId)`. Both re-creation sites forward it. + +*Alternatives*: a separate `DataNodeInitializedEvent` class would make every adapter-side consumer map two classes to `KeyAdded`. Keeping the no-`userId` quirk would leave it impossible to tell an initialization event from a genuine one, and D2 removes the quirk anyway. + +### D2. Explicit `createDataNode` dispatches synchronously + +The microtask in `createDataNode` exists only to order initialization events after `BlockAddedEvent`. It is kept for `#initialize` only. A call on an already constructed block dispatches synchronously, so `EditorJSModel` reads the `userId` from the live `WithContext` frame, as it does for every other event. + +### D3. Operation shapes + +| Model event | Operation | `index` | `data` | +|---|---|---|---| +| `DataNodeAddedEvent` (not initialization) | `Insert` | `DataIndex` | `{ payload: [subtree] }` | +| `DataNodeRemovedEvent` | `Delete` | `DataIndex` | `{ payload: [subtree] }` | +| `ValueModifiedEvent` | `Modify` | `DataIndex` | `{ payload: value, prevPayload: previous }` | + +`subtree` is the event's `BlockNodeDataSerializedValue`. Wrapping it in a one-element array keeps `InsertOrDeleteOperationData.payload` `ArrayLike`, matching block operations (`[BlockNodeSerialized]`). It also means the text transformer's `payload.length` reads never see an arbitrary object. `ModifyOperationData.payload` / `prevPayload` widen from `Record` to any JSON value (`depth: 2`, `checked: false`), the same widening #192 makes for plugin data. + +The model's `insertData` / `removeData` take the raw subtree for a `DataIndex`. A single exported helper, `toModelData(operation)`, unwraps `[subtree]` for a `DataIndex` Insert/Delete and returns `payload` unchanged otherwise. `CollaborationManager.applyOperation` and `ot-server`'s `DocumentManager#applyOperationToModel` both call it, so there is one source of truth for the shape. + +`BatchedOperation.canAdd` already returns `false` for non-text indexes, so each data operation is its own undo step. + +### D4. Model replay semantics for `DataIndex` + +- `modifyData(DataIndex, { value })` calls `updateValue(blockIndex, dataKey, value)`. It creates the node if it is absent, as `updateValue` already does. +- `insertData(DataIndex, subtree)`: + - when the parent is an array, it splices, as `createDataNode` does now; + - when the key does not exist, it creates the node; + - when the key already exists outside an array, it removes the existing node and then creates the new one. This emits `DataNodeRemoved` and then `DataNodeAdded`. + + The direct `createDataNode` API keeps throwing `AlreadyExistingKeyError`. Only the replay path replaces. +- `removeData(DataIndex)` is unchanged (`removeDataNode`). + +Replacing on insert is what lets two concurrent creations of the same object key converge (D6). Without it, `ot-server` throws on the second one. + +### D5. Array positions in the transformer + +The transformer has no model, so it reads array positions from the key: **a path segment that is a non-negative integer addresses an array element.** This matches `keypath.insert` / `remove` and `renumberKeys`, which already treat numeric segments as array indices. Object keys made only of digits are not supported for array semantics. A tool must not use them, and the spec says so. + +For an operation `against` at `P.i` (prefix `P`, last segment the integer `i`) and an operation `op` whose key (`DataIndex.dataKey` or `TextIndex.dataKey`) is `P.j` or `P.j.rest`, in the same block: + +| `against` | `op` relation | Result | +|---|---|---| +| Insert at `P.i` | `j > i` | `j → j+1` | +| Insert at `P.i` | `j == i`, `op` key is deeper (`P.i.rest`) | `j → j+1` (the element moved) | +| Insert at `P.i` | `j == i`, `op` is an Insert at exactly `P.i` | tie-break (below) | +| Insert at `P.i` | `j == i`, `op` is a Delete at exactly `P.i` | `j → j+1` | +| Delete at `P.i` | `j > i` | `j → j−1` | +| Delete at `P.i` | `j == i`, `op` is an Insert at exactly `P.i` | unchanged | +| Delete at `P.i` | `j == i`, anything else (same element or inside it) | `Neutral` | +| any | `j < i`, or `op` key outside `P` | unchanged | + +For an operation `against` that deletes a key `K` whose last segment is **not** an integer (an object member), any `op` at `K` or under `K.` becomes `Neutral`, except an Insert at exactly `K`, which re-creates it and is unchanged. + +Prefixes nest: `P` itself may contain array segments (`rows.2.cells.0`). Only the segment at depth `|P|` is compared and rewritten. A text operation keeps its `textRange` and only its `dataKey` is rewritten (a `TextIndex` with the new key). + +**Tie-break for two Inserts at the same array position.** This uses the explicit order argument from `fix-ot-client-convergence`, `op.transform(against, againstIsLater)`. `op` shifts to `i+1` iff `against` comes earlier (`againstIsLater` is false). Revisions are not consulted: remote operations reach the undo stacks rebuilt from model events, without one. All three paths give the same order: + +- *Server.* Incoming `A` is reduced through history op `B` (default order), so `A` shifts. `B` stays at `i` and `A` goes to `i+1`. +- *Author of `A`.* `OTClient` transforms incoming `B` against its unacknowledged `A` with `againstIsLater: true`, so `B` stays at `i`. The local `A` moves to `i+1` because the model splices, and the client rebases `A` against `B` with the default order. The result is the same order. +- *Undo stacks and the open batch.* An entry transformed against a remote insert at the same position (default order) shifts, which is correct: the remote element now sits in front of it. + +### D6. Same-key conflicts that do not shift + +- **Modify vs. Modify, same block and key.** Last-writer-wins in server order: `op` becomes `Neutral` iff `against` comes later (`againstIsLater`). Otherwise `op` is kept and applied after `against`. This is the rule `fix-ot-client-convergence` sets for values. +- **Insert vs. Insert on the same object key** (last segment not an integer). The same rule as Modify. With replace-on-insert (D4), the later write in server order wins on the server and on every client, exactly as for values. +- **Modify vs. Insert / Delete** follows D5. A Modify under a deleted element or member becomes `Neutral`. A Modify inside a shifted element is re-keyed. + +Every new rule is added to the existing `#transformAgainstDataOperation` branch, which `#applyTransformation` already dispatches to for any `DataIndex` `againstOp`. Text operations stop being returned unchanged there. Data operations transformed against *text* operations, and anything transformed against *block* operations, keep their current rules: `DataIndex` already has `withBlockIndex`. + +### D7. Undo/redo + +`Operation.inverse()` already swaps Insert ↔ Delete with the same payload and swaps `payload` / `prevPayload` for Modify. With D3 and D4 in place, collaboration undo of a data operation works without new code. Core's `UndoRedoManager` replays `event.data` for Added/Removed (the raw subtree, which matches the model) and inverts Modified, so it works once D1 (skip the marker), D2 (attribution) and D4 (`modifyData`) are in place. + +## Risks / Trade-offs + +- **Stale delete payloads.** A Delete carries a snapshot of the removed subtree. If a peer edits inside the element concurrently, the server still deletes the right element, but undoing the delete restores the snapshot without the peer's edit. Block deletes behave the same way today. This is accepted and documented. +- **Undoing a Modify overwrites a newer remote value.** Undo stack entries are transformed with the default order, so a remote Modify on the same key does not neutralize them. Undo then restores the local `prevPayload` over the peer's value. This is current behavior for data operations and is unchanged. +- **Dependency on `fix-ot-client-convergence`.** Until it lands, the server never transforms client operations and the client skips its in-flight operation, so concurrent array edits diverge exactly as concurrent text edits do today. The rules here are correct only on top of that fix. +- **The numeric-segment convention** rules out digit-only object keys for array semantics. It is cheap to state, and no current tool uses such keys. +- **Wire compatibility.** An older `ot-server` silently ignores `DataIndex` Insert/Delete (no model support) and drops `Modify`. Clients and server deploy together, which is already the rule for this monorepo. + +## Migration Plan + +No data migration. Ship `model-types`, `model`, `collaboration-manager`, `core` and `ot-server` together. + +## Open Questions + +None blocking. The array re-keying change must land before the List tool enables structural editing in collaboration mode. diff --git a/openspec/changes/add-data-node-operations/proposal.md b/openspec/changes/add-data-node-operations/proposal.md new file mode 100644 index 00000000..8c657ffd --- /dev/null +++ b/openspec/changes/add-data-node-operations/proposal.md @@ -0,0 +1,46 @@ +## Why + +Changes to a block's data tree other than text are local-only today. A data node created or removed (`DataNodeAddedEvent` / `DataNodeRemovedEvent`) or a value updated (`ValueModifiedEvent`) is never sent to collaborators and cannot be undone: + +- `CollaborationManager#handleEvent` only maps text and block events to `Operation`s. The three data events fall through to `console.error('Unknown event type')`. +- `EditorDocument.modifyData` handles only `TextIndex` (`@todo implement other actions`). So a `Modify` on a `DataIndex` does nothing, whether it comes from undo, a remote peer or `ot-server`. This is true for the core `UndoRedoManager` as well as the collaboration one. +- A locally created data node reports no `userId`. `BlockNode.createDataNode` dispatches `DataNodeAddedEvent` in a microtask, `EditorDocument` drops `detail.userId` when it bubbles the event, and `EditorJSModel` re-reads an execution context that has already been popped. Even if the event were mapped, it would be treated as remote and never sent. +- `OperationsTransformer` handles `DataIndex` with last-writer-wins on the exact same key only. Nothing shifts positions in an array, so concurrent inserts and deletes in the same array (or text edits inside a shifted element, e.g. `items.3.content` after an insert at `items.1`) land on the wrong element. + +The v3 List tool depends on all four. It stores items as one flat array, `items: [{ content, depth, checked? }]`. Tab/Shift+Tab is `updateValue('items.N.depth')`, Enter inserts an array element, a Backspace merge removes one, and a checkbox toggle is `updateValue('items.N.checked')`. Each of these must sync to peers and be undoable. + +## What Changes + +- **Model events carry their author.** `createDataNode` called on an existing block dispatches `DataNodeAddedEvent` synchronously with the context `userId`. `DataNodeAddedEvent`s dispatched while a `BlockNode` is being constructed are marked as initialization events. They still reach adapters, which is how tools render their inputs data-first, but they never become operations or undo steps, because `BlockAddedEvent` already carries the whole block. +- **The model applies data operations by index.** `modifyData` applies a `DataIndex` change through `updateValue`. `insertData` on a `DataIndex` whose key already exists (outside an array) replaces the node instead of throwing, so concurrent creations of the same key converge on last-writer-wins. +- **New operation kinds in `collaboration-manager`.** `DataNodeAdded` becomes an `Insert` and `DataNodeRemoved` a `Delete` on a `DataIndex`, with a one-element `payload: [subtree]`. `ValueModified` becomes a `Modify` with `payload` / `prevPayload`. `ModifyOperationData.payload` widens to any JSON value, the same widening as #192. The client and `ot-server` share one helper that turns an operation into model-shaped data. +- **Transformer rules for array positions.** Inserts and deletes of array elements shift the positions of other operations in the same array: data operations and text operations whose `dataKey` passes through that array. Operations inside a deleted element or a deleted subtree become `Neutral`. Two inserts at the same position break the tie with the explicit transform order from `fix-ot-client-convergence`, so the server and every client order them the same way. Value vs. value on the same key keeps last-writer-wins under that same order. +- **Undo/redo of data changes works** in both the core and collaboration undo managers. No new mechanism is needed: the existing inversion works once the model applies the inverted change. + +## Capabilities + +### New Capabilities + +None. + +### Modified Capabilities + +- `collaboration-manager`: data-node and value events become operations; new transformation rules for array positions and subtree deletion; undo/redo of data operations. +- `model`: `modifyData` / `insertData` semantics for `DataIndex`; synchronous, attributed `DataNodeAddedEvent` outside construction. +- `model-types`: `DataNodeAddedEvent` gains the initialization marker, and bubbling keeps it. +- `core`: the local `UndoRedoManager` records data-node and value changes and skips initialization events. +- `ot-server`: `DocumentManager` applies data-node and value operations to its model. + +## Out of scope / dependencies + +- **Array element re-keying in the model and the DOM (separate change, hard prerequisite for List).** `BlockNode` node listeners capture their key at creation (`#listenAndBubbleTextNodeEvent` / `#listenAndBubbleValueNodeEvent`), and `InputsRegistry` in `dom-adapters` is not re-keyed. After an insert at `items.1`, the node now at `items.2` keeps reporting `items.1`, so local edits there produce wrongly addressed operations. This change only makes *operations in flight* account for shifts. The tests here apply operations and never edit a node whose position has moved. +- **Undo grouping in collaboration mode.** Data operations are never batched in `BatchedOperation`, so List Enter (text delete + item insert) is two undo steps when collaboration is enabled. Core's grouping by browser task (#201 / #203) does not cover `CollaborationManager`. #201 already lists this as a follow-up. +- **Interaction with #201 / #203.** #201's design (R2) relies on construction-time `DataNodeAddedEvent`s having no `userId`. This change replaces that accident with an explicit marker. Whichever lands second updates the R2 test to assert on the marker. +- **Depends on `fix-ot-client-convergence`.** That change makes the server actually transform client operations, makes the client transform against its in-flight operation and rebase its queue, and adds `transform(against, againstIsLater)`. The tie-break and same-key rules here are written in terms of that order argument, and convergence for array edits holds only once it has landed. +- **Interaction with #192.** #192 widens `ModifyOperationData` in the same way. Whichever lands second drops its duplicate. + +## Impact + +- **Code**: `packages/model-types/src/events/DataNodeAddedEvent.ts`; `packages/model/src/entities/BlockNode/index.ts`, `EditorDocument/index.ts`, `EditorJSModel.ts`; `packages/collaboration-manager/src/{CollaborationManager,Operation,OperationsTransformer}.ts`; `packages/core/src/components/UndoRedoManager.ts`; `packages/ot-server/src/DocumentManager.ts`. +- **Wire format**: additive. `Insert` / `Delete` / `Modify` on `k: "data"` indexes, which already serialize. Clients and `ot-server` must deploy together, because an older server drops these operations. +- **Docs**: `docs/collaboration.md` (operation kinds and the transform rules table), `docs/events.md` (`DataNodeAddedEvent` marker and synchronous dispatch). The "Step 1: transform each pending local op against the incoming remote op" in `docs/collaboration.md` does not match `OTClient`, which only transforms the incoming op against pending ones. This change does not alter that and notes it in design.md. diff --git a/openspec/changes/add-data-node-operations/specs/collaboration-manager/spec.md b/openspec/changes/add-data-node-operations/specs/collaboration-manager/spec.md new file mode 100644 index 00000000..87e3b1f1 --- /dev/null +++ b/openspec/changes/add-data-node-operations/specs/collaboration-manager/spec.md @@ -0,0 +1,87 @@ +## ADDED Requirements + +### Requirement: Data node and value operations +The system SHALL convert a `DataNodeAddedEvent` that is not an initialization event into an `Insert` operation, a `DataNodeRemovedEvent` into a `Delete` operation, and a `ValueModifiedEvent` into a `Modify` operation, each addressed by the event's `DataIndex`. Insert and Delete SHALL carry the removed or added subtree as a one-element `payload` array. Modify SHALL carry the new value as `payload` and the previous value as `prevPayload`, where either may be any JSON value. The system SHALL ignore `DataNodeAddedEvent`s marked as initialization events: it creates no operation, records nothing for undo, and does not transform the undo/redo stacks against them. `applyOperation` and `ot-server` SHALL convert an operation to model data through one shared helper that unwraps the one-element payload of a `DataIndex` Insert/Delete. + +#### Scenario: Local value change is sent and recorded +- **GIVEN** the local user calls `updateValue` for key `items.1.checked` on block 0, changing `false` to `true` +- **WHEN** `CollaborationManager` handles the resulting `ValueModifiedEvent` +- **THEN** it sends a `Modify` operation on `DataIndex(0, 'items.1.checked')` with `payload: true` and `prevPayload: false`, and records it as an undo step + +#### Scenario: Local array element insert is sent +- **GIVEN** the local user creates a data node at `items.1` of block 0, whose `items` is an array +- **WHEN** `CollaborationManager` handles the resulting `DataNodeAddedEvent` +- **THEN** it sends an `Insert` operation on `DataIndex(0, 'items.1')` whose `payload` is a one-element array holding the serialized element + +#### Scenario: Initialization events produce no operation +- **GIVEN** a block is added, locally or by a remote operation +- **WHEN** the `DataNodeAddedEvent`s dispatched during its construction reach `CollaborationManager` +- **THEN** no operation is sent, nothing is added to the undo stack, and the undo/redo stacks are not transformed + +#### Scenario: Remote data operations are applied +- **GIVEN** a remote `Insert`, `Delete` or `Modify` operation on a `DataIndex` +- **WHEN** `applyOperation` is called with it +- **THEN** the model contains, or no longer contains, the subtree or value at that key, exactly as on the author's client + +### Requirement: Array position transformation +The system SHALL treat a data-key segment that is a non-negative integer as an array position. When an operation is transformed against an Insert or Delete on a `DataIndex` at `P.i` in the same block, the system SHALL rewrite the position segment of any data or text operation whose key is `P.j` or lies under `P.j`: +- an Insert at `P.i` shifts `j ≥ i` to `j+1`; +- a Delete at `P.i` shifts `j > i` to `j−1`, and turns operations at or under `P.i` into `Neutral`, except an Insert at exactly `P.i`, which stays unchanged. + +For two Inserts at exactly the same position, the operation being transformed SHALL shift iff the other operation comes earlier in the transform order (`againstIsLater` is false). A Delete of a key whose last segment is not an integer SHALL turn every operation at or under that key into `Neutral`, except an Insert at exactly that key. + +#### Scenario: Text edit inside a shifted element +- **GIVEN** a text insert on `TextIndex` with `dataKey: 'items.3.content'` in block 0 +- **WHEN** it is transformed against an Insert on `DataIndex(0, 'items.1')` +- **THEN** its `dataKey` becomes `items.4.content`, and its block index, text range and payload are unchanged + +#### Scenario: Value change before the deleted element is not affected +- **GIVEN** a `Modify` on `DataIndex(0, 'items.0.depth')` +- **WHEN** it is transformed against a Delete on `DataIndex(0, 'items.2')` +- **THEN** it is returned unchanged + +#### Scenario: Value change inside a deleted element +- **GIVEN** a `Modify` on `DataIndex(0, 'items.2.checked')` +- **WHEN** it is transformed against a Delete on `DataIndex(0, 'items.2')` +- **THEN** it becomes `Neutral` + +#### Scenario: Deleting the same element twice +- **GIVEN** two concurrent Deletes on `DataIndex(0, 'items.2')` +- **WHEN** the second one is transformed against the first +- **THEN** it becomes `Neutral` + +#### Scenario: Concurrent inserts at the same position converge +- **GIVEN** clients X and Y both insert an element at `items.1` of block 0 at the same revision, and the server processes Y's operation first +- **WHEN** the server transforms X's operation against Y's, and client X transforms Y's broadcast operation against its pending operation +- **THEN** the server and both clients hold Y's element at `items.1` and X's element at `items.2` + +#### Scenario: Operations in another array or block are not shifted +- **GIVEN** an operation on key `rows.3` in block 0, or on `items.3` in block 1 +- **WHEN** it is transformed against an Insert on `DataIndex(0, 'items.1')` +- **THEN** it is returned unchanged + +### Requirement: Same-key data write conflicts +The system SHALL resolve two `Modify` operations on the same block and data key, and two `Insert` operations on the same block and a data key whose last segment is not an integer, by transform order. The operation being transformed SHALL become `Neutral` iff the other operation comes later (`againstIsLater` is true). Otherwise it SHALL be returned unchanged, to be applied after the other one. + +#### Scenario: Concurrent value changes converge on the later write +- **GIVEN** clients X and Y both modify `items.0.depth` of block 0 at the same revision, and the server processes Y's operation first +- **WHEN** the server transforms X's operation against Y's, and client X transforms Y's broadcast operation against its pending operation +- **THEN** the server and both clients end with X's value + +### Requirement: Undo and redo of data operations +The system SHALL undo a recorded data-node Insert by deleting that node, a data-node Delete by re-inserting the recorded subtree at its key, and a value Modify by restoring `prevPayload`. Redo SHALL re-apply the original. Each data operation SHALL be its own undo step, and the undo/redo stacks SHALL be transformed against remote data operations under the same rules as any other remote operation. + +#### Scenario: Undoing an item indent +- **GIVEN** the local user changed `items.1.depth` from `0` to `1` +- **WHEN** `undo()` is called +- **THEN** `items.1.depth` is `0` again and the inverse `Modify` is sent to the server, and a following `redo()` sets it back to `1` + +#### Scenario: Undoing an item removal +- **GIVEN** the local user removed the data node at `items.2` +- **WHEN** `undo()` is called +- **THEN** the removed element, including its text content, is inserted back at `items.2` and later elements shift back by one + +#### Scenario: Undo stack follows a remote insert +- **GIVEN** the undo stack holds a local `Modify` on `items.2.checked` +- **WHEN** a remote Insert on `items.0` of the same block arrives and `undo()` is called +- **THEN** the undo restores `prevPayload` on `items.3.checked` diff --git a/openspec/changes/add-data-node-operations/specs/core/spec.md b/openspec/changes/add-data-node-operations/specs/core/spec.md new file mode 100644 index 00000000..15bb49d7 --- /dev/null +++ b/openspec/changes/add-data-node-operations/specs/core/spec.md @@ -0,0 +1,14 @@ +## ADDED Requirements + +### Requirement: Local undo of data node and value changes +The system SHALL record local `DataNodeAddedEvent`, `DataNodeRemovedEvent` and `ValueModifiedEvent`s in `UndoRedoManager` and undo them by removing the node, re-inserting the recorded subtree, or restoring the previous value. It SHALL ignore `DataNodeAddedEvent`s marked as initialization events. + +#### Scenario: Undoing a value change without collaboration +- **GIVEN** collaboration is not enabled and the local user toggles `items.0.checked` from `false` to `true` +- **WHEN** `undo()` is called +- **THEN** `items.0.checked` is `false` again + +#### Scenario: Initialization events are not recorded +- **GIVEN** collaboration is not enabled +- **WHEN** the local user inserts a block with data +- **THEN** the recorded undo step contains the `BlockAddedEvent` only, not the block's initialization `DataNodeAddedEvent`s diff --git a/openspec/changes/add-data-node-operations/specs/model-types/spec.md b/openspec/changes/add-data-node-operations/specs/model-types/spec.md new file mode 100644 index 00000000..8cab5f18 --- /dev/null +++ b/openspec/changes/add-data-node-operations/specs/model-types/spec.md @@ -0,0 +1,17 @@ +## ADDED Requirements + +### Requirement: Initialization marker on DataNodeAddedEvent +The system SHALL expose on `DataNodeAddedEvent` a boolean `detail.isInitialization`, which is `true` for data nodes created while a `BlockNode` is being constructed and `false` otherwise. The default is `false` when a constructor call omits it. + +#### Scenario: Distinguishing initialization events +- **GIVEN** a consumer of model events receives a `DataNodeAddedEvent` +- **WHEN** it reads `detail.isInitialization` +- **THEN** it can tell a node created as part of a new block (`true`) from a node added to an existing block (`false`) + +### Requirement: Array positions in data keys +The system SHALL treat a dot-notation data-key segment that is a non-negative integer as a position in an array, in the keypath utilities and in operation transformation. Tools SHALL NOT rely on digit-only object member names. + +#### Scenario: Numeric segment addresses an array element +- **GIVEN** the data key `items.3.content` +- **WHEN** it is interpreted +- **THEN** `3` is the position of an element in the array at `items`, and `content` is a member of that element diff --git a/openspec/changes/add-data-node-operations/specs/model/spec.md b/openspec/changes/add-data-node-operations/specs/model/spec.md new file mode 100644 index 00000000..01170fb1 --- /dev/null +++ b/openspec/changes/add-data-node-operations/specs/model/spec.md @@ -0,0 +1,32 @@ +## ADDED Requirements + +### Requirement: Data node event attribution +The system SHALL dispatch the `DataNodeAddedEvent` of a `createDataNode` call on an already constructed `BlockNode` synchronously, so the event carries the `userId` of the `EditorJSModel` call that caused it. Data nodes created while a `BlockNode` is being constructed SHALL still dispatch `DataNodeAddedEvent` after the block's `BlockAddedEvent`, marked as initialization events. `EditorDocument` and `EditorJSModel` SHALL keep the marker when they re-dispatch the event. + +#### Scenario: Explicit data node creation is attributed +- **GIVEN** a block exists at index 0 +- **WHEN** `EditorJSModel.createDataNode('user-1', 0, 'items.1', element)` is called +- **THEN** a `DataNodeAddedEvent` for `items.1` is dispatched before the call returns, with `userId: 'user-1'`, and is not marked as an initialization event + +#### Scenario: Construction-time data nodes are marked +- **GIVEN** `addBlock` is called with data containing keys `style` and `items` +- **WHEN** the block's events are dispatched +- **THEN** `BlockAddedEvent` comes first, followed by one `DataNodeAddedEvent` per key, each marked as an initialization event + +### Requirement: Replaying data changes by index +The system SHALL apply data changes addressed by a `DataIndex` through `EditorDocument.insertData`, `removeData` and `modifyData`: +- `modifyData` SHALL set the value at the key via `updateValue`; +- `insertData` SHALL splice the subtree in when the key's parent is an array, create it when the key is absent, and replace the existing node otherwise, dispatching `DataNodeRemovedEvent` then `DataNodeAddedEvent`; +- `removeData` SHALL remove the node at the key. + +The direct `createDataNode` method SHALL keep throwing `AlreadyExistingKeyError` for an existing key. + +#### Scenario: Modifying a value by index +- **GIVEN** block 0 has value `1` at `items.0.depth` +- **WHEN** `modifyData(DataIndex(0, 'items.0.depth'), { value: 0, previous: 1 })` is called +- **THEN** the value at `items.0.depth` is `0` and a `ValueModifiedEvent` is dispatched + +#### Scenario: Inserting over an existing object key replaces it +- **GIVEN** block 0 has a value node at `meta` +- **WHEN** `insertData(DataIndex(0, 'meta'), newSubtree)` is called +- **THEN** `meta` holds `newSubtree`, no error is thrown, and `DataNodeRemovedEvent` then `DataNodeAddedEvent` are dispatched diff --git a/openspec/changes/add-data-node-operations/specs/ot-server/spec.md b/openspec/changes/add-data-node-operations/specs/ot-server/spec.md new file mode 100644 index 00000000..1f9304c8 --- /dev/null +++ b/openspec/changes/add-data-node-operations/specs/ot-server/spec.md @@ -0,0 +1,9 @@ +## ADDED Requirements + +### Requirement: Applying data node and value operations +The system SHALL apply `Insert`, `Delete` and `Modify` operations addressed by a `DataIndex` to the per-document `EditorJSModel`, converting them to model data through the shared helper from `@editorjs/collaboration-manager`, after transforming them against history under the collaboration transformation rules. + +#### Scenario: Late-joining client sees structural list edits +- **GIVEN** a client inserted an element at `items.1` and changed `items.1.depth` +- **WHEN** the server has processed both operations and a new client connects +- **THEN** `currentModelState()` contains the new element at `items.1` with the new depth diff --git a/openspec/changes/add-data-node-operations/tasks.md b/openspec/changes/add-data-node-operations/tasks.md new file mode 100644 index 00000000..780ac561 --- /dev/null +++ b/openspec/changes/add-data-node-operations/tasks.md @@ -0,0 +1,53 @@ +## 0. Prerequisite + +- [ ] 0.1 Confirm `fix-ot-client-convergence` has landed (explicit transform order, revision stamping, in-flight rebasing) + +## 1. Event attribution and initialization marker + +- [ ] 1.1 Write failing specs in `packages/model-types` for `DataNodeAddedEvent.detail.isInitialization`: it is `true` when passed and defaults to `false` +- [ ] 1.2 Add the `isInitialization` constructor parameter and detail field to `DataNodeAddedEvent` +- [ ] 1.3 Write failing `BlockNode` specs: `createDataNode` on a constructed block dispatches synchronously and unmarked; nodes created in `#initialize` dispatch after construction, marked +- [ ] 1.4 Split `BlockNode.createDataNode` so that only `#initialize` keeps the microtask and sets the marker +- [ ] 1.5 Write failing `EditorDocument` / `EditorJSModel` specs: a re-dispatched `DataNodeAddedEvent` keeps the marker, and an explicit `createDataNode('user-1', …)` arrives with `userId: 'user-1'` +- [ ] 1.6 Forward the marker in `EditorDocument#listenAndBubbleBlockEvent` and `EditorJSModel#listenAndBubbleDocumentEvents` + +## 2. Model replay by DataIndex + +- [ ] 2.1 Write failing `EditorDocument` specs for `modifyData` on a `DataIndex` (set value, emits `ValueModifiedEvent`) +- [ ] 2.2 Implement the `DataIndex` branch of `modifyData` via `updateValue` +- [ ] 2.3 Write failing specs for `insertData` on a `DataIndex`: array splice, absent key, existing object key replaced (Removed then Added event, no throw); `createDataNode` still throws for an existing key +- [ ] 2.4 Implement replace-on-insert in the `DataIndex` branch of `insertData` + +## 3. Operations + +- [ ] 3.1 Widen `ModifyOperationData` payload/prevPayload to any JSON value and narrow the text transformer's `payload.length` reads to `InsertOrDeleteOperationData` (skip if #192 has landed) +- [ ] 3.2 Write failing specs for `toModelData(operation)`: unwraps `[subtree]` for a `DataIndex` Insert/Delete, passes other payloads through +- [ ] 3.3 Implement and export `toModelData`; use it in `CollaborationManager.applyOperation` +- [ ] 3.4 Write failing `CollaborationManager` specs: the three events map to Insert/Delete/Modify with the D3 shapes; marked initialization events produce no operation, no undo entry and no stack transform +- [ ] 3.5 Map the three events in `#handleEvent` and skip marked events before the local/remote branch + +## 4. Transformer + +- [ ] 4.1 Write failing `OperationsTransformer` specs for every row of the D5 table, for both data and text operations, including nested prefixes (`rows.2.cells.0`) and other blocks or arrays left unchanged +- [ ] 4.2 Write failing specs for the same-position Insert tie-break with the default order (shifts) and with `againstIsLater: true` (keeps position) +- [ ] 4.3 Write failing specs for object-member Delete (`Neutral` at or under the key, re-create left unchanged) and for Insert vs. Insert on the same object key by transform order +- [ ] 4.4 Implement a key-relation helper (common prefix, array position at that depth) and extend `#transformAgainstDataOperation` to handle Insert/Delete against operations, re-keying `DataIndex` and `TextIndex` via a new data-key copy method +- [ ] 4.5 Add a two-client convergence spec driving `DocumentManager` and `OTClient`-style pending transforms for concurrent same-position inserts and an insert vs. a text edit in a later element + +## 5. Undo/redo + +- [ ] 5.1 Write failing collaboration `UndoRedoManager` / `CollaborationManager` specs: undo/redo of a data Insert, Delete (subtree with text restored) and Modify; undo stack re-keyed by a remote array insert +- [ ] 5.2 Write failing core `UndoRedoManager` specs: value change undone without collaboration; block insert records `BlockAddedEvent` only +- [ ] 5.3 Skip marked initialization events in core `UndoRedoManager#handleEvent`; update the #201 R2 test to assert on the marker if that PR has landed + +## 6. ot-server + +- [ ] 6.1 Write a failing `DocumentManager` spec: data Insert and Modify are applied and visible in `currentModelState()` +- [ ] 6.2 Use `toModelData` in `DocumentManager#applyOperationToModel` + +## 7. Docs and wrap-up + +- [ ] 7.1 Update `docs/collaboration.md` with the data operation kinds and the array transform rules +- [ ] 7.2 Update `docs/events.md` for `isInitialization` and synchronous dispatch +- [ ] 7.3 Run `yarn build`, `yarn lint`, `yarn test`, and mutation tests for `collaboration-manager` and `model` +- [ ] 7.4 Run `openspec validate add-data-node-operations --type change`