Skip to content

feat!: implement per-block plugin data - #192

Merged
gohabereg merged 22 commits into
mainfrom
feat/plugin-block-data
Nov 8, 2026
Merged

gohabereg merged 22 commits into
mainfrom
feat/plugin-block-data

Conversation

@gohabereg

@gohabereg gohabereg commented Oct 4, 2026 •

Copy link
Copy Markdown
Member

Implements the plugin-block-data change from #189. Stacked on #189 — review that one first; this PR's diff is implementation only.

Makes per-block data a working, plugin-owned store. Today BlockNode has a tunes store that nothing above the Model can reach: updateTuneData crashes for an entry the block wasn't created with, BlocksAPI can't read or write it, undo is a silent no-op, and CollaborationManager drops the event as "Unknown event type".

What's in it

  • Model. The tunes store becomes plugins, keyed by plugin name. Writing to an absent entry creates it; setting a key to undefined removes it; empty entries are left out of serialization.
  • Renames. TuneIndex → PluginDataIndex, Index.tune() → Index.pluginData(), TuneModifiedEvent → PluginDataModifiedEvent, BlockTuneName/BlockTuneSerialized → PluginDataName/PluginDataSerialized, and the BlockTune model entity → PluginDataNode.
  • Undo/redo. EditorDocument.modifyData applies Modified changes addressed by a PluginDataIndex, so the generic inversion in UndoRedoManager works for plugin data.
  • Collaboration. PluginDataModifiedEvent becomes a Modify operation, and OperationsTransformer gains a plugin-data branch so such an operation can also be the one transformed against — without it the transformer throws 'Unsupported index type' on the first remote plugin-data change, on every client and on ot-server. ModifyOperationData's payload widens from Record<any, any> so scalar values are representable. Two clients writing the same key converge on the rule data values already use: an incoming operation becomes Neutral when the local client still holds an unsent write to that same block, plugin and key, which is what stops it applying the remote value and ending on one the server does not hold.
  • API. BlocksAPI.getPluginData({ block, plugin }) and updatePluginData({ block, plugin, data, userId? }); insert/insertMany accept a plugins map; move and convert preserve plugin data and split leaves it on the original block. A new augmentable EditorjsPluginDataMap types both accessors, alongside EditorjsPluginApiMap and ToolPluginOptionsMap.
  • v2 conversion. composeDataFromVersion2 carries each v2 block's tunes into plugins, keys verbatim, so a v3 plugin adopting a v2 tune's name finds its data. Object data is copied key by key; a primitive or array is stored under value. The converter dropped tunes silently before.

Fixed along the way, unrelated to plugin data

BlocksAPI.insert silently discarded focus, plugins and userId; it forwards them now.

This section previously also covered BlocksManager.insert dropping the block's data — it spread ...data into the block init while BlockNode reads a nested data key, so insert({ type, data }) produced an empty block. That reached main independently in #163, so this PR no longer carries it.

Breaking (pre-1.0)

The serialized block key tunes → plugins, and the serialized index k: "tune" → k: "plugin". ot-server is not a passthrough — it keeps its own EditorJSModel and applies every operation — so clients and server deploy together.

