docs(openspec): propose replacing Block Tunes with plugins

[gohabereg]

Follows up on the review in #157. Instead of wiring a BlockTuneAdapter and a BlockTunesManager around the Block Tune entity, this proposes removing the entity: a "tune" becomes a plain plugin that stores per-block data in the Model and adds an item to the block settings menu. "Tune" stays as a UI term only.

Artifacts only — no implementation in this PR. Three changes, so each lands on its own:

plugin-block-data (36 tasks, no dependencies)

BlockNode's tunes store becomes plugins, keyed by plugin name, created on first write (today updateTuneData crashes for an absent entry). Adds BlocksAPI.getPluginData/updatePluginData, makes plugin-data changes undoable and collaborative, renames the model's tune vocabulary (PluginDataNode, PluginDataIndex with k: "plugin", PluginDataModifiedEvent), types the accessors through a new augmentable EditorjsPluginDataMap, and carries v2 tunes data across in composeDataFromVersion2.

Breaking, pre-1.0: the serialized block key tunes → plugins, and the serialized index k: "tune" → k: "plugin". Clients and ot-server deploy together, since the server applies operations against its own model.

block-settings-ui (31 tasks)

BlockSettingsUI (name: 'block-settings') renders the settings popover and exposes register(provider), where a provider returns a MenuConfig for the target block each time the menu opens — the same model as InlineTool#getToolbarConfig. ToolbarUI grows a settings button, and the built-in Move up / Move down / Delete become @editorjs/block-actions-plugin. Ports the toolbar button, popover wiring and internal-tune behavior from #157 (credited to @bettysteger).

Assumes test/editorjs-e2e-and-aria-openspec has merged, since it builds on that branch's messages.ts, toolbar ARIA/roving-tabindex behavior, Playwright harness and @editorjs/ui-kit 2.x. Changing a block's appearance from a plugin is deliberately deferred to its own change; the analysis is parked in its design.md.

remove-block-tunes (15 tasks, no dependencies)

Deletes ToolType.Tune, BlockTune, BlockTuneFacade, ToolsCollection#blockTunes, the tool tunes option and its facade getters. A registered tune is currently built into a facade that nothing ever reads, so nothing working is lost.

---

Plan: this PR reviews the plan; implementation follows as stacked PRs, starting with plugin-block-data and remove-block-tunes. Supersedes #157.

🤖 Generated with Claude Code

[neSpecc]

I'm a bit uneasy about using the word plugins in data to store "tunes" data. "Plugin" is a code-organization term, and from a data-model perspective it feels a bit out of place. Maybe meta would be better? Or something closer to the data model. In the code, these could all still be plugins. Though I realize that might cause some confusion.

[gohabereg]

Do you suggest to rename per-tool configuration as well? We had tunes property in the tool config to list tunes for blocks of the type. Now it's going to be plugins

Something like

EditorJS.use(Paragraph, { plugins: ['spoiler'] }

I think meta wouldn't work there. Or it would be plugins in the config, but meta in the model and the output?

I also would reserve meta for actual metadata (e.g. createdAt, author, etc). I agree from model perspective plugins is not the right term, but from the developer perspective I would load plugins and would expect plugins in the output. So maybe naming consistency is more important here than contextual correctness

[neSpecc]

ok, let's try "plugins" in data.

[Reversean]

2 concurrent operations may lead to clients divergence:

• clients A and B write concurrently
• server applies A, then B
• client B already applied own op locally, then receives original A (applied before B) and ends with A

Regular block data already handles this case: transformAgainstDataOperation turns an incoming operation into Neutral when it targets the same key as an unsent local one.

[gohabereg]

You're right, and the spec sentence was mandating it. I traced it through to be sure:

• B writes locally, its operation unsent (rev undefined).
• OTClient#onMessage transforms every incoming remote operation against the pending local ones — but the plugin data branch returned them untouched, so A's value was applied on B.
• B's own operation is never echoed back to it (message.payload.userId === this.#userId returns early), so nothing restored false.
• Server false, A false, B true. Exactly the divergence you described.

Fixed by giving the plugin data branch the rule #transformAgainstDataOperation already uses: an against-operation with no revision counts as Infinity, so the incoming one becomes Neutral and the unsent local write stands. Scoped to the same block, plugin and key, since nothing else describes the same value — a write to anchors.visible must not neutralize one to anchors.id.

The delta now states that rule instead of the old "left untransformed", with scenarios for the same-key and different-key cases. Implementation and tests are in #192. The test that proves it: should become Neutral against an unsent write to the same key fails against the previous return Operation.from(operation), and three more fail if the index comparison is dropped, so the narrowing is covered too.

[Reversean]

Spec and code match now, but plugin-block-data/design.md (line 58 and the same-key Risks entries) still says plugin data ops stay untransformed.

[Reversean]

This contradicts specs/block-settings/spec.md and specs/ui/spec.md.

Spec claims that

• BlockSettingsUI
  • renders button
  • tracks block selection
  • announces button via event
• ToolbarUI
  • reassigns its tab stop when the button joins

Design claims that ToolbarUI owns button and hovered block index.

I suppose design is the right one, but specs require sync.

[gohabereg]

Right that they contradict — but it's the other way round: the specs are current and design.md is stale, from before the ARIA work was folded into this change.

The code agrees with the specs: the button, its aria-haspopup/aria-expanded, the focus-before-open and the block it acts on all live in BlockSettingsUI, and ToolbarUI only mounts the two elements it's handed and reassigns its tab stop. There's no ui:block-settings:open dispatch from the toolbar at all.

I've updated design.md to match, and added the reasoning that was missing: a menu button's aria-expanded has to track the menu, and the menu's open state is the plugin's — split across the two, every open and close needs a round trip through the event bus to keep an attribute honest, and the button can end up reporting a block the menu wasn't built for. ToolbarUI treats it as a control of the container like its own plus button: named and operated by its owner, positioned and tab-managed by the toolbar.

Its remaining MenuConfig references are now BlockSettingsMenuConfig, and the claim that @editorjs/sdk owns the item shape is corrected — the SDK's MenuConfig is a different, narrower type for inline tools, which is why the UI's was renamed apart from it.

[Reversean]

proposal.md (lines 18–19, 31, 37) and tasks.md (3.1, line 49) still put the button in ToolbarUI.