Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 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
7e001ac
refactor!: remove the Block Tune tool kind
gohabereg Sep 26, 2026
111c671
docs: drop the Block Tune tool kind
gohabereg Sep 26, 2026
56a3f4e
test(core): cover the tool routing the tune case was removed from
gohabereg Sep 26, 2026
f484edd
docs(openspec): check off the implemented remove-block-tunes tasks
gohabereg Sep 26, 2026
e2760fa
docs(sdk): stop MenuConfig describing a contract that no longer exists
gohabereg Oct 10, 2026
f27b62a
Merge branch 'main' into feat/remove-block-tunes
gohabereg Nov 8, 2026
3d3b078
chore(openspec): archive plugin-block-data
gohabereg Nov 8, 2026
d350d33
chore(openspec): archive remove-block-tunes
gohabereg Nov 8, 2026
896c4c2
chore(openspec): mark remove-block-tunes task 4.5 done
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 docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ The system stays decoupled because each step communicates through interfaces and

- `EditorjsPlugin`: general UI/behavior plugin registered via `core.use()` with `PluginType.Plugin`. UI components like `BlocksUI` typically declare a `static type` from `UiComponentType` but are bound to `PluginType.Plugin` internally.
- `UiComponentType`: reserved string keys for UI component slots (`shell`, `blocks`, `inline-toolbar`, `toolbox`, `toolbar`). These name components in the UI layer but are **not** used as arguments to `core.use()` — plugins are registered by `PluginType` or `ToolType` values.
- `BlockTool` / `InlineTool` / `BlockTune`: tool contracts registered via `core.use(ToolConstructor, options)` during setup. The `tools` config field provides tool settings that `ToolsManager` applies during `initialize()`.
- `BlockTool` / `InlineTool`: tool contracts registered via `core.use(ToolConstructor, options)` during setup. The `tools` config field provides tool settings that `ToolsManager` applies during `initialize()`.
- `Index`: serializable location in the document tree, independent of DOM nodes. Subclasses (e.g. `BlockIndex`, `TextIndex`, `DataIndex`) cover distinct target types. Built with immutable factory methods like `Index.block()` or `Index.text()`; serialized to a compact JSON string for caret storage and OT operations.
- `DataKey`: branded string identifying a data slot inside a `BlockNode` (e.g. `"text"`, `"caption"`). Created via `createDataKey()`.
- `BatchedOperation`: groups rapid single-character inserts or deletes on the same data key into one logical edit for undo/redo. Lives in `@editorjs/collaboration-manager`.
Expand Down
6 changes: 3 additions & 3 deletions docs/diagrams/plugin-lifecycle-flow.mmd
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ sequenceDiagram
Core->>Plugins: bind PluginType.Plugin = SomePlugin

Dev->>Core: use(SomeTool, settings)
Core->>Plugins: bind ToolType.Block / Inline / Tune = [SomeTool, settings]
Core->>Plugins: bind ToolType.Block / Inline = [SomeTool, settings]

%% ── await initialize() ───────────────────────────
Dev->>Core: await initialize()
Expand All @@ -47,9 +47,9 @@ sequenceDiagram
Core->>CollabMgr: new CollaborationManager(config, api, eventBus)
CollabMgr->>EventBus: wire event listeners

Core->>Plugins: getAll(ToolType.Block / Inline / Tune)
Core->>Plugins: getAll(ToolType.Block / Inline)
Plugins-->>Core: [[SomeTool, settings], ...]
Core->>ToolsManager: prepareTools(blockTools, inlineTools, blockTunes)
Core->>ToolsManager: prepareTools(blockTools, inlineTools)
loop for each tool
ToolsManager->>Tool: Tool.prepare({ toolName, config })
ToolsManager->>ToolsManager: wrap in BlockToolFacade or InlineToolFacade
Expand Down
6 changes: 4 additions & 2 deletions docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Package boundary