Notes for review

  • The SDK's BlockTune tool contract is untouched here. It never read Model tune data; removing it is the next PR in the stack.
  • The naming of the plugins key is under discussion in docs(openspec): propose replacing Block Tunes with plugins #189. If it changes, the rename is mechanical and lands here.
  • Task 6.4 is intentionally unchecked: the archive gate uses an all-checked tasks list as the ready-to-archive signal, and its second half (filling the new capability's ## Purpose, which the mechanical fold writes as a placeholder) can only happen after /archive.

Verified: yarn build, yarn lint and yarn test clean; surviving mutants killed in the plugin-data paths; openspec validate plugin-block-data --type change passes.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

Unit Tests

Package Coverage Delta
@editorjs/dom-adapters 86.95% 0% ⚪️
@editorjs/shortcuts-plugin 100% 0% ⚪️
@editorjs/model 98.61% +0.13% 🟢
@editorjs/core 76.69% +3.55% 🟢
@editorjs/editorjs 100% 0% ⚪️
@editorjs/ot-server 20% 0% ⚪️
@editorjs/clipboard-plugin 66.66% 0% ⚪️
@editorjs/model-types 67.85% +8.03% 🟢
@editorjs/collaboration-manager 87.58% +1.77% 🟢

Mutation Tests

Package Mutation score Dashboard URL
@editorjs/shortcuts-plugin No files to mutate found.
@editorjs/model 90.46% 🟢 Dashboard
@editorjs/clipboard-plugin No files to mutate found.
@editorjs/collaboration-manager 58.96% 🔴 Dashboard
@editorjs/dom-adapters No files to mutate found.
@editorjs/core 71.10% 🟡 Dashboard

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved data-integrity and collaboration issues can lose changes, diverge clients, or block server processing.

5 open issues
What changed in this PR

Implements the per-block plugin store proposed in #189, connecting model data to the SDK, undo/redo, and collaboration.

Changes:

  • Replaces model tune entities, events, and serialized fields with plugin-data equivalents.
  • Adds typed accessors, preserves plugin data during block operations, and migrates v2 tunes.
  • Fixes initial block-data insertion and expands tests and documentation.
File Description
packages/​sdk/​src/​pluginTypeMaps.spec.ts Tests plugin-data type augmentation.
packages/​sdk/​src/​index.ts Exports plugin-data types and map.
packages/​sdk/​src/​api/​BlocksAPI.ts Declares plugin-data accessors.
packages/​ot-server/​src/​DocumentManager.spec.ts Updates serialized fixtures.
packages/​model/​src/​entities/​PluginDataNode/​types/​PluginDataNodeConstructorParameters.ts Defines constructor parameters.
packages/​model/​src/​entities/​PluginDataNode/​types/​index.ts Exports constructor types.
packages/​model/​src/​entities/​PluginDataNode/​PluginDataNode.spec.ts Tests updates, deletion, and events.
packages/​model/​src/​entities/​PluginDataNode/​index.ts Implements plugin-data storage.
packages/​model/​src/​entities/​PluginDataNode/​__mocks__/​index.ts Adds plugin-data mock.
packages/​model/​src/​entities/​index.ts Exports the replacement entity.
packages/​model/​src/​entities/​EditorDocument/​index.ts Applies plugin-data modifications.
packages/​model/​src/​entities/​EditorDocument/​EditorDocument.spec.ts Tests delegation and event bubbling.
packages/​model/​src/​entities/​BlockTune/​types/​index.ts Removes legacy type export.
packages/​model/​src/​entities/​BlockTune/​types/​BlockTuneConstructorParameters.ts Removes legacy constructor types.
packages/​model/​src/​entities/​BlockTune/​index.ts Removes legacy model entity.
packages/​model/​src/​entities/​BlockTune/​BlockTune.spec.ts Replaces legacy entity tests.
packages/​model/​src/​entities/​BlockTune/​__mocks__/​index.ts Removes legacy mock.
packages/​model/​src/​entities/​BlockNode/​types/​BlockNodeConstructorParameters.ts Accepts initial plugin data.
packages/​model/​src/​entities/​BlockNode/​index.ts Creates and serializes plugin entries.
packages/​model/​src/​entities/​BlockNode/​BlockNode.spec.ts Updates storage and event tests.
packages/​model/​src/​entities/​BlockNode/​BlockNode.integration.spec.ts Tests entry lifecycle and names.
packages/​model/​src/​entities/​BlockNode/​__mocks__/​index.ts Renames mocked update method.
packages/​model/​src/​EditorJSModel.ts Exposes contextual plugin updates.
packages/​model/​src/​EditorJSModel.spec.ts Updates method allowlist.
packages/​model-types/​src/​PluginData.ts Defines plugin-data names and records.
packages/​model-types/​src/​Index/​TuneIndex.ts Removes legacy index.
packages/​model-types/​src/​Index/​PluginDataIndex.ts Adds plugin-data index serialization.
packages/​model-types/​src/​Index/​PartialIndex.ts Resolves plugin-data fields.
packages/​model-types/​src/​Index/​IndexBase.ts Renames index kind and fields.
packages/​model-types/​src/​Index/​index.ts Adds index factory and parsing.
packages/​model-types/​src/​Index/​Index.spec.ts Tests index serialization and resolution.
packages/​model-types/​src/​index.ts Updates public exports.
packages/​model-types/​src/​events/​TuneModifiedEvent.ts Removes legacy event.
packages/​model-types/​src/​events/​PluginDataModifiedEvent.ts Defines plugin-data modification event.
packages/​model-types/​src/​events/​index.ts Exports replacement event.
packages/​model-types/​src/​EventMap.ts Updates event unions.
packages/​model-types/​src/​BlockTune.ts Removes legacy tune types.
packages/​model-types/​src/​BlockNode.ts Renames serialized store to plugins.
packages/​core/​src/​utils/​composeDataFromVersion2.ts Migrates v2 tune data.
packages/​core/​src/​utils/​composeDataFromVersion2.spec.ts Tests migration shapes.
packages/​core/​src/​components/​UndoRedoManager.integration.spec.ts Tests plugin-data undo/redo.
packages/​core/​src/​components/​BlockManager.ts Adds accessors and preserves insertion data.
packages/​core/​src/​components/​BlockManager.spec.ts Tests insertion and conversion preservation.
packages/​core/​src/​api/​BlocksAPI.ts Implements accessor delegation.
packages/​core/​src/​api/​BlocksAPI.spec.ts Updates forwarding expectations.
packages/​core/​src/​api/​BlocksAPI.integration.spec.ts Tests plugin-data API flows.
packages/​collaboration-manager/​src/​OperationsTransformer.ts Adds plugin-data conflict transformation.
packages/​collaboration-manager/​src/​OperationsTransformer.spec.ts Tests plugin-data transformations.
packages/​collaboration-manager/​src/​Operation.ts Allows scalar modification payloads.
packages/​collaboration-manager/​src/​Operation.spec.ts Tests deletion wire serialization.
packages/​collaboration-manager/​src/​CollaborationManager.ts Converts plugin events into operations.
packages/​collaboration-manager/​src/​CollaborationManager.spec.ts Tests operation creation and application.
openspec/​changes/​plugin-block-data/​tasks.md Records implementation progress.
docs/​plugins.md Documents accessors and behavior.
docs/​model.md Updates model terminology.
docs/​index-serialization.md Documents plugin index wire format.
docs/​events.md Documents replacement event.
docs/​diagrams/​model-tree-structure.mmd Updates storage relationships.
docs/​diagrams/​events-catalog.mmd Renames event diagram entries.
docs/​diagrams/​architecture-overview.mmd Updates index factory diagram.
.github/​agents/​docs-updater.agent.md Updates model documentation mapping.

Review effort: Balanced

Comment on lines +245 to +246
if (againstRevision > operation.rev!) {
return new Operation(OperationType.Neutral, index, { payload: [] }, operation.userId, operation.rev);

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed, and the blast radius is as you describe. Reproduced against DocumentManager with three same-key writes sharing one base revision:

r1 modify  r2 modify
third: THREW: Unknown operation type
after: LATER REQUEST THREW: Unknown operation type
final value: {"anchors":{"id":"B"}}

So the document is wedged for every later operation, not just the one that threw, and the third write is dropped — your point that handling Neutral alone would still discard it holds.

The underlying defect is pre-existing: plain data values produce Neutral through the same revision comparison and wedge the server identically on main. What this PR changes is reachability — before it, two plugin data operations were never transformed against each other, so plugin data could not get there. Tracked on the board as "Concurrent same-key writes diverge clients and can wedge the OT server" (Collaborative capabilities), with the base-vs-server revision distinction as the root fix.

super();

this.#name = name;
this.#data = data;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. Both halves reproduce: a {"__proto__": "evil", "ok": 1} entry loaded from a document round-tripped as {"ok": 1}, and a first write to toString recorded a previous value that was Object.prototype.toString itself — onto the undo stack and the wire.

The inner record is now copied onto a null prototype, which is also what makes key in this.#data answer honestly in the no-op guard. The contrast you point at is the sharp part: BlockNode already uses Object.create(null) for the outer store, with a comment spelling out this exact hazard, and the node it creates never got the same treatment.

Three regression cases in PluginDataNode.spec.ts, each verified to fail against the old constructor.

* Returns serialized version of the plugin's data.
*/
public get serialized(): PluginDataSerialized {
return this.#data;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed — serialized returns a detached copy now, so this closes api.document.data as well as getPluginData.

Worth recording why it was silent rather than merely untracked: the no-op guard added in an earlier review round is what swallows it. The caller's edit has already changed the record, so updatePluginData finds Object.is(previous, value) true and returns before dispatching — no event, no operation, no undo step. Before that guard the same sequence at least emitted, so collaborators converged. Read-modify-write is the obvious way to use these two methods together, and it was the one shape that lost data outright.

Two cases cover it at the node and two more at the BlocksAPI level, including one asserting the write-back still emits exactly one change.

public getPluginData(blockIndexOrId: number | BlockId, pluginName: string): PluginDataSerialized | undefined {
const blockIndex = this.#model.resolveBlockIndex(blockIndexOrId);

return this.#model.getBlockSerialized(blockIndex).plugins?.[pluginName];

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. getPluginData checks for an own entry before returning, so a plugin named toString or constructor reads as undefined rather than as the inherited function — including after its last key is removed, since an empty entry is filtered out of the serialized map.

Checked at the read site rather than by giving the map a null prototype, to keep api.document.data an ordinary object for everyone else.

@gohabereg
gohabereg force-pushed the feat/plugin-block-data branch from dd75828 to d555032 Compare October 16, 2026 23:01
* holding `undefined` entirely. It survives only because reading a key that is not there
* gives `undefined` back -- which is worth an assertion, since nothing in the types says so.
*/
it('should carry a plugin data removal through the wire', () => {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what does it mean "through the wire"?

'user2'
);

expect(transformer.transform(incoming, unsentLocal).type).toBe(OperationType.Modify);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should not be transformed

I don't see this assertion. You're checking only a type.

Base automatically changed from spec/tunes-as-plugins to main October 19, 2026 17:17
gohabereg and others added 12 commits November 5, 2026 01:19
Renames the model's tune vocabulary so per-block extra data belongs to
plugins rather than to a dedicated Block Tune entity:

- BlockTune entity -> PluginDataNode, with key deletion when a value is set
  to undefined and an isEmpty getter
- TuneIndex -> PluginDataIndex, serialized as {"k":"plugin",...,"plugin":...}
- TuneModifiedEvent -> PluginDataModifiedEvent, BlockTuneEvents ->
  PluginDataEvents
- BlockTuneName/BlockTuneSerialized -> PluginDataName/PluginDataSerialized
- the serialized block key `tunes` -> `plugins`

Behavior changes beyond the rename:

- BlockNode.updatePluginData creates a missing entry instead of throwing. The
  node is created empty and its listener attached before the first update,
  because PluginDataNode dispatches synchronously.
- entries live in a null-prototype record, and an empty plugin name throws, so
  a document-supplied name like __proto__ is stored as plain data
- empty entries are left out of serialization
- EditorDocument.modifyData applies a Modified change addressed by a
  PluginDataIndex, so undo/redo and remote operations can replay plugin data
- the bubbled event carries the acting user from the context instead of a
  hardcoded 'user'

BREAKING CHANGE: the serialized block key `tunes` is now `plugins`, and the
serialized index kind "tune" is now "plugin".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- re-export the renamed model types (PluginDataName, PluginDataSerialized,
  PluginDataIndex, PluginDataModifiedEvent, createPluginDataName)
- declare EditorjsPluginDataMap, a third augmentable map alongside
  EditorjsPluginApiMap and ToolPluginOptionsMap, and resolve a plugin's data
  shape through PluginDataFor<Id>. An undeclared id falls back to a plain
  record rather than never, since per-block data is often stored by a plugin
  that has no reason to publish its shape.
- add BlocksAPI.getPluginData / updatePluginData and a `plugins` map on insert

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- BlocksAPI.getPluginData / updatePluginData, backed by BlocksManager, with
  the acting user defaulting to the configured one
- insert() accepts a `plugins` map, and convert() carries plugin data over to
  the converted block
- fix insert() dropping the block's data: BlocksManager spread `...data` into
  the block init while BlockNode reads a nested `data` key, so inserting with
  data silently produced an empty block. `plugins` is passed as its own key.
- fix BlocksAPI.insert not forwarding `focus`, `plugins` and `userId`
- add UndoRedoManager integration tests over a real model: undoing a first
  write removes the entry, redo restores it, and undoing one key leaves the
  plugin's other keys untouched
- fix the BlocksAPI integration spec wiring a second, empty model into the API,
  which made every direct model read in it see an empty document

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- map PluginDataModifiedEvent to a Modify operation carrying the new and
  previous values, instead of logging it as an unknown event type
- add a PluginDataIndex branch to OperationsTransformer#applyTransformation,
  which dispatches on the against-operation's index kind and previously threw
  'Unsupported index type'. Without it the first remote plugin data change
  threw in OTClient's pending-operation reduce, in transformStacks for every
  remote event, and in ot-server's conflicting-operation reduce.
- widen ModifyOperationData's payload from Record<any, any> to unknown, so a
  scalar plugin data value is representable, and narrow the two payload length
  reads that relied on the old type
- move the ot-server fixtures off the `tunes` key

Two concurrent writes to the same key stay untransformed: server order decides
and the last applied one wins.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Mutation testing (scoped to the changed files, as CI does) pointed at four
real gaps:

- BlocksManager.insert: nothing asserted that block data is nested under a
  `data` key rather than spread, nor that the plugins map is forwarded and
  omitted when absent
- convertBlock: nothing covered carrying plugin data to the converted block
- EditorDocument.modifyData: the PluginDataIndex branch had no model-level test
- BlockNode: the initial-data path of plugin node creation was unasserted

Fixing the last one surfaced a bug in BlockNode.serialized: it assigned entries
into a plain object, so a plugin named `__proto__` set the object's prototype
instead of becoming a key and vanished from the serialized block. The entry map
is now built with Object.fromEntries. The previous test only passed because its
expected literal was broken the same way — writing the key as a computed
property, to satisfy the naming-convention lint rule, is what exposed it.

Scores for the changed files: model 90.38 (threshold 75), core 86.72,
collaboration-manager 52.08 (threshold 0, unchanged file-level scores). No
surviving mutants remain on lines this branch touched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
composeDataFromVersion2 dropped each v2 block's `tunes` silently. It now maps
them onto the v3 `plugins` key:

- names are kept verbatim, so a v3 plugin that adopts a v2 tune's name finds
  its data without a rename table
- object data is copied key by key
- a primitive, an array or null goes under the `value` key, since a plugin entry
  is a key/value map while v2 tune data is any JSON value
- a block with no tunes, or an empty map, produces no `plugins` key
- the entry map is built with Object.fromEntries, so a tune named `__proto__`
  survives instead of setting a prototype

Adds the file's first spec, including the converter's existing data handling,
and an integration test taking a v2 document through the converter into the
model and reading it back with api.blocks.getPluginData.

The spec stubs DOMParser, which the pre-existing inline-fragment extraction
needs and this package's node test environment lacks. That extraction stays
untested, so the file's mutation score is low (25%, threshold 0) — it simply
had no spec at all before.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- model.md, events.md, index-serialization.md: PluginDataNode,
  PluginDataIndex (`k: "plugin"` with `plugin`/`key` fields),
  PluginDataModifiedEvent, and Index.pluginData
- plugins.md: a new "Per-block plugin data" section for plugin authors — the
  two API calls, the EditorjsPluginDataMap augmentation, and the behaviors that
  bite (key removal, per-key undo granularity, last-writer-wins on the same
  key, preserved data for unregistered plugins, move/convert/split, v2 carry
  over) — plus the two new api.blocks rows and the third type map
- diagrams: model-tree-structure, events-catalog, architecture-overview
- docs-updater agent: map the renamed model entity to docs/model.md

Mentions of the Block Tune *tool kind* stay: they belong to remove-block-tunes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every task is done except the final one, which is the ready-to-archive signal:
leaving it unchecked keeps the archive gate quiet until a maintainer comments
/archive on the PR, per CONTRIBUTING.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Six comments added by this change ran to three. Same content, tightened:
the v2 tune mapping, the BlockNode class doc and its `#plugins` field, the
`updatePluginData` contract and `PluginDataFor`'s fallback.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`PluginDataNode.update` dispatched unconditionally, carried over from
`BlockTune`, where it was nearly harmless because tunes were rarely
written. `updatePluginData` is now a public API that plugins call on every
toggle, and each event becomes an operation for collaborators and a step on
the undo stack — so re-applying the state a plugin just read filled the undo
stack with entries that undo nothing.

Storing the value a key already holds, or removing a key that is not there,
now returns before dispatching. The removal case needs the extra clause:
both sides are `undefined` whether the key is absent or present holding
`undefined`, and only the latter is a real change.

Also locks down the wire format for a removal, which has no test today: the
payload is `undefined`, `JSON.stringify` drops the key outright, and the
removal survives only because reading a missing key gives `undefined` back.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two clients writing the same plugin data key left one of them on a value
the server does not hold. Remote operations are transformed against the
pending local ones, and the plugin data path returned them untouched, so
the client with an unsent write applied the incoming value over its own --
and since its operation is never echoed back to it, nothing restored what
the server ended up with.

The rule is now the one #transformAgainstDataOperation already applies to
data values: an against-operation with no revision counts as the later of
the two, and the operation being transformed becomes Neutral. It is scoped
to the same block, plugin and key, since nothing else describes the same
value.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
gohabereg and others added 6 commits November 5, 2026 01:19
Plugin names and the keys inside an entry are document data, and both
could collide with the prototype.

PluginDataNode kept its keys on a plain object while the block's own
plugin store already used a null prototype. A `__proto__` key loaded from
a document reached the prototype setter instead of becoming an own
property and vanished from serialization; a first write to a key like
`toString` read the inherited function as its previous value and put that
on the undo stack and the wire. The record is now copied onto a null
prototype, as the outer store is.

`serialized` handed out the live record, so `getPluginData` and
`api.document.data` both exposed an untracked write path into the Model.
Read, change, write back -- the obvious way to use the two methods
together -- changed the document on the read and then emitted nothing,
because the no-op guard found the value already updated. Callers get a
detached copy.

BlocksManager.getPluginData indexed the serialized map directly, so a
plugin named toString or constructor read back as the inherited function
rather than undefined. It checks for an own entry first.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The cases asserting that a plugin data operation is left alone checked
only that its type was still Modify. That says it was not neutralised and
nothing more: with the untransformed branch returning an operation whose
block index was shifted by 99, all thirty cases still passed. Comparing
the serialized form covers the index, both payloads, the user and the
revision in one assertion.

The two serialization cases were named after a metaphor rather than what
they do, which is a JSON round-trip standing in for what reaches the OT
server.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A plugin that wrote an object kept a reference into the Model: editing it moved the document
with no write at all, and the write-back that should have announced the change found the value
unchanged and emitted nothing -- no operation for collaborators, no step to undo. The data a
node was constructed with was shared the same way, down from a loaded document.

Incoming values are now cloned on the way in and for the event payload, since an operation and
an undo step both outlive the call that recorded them. Because what is stored is therefore a
copy, the no-op guard compares structurally; `deepEqual` moves into its own util for
`isSameInlineData` to share, and reports a value whose state is not in its own keys -- a `Date`,
a `Map` -- as different rather than as equal to any other of its kind.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`againstRevision > operation.rev!` was false whenever the left side came off an undo or redo
stack, because those entries are built from model events and never carry a revision. The entry
survived, so undoing a local first write to a key a collaborator had since overwritten wrote
`prevPayload` over their value and deleted it.

An operation with no revision of its own now loses to whatever it is transformed against, which
in that path is only ever an operation the model has already applied. Server operations always
carry a revision, so nothing else reaches the comparison without one.

`#transformAgainstDataOperation` has the same hole for `data` values on `main`; it belongs with
the other pre-existing OT defects on the board rather than in this PR.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ata follow-ups

The spec change for the stack is merged, so this round's delta specs land here, with the code
that implements them, rather than in a spec PR of their own.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@gohabereg
gohabereg force-pushed the feat/plugin-block-data branch from 7aefa42 to 384329c Compare November 5, 2026 01:55
Scoped mutation runs over the files this round touched left six survivors. Four are now dead:

- The array-vs-record kind check in `deepEqual` was only tested with `[]` against `{}`, which
  returns `false` either way. An array and an array-like record agree on `length` and on every
  index, so `{ length: 0 }` is the case that tells the branch apart.
- Array lengths were only compared for arrays that also differed in content, so a matching
  prefix of a longer array went untested.
- The `||` in the kind guard short-circuits the same way as `&&` when neither side is keyed,
  which is all the `Date`-against-`Date` cases did. Mixed sides are what it guards.
- Removing a key that is present and explicitly holds `undefined` -- which only a loaded
  document can produce -- is a real change that no test covered, though the comment beside the
  no-op guard has described it since the write-that-changes-nothing round.

The four left on `copyValue`'s guard all amount to cloning when nothing needs it, which is
observable only for a value that cannot be cloned at all. Tightening that is a contract change
rather than a test gap, so it stays as it is. `model` scores 94% over these files against a
threshold of 75%, with `deepEqual.ts` and `isSameInlineData.ts` at 100%.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@gohabereg
gohabereg requested a review from Reversean November 5, 2026 02:02
gohabereg and others added 2 commits November 8, 2026 13:43
… acknowledged

`#sendNextOperation` shifted an operation off `#pendingOperations` in order to send it, and only
pushed it to `#resolvedOperations` -- which nothing reads -- once the server acknowledged it. For
the whole round trip the operation was in neither place, and `#onMessage` transforms incoming
operations against `#pendingOperations` alone: a collaborator's write to the same value arriving
in that window was transformed against nothing, applied over the local one, and never corrected,
since a client's own operations are not echoed back to it.

The convergence rule added earlier covered only the window before an operation is sent, which is
a microtask, while this one is a full round trip -- so it is the window a simultaneous pair of
`updatePluginData` calls actually lands in. `openspec/specs/collaboration-manager/spec.md` already
required this behaviour; the code did not conform.

Safety rests on the server ordering its messages: while an acknowledgement is outstanding, every
remote operation delivered was ordered before the local one, so neutralising it is correct, and
once it arrives, everything after it was ordered later and applies normally.

Reading the head without removing it meant two concurrent `send` calls would both read the same
operation and send it twice, so `#awaitingAcknowledgement` is now claimed before the first await.
The guard on the acknowledgement handler also carries more weight than it did: mistaking a remote
operation for the acknowledgement would now drop a still-in-flight operation from the pending
list, reopening the window this closes, so it has a test of its own.

The tests also close a hole they uncovered: nothing checked that sending ever resumes after an
acknowledgement, only that a queued operation is held back while one is in flight -- so the
acknowledgement gate could have latched shut permanently with the suite still green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ta follow-ups

The convergence rule said "unsent" where it meant "unacknowledged", which is the distinction the
round turned on.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@gohabereg
gohabereg requested a review from Reversean November 8, 2026 13:53
@gohabereg
gohabereg added this pull request to the merge queue Nov 8, 2026
Merged via the queue into main with commit 30bccef Nov 8, 2026
80 checks passed
@gohabereg
gohabereg deleted the feat/plugin-block-data branch November 8, 2026 15:51
gohabereg added a commit that referenced this pull request Nov 8, 2026
Archive the change implemented in #192 and sync its delta specs into
the main specs. Restore the original title of the sdk "Plugin package
augments both maps" scenario in the delta so the archive does not read
the rename as a dropped scenario, and fill the Purpose of the new
plugin-block-data spec from the proposal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TffpCm82NH5xXR1yeBew6Q
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants