Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
44769dc
refactor(model)!: rename block tunes to per-plugin block data
gohabereg Sep 25, 2026
4a68df3
feat(sdk): expose typed per-block plugin data
gohabereg Sep 25, 2026
c8a1b90
feat(core): read and write per-block plugin data through BlocksAPI
gohabereg Sep 25, 2026
273ca74
feat(collaboration-manager): synchronize per-block plugin data
gohabereg Sep 25, 2026
568b6a5
test: kill surviving mutants in the plugin data paths
gohabereg Sep 25, 2026
12573ee
feat(core): carry v2 tune data into plugin data on conversion
gohabereg Sep 25, 2026
eb540c6
docs: describe per-block plugin data in place of block tunes
gohabereg Sep 26, 2026
b62d820
docs(openspec): check off the implemented plugin-block-data tasks
gohabereg Sep 26, 2026
a587f53
docs: keep the plugin-data comments to two sentences
gohabereg Oct 9, 2026
1a140c8
fix(model): keep a plugin data write that changes nothing off the wire
gohabereg Oct 10, 2026
8228e73
fix(collaboration-manager): converge concurrent plugin data writes
gohabereg Oct 11, 2026
7546fa2
docs(openspec): check off the second-round plugin-block-data follow-ups
gohabereg Oct 11, 2026
e47f784
fix(model,core): keep plugin data out of reach of Object.prototype
gohabereg Oct 16, 2026
f8fa0cd
docs(openspec): check off the third-round plugin-block-data follow-ups
gohabereg Oct 16, 2026
b004126
test(collaboration-manager): say what "not transformed" actually means
gohabereg Oct 17, 2026
92c0657
fix(model): copy plugin data values in and out of the store
gohabereg Nov 5, 2026
6121800
fix(collaboration-manager): drop undo entries a collaborator overwrote
gohabereg Nov 5, 2026
384329c
docs(openspec): specify and check off the fourth-round plugin-block-d…
gohabereg Nov 5, 2026
9b749a4
test(model): kill the surviving mutants in the plugin data copy paths
gohabereg Nov 5, 2026
a268f2c
fix(collaboration-manager): keep a sent operation pending until it is…
gohabereg Nov 8, 2026
99dc155
docs(openspec): specify and check off the fifth-round plugin-block-da…
gohabereg Nov 8, 2026
ac5a410
Merge branch 'main' into feat/plugin-block-data
gohabereg Nov 8, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/agents/docs-updater.agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Follow this sequence for every run:
| Changed area | Primary doc(s) | Diagram(s) |
|---|---|---|
| Package list, dependencies, overall structure | `docs/architecture.md`, root `README.md` | `diagrams/architecture-overview.mmd` |
| `EditorJSModel`, `EditorDocument`, `BlockNode`, `TextNode`, `ValueNode`, `BlockTune`, `Index`, `CaretManager` | `docs/model.md` | `diagrams/model-tree-structure.mmd` |
| `EditorJSModel`, `EditorDocument`, `BlockNode`, `TextNode`, `ValueNode`, `PluginDataNode`, `Index`, `CaretManager` | `docs/model.md` | `diagrams/model-tree-structure.mmd` |
| Event classes, `EventType`, `EventBus` | `docs/events.md` | `diagrams/events-catalog.mmd` |
| `Core`, `BlocksManager`, `BlockRenderer`, `SelectionManager`, `ToolsManager`, `EditorAPI`, plugin/tool lifecycle | `docs/plugins.md` | `diagrams/plugin-lifecycle-flow.mmd` |
| `DOMBlockToolAdapter`, `CaretAdapter`, `FormattingAdapter`, `InputsRegistry`, `BeforeInputUIEvent` | `docs/input-handling.md` | `diagrams/block-adapter-input-flow.mmd`, `diagrams/caret-selection-flow.mmd`, `diagrams/inline-formatting-flow.mmd` |
Expand Down
2 changes: 1 addition & 1 deletion docs/diagrams/architecture-overview.mmd
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ classDiagram
+block(blockIndex, documentId?)$ BlockIndex
+text(segments)$ TextIndex
+data(blockIndex, dataKey)$ DataIndex
+tune(blockIndex, tuneName, tuneKey)$ TuneIndex
+pluginData(blockIndex, pluginName, pluginKey)$ PluginDataIndex
}
}

Expand Down
4 changes: 2 additions & 2 deletions docs/diagrams/events-catalog.mmd
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ classDiagram
detail.data.value: T
detail.data.previous: T
}
class TuneModifiedEvent {
class PluginDataModifiedEvent {
detail.data.value: T
detail.data.previous: T
}
Expand Down Expand Up @@ -163,7 +163,7 @@ classDiagram
DataNodeAddedEvent --|> BaseDocumentEvent
DataNodeRemovedEvent --|> BaseDocumentEvent
ValueModifiedEvent --|> BaseDocumentEvent
TuneModifiedEvent --|> BaseDocumentEvent
PluginDataModifiedEvent --|> BaseDocumentEvent
PropertyModifiedEvent --|> BaseDocumentEvent

BlockAddedCoreEvent --|> CoreEventBase
Expand Down
11 changes: 6 additions & 5 deletions docs/diagrams/model-tree-structure.mmd
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ classDiagram
class BlockNode {
+name: BlockToolName
+data: BlockNodeData
+tunes: Record~BlockTuneName, BlockTune~
+plugins: Record~PluginDataName, PluginDataNode~
+parent: EditorDocument
+createDataNode(key, data)
+removeDataNode(key)
Expand All @@ -47,9 +47,10 @@ classDiagram
+getFragments(key, ...): InlineFragment[]
}

class BlockTune {
+name: BlockTuneName
class PluginDataNode {
+name: PluginDataName
+data: Record~string, unknown~
+isEmpty: boolean
+update(key, value)
}

Expand Down Expand Up @@ -123,7 +124,7 @@ classDiagram
EditorJSModel --|> EventBus
EditorDocument --|> EventBus
BlockNode --|> EventBus
BlockTune --|> EventBus
PluginDataNode --|> EventBus
ValueNode --|> EventBus
ParentInlineNode --|> EventBus

Expand All @@ -134,7 +135,7 @@ classDiagram
EditorDocument "1" *-- "0..*" BlockNode : children
BlockNode "1" *-- "0..*" TextNode : data[key]
BlockNode "1" *-- "0..*" ValueNode : data[key]
BlockNode "1" *-- "0..*" BlockTune : tunes[name]
BlockNode "1" *-- "0..*" PluginDataNode : plugins[name]

%% Inline tree
TextNode --|> ParentInlineNode
Expand Down
4 changes: 2 additions & 2 deletions docs/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The editor exposes two public event transports.

| Transport | Dispatched on | Event types |
|---|---|---|
| `EditorJSModel` `EventType.Changed` | `EditorJSModel` instance | `BlockAddedEvent`, `BlockRemovedEvent`, `TextAddedEvent`, `TextRemovedEvent`, `TextFormattedEvent`, `TextUnformattedEvent`, `ValueModifiedEvent`, `TuneModifiedEvent`, `DataNodeAddedEvent`, `DataNodeRemovedEvent`, `PropertyModifiedEvent` |
| `EditorJSModel` `EventType.Changed` | `EditorJSModel` instance | `BlockAddedEvent`, `BlockRemovedEvent`, `TextAddedEvent`, `TextRemovedEvent`, `TextFormattedEvent`, `TextUnformattedEvent`, `ValueModifiedEvent`, `PluginDataModifiedEvent`, `DataNodeAddedEvent`, `DataNodeRemovedEvent`, `PropertyModifiedEvent` |
| `EditorJSModel` `EventType.CaretManagerUpdated` | `EditorJSModel` instance | `CaretManagerCaretUpdatedEvent`, `CaretManagerCaretAddedEvent`, `CaretManagerCaretRemovedEvent` |
| Core `EventBus` (per editor instance) | `EventBus` held in the IoC container | `BlockAddedCoreEvent`, `BlockRemovedCoreEvent`, `ToolLoadedCoreEvent`, `SelectionChangedCoreEvent`, `UndoCoreEvent`, `RedoCoreEvent`, `BeforeInputUIEvent` |

Expand All @@ -27,7 +27,7 @@ All document mutation events extend `BaseDocumentEvent`:
| `TextFormattedEvent` | `{ tool, data }` | An inline tool was applied to a text range |
| `TextUnformattedEvent` | `{ tool, data }` | An inline tool was removed from a text range |
| `ValueModifiedEvent` | `{ value, previous }` | A `ValueNode`'s value was changed |
| `TuneModifiedEvent` | `{ value, previous }` | A `BlockTune`'s data was updated |
| `PluginDataModifiedEvent` | `{ value, previous }` | One key of a plugin's per-block data was updated; `value` is `undefined` when the key was removed |
| `DataNodeAddedEvent` | `BlockNodeDataSerializedValue` | A data node (text or value) was created on a block |
| `DataNodeRemovedEvent` | `BlockNodeDataSerializedValue` | A data node was removed from a block |
| `PropertyModifiedEvent` | `{ value, previous }` | A top-level document property was set |
Expand Down
26 changes: 13 additions & 13 deletions docs/index-serialization.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,19 +64,19 @@ All fields that can be omitted (`id`) are absent from the JSON when `undefined`

---

## `TuneIndex` — `k: "tune"`
## `PluginDataIndex` — `k: "plugin"`

```json
{ "k": "tune", "b": 2, "tune": "<tuneName>", "key": "<tuneKey>", "id": "<documentId>" }
{ "k": "plugin", "b": 2, "plugin": "<pluginName>", "key": "<pluginKey>", "id": "<documentId>" }
```

| Field | Type | Required |
|--------|----------|----------|
| `k` | `"tune"` | yes |
| `b` | number | yes — zero-based block position |
| `tune` | string | yes — block tune name |
| `key` | string | yes — key within the tune |
| `id` | string | no |
| Field | Type | Required |
|----------|------------|----------|
| `k` | `"plugin"` | yes |
| `b` | number | yes — zero-based block position |
| `plugin` | string | yes — name the data is stored under, by convention the plugin's `name` |
| `key` | string | yes — key within that plugin's data |
| `id` | string | no |

---

Expand Down Expand Up @@ -167,13 +167,13 @@ Index.block(2, 'doc-abc').serialize()
// → '{"k":"block","b":2,"id":"doc-abc"}'
```

### Tune property change
### Plugin data change

A `fontSize` tune on block 1, key `"size"` changed.
The `fontSize` plugin's `"size"` key changed on block 1.

```ts
Index.tune(1, 'fontSize', 'size').serialize()
// → '{"k":"tune","b":1,"tune":"fontSize","key":"size"}'
Index.pluginData(1, 'fontSize', 'size').serialize()
// → '{"k":"plugin","b":1,"plugin":"fontSize","key":"size"}'
```

### Round-trip through `Index.parse`
Expand Down
6 changes: 3 additions & 3 deletions docs/model.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Each `BlockNode` contains keyed data nodes:

- `TextNode`: rich text with inline tree (`FormattingInlineNode` + `TextInlineNode`).
- `ValueNode<T>`: non-text typed value for tools.
- `BlockTune`: per-block tune configuration.
- `PluginDataNode`: per-block data owned by a plugin, keyed by the plugin's `name`.

## Mutation and event invariant

Expand Down Expand Up @@ -41,7 +41,7 @@ IndexBase (abstract)
├── PropertyIndex — top-level document property
├── BlockIndex — a single block
├── DataIndex — a data key inside a block
├── TuneIndex — a key inside a block tune
├── PluginDataIndex — a key inside one plugin's per-block data
└── TextIndex — character range(s) inside a text node
```

Expand All @@ -68,7 +68,7 @@ Index.document(documentId)
Index.property(name, documentId?)
Index.block(blockIndex, documentId?)
Index.data(blockIndex, dataKey, documentId?)
Index.tune(blockIndex, tuneName, tuneKey, documentId?)
Index.pluginData(blockIndex, pluginName, pluginKey, documentId?)
Index.text(segments)
Index.parse(serialized) // deserialize from string
```
Expand Down
49 changes: 46 additions & 3 deletions docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,11 +114,52 @@ Merging is shallow **at the plugin-id level**: a slice supplied through `use()`
const { shortcut } = toolFacade.pluginOptions('shortcuts') ?? {};
```

## Per-block plugin data

A plugin stores its own data on a block through `api.blocks`, under a key that is by convention the
plugin's `name`. The entry is created on first write, so there is nothing to initialize:

```ts
api.blocks.updatePluginData({ block: blockId, plugin: 'anchors', data: { id: 'intro' } });

api.blocks.getPluginData({ block: blockId, plugin: 'anchors' }); // → { id: 'intro' }
```

Declare the shape once and both calls are typed, with a wrong value a compile error:

```ts
declare module '@editorjs/sdk' {
interface EditorjsPluginDataMap {
anchors: { id: string };
}
}
```

A plugin that never augments the map still works: its data is typed as `Record<string, unknown>`.

Things worth knowing before relying on it:

- **A key set to `undefined` is removed**, and an entry with no keys left is dropped from the
serialized block. So `getPluginData` returns `undefined` both for a plugin that never wrote
anything and for one whose last key was removed.
- **Each key is its own change.** Writing two keys in one call produces two modifications, so one
undo reverts only the last of them. Write a single key when the change must be atomic.
- **Concurrent writes to the same key resolve last-writer-wins.** Two collaborators toggling
different keys of the same plugin do not collide; two writing the same key do, and the operation
the server orders last wins. Split state across keys when that matters.
- **Data for an unregistered plugin is preserved**, not dropped, so opening a document in an editor
without that plugin does not lose it.
- **Blocks keep their data through `move` and `convert`**; a `split` leaves it on the original block
and gives the new one none.
- **v2 documents carry over**: a v2 block's `tunes` are mapped onto the same keys on load, and a
tune whose data was not an object lands under a `value` key.

## TypeScript caveats

Both features — calling a plugin API and configuring a plugin from a tool — are typed the same
way: `@editorjs/sdk` declares two empty interfaces (`EditorjsPluginApiMap`, `ToolPluginOptionsMap`)
and each plugin package fills in its own row via module augmentation. That gives inference with no
Three features — calling a plugin API, configuring a plugin from a tool, and storing per-block
plugin data — are typed the same way: `@editorjs/sdk` declares three empty interfaces
(`EditorjsPluginApiMap`, `ToolPluginOptionsMap`, `EditorjsPluginDataMap`) and each plugin package
fills in its own row via module augmentation. That gives inference with no
casts, but it comes with rules worth knowing before you hit them.

### The augmentation must be in *your* compilation
Expand Down Expand Up @@ -267,6 +308,8 @@ Programmatic block management — delegates to `BlocksManager`.
| `render(document)` | Re-initialize the document from serialised data |
| `clear()` | Remove all blocks |
| `getBlocksCount()` | Return the total number of blocks |
| `getPluginData({ block, plugin })` | Read a plugin's per-block data, or `undefined` |
| `updatePluginData({ block, plugin, data, userId? })` | Merge keys into a plugin's per-block data |

### `api.selection`

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
## ADDED Requirements

### Requirement: Plugin data operations
`CollaborationManager` SHALL translate a `PluginDataModifiedEvent` into a `Modify` `Operation` on its `PluginDataIndex`, with `payload` set to the new value and `prevPayload` to the previous value. `OperationsTransformer` SHALL shift a plugin data operation's block index against block insertions and removals the same way it does for data index operations, SHALL turn it into a `Neutral` operation when its block is removed, and SHALL resolve two concurrent writes to the same block, plugin and key the same way it resolves two concurrent writes to the same data key: the operation being transformed becomes `Neutral` when the operation it is transformed against is the later of the two, an unsent local operation counting as later than any revision. Writes to different blocks, different plugins or different keys SHALL be left untransformed, since one cannot shift another's position. Transformation SHALL also accept a plugin data operation as the operation being transformed *against*, rather than rejecting its index kind. The `Modify` operation payload type SHALL admit any JSON value, including primitives.
`CollaborationManager` SHALL translate a `PluginDataModifiedEvent` into a `Modify` `Operation` on its `PluginDataIndex`, with `payload` set to the new value and `prevPayload` to the previous value. `OperationsTransformer` SHALL shift a plugin data operation's block index against block insertions and removals the same way it does for data index operations, SHALL turn it into a `Neutral` operation when its block is removed, and SHALL resolve two concurrent writes to the same block, plugin and key the same way it resolves two concurrent writes to the same data key: the operation being transformed becomes `Neutral` when the operation it is transformed against is the later of the two, a local operation the server has not acknowledged counting as later than any revision. A local operation SHALL count as unacknowledged for the whole round trip, not merely until it leaves for the server, so the client SHALL keep it among the operations an incoming one is transformed against until its acknowledgement arrives. The acknowledgement is what establishes the server's order: while it is outstanding, every remote operation the server delivers was ordered before the local one, and once it arrives, everything after it was ordered later. Writes to different blocks, different plugins or different keys SHALL be left untransformed, since one cannot shift another's position. An operation carrying no revision of its own SHALL lose to whatever it is transformed against. Such an operation comes from an undo or redo stack, whose entries are built from model events and are never numbered, while an operation from the server always is; and the operation it is transformed against has already been applied to the document. Keeping it would leave an undo step that writes a value the document has moved on from, and whose recorded previous value is older still, so undoing a local write that a collaborator had overwritten would delete the collaborator's value. Transformation SHALL also accept a plugin data operation as the operation being transformed *against*, rather than rejecting its index kind. The `Modify` operation payload type SHALL admit any JSON value, including primitives.

#### Scenario: Local plugin data change becomes an operation
- **GIVEN** the local user changes `anchors.visible` on block 1 from `true` to `false`
Expand Down Expand Up @@ -35,9 +35,29 @@

#### Scenario: Two clients write the same key concurrently
- **GIVEN** clients A and B both write `anchors.visible` on block 1, and the server applies A before B
- **WHEN** B receives A's operation while its own write is still unsent
- **WHEN** B receives A's operation while its own write is still unacknowledged
- **THEN** A's operation is transformed to `Neutral` on B, so B keeps the value the server will end up holding rather than being left on A's

#### Scenario: A collaborator writes while the local write is in flight
- **GIVEN** the local client has sent a write of `anchors.color` and is waiting for its acknowledgement
- **WHEN** a collaborator's write to the same key arrives before that acknowledgement
- **THEN** it is transformed to `Neutral` and not applied, since the server will apply the local write after it -- and a client's own operations are not echoed back to it, so nothing would restore the value the server ends up holding

#### Scenario: A collaborator writes once the local write is acknowledged
- **GIVEN** the local client's write of `anchors.color` has been acknowledged
- **WHEN** a collaborator's write to the same key arrives
- **THEN** it is applied, because the server ordered it after the local write

#### Scenario: Undoing a write a collaborator overwrote
- **GIVEN** the local user wrote `anchors.color` on block 0, and a collaborator then overwrote the same key
- **WHEN** the undo stack is transformed against the collaborator's operation
- **THEN** the entry is dropped, so undo reaches past it rather than writing a value that is gone and deleting the collaborator's

#### Scenario: Undoing a write to a key nobody else touched
- **GIVEN** the local user wrote `anchors.color` and a collaborator wrote `anchors.label` on the same block
- **WHEN** the undo stack is transformed against the collaborator's operation
- **THEN** the entry survives, because the two do not describe the same value

#### Scenario: Concurrent writes to different keys
- **GIVEN** a plugin data operation on `anchors.visible` and a concurrent one on `anchors.id` of the same block
- **WHEN** one is transformed against the other
Expand Down
22 changes: 22 additions & 0 deletions openspec/changes/plugin-block-data/specs/plugin-block-data/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ Plugin names and the keys within an entry are document data, not identifiers the

What `getPluginData` and the serialized document hand back SHALL be detached from the store, so that changing it does not change the document. Reading an entry, editing it and passing it back to `updatePluginData` is the obvious way to use the two together, and over a live record the no-op rule above turns it into silent loss: the document has already changed, so the write that should have announced it emits nothing.

A value handed to the store SHALL be detached the same way before it is stored and before the change is recorded, down to nested objects and arrays, and so SHALL the data a block is initialized with. This is the same read-modify-write from the other end: a plugin keeps the object it wrote and edits it again, and over a shared object the document moves with no write at all, no operation for collaborators and no step to undo — two documents diverging with nothing to say so. What is recorded needs detaching for the same reason, since an operation and an undo step both outlive the call that produced them. Because what is stored is therefore a copy of what was written, the no-op rule above SHALL compare values structurally rather than by identity, which could only ever match a primitive.

#### Scenario: A block with no plugin data
- **GIVEN** a block that has no plugin data at all
- **WHEN** it is serialized
Expand Down Expand Up @@ -44,6 +46,26 @@ What `getPluginData` and the serialized document hand back SHALL be detached fro
- **WHEN** `{ visible: undefined }` is written for `anchors`
- **THEN** the data is unchanged and no `PluginDataModifiedEvent` is emitted

#### Scenario: Editing a value that was written earlier
- **GIVEN** a plugin wrote `{ align: "left" }` for a key and still holds that object
- **WHEN** it changes the object to `{ align: "center" }` and writes it again
- **THEN** the document held `left` until that write, which emits a `PluginDataModifiedEvent` with `previous` `{ align: "left" }` and `value` `{ align: "center" }`

#### Scenario: Writing an equal object again
- **GIVEN** a key holds `{ align: "left" }`
- **WHEN** a different object holding `{ align: "left" }` is written for it
- **THEN** no `PluginDataModifiedEvent` is emitted, because nothing about the stored data changed

#### Scenario: Editing an object after the change was recorded
- **GIVEN** a plugin wrote an object for a key, and the change was recorded
- **WHEN** it changes that object afterwards
- **THEN** the recorded value is unaffected, so neither the operation sent to collaborators nor the undo step is rewritten

#### Scenario: Reusing the data a block was initialized with
- **GIVEN** a block is initialized with a `plugins` map whose nested values the caller still holds
- **WHEN** the caller changes one of them
- **THEN** the block's plugin data is unaffected

#### Scenario: Reading an entry whose keys were all removed
- **GIVEN** a block whose `anchors` entry existed and then had every key removed
- **WHEN** its plugin data is read
Expand Down
Loading
Loading