Tools and plugins should only depend on `@editorjs/sdk` — never on `@editorjs/model` or `@editorjs/model-types` directly. `sdk` re-exports every type a tool/plugin author needs (`Index`, event classes, `BlockTool`/`InlineTool`/`BlockTune` contracts, etc.); `model` is the engine implementation that `core` and `ot-server` orchestrate, and `model-types` is an internal foundation shared only by `model` and `sdk`. Neither is part of the stable, tool-facing API.
Tools and plugins should only depend on `@editorjs/sdk` — never on `@editorjs/model` or `@editorjs/model-types` directly. `sdk` re-exports every type a tool/plugin author needs (`Index`, event classes, `BlockTool`/`InlineTool` contracts, etc.); `model` is the engine implementation that `core` and `ot-server` orchestrate, and `model-types` is an internal foundation shared only by `model` and `sdk`. Neither is part of the stable, tool-facing API.

## Registration

Expand All @@ -26,7 +26,9 @@ Tools are registered via `core.use(ToolConstructor, options)` during setup. The
| UI Plugin | `EditorjsPlugin` | UI component/behavior registered via `core.use(...)` |
| Block Tool | `BlockTool` (from config `tools`) | Block rendering and block-specific behavior |
| Inline Tool | `InlineTool` (from config `tools`) | Selection formatting actions |
| Block Tune | `BlockTune` (from config `tools`) | Per-block tune behavior |

There is no Block Tune tool kind. What v2 called a tune is a UI plugin: it puts an item in the
block settings menu and stores its state as [per-block plugin data](#per-block-plugin-data).

## Initialization sequence

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
### Requirement: Augmentable plugin type maps
The system SHALL declare three empty, augmentable interfaces — `EditorjsPluginApiMap` (plugin id → public API type), `ToolPluginOptionsMap` (plugin id → tool-directed options type), and `EditorjsPluginDataMap` (plugin id → the shape of the per-block data that plugin stores) — that plugin packages extend via module augmentation of `@editorjs/sdk`. `PluginId` SHALL include the keys of all three maps. `BlocksAPI.getPluginData`/`updatePluginData` SHALL resolve their data type from `EditorjsPluginDataMap` for a declared id, and SHALL fall back to `Record<string, unknown>` for an id absent from it, using a non-distributive conditional so the `string & {}` member of `PluginId` does not widen a declared id's type.

#### Scenario: Plugin package augments the api and options maps
#### Scenario: Plugin package augments both maps
- **GIVEN** a plugin package declares `declare module '@editorjs/sdk'` augmenting `EditorjsPluginApiMap` and `ToolPluginOptionsMap` under its `name`
- **WHEN** a consumer's compilation includes that package's types
- **THEN** `api.plugins.<name>` and `options.plugins.<name>` are both fully typed with no cast
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@
- [x] 6.1 Update `docs/model.md`, `docs/index-serialization.md` and `docs/events.md` for `PluginDataNode`, `PluginDataIndex` and `PluginDataModifiedEvent`, plus `docs/plugins.md` (the SDK declares **three** augmentable interfaces now) and `.github/agents/docs-updater.agent.md` (its `BlockTune` → `docs/model.md` mapping)
- [x] 6.2 Update the diagrams `model-tree-structure.mmd`, `events-catalog.mmd` and `architecture-overview.mmd`
- [x] 6.3 Run `yarn lint`, `yarn test`, and the mutation tests for the touched packages that have them. Fix any regressions
- [ ] 6.4 Run `openspec validate plugin-block-data --type change` and confirm it passes. After archiving, fill the `## Purpose` of the new `plugin-block-data` spec from the proposal's intended-Purpose text
- [x] 6.4 Run `openspec validate plugin-block-data --type change` and confirm it passes. After archiving, fill the `## Purpose` of the new `plugin-block-data` spec from the proposal's intended-Purpose text

## 7. Review follow-ups

Expand Down
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
## 1. Guard the removal with tests

- [ ] 1.1 Add type-level assertions (`@ts-expect-error`) that these no longer exist: `ToolType.Tune`, the `BlockTune*` entity exports, `BlockTuneFacade`, `BlockToolOptionKey.Tunes`, `BlockToolOptions['tunes']`, `UserToolOptions.EnabledBlockTunes` and `BlockToolFacade#enabledBlockTunes`. Enumerate tool-kind names only — the model-layer `BlockTuneName`/`BlockTuneSerialized` re-exports belong to `plugin-block-data`
- [ ] 1.2 Write a failing `ToolsCollection` spec case: the collection should expose only `blockTools`/`inlineTools`. Also write a `Core`/`ToolsManager` case: a plugin that contributes block settings items should be instantiated as a plugin and absent from the tool collections
- [x] 1.1 Add type-level assertions (`@ts-expect-error`) that these no longer exist: `ToolType.Tune`, the `BlockTune*` entity exports, `BlockTuneFacade`, `BlockToolOptionKey.Tunes`, `BlockToolOptions['tunes']`, `UserToolOptions.EnabledBlockTunes` and `BlockToolFacade#enabledBlockTunes`. Enumerate tool-kind names only — the model-layer `BlockTuneName`/`BlockTuneSerialized` re-exports belong to `plugin-block-data`
- [x] 1.2 Write a failing `ToolsCollection` spec case: the collection should expose only `blockTools`/`inlineTools`. Also write a `Core`/`ToolsManager` case: a plugin that contributes block settings items should be instantiated as a plugin and absent from the tool collections

## 2. Remove from SDK

- [ ] 2.1 Delete `sdk/src/entities/BlockTune.ts` and `sdk/src/tools/facades/BlockTuneFacade.ts` (with its spec), and remove their exports
- [ ] 2.2 Remove `ToolType.Tune`, `BaseToolFacade#isTune()` and `ToolsCollection#blockTunes` (its only consumer)
- [ ] 2.3 Remove `BlockTuneConstructor` from `ToolConstructable`, `BlockTuneFacade` from `ToolFacadeClass` (and its export), `ToolTypeToOptions[ToolType.Tune]`, the `ToolStaticOptions` member, the `BlockTuneOptions` re-exports in `BaseTool.ts`/`BaseToolFacade.ts`, and the `./BlockTune.js` line in the entities barrel
- [ ] 2.4 Remove `BlockToolOptionKey.Tunes` and its `BlockToolOptions` member, `UserToolOptions.EnabledBlockTunes`, `BlockToolFacade#enabledBlockTunes` and `BlockToolFacade#tunes`
- [x] 2.1 Delete `sdk/src/entities/BlockTune.ts` and `sdk/src/tools/facades/BlockTuneFacade.ts` (it had no spec), and remove their exports
- [x] 2.2 Remove `ToolType.Tune`, `BaseToolFacade#isTune()` and `ToolsCollection#blockTunes` (its only consumer)
- [x] 2.3 Remove `BlockTuneConstructor` from `ToolConstructable`, `BlockTuneFacade` from `ToolFacadeClass` (and its export), `ToolTypeToOptions[ToolType.Tune]`, the `ToolStaticOptions` member, the `BlockTuneOptions` re-exports in `BaseTool.ts`/`BaseToolFacade.ts`, and the `./BlockTune.js` line in the entities barrel
- [x] 2.4 Remove `BlockToolOptionKey.Tunes` and its `BlockToolOptions` member, `UserToolOptions.EnabledBlockTunes`, `BlockToolFacade#enabledBlockTunes` and `BlockToolFacade#tunes`

## 3. Remove from Core and dependents

- [ ] 3.1 Remove the Tune branch from `Core#use`, the `getAll(ToolType.Tune)` step in tool preparation, the Tune case in `ToolsFactory`, and `ToolsManager#blockTunes`
- [ ] 3.2 Remove `#processBlockTune` and the `BlockTuneFacade` import from `packages/plugins/shortcuts-plugin/src/index.ts`
- [ ] 3.3 Grep the workspace for the removed tool-kind symbols (not the bare word `tunes`, which the model layer still uses until `plugin-block-data` lands), fix any leftovers, and confirm `yarn build` is clean
- [x] 3.1 Remove the Tune branch from `Core#use`, the `getAll(ToolType.Tune)` step in tool preparation, the Tune case in `ToolsFactory`, and `ToolsManager#blockTunes`
- [x] 3.2 Remove `#processBlockTune` and the `BlockTuneFacade` import from `packages/plugins/shortcuts-plugin/src/index.ts`
- [x] 3.3 Grep the workspace for the removed tool-kind symbols (not the bare word `tunes`, which the model layer still uses until `plugin-block-data` lands), fix any leftovers, and confirm `yarn build` is clean

## 4. Docs and wrap-up

- [ ] 4.1 Update `docs/plugins.md` (the "Block Tune" table row and the SDK re-export list on line 5), `docs/README.md` (drop the `BlockTune` contract mention) and `docs/diagrams/plugin-lifecycle-flow.mmd` (drop the `ToolType.Tune` binding and `blockTunes`)
- [ ] 4.2 Hand-edit the **Purpose** preamble of `openspec/specs/sdk/spec.md` to drop "block tunes" — the mechanical archive fold only rewrites `### Requirement:` blocks
- [ ] 4.3 Change the `shortcuts-plugin` spec's reserved-work note from "block tunes" to "block settings items"
- [ ] 4.4 Run `yarn lint` and `yarn test`. Fix any regressions
- [ ] 4.5 Comment on PR #157 linking `plugin-block-data`, `block-settings-ui` and `remove-block-tunes` as its replacement
- [ ] 4.6 Run `openspec validate remove-block-tunes --type change` and confirm it passes
- [x] 4.1 Update `docs/plugins.md` (the "Block Tune" table row and the SDK re-export list on line 5), `docs/README.md` (drop the `BlockTune` contract mention) and `docs/diagrams/plugin-lifecycle-flow.mmd` (drop the `ToolType.Tune` binding and `blockTunes`)
- [x] 4.2 Hand-edit the **Purpose** preamble of `openspec/specs/sdk/spec.md` to drop "block tunes" — the mechanical archive fold only rewrites `### Requirement:` blocks
- [x] 4.3 Change the `shortcuts-plugin` spec's reserved-work note from "block tunes" to "block settings items"
- [x] 4.4 Run `yarn lint` and `yarn test`. Fix any regressions
- [x] 4.5 Comment on PR #157 linking `plugin-block-data`, `block-settings-ui` and `remove-block-tunes` as its replacement
- [x] 4.6 Run `openspec validate remove-block-tunes --type change` and confirm it passes
66 changes: 64 additions & 2 deletions openspec/specs/collaboration-manager/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,7 @@
## Purpose

`@editorjs/collaboration-manager` is a core plugin that listens to document model events, converts them into operational-transformation (OT) `Operation`s, batches rapid local edits for undo/redo, maintains local undo/redo stacks transformed against remote edits, and optionally syncs with a remote OT server over WebSocket using a handshake + serialized-ack protocol.

## Requirements

### Requirement: Operation model
The system SHALL represent every document mutation as an `Operation` (Insert/Delete/Modify/Neutral) supporting `inverse()`, `transform()` against another operation, `serialize()`, and `getEffectiveRange()`.

Expand Down Expand Up @@ -105,3 +103,67 @@ The system SHALL classify how two text ranges relate (None/Left/Right/Includes/I
- **THEN** it returns one of `None`, `Left`, `Right`, `Includes`, or `IncludedBy` describing how the ranges overlap

Implemented in `src/utils/getRangesIntersectionType.ts`.

### 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, 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`
- **WHEN** `CollaborationManager` handles the resulting event
- **THEN** it sends a `Modify` operation on `Index.pluginData(1, 'anchors', 'visible')` with `payload` `false` and `prevPayload` `true`, rather than logging an unknown event

#### Scenario: Inverting a plugin data operation
- **GIVEN** a plugin data `Modify` operation with `payload` `false` and `prevPayload` `true`
- **WHEN** `inverse()` is called
- **THEN** it returns a `Modify` operation on the same index with `payload` `true` and `prevPayload` `false`

#### Scenario: Transforming against a block insertion
- **GIVEN** a plugin data operation on block 2 and a concurrent block insertion at index 0
- **WHEN** the plugin data operation is transformed against the insertion
- **THEN** its index targets block 3

#### Scenario: A plugin data operation as the against-operation
- **GIVEN** any pending or stacked operation and a plugin data `Modify` operation to transform it against
- **WHEN** the transformation runs — as it does for pending operations on the client, for the undo/redo stacks on every remote plugin data event, and for conflicting operations on the server
- **THEN** it completes and returns an operation, rather than throwing an unsupported-index error

#### Scenario: A scalar payload
- **GIVEN** a plugin data change whose value is a boolean
- **WHEN** the operation is constructed
- **THEN** the payload type admits it, so scalar plugin data is representable in an operation

#### Scenario: Transforming against removal of its block
- **GIVEN** a plugin data operation on block 2 and a concurrent removal of block 2
- **WHEN** the plugin data operation is transformed against the removal
- **THEN** it becomes a `Neutral` operation

#### 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 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
- **THEN** it is returned unchanged, because the two do not describe the same value

Loading
Loading