@bloklabs/cli 1.15.1 → 1.16.0

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 import * as e from "node:fs";
 //#region src/cli/commands/migrationContent.ts
-var t = "# Migrating from EditorJS to Blok\n\nThis guide covers the breaking changes when migrating from EditorJS to Blok.\n\n## Table of Contents\n\n- [Supported Editor.js Versions](#supported-editorjs-versions)\n- [Core Changes](#core-changes)\n- [Data Attributes](#data-attributes)\n- [CSS Classes](#css-classes)\n- [Bundled Tools](#bundled-tools)\n  - [Tool Configuration](#tool-configuration)\n  - [Lifecycle Hooks](#lifecycle-hooks)\n  - [Delimiter → Divider](#delimiter--divider)\n- [Migrating Custom Tools](#migrating-custom-tools)\n  - [Custom Block Tools (port unchanged)](#custom-block-tools-port-unchanged)\n  - [Custom Inline Tools (breaking rewrite)](#custom-inline-tools-breaking-rewrite)\n- [Saved Content / Data Migration](#saved-content--data-migration)\n  - [Auto-Migrated on Load](#auto-migrated-on-load)\n  - [Dropped Fields](#dropped-fields)\n- [Configuration Defaults](#configuration-defaults)\n- [New API Methods](#new-api-methods)\n- [DOM Selectors](#dom-selectors)\n- [E2E Test Selectors](#e2e-test-selectors)\n\n---\n\n## Supported Editor.js Versions\n\nBlok targets the **Editor.js 2.x** line. The [codemod](./codemod) is built against the package versions a typical Editor.js 2.x project ships — `@editorjs/editorjs@^2.28.x`, `@editorjs/header@^2.8.x`, `@editorjs/paragraph@^2.11.x`, `@editorjs/list@^1.9.x` — and the runtime auto-migration reads the saved-data shapes those versions produce. Older 2.x data formats are still recognized; the matrix below describes coverage per block/tool, not per Editor.js point release.\n\nThere is no pinned single source version: Blok is API-compatible with the Editor.js 2.x `BlockTool` / `InlineTool` contracts, so what matters is **which tools your content uses**, covered below.\n\n### Compatibility Matrix\n\nHow each Editor.js block/tool is handled. \"Auto-migrated at runtime\" means the conversion happens on `render()` with no script needed; \"Codemod\" means the [codemod](./codemod) rewrites saved JSON; \"Drop-in unchanged\" means the data passes through as-is; \"Not bundled\" means Blok ships no equivalent tool, so you must register your own (a ported Editor.js block tool works unchanged — see [Migrating Custom Tools](#migrating-custom-tools)) or the block renders as a preserved stub with a `console.warn` and round-trips untouched on save.\n\n| Editor.js block / tool | Migration status | Notes |\n|------------------------|------------------|-------|\n| `paragraph` | Drop-in unchanged | Bundled as `Blok.Paragraph` (the default block). |\n| `header` | Drop-in unchanged | Bundled as `Blok.Header`. |\n| `list` (nested **and** string-array items) | Auto-migrated at runtime **+** codemod | Each item expands to a flat `list` block. Both list dialects are read: v1 (`data.start`, `item.checked`) and v2 / nested-list (`data.meta.start`, `item.meta.checked`). `meta.counterType` is dropped (warns) — Blok's ordered lists use decimal markers. |\n| `checklist` (standalone tool) | Auto-migrated at runtime **+** codemod | Becomes `list` blocks with checklist style. |\n| `toggleList` | Auto-migrated at runtime **+** codemod → `toggle` | Becomes a `toggle` block (or a toggle `header` when `titleVariant` is set); body blocks flatten into parented children. |\n| `callout` (legacy `body`/`variant` shape) | Auto-migrated at runtime **+** codemod | Legacy `{ body, variant, emoji }` → flat `{ emoji, textColor, backgroundColor }`; body blocks flatten into parented children. |\n| `image`, `simple-image` | Auto-migrated at runtime **+** codemod | `file.url` (or `simple-image`'s flat `url`) → `url`; `withBorder` → `frame`, `stretched: true` → `size: full`. `withBackground` is dropped (warns). |\n| `linkTool` | Auto-migrated at runtime **+** codemod → `bookmark` | `meta` flattens onto the bookmark shape; `meta.site_name` is dropped (warns). |\n| `delimiter` | Codemod renames type → `divider` | Data format is identical (`{}`). Also recognized at render, so existing data works without the rename. |\n| `quote` | Auto-migrated at runtime **+** codemod | `caption` becomes a trailing `paragraph` sibling; `alignment` is dropped (warns). The quote text/size render unchanged. |\n| `code` | Drop-in unchanged | Passes through to Blok's bundled `code` tool. |\n| `table` (HTML-string cells) | Auto-migrated at runtime **+** codemod | Each non-empty cell becomes a `{ blocks: [id] }` cell-ref plus a child `paragraph` (`parent` = table id); empty cells become `{ blocks: [] }`. `withHeadings` is preserved. Cells already in block-ref shape pass through. |\n| `embed` | Drop-in unchanged | Bundled as `Blok.Embed`. `{ service, source, embed, width, height, caption }` map 1:1; iframe providers render correctly (Blok-only fields default). |\n| `raw` | Auto-migrated at runtime **+** codemod → `code` | Blok has no raw tool; `{ html }` becomes a `code` block showing the markup as source verbatim. |\n| `warning` | Auto-migrated at runtime **+** codemod → `callout` | Becomes a ⚠️ orange `callout`; `title` and `message` become child `paragraph` blocks. |\n| `attaches` | Auto-migrated at runtime **+** codemod → `bookmark` | `file.url` + `title` map to a `bookmark`; file metadata (`name`/`size`/`extension`) is dropped (warns). |\n| `marker`, `inlineCode` (inline) | Not bundled | Register your own (port unchanged or wrap with `wrapLegacyInlineTool`). See [Custom Inline Tools](#custom-inline-tools). |\n| Other third-party block tools (`personality`, `button`, audio, …) | Not bundled | No built-in equivalent. Register a tool to render them; otherwise the block is preserved as a stub (warns) and survives a save/load round-trip. |\n\n> **Heads-up:** any block type Blok doesn't recognize and has no registered tool for renders as a stub and logs `Tool «<name>» is not found`. Its data is preserved, so registering the tool later restores the block.\n\n---\n\n## Core Changes\n\n### Class Name\n\n```diff\n- import EditorJS from '@editorjs/editorjs';\n+ import Blok from '@bloklabs/core';\n\n- const editor = new EditorJS({ ... });\n+ const editor = new Blok({ ... });\n```\n\n`Blok` is also exported as the **default export** and under an `EditorJS` alias, so you can keep your existing variable name and only change the import path — a minimal-diff, drop-in migration:\n\n```diff\n- import EditorJS from '@editorjs/editorjs';\n+ import { EditorJS } from '@bloklabs/core';\n\n  const editor = new EditorJS({ ... }); // unchanged\n```\n\n`import Blok`, `import { Blok }`, and `import { EditorJS }` all resolve to the same class.\n\n### Default Holder\n\nThe default holder ID changed from `editorjs` to `blok`:\n\n```diff\n- <div id=\"editorjs\"></div>\n+ <div id=\"blok\"></div>\n```\n\nOr specify explicitly:\n\n```javascript\nconst editor = new Blok({\n  holder: 'my-editor', // works the same as before\n});\n```\n\n### TypeScript Types\n\n```diff\n- import type { EditorConfig, OutputData } from '@editorjs/editorjs';\n+ import type { BlokConfig, OutputData } from '@bloklabs/core';\n```\n\n---\n\n## Data Attributes\n\nBlok uses `data-blok-*` attributes instead of EditorJS's mixed naming conventions.\n\n| EditorJS | Blok |\n|----------|------|\n| `data-id` | `data-blok-id` |\n| `data-item-name` | `data-blok-item-name` |\n| `data-empty` | `data-blok-empty` |\n| `.ce-block--selected` (class) | `data-blok-selected=\"true\"` |\n| — | `data-blok-component` (tool name) |\n| — | `data-blok-interface` (element type) |\n| — | `data-blok-testid` (testing) |\n| — | `data-blok-opened` (toolbar state) |\n| — | `data-blok-placeholder` |\n| — | `data-blok-stretched` |\n| — | `data-blok-focused` |\n| — | `data-blok-popover-opened` |\n| — | `data-blok-tool` (tool name on rendered element) |\n| — | `data-blok-dragging` (block being dragged) |\n| — | `data-blok-hidden` (hidden state) |\n| — | `data-blok-rtl` (RTL mode) |\n| — | `data-blok-drag-handle` (drag handle element) |\n| — | `data-blok-overlay` (selection overlay) |\n| — | `data-blok-overlay-rectangle` (selection rectangle) |\n\n### Querying Blocks\n\n```diff\n- document.querySelector('[data-id=\"abc123\"]');\n+ document.querySelector('[data-blok-id=\"abc123\"]');\n\n- document.querySelector('[data-item-name=\"bold\"]');\n+ document.querySelector('[data-blok-item-name=\"bold\"]');\n```\n\n---\n\n## CSS Classes\n\nBlok replaces BEM class names with data attributes for selection.\n\n### Editor Wrapper\n\n| EditorJS | Blok |\n|----------|------|\n| `.codex-editor` | `[data-blok-editor]` |\n| `.codex-editor__redactor` | `[data-blok-redactor]` |\n| `.codex-editor--rtl` | `[data-blok-rtl=\"true\"]` |\n\n### Block Elements\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-block` | `[data-blok-element]` |\n| `.ce-block--selected` | `[data-blok-selected=\"true\"]` |\n| `.ce-block--stretched` | `[data-blok-stretched=\"true\"]` |\n| `.ce-block--focused` | `[data-blok-focused=\"true\"]` |\n| `.ce-block__content` | `[data-blok-element-content]` |\n\n### Toolbar\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-toolbar` | `[data-blok-toolbar]` |\n| `.ce-toolbar__plus` | `[data-blok-testid=\"plus-button\"]` |\n| `.ce-toolbar__settings-btn` | `[data-blok-settings-toggler]` |\n| `.ce-toolbar__actions` | `[data-blok-testid=\"toolbar-actions\"]` |\n| `.ce-toolbox` | `[data-blok-toolbox]` |\n| `.ce-toolbox--opened` | `[data-blok-toolbox][data-blok-opened=\"true\"]` |\n\n### Inline Toolbar\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-inline-toolbar` | `[data-blok-testid=\"inline-toolbar\"]` |\n| `.ce-inline-tool` | `[data-blok-testid=\"inline-tool\"]` |\n| `.ce-inline-tool--link` | `[data-blok-testid=\"inline-tool-link\"]` |\n| `.ce-inline-tool--bold` | `[data-blok-testid=\"inline-tool-bold\"]` |\n| `.ce-inline-tool--italic` | `[data-blok-testid=\"inline-tool-italic\"]` |\n\n### Popover\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-popover` | `[data-blok-popover]` |\n| `.ce-popover--opened` | `[data-blok-popover][data-blok-opened=\"true\"]` |\n| `.ce-popover__container` | `[data-blok-popover-container]` |\n| `.ce-popover-item` | `[data-blok-testid=\"popover-item\"]` |\n| `.ce-popover-item--focused` | `[data-blok-focused=\"true\"]` |\n| `.ce-popover-item--confirmation` | `[data-blok-confirmation=\"true\"]` |\n| `.ce-popover-item__icon` | `[data-blok-testid=\"popover-item-icon\"]` |\n| `.ce-popover-item__icon--tool` | `[data-blok-testid=\"popover-item-icon-tool\"]` |\n\n### Tool-Specific Classes\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-paragraph` | `[data-blok-tool=\"paragraph\"]` |\n| `.ce-header` | `[data-blok-tool=\"header\"]` |\n\n### Conversion Toolbar & Settings\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-conversion-toolbar` | `[data-blok-testid=\"conversion-toolbar\"]` |\n| `.ce-conversion-tool` | `[data-blok-testid=\"conversion-tool\"]` |\n| `.ce-settings` | `[data-blok-testid=\"block-settings\"]` |\n| `.ce-tune` | `[data-blok-testid=\"block-tune\"]` |\n\n### Other Elements\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-stub` | `[data-blok-stub]` |\n| `.ce-drag-handle` | `[data-blok-drag-handle]` |\n| `.ce-ragged-right` | `[data-blok-ragged-right=\"true\"]` |\n\n### CDX List Classes\n\n| EditorJS | Blok |\n|----------|------|\n| `.cdx-list` | `[data-blok-list]` |\n| `.cdx-list__item` | `[data-blok-list-item]` |\n| `.cdx-list--ordered` | `[data-blok-list=\"ordered\"]` |\n| `.cdx-list--unordered` | `[data-blok-list=\"unordered\"]` |\n\n### CDX Utility Classes\n\n| EditorJS | Blok |\n|----------|------|\n| `.cdx-button` | `[data-blok-button]` |\n| `.cdx-input` | `[data-blok-input]` |\n| `.cdx-loader` | `[data-blok-loader]` |\n| `.cdx-search-field` | `[data-blok-search-field]` |\n\n---\n\n## Bundled Tools\n\nBlok includes Header and Paragraph tools. No external packages needed:\n\n```diff\n- import Header from '@editorjs/header';\n- import Paragraph from '@editorjs/paragraph';\n\n+ import Blok from '@bloklabs/core';\n\nconst editor = new Blok({\n  tools: {\n-   header: Header,\n-   paragraph: Paragraph,\n+   header: Blok.Header,\n+   paragraph: Blok.Paragraph, // optional, it's the default\n  },\n});\n```\n\n### Tool Configuration\n\nBoth bundled tools accept configuration options:\n\n#### HeaderConfig\n\n```typescript\nimport type { HeaderConfig } from '@bloklabs/core';\n\nconst editor = new Blok({\n  tools: {\n    header: {\n      class: Blok.Header,\n      config: {\n        placeholder: 'Enter a heading',\n        levels: [2, 3, 4],      // Restrict to H2-H4 only\n        defaultLevel: 2,        // Default to H2\n      } as HeaderConfig,\n    },\n  },\n});\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `placeholder` | `string` | `''` | Placeholder text for empty header |\n| `levels` | `number[]` | `[1,2,3,4,5,6]` | Available heading levels (1-6) |\n| `defaultLevel` | `number` | `2` | Default heading level |\n\n#### ParagraphConfig\n\n```typescript\nimport type { ParagraphConfig } from '@bloklabs/core';\n\nconst editor = new Blok({\n  tools: {\n    paragraph: {\n      class: Blok.Paragraph,\n      config: {\n        placeholder: 'Start typing...',\n        preserveBlank: true,\n      } as ParagraphConfig,\n    },\n  },\n});\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `placeholder` | `string` | `''` | Placeholder text for empty paragraph |\n| `preserveBlank` | `boolean` | `false` | Keep empty paragraphs when saving |\n\n### Delimiter → Divider\n\nEditor.js's `@editorjs/delimiter` is replaced by Blok's built-in `divider` tool:\n\n```diff\n- import Delimiter from '@editorjs/delimiter';\n\nconst editor = new Blok({\n  tools: {\n-   delimiter: Delimiter,\n+   divider: Blok.Divider,\n  },\n});\n```\n\n**Saved data migration:** The block type name changed from `\"delimiter\"` to `\"divider\"`. The data format is identical (empty `{}`):\n\n```diff\n  {\n-   \"type\": \"delimiter\",\n+   \"type\": \"divider\",\n    \"data\": {}\n  }\n```\n\n> **Note:** Blok automatically recognizes `\"delimiter\"` blocks and renders them as dividers, so existing articles work without data migration. However, renaming the type in your database is recommended for consistency.\n\n---\n\n## Migrating Custom Tools\n\nIf your project ships its own tools, here's what changes and what doesn't.\n\n### Custom Block Tools (port unchanged)\n\n**Custom block tools work as-is.** Blok's `BlockTool` interface keeps the same shape as EditorJS, read by the **same keys**:\n\n- Methods: `render()`, `save()`, `validate()`, `renderSettings()`, `merge()`, `onPaste()`, and the lifecycle hooks `rendered()`, `updated()`, `removed()`, `moved()`.\n- Statics: `toolbox`, `conversionConfig`, `pasteConfig`, `isReadOnlySupported`, `enableLineBreaks`.\n\nIn most cases you can drop your existing block tool into Blok without touching its code.\n\n#### New optional `setReadOnly(state)` method\n\nBlok adds an **optional** `setReadOnly(state: boolean)` method. It is not a breaking change:\n\n- **If you omit it**, read-only toggling still works — Blok falls back to a full re-render of the block (graceful degradation).\n- **If you implement it**, Blok performs a cheaper in-place toggle instead of re-rendering.\n\n```typescript\nclass MyTool {\n  // ...render / save / validate as before...\n\n  // Optional: enables the cheaper in-place read-only toggle\n  setReadOnly(state: boolean): void {\n    this.input.contentEditable = state ? 'false' : 'true';\n  }\n}\n```\n\n#### New optional statics\n\nTwo new **optional** statics exist for advanced cases; existing tools never need them:\n\n- `titleKey` — a translation key for the tool's toolbox title (i18n).\n- `provides` — lets one class register multiple block types.\n\n### Custom Inline Tools\n\n**This is the one API difference for custom tools.** EditorJS inline tools built a DOM button and used imperative `surround` / `checkState` / `renderActions` / `clear` methods. Blok's `InlineTool` (`types/tools/inline-tool.d.ts`) instead expects `render()` to return a declarative `MenuConfig` object with `onActivate` / `isActive` callbacks.\n\nYou have two paths:\n\n#### Fast path — wrap with `wrapLegacyInlineTool`\n\nTo keep an existing EditorJS inline tool working without a rewrite, wrap its class:\n\n```typescript\nimport { wrapLegacyInlineTool } from '@bloklabs/core';\nimport MarkerTool from './marker-tool'; // your existing EditorJS inline tool\n\nconst editor = new Blok({\n  tools: {\n    marker: wrapLegacyInlineTool(MarkerTool),\n  },\n});\n```\n\nThe shim adapts the legacy contract automatically: it calls your tool's `render()` for the icon, routes `onActivate` → `surround(range)` and `isActive` → `checkState(selection)`, and forwards the static `title` / `shortcut` / `sanitize`. Without wrapping, Blok silently skips a legacy `render()` that returns an `HTMLElement`, so the tool would vanish from the inline toolbar. `renderActions()` / `clear()` are not bridged.\n\n#### Native path — rewrite to `MenuConfig` (recommended)\n\nFor full access to Blok features (nested items, confirmation), port to the native shape:\n\n#### Before (EditorJS)\n\n```typescript\nclass MarkerTool {\n  static get isInline() { return true; }\n  static get title() { return 'Marker'; }\n\n  private button: HTMLButtonElement;\n\n  render(): HTMLElement {\n    this.button = document.createElement('button');\n    this.button.innerHTML = '<svg>...</svg>';\n    return this.button;\n  }\n\n  // Apply / remove formatting on the current range\n  surround(range: Range): void {\n    document.execCommand('backColor', false, '#ffd700');\n  }\n\n  // Reflect active state by inspecting the selection\n  checkState(selection: Selection): boolean {\n    const isActive = /* ...inspect selection... */;\n    this.button.classList.toggle('active', isActive);\n    return isActive;\n  }\n\n  renderActions(): HTMLElement { /* extra UI */ }\n  clear(): void { /* reset extra UI */ }\n}\n```\n\n#### After (Blok)\n\n```typescript\nimport type { InlineTool, MenuConfig } from '@bloklabs/core';\n\nclass MarkerTool implements InlineTool {\n  static isInline = true;\n  static title = 'Marker';\n  static titleKey = 'marker'; // optional i18n key\n\n  // render() now returns a MenuConfig object, not an HTMLElement\n  render(): MenuConfig {\n    return {\n      icon: '<svg>...</svg>',\n      name: 'marker',\n      // surround(range) logic moves here\n      onActivate: () => {\n        document.execCommand('backColor', false, '#ffd700');\n      },\n      // checkState(selection) logic moves here\n      isActive: () => {\n        const selection = window.getSelection();\n        return selection ? /* ...inspect selection... */ false : false;\n      },\n    };\n  }\n}\n```\n\n> See `src/components/inline-tools/inline-tool-bold.ts` for Blok's canonical inline tool. Its `render()` returns a `MenuConfig` with `onActivate` (apply/remove bold) and `isActive` (read the selection).\n\n#### Mapping reference\n\n| EditorJS | Blok |\n|----------|------|\n| `render()` returns an `HTMLElement` button | `render()` returns a `MenuConfig` `{ icon, name, onActivate, isActive }` |\n| `surround(range)` | logic moves into `onActivate()` |\n| `checkState(selection)` | logic moves into `isActive()` |\n| `renderActions()` / `clear()` | **removed** — no direct equivalent; use `MenuConfig` `children` for nested items |\n| `static get isInline()` / `static get title()` | still apply (plus optional `titleKey` for i18n) |\n\n#### Mark-shaped tools — skip the DOM plumbing entirely (`api.marks`)\n\nIf your inline tool wraps text in one element (a highlight `<span>`, a colour\n`<mark>`, a comment anchor), you no longer need to write any range logic.\nDescribe the wrapper as a `MarkSpec` and drive it through `api.marks`\n(`has` / `find` / `read` / `apply` / `remove` / `toggle`, all range-aware):\n\n```typescript\nclass HighlightTool {\n  static isInline = true;\n  static title = 'Highlight';\n  static sanitize = markSanitizerConfig(HIGHLIGHT); // derived, stays in sync\n\n  constructor({ api }) {\n    this.api = api;\n  }\n\n  render() {\n    return {\n      icon: '<svg>…</svg>',\n      name: 'highlight',\n      onActivate: () => this.api.marks.toggle(HIGHLIGHT),\n      isActive: () => this.api.marks.has(HIGHLIGHT),\n    };\n  }\n}\n\nconst HIGHLIGHT = { tag: 'span', className: 'my-highlight' };\n```\n\n(React consumers get the same thing as a single spec field:\n`createReactInlineTool({ …, mark: { tag: 'span', className: 'my-highlight' } })`.)\n\n**Behavioural note when porting hand-rolled range code onto `api.marks`.** The\nengine is *more correct* than typical hand-rolled implementations on\nselections that span a wrapper boundary — expect these deltas:\n\nBefore (typical hand-rolled tool):\n\n- A selection covering half a wrapper plus outside text unwrapped or re-wrapped\n  the WHOLE wrapper (formatting outside the selection was lost).\n- Toggling \"off\" on a partially covered wrapper removed the whole run.\n- `Ctrl+A` selections silently dropped trailing spaces from the formatted run\n  (Chromium/WebKit place the range end before trailing whitespace).\n\nAfter (`api.marks`):\n\n- Partially covered wrappers are split at the selection boundaries; text\n  outside the selection keeps its formatting.\n- `apply` and `remove` extend the range over browser-excluded trailing\n  whitespace, so the visible selection and the formatted run agree (and\n  toggling off never strands a whitespace-only wrapper).\n- Two specs sharing a wrapper family (same tag/classes, different declared\n  style property — e.g. text colour and background) compose on ONE element\n  instead of nesting or cancelling each other.\n- Legacy tag variants can be declared as the SAME mark via `aliasTags`\n  (e.g. `{ tag: 'strong', aliasTags: ['b'] }`): alias-tagged wrappers are\n  recognized, split and stripped like canonical ones, while newly created\n  wrappers always use `tag`. Blok's own Bold (`strong`+`b`) and Italic\n  (`i`+`em`) run on exactly this.\n\n---\n\n## Saved Content / Data Migration\n\nExisting EditorJS output data keeps working. Blok converts legacy block shapes to its own format **automatically when the block renders** — no migration script needed.\n\n### Auto-Migrated on Load\n\nThese EditorJS block types and data shapes are recognized and converted on `render()`:\n\n| EditorJS block / shape | Becomes in Blok |\n|------------------------|-----------------|\n| `list` (nested items **and** string-array items) | Blok `list` |\n| `checklist` (standalone tool) | Blok `list` (checklist style) |\n| `image` `{ file: { url }, withBorder, stretched }` | Blok `image` |\n| `table` (HTML-string cells) | Blok `table` |\n| `header` | Blok `header` |\n| `code` | Blok `code` |\n| `delimiter` | Blok `divider` |\n| `linkTool` | Blok `bookmark` |\n\nNo action is required — load your existing data and it renders correctly.\n\n### Dropped Fields\n\nA few EditorJS fields have no Blok equivalent and are **dropped** on load. The block still renders; only these specific fields are lost:\n\n| Block | Dropped field(s) |\n|-------|------------------|\n| `quote` | `caption`, `alignment` |\n| `image` | `withBackground` |\n| `linkTool` | `meta.site_name` |\n| `list` | `meta.counterType` (ordered-list marker style) |\n\nWhen migration drops one of these, Blok emits a `console.warn` (prefixed `[Blok migration]`) naming the block type and field, so the loss is visible in the console rather than silent. If you depend on any of these, capture them before migrating.\n\nFor an offline batch upgrade, take delivery of that report instead of reading the console — every dropped field arrives as data:\n\n```javascript\nimport { migrate } from '@bloklabs/core/migrate';\n\nconst { data, report } = migrate(storedDocument);\n\nreport.lossyFields; // [{ blockType: 'linkTool', field: 'meta.site_name', verb: 'dropped' }, …]\n```\n\n### Migrating Explicitly (`@bloklabs/core/migrate`)\n\nThe same transform the renderer runs at load is exported, so you can upgrade persisted records without opening an editor:\n\n```javascript\nimport {\n  migrate,\n  migrateLegacyBlocks,\n  migrateLegacyOutputData,\n  needsLegacyMigration,\n  matchLegacyRule,\n  LEGACY_GRAMMAR,\n} from '@bloklabs/core/migrate';\n```\n\nTwo kinds of rule compose here, and `migrate(data, options)` runs them in the one correct order:\n\n1. **Data rules** (`migrations`) rewrite a single block's `data` — old shape → new shape, keyed by block type. They run **first**.\n2. **Grammar rules** (`rules`) restructure the tree: change a block's `type`, split one block into several, absorb following siblings, recurse into container bodies.\n\nThat order is load-bearing, because data rules are keyed by block **type** and the grammar rewrites types (`linkTool` → `bookmark`) and explodes containers into many blocks. Run them the other way round and a rule keyed on a legacy type never fires — the type it named no longer exists — and the block stays silently unmigrated. Practically: data rules shape the grammar's **input** (repair a legacy field so a built-in rule can detect it); the grammar owns the **output** for types it rewrites, so extra fields a data rule adds are not merged into the target shape.\n\n```javascript\nlet n = 0;\nconst { data, report } = migrate(storedDocument, {\n  migrations: { myCard: (d) => ('name' in d ? { ...d, title: d.name } : d) },\n  rules: [alertRule],\n  // Supplying generateId makes the migration PURE: the same document migrates\n  // to an equal result every time, so you can compare stored vs. migrated.\n  generateId: () => `blk-${n++}`,\n});\n```\n\n#### Teaching it a legacy shape Blok doesn't know\n\nA grammar entry reuses the whole interpreter — container recursion, orphan re-parenting, 1:N splits, id minting — so you never re-implement the dispatch loop. Host entries are matched **before** the built-in table, so they can also override a built-in mapping.\n\n```javascript\nconst alertRule = {\n  legacyType: 'alert',\n  targetType: 'callout',\n  cardinality: '1:N',\n  contributesNesting: true,\n  lossyFields: [],\n  docNote: '`alert` → `callout` + message paragraph.',\n  detect: (block) => block.type === 'alert',\n  expand: (block, ctx) => {\n    const calloutId = block.id ?? ctx.generateId();\n    const childId = ctx.generateId();\n\n    return [\n      { id: calloutId, type: 'callout', data: { emoji: '🚨' }, content: [childId] },\n      { id: childId, type: 'paragraph', data: { text: block.data.message }, parent: calloutId },\n    ];\n  },\n};\n```\n\nFor a legacy container that stores its body as a **count of following siblings** (common in Editor.js-era tools), return `{ blocks, consumed }` — the interpreter skips exactly that many siblings, and `consumed` is clamped to what remains, so a truncated document can't over-consume:\n\n```javascript\nexpand: (block, ctx, { siblings, index }) => {\n  const id = block.id ?? ctx.generateId();\n  const followers = siblings.slice(index + 1, index + 1 + block.data.items);\n  const children = followers.map((child) => ({ ...child, id: child.id ?? ctx.generateId(), parent: id }));\n\n  return {\n    blocks: [{ id, type: 'toggle', data: { text: block.data.text }, content: children.map((c) => c.id) }, ...children],\n    consumed: followers.length,\n  };\n}\n```\n\n`matchLegacyRule(block, options?)` returns the entry claiming a single block (or `null`) — use it to dispatch per block instead of re-scanning the table each time. `LEGACY_GRAMMAR` is the built-in table itself, readable for coverage introspection.\n\n---\n\n## Configuration Defaults\n\n| Option | EditorJS | Blok |\n|--------|----------|------|\n| `holder` | `\"editorjs\"` | `\"blok\"` |\n| `defaultBlock` | `\"paragraph\"` | `\"paragraph\"` |\n\n---\n\n## New API Methods\n\nBlok exposes shorthand methods directly on the instance:\n\n```javascript\nconst editor = new Blok({ ... });\n\n// Shorthand methods\nawait editor.save();      // Same as editor.saver.save()\neditor.clear();           // Same as editor.blocks.clear()\nawait editor.render(data);// Same as editor.blocks.render(data)\neditor.focus();           // Same as editor.caret.focus()\n\n// Event methods\neditor.on('change', handler);   // Same as editor.events.on()\neditor.off('change', handler);  // Same as editor.events.off()\neditor.emit('custom', data);    // Same as editor.events.emit()\n```\n\n---\n\n## DOM Selectors\n\nBlok uses consistent `data-blok-interface` attributes for major UI components:\n\n```javascript\n// Find the editor wrapper\nconst editorWrapper = document.querySelector('[data-blok-interface=\"blok\"]');\n\n// Find inline toolbar\nconst inlineToolbar = document.querySelector('[data-blok-interface=\"inline-toolbar\"]');\n\n// Find tooltip\nconst tooltip = document.querySelector('[data-blok-interface=\"tooltip\"]');\n```\n\nThese selectors are stable and recommended for programmatic access to Blok's UI components.\n\n### Key Changes\n\n1. **Prefix custom classes** with `blok-` instead of `ce-` or `cdx-`\n2. **Use `data-blok-*`** attributes instead of `data-*`\n\n---\n\n## E2E Test Selectors\n\nUpdate your test selectors to use Blok's `data-blok-testid` attributes:\n\n| EditorJS | Blok |\n|----------|------|\n| `[data-cy=editorjs]` | `[data-blok-testid=\"blok-editor\"]` |\n| `.ce-block` | `[data-blok-element]` |\n| `.ce-block__content` | `[data-blok-element-content]` |\n| `.ce-toolbar` | `[data-blok-toolbar]` |\n| `.ce-toolbar__plus` | `[data-blok-testid=\"plus-button\"]` |\n| `.ce-toolbar__settings-btn` | `[data-blok-settings-toggler]` |\n| `.ce-toolbar__actions` | `[data-blok-testid=\"toolbar-actions\"]` |\n| `.ce-toolbox` | `[data-blok-toolbox]` |\n| `.ce-inline-toolbar` | `[data-blok-testid=\"inline-toolbar\"]` |\n| `.ce-popover` | `[data-blok-popover]` |\n| `.ce-popover-item` | `[data-blok-testid=\"popover-item\"]` |\n| `[data-item-name=\"...\"]` | `[data-blok-item-name=\"...\"]` |\n\n### Playwright Example\n\n```diff\n// EditorJS\n- await page.locator('[data-cy=editorjs] .ce-block').click();\n- await page.locator('.ce-toolbar__settings-btn').click();\n- await page.locator('[data-item-name=\"delete\"]').click();\n\n// Blok\n+ await page.locator('[data-blok-element]').click();\n+ await page.locator('[data-blok-settings-toggler]').click();\n+ await page.locator('[data-blok-item-name=\"delete\"]').click();\n```\n\n### Additional Test Selectors\n\n| Element | Selector |\n|---------|----------|\n| Block tunes popover | `[data-blok-testid=\"block-tunes-popover\"]` |\n| Popover search input | `[data-blok-testid=\"popover-search-input\"]` |\n| Popover item title | `[data-blok-testid=\"popover-item-title\"]` |\n| Popover overlay | `[data-blok-testid=\"popover-overlay\"]` |\n| Inline tool input | `[data-blok-testid=\"inline-tool-input\"]` |\n| Tooltip | `[data-blok-testid=\"tooltip\"]` |\n| Redactor | `[data-blok-testid=\"redactor\"]` |\n| Toolbox | `[data-blok-testid=\"toolbox\"]` |\n| Toolbox popover | `[data-blok-testid=\"toolbox-popover\"]` |\n| Selection overlay | `[data-blok-testid=\"overlay\"]` |\n| Selection rectangle | `[data-blok-testid=\"overlay-rectangle\"]` |\n\n---\n\n### State Selectors\n\n| State | Selector |\n|-------|----------|\n| Toolbar opened | `[data-blok-opened=\"true\"]` |\n| Block selected | `[data-blok-selected=\"true\"]` |\n| Popover opened | `[data-blok-popover-opened=\"true\"]` |\n| Item focused | `[data-blok-focused=\"true\"]` |\n| Item disabled | `[data-blok-disabled=\"true\"]` |\n| Nested popover | `[data-blok-nested=\"true\"]` |\n| Toolbox opened | `[data-blok-toolbox-opened=\"true\"]` |\n| Block dragging | `[data-blok-dragging=\"true\"]` |\n| Element hidden | `[data-blok-hidden=\"true\"]` |\n| RTL mode | `[data-blok-rtl=\"true\"]` |\n\n---\n\n## Quick Checklist\n\n- [ ] Replace `new EditorJS` with `new Blok`\n- [ ] Update imports from `@editorjs/*` to `@bloklabs/core`\n- [ ] Change holder from `editorjs` to `blok` (or specify explicitly)\n- [ ] Use bundled tools: `Blok.Header`, `Blok.Paragraph`\n- [ ] Replace `@editorjs/delimiter` with built-in `Blok.Divider`\n- [ ] Update `EditorConfig` type to `BlokConfig`\n- [ ] Replace `data-id` with `data-blok-id` in queries\n- [ ] Replace `data-item-name` with `data-blok-item-name`\n- [ ] Replace `.ce-*` selectors with `[data-blok-*]` attributes\n- [ ] Replace `.cdx-*` selectors with `[data-blok-*]` attributes\n- [ ] Update E2E test selectors\n", n = (e) => [
+var t = "# Migrating from EditorJS to Blok\n\nThis guide covers the breaking changes when migrating from EditorJS to Blok.\n\n## Table of Contents\n\n- [Supported Editor.js Versions](#supported-editorjs-versions)\n- [Core Changes](#core-changes)\n- [Data Attributes](#data-attributes)\n- [CSS Classes](#css-classes)\n- [Bundled Tools](#bundled-tools)\n  - [Tool Configuration](#tool-configuration)\n  - [Lifecycle Hooks](#lifecycle-hooks)\n  - [Delimiter → Divider](#delimiter--divider)\n- [Migrating Custom Tools](#migrating-custom-tools)\n  - [Custom Block Tools (port unchanged)](#custom-block-tools-port-unchanged)\n  - [Custom Inline Tools (breaking rewrite)](#custom-inline-tools-breaking-rewrite)\n- [Saved Content / Data Migration](#saved-content--data-migration)\n  - [Auto-Migrated on Load](#auto-migrated-on-load)\n  - [Dropped Fields](#dropped-fields)\n- [Rich Text Is Saved as Segments](#rich-text-is-saved-as-segments)\n  - [The Shape](#the-shape)\n  - [What Returns Segments](#what-returns-segments)\n  - [What Stays HTML](#what-stays-html)\n  - [Input Takes Both Shapes](#input-takes-both-shapes)\n  - [Custom Block Tools](#custom-block-tools)\n  - [Types](#types)\n  - [Controlled Components](#controlled-components)\n  - [Collaboration](#collaboration)\n  - [Converting Stored Documents](#converting-stored-documents)\n- [Configuration Defaults](#configuration-defaults)\n- [New API Methods](#new-api-methods)\n- [DOM Selectors](#dom-selectors)\n- [E2E Test Selectors](#e2e-test-selectors)\n\n---\n\n## Supported Editor.js Versions\n\nBlok targets the **Editor.js 2.x** line. The [codemod](./codemod) is built against the package versions a typical Editor.js 2.x project ships — `@editorjs/editorjs@^2.28.x`, `@editorjs/header@^2.8.x`, `@editorjs/paragraph@^2.11.x`, `@editorjs/list@^1.9.x` — and the runtime auto-migration reads the saved-data shapes those versions produce. Older 2.x data formats are still recognized; the matrix below describes coverage per block/tool, not per Editor.js point release.\n\nThere is no pinned single source version: Blok is API-compatible with the Editor.js 2.x `BlockTool` / `InlineTool` contracts, so what matters is **which tools your content uses**, covered below.\n\n### Compatibility Matrix\n\nHow each Editor.js block/tool is handled. \"Auto-migrated at runtime\" means the conversion happens on `render()` with no script needed; \"Codemod\" means the [codemod](./codemod) rewrites saved JSON; \"Drop-in unchanged\" means the data passes through as-is; \"Not bundled\" means Blok ships no equivalent tool, so you must register your own (a ported Editor.js block tool works unchanged — see [Migrating Custom Tools](#migrating-custom-tools)) or the block renders as a preserved stub with a `console.warn` and round-trips untouched on save.\n\n| Editor.js block / tool | Migration status | Notes |\n|------------------------|------------------|-------|\n| `paragraph` | Drop-in unchanged | Bundled as `Blok.Paragraph` (the default block). |\n| `header` | Drop-in unchanged | Bundled as `Blok.Header`. |\n| `list` (nested **and** string-array items) | Auto-migrated at runtime **+** codemod | Each item expands to a flat `list` block. Both list dialects are read: v1 (`data.start`, `item.checked`) and v2 / nested-list (`data.meta.start`, `item.meta.checked`). `meta.counterType` is dropped (warns) — Blok's ordered lists use decimal markers. |\n| `checklist` (standalone tool) | Auto-migrated at runtime **+** codemod | Becomes `list` blocks with checklist style. |\n| `toggleList` | Auto-migrated at runtime **+** codemod → `toggle` | Becomes a `toggle` block (or a toggle `header` when `titleVariant` is set); body blocks flatten into parented children. |\n| `callout` (legacy `body`/`variant` shape) | Auto-migrated at runtime **+** codemod | Legacy `{ title, body, variant, emoji }` → flat `{ emoji, textColor, backgroundColor }`; a non-empty `title` becomes the first child paragraph, then body blocks flatten into parented children. |\n| `image`, `simple-image` | Auto-migrated at runtime **+** codemod | `file.url` (or `simple-image`'s flat `url`) → `url`; `withBorder` → `frame`, `stretched: true` → `size: full`. `withBackground` is dropped (warns). |\n| `linkTool` | Auto-migrated at runtime **+** codemod → `bookmark` | `meta` flattens onto the bookmark shape; `meta.site_name` is dropped (warns). |\n| `delimiter` | Codemod renames type → `divider` | Data format is identical (`{}`). Also recognized at render, so existing data works without the rename. |\n| `quote` | Auto-migrated at runtime **+** codemod | `caption` becomes a trailing `paragraph` sibling; `alignment` is dropped (warns). The quote text/size render unchanged. |\n| `code` | Drop-in unchanged | Passes through to Blok's bundled `code` tool. |\n| `table` (HTML-string cells) | Auto-migrated at runtime **+** codemod | Each non-empty cell becomes a `{ blocks: [ids] }` cell-ref plus child blocks (`parent` = table id). In the editor and `migrate()` with a DOM, lines and lists in the cell become separate `paragraph`/`list` blocks; the codemod (no DOM) keeps the cell as one `paragraph`; empty cells become `{ blocks: [] }`. `withHeadings` is preserved. Cells already in block-ref shape pass through. |\n| `embed` | Drop-in unchanged | Bundled as `Blok.Embed`. `{ service, source, embed, width, height, caption }` map 1:1; iframe providers render correctly (Blok-only fields default). |\n| `raw` | Auto-migrated at runtime **+** codemod → `code` | Blok has no raw tool; `{ html }` becomes a `code` block showing the markup as source verbatim. |\n| `warning` | Auto-migrated at runtime **+** codemod → `callout` | Becomes a ⚠️ orange `callout`; `title` and `message` become child `paragraph` blocks. |\n| `attaches` | Auto-migrated at runtime **+** codemod → `bookmark` | `file.url` + `title` map to a `bookmark`; file metadata (`name`/`size`/`extension`) is dropped (warns). |\n| `marker`, `inlineCode` (inline) | Not bundled | Register your own (port unchanged or wrap with `wrapLegacyInlineTool`). See [Custom Inline Tools](#custom-inline-tools). |\n| Other third-party block tools (`personality`, `button`, audio, …) | Not bundled | No built-in equivalent. Register a tool to render them; otherwise the block is preserved as a stub (warns) and survives a save/load round-trip. |\n\n> **Heads-up:** any block type Blok doesn't recognize and has no registered tool for renders as a stub and logs `Tool «<name>» is not found`. Its data is preserved, so registering the tool later restores the block.\n\n---\n\n## Core Changes\n\n### Class Name\n\n```diff\n- import EditorJS from '@editorjs/editorjs';\n+ import Blok from '@bloklabs/core';\n\n- const editor = new EditorJS({ ... });\n+ const editor = new Blok({ ... });\n```\n\n`Blok` is also exported as the **default export** and under an `EditorJS` alias, so you can keep your existing variable name and only change the import path — a minimal-diff, drop-in migration:\n\n```diff\n- import EditorJS from '@editorjs/editorjs';\n+ import { EditorJS } from '@bloklabs/core';\n\n  const editor = new EditorJS({ ... }); // unchanged\n```\n\n`import Blok`, `import { Blok }`, and `import { EditorJS }` all resolve to the same class.\n\n### Default Holder\n\nThe default holder ID changed from `editorjs` to `blok`:\n\n```diff\n- <div id=\"editorjs\"></div>\n+ <div id=\"blok\"></div>\n```\n\nOr specify explicitly:\n\n```javascript\nconst editor = new Blok({\n  holder: 'my-editor', // works the same as before\n});\n```\n\n### TypeScript Types\n\n```diff\n- import type { EditorConfig, OutputData } from '@editorjs/editorjs';\n+ import type { BlokConfig, OutputData } from '@bloklabs/core';\n```\n\n---\n\n## Data Attributes\n\nBlok uses `data-blok-*` attributes instead of EditorJS's mixed naming conventions.\n\n| EditorJS | Blok |\n|----------|------|\n| `data-id` | `data-blok-id` |\n| `data-item-name` | `data-blok-item-name` |\n| `data-empty` | `data-blok-empty` |\n| `.ce-block--selected` (class) | `data-blok-selected=\"true\"` |\n| — | `data-blok-component` (tool name) |\n| — | `data-blok-interface` (element type) |\n| — | `data-blok-testid` (testing) |\n| — | `data-blok-opened` (toolbar state) |\n| — | `data-blok-placeholder` |\n| — | `data-blok-stretched` |\n| — | `data-blok-focused` |\n| — | `data-blok-popover-opened` |\n| — | `data-blok-tool` (tool name on rendered element) |\n| — | `data-blok-dragging` (block being dragged) |\n| — | `data-blok-hidden` (hidden state) |\n| — | `data-blok-rtl` (RTL mode) |\n| — | `data-blok-drag-handle` (drag handle element) |\n| — | `data-blok-overlay` (selection overlay) |\n| — | `data-blok-overlay-rectangle` (selection rectangle) |\n\n### Querying Blocks\n\n```diff\n- document.querySelector('[data-id=\"abc123\"]');\n+ document.querySelector('[data-blok-id=\"abc123\"]');\n\n- document.querySelector('[data-item-name=\"bold\"]');\n+ document.querySelector('[data-blok-item-name=\"bold\"]');\n```\n\n---\n\n## CSS Classes\n\nBlok replaces BEM class names with data attributes for selection.\n\n### Editor Wrapper\n\n| EditorJS | Blok |\n|----------|------|\n| `.codex-editor` | `[data-blok-editor]` |\n| `.codex-editor__redactor` | `[data-blok-redactor]` |\n| `.codex-editor--rtl` | `[data-blok-rtl=\"true\"]` |\n\n### Block Elements\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-block` | `[data-blok-element]` |\n| `.ce-block--selected` | `[data-blok-selected=\"true\"]` |\n| `.ce-block--stretched` | `[data-blok-stretched=\"true\"]` |\n| `.ce-block--focused` | `[data-blok-focused=\"true\"]` |\n| `.ce-block__content` | `[data-blok-element-content]` |\n\n### Toolbar\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-toolbar` | `[data-blok-toolbar]` |\n| `.ce-toolbar__plus` | `[data-blok-testid=\"plus-button\"]` |\n| `.ce-toolbar__settings-btn` | `[data-blok-settings-toggler]` |\n| `.ce-toolbar__actions` | `[data-blok-testid=\"toolbar-actions\"]` |\n| `.ce-toolbox` | `[data-blok-toolbox]` |\n| `.ce-toolbox--opened` | `[data-blok-toolbox][data-blok-opened=\"true\"]` |\n\n### Inline Toolbar\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-inline-toolbar` | `[data-blok-testid=\"inline-toolbar\"]` |\n| `.ce-inline-tool` | `[data-blok-testid=\"inline-tool\"]` |\n| `.ce-inline-tool--link` | `[data-blok-testid=\"inline-tool-link\"]` |\n| `.ce-inline-tool--bold` | `[data-blok-testid=\"inline-tool-bold\"]` |\n| `.ce-inline-tool--italic` | `[data-blok-testid=\"inline-tool-italic\"]` |\n\n### Popover\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-popover` | `[data-blok-popover]` |\n| `.ce-popover--opened` | `[data-blok-popover][data-blok-opened=\"true\"]` |\n| `.ce-popover__container` | `[data-blok-popover-container]` |\n| `.ce-popover-item` | `[data-blok-testid=\"popover-item\"]` |\n| `.ce-popover-item--focused` | `[data-blok-focused=\"true\"]` |\n| `.ce-popover-item--confirmation` | `[data-blok-confirmation=\"true\"]` |\n| `.ce-popover-item__icon` | `[data-blok-testid=\"popover-item-icon\"]` |\n| `.ce-popover-item__icon--tool` | `[data-blok-testid=\"popover-item-icon-tool\"]` |\n\n### Tool-Specific Classes\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-paragraph` | `[data-blok-tool=\"paragraph\"]` |\n| `.ce-header` | `[data-blok-tool=\"header\"]` |\n\n### Conversion Toolbar & Settings\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-conversion-toolbar` | `[data-blok-testid=\"conversion-toolbar\"]` |\n| `.ce-conversion-tool` | `[data-blok-testid=\"conversion-tool\"]` |\n| `.ce-settings` | `[data-blok-testid=\"block-settings\"]` |\n| `.ce-tune` | `[data-blok-testid=\"block-tune\"]` |\n\n### Other Elements\n\n| EditorJS | Blok |\n|----------|------|\n| `.ce-stub` | `[data-blok-stub]` |\n| `.ce-drag-handle` | `[data-blok-drag-handle]` |\n| `.ce-ragged-right` | `[data-blok-ragged-right=\"true\"]` |\n\n### CDX List Classes\n\n| EditorJS | Blok |\n|----------|------|\n| `.cdx-list` | `[data-blok-list]` |\n| `.cdx-list__item` | `[data-blok-list-item]` |\n| `.cdx-list--ordered` | `[data-blok-list=\"ordered\"]` |\n| `.cdx-list--unordered` | `[data-blok-list=\"unordered\"]` |\n\n### CDX Utility Classes\n\n| EditorJS | Blok |\n|----------|------|\n| `.cdx-button` | `[data-blok-button]` |\n| `.cdx-input` | `[data-blok-input]` |\n| `.cdx-loader` | `[data-blok-loader]` |\n| `.cdx-search-field` | `[data-blok-search-field]` |\n\n---\n\n## Bundled Tools\n\nBlok includes Header and Paragraph tools. No external packages needed:\n\n```diff\n- import Header from '@editorjs/header';\n- import Paragraph from '@editorjs/paragraph';\n\n+ import Blok from '@bloklabs/core';\n\nconst editor = new Blok({\n  tools: {\n-   header: Header,\n-   paragraph: Paragraph,\n+   header: Blok.Header,\n+   paragraph: Blok.Paragraph, // optional, it's the default\n  },\n});\n```\n\n### Tool Configuration\n\nBoth bundled tools accept configuration options:\n\n#### HeaderConfig\n\n```typescript\nimport type { HeaderConfig } from '@bloklabs/core';\n\nconst editor = new Blok({\n  tools: {\n    header: {\n      class: Blok.Header,\n      config: {\n        placeholder: 'Enter a heading',\n        levels: [2, 3, 4],      // Restrict to H2-H4 only\n        defaultLevel: 2,        // Default to H2\n      } as HeaderConfig,\n    },\n  },\n});\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `placeholder` | `string` | `''` | Placeholder text for empty header |\n| `levels` | `number[]` | `[1,2,3,4,5,6]` | Available heading levels (1-6) |\n| `defaultLevel` | `number` | `2` | Default heading level |\n\n#### ParagraphConfig\n\n```typescript\nimport type { ParagraphConfig } from '@bloklabs/core';\n\nconst editor = new Blok({\n  tools: {\n    paragraph: {\n      class: Blok.Paragraph,\n      config: {\n        placeholder: 'Start typing...',\n        preserveBlank: true,\n      } as ParagraphConfig,\n    },\n  },\n});\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `placeholder` | `string` | `''` | Placeholder text for empty paragraph |\n| `preserveBlank` | `boolean` | `false` | Keep empty paragraphs when saving |\n\n### Delimiter → Divider\n\nEditor.js's `@editorjs/delimiter` is replaced by Blok's built-in `divider` tool:\n\n```diff\n- import Delimiter from '@editorjs/delimiter';\n\nconst editor = new Blok({\n  tools: {\n-   delimiter: Delimiter,\n+   divider: Blok.Divider,\n  },\n});\n```\n\n**Saved data migration:** The block type name changed from `\"delimiter\"` to `\"divider\"`. The data format is identical (empty `{}`):\n\n```diff\n  {\n-   \"type\": \"delimiter\",\n+   \"type\": \"divider\",\n    \"data\": {}\n  }\n```\n\n> **Note:** Blok automatically recognizes `\"delimiter\"` blocks and renders them as dividers, so existing articles work without data migration. However, renaming the type in your database is recommended for consistency.\n\n---\n\n## Migrating Custom Tools\n\nIf your project ships its own tools, here's what changes and what doesn't.\n\n### Custom Block Tools (port unchanged)\n\n**Custom block tools work as-is.** Blok's `BlockTool` interface keeps the same shape as EditorJS, read by the **same keys**:\n\n- Methods: `render()`, `save()`, `validate()`, `renderSettings()`, `merge()`, `onPaste()`, and the lifecycle hooks `rendered()`, `updated()`, `removed()`, `moved()`.\n- Statics: `toolbox`, `conversionConfig`, `pasteConfig`, `isReadOnlySupported`, `enableLineBreaks`.\n\nIn most cases you can drop your existing block tool into Blok without touching its code.\n\n#### New optional `setReadOnly(state)` method\n\nBlok adds an **optional** `setReadOnly(state: boolean)` method. It is not a breaking change:\n\n- **If you omit it**, read-only toggling still works — Blok falls back to a full re-render of the block (graceful degradation).\n- **If you implement it**, Blok performs a cheaper in-place toggle instead of re-rendering.\n\n```typescript\nclass MyTool {\n  // ...render / save / validate as before...\n\n  // Optional: enables the cheaper in-place read-only toggle\n  setReadOnly(state: boolean): void {\n    this.input.contentEditable = state ? 'false' : 'true';\n  }\n}\n```\n\n#### New optional statics\n\nTwo new **optional** statics exist for advanced cases; existing tools never need them:\n\n- `titleKey` — a translation key for the tool's toolbox title (i18n).\n- `provides` — lets one class register multiple block types.\n\n### Custom Inline Tools\n\n**This is the one API difference for custom tools.** EditorJS inline tools built a DOM button and used imperative `surround` / `checkState` / `renderActions` / `clear` methods. Blok's `InlineTool` (`types/tools/inline-tool.d.ts`) instead expects `render()` to return a declarative `MenuConfig` object with `onActivate` / `isActive` callbacks.\n\nYou have two paths:\n\n#### Fast path — wrap with `wrapLegacyInlineTool`\n\nTo keep an existing EditorJS inline tool working without a rewrite, wrap its class:\n\n```typescript\nimport { wrapLegacyInlineTool } from '@bloklabs/core';\nimport MarkerTool from './marker-tool'; // your existing EditorJS inline tool\n\nconst editor = new Blok({\n  tools: {\n    marker: wrapLegacyInlineTool(MarkerTool),\n  },\n});\n```\n\nThe shim adapts the legacy contract automatically: it calls your tool's `render()` for the icon, routes `onActivate` → `surround(range)` and `isActive` → `checkState(selection)`, and forwards the static `title` / `shortcut` / `sanitize`. Without wrapping, Blok silently skips a legacy `render()` that returns an `HTMLElement`, so the tool would vanish from the inline toolbar. `renderActions()` / `clear()` are not bridged.\n\n#### Native path — rewrite to `MenuConfig` (recommended)\n\nFor full access to Blok features (nested items, confirmation), port to the native shape:\n\n#### Before (EditorJS)\n\n```typescript\nclass MarkerTool {\n  static get isInline() { return true; }\n  static get title() { return 'Marker'; }\n\n  private button: HTMLButtonElement;\n\n  render(): HTMLElement {\n    this.button = document.createElement('button');\n    this.button.innerHTML = '<svg>...</svg>';\n    return this.button;\n  }\n\n  // Apply / remove formatting on the current range\n  surround(range: Range): void {\n    document.execCommand('backColor', false, '#ffd700');\n  }\n\n  // Reflect active state by inspecting the selection\n  checkState(selection: Selection): boolean {\n    const isActive = /* ...inspect selection... */;\n    this.button.classList.toggle('active', isActive);\n    return isActive;\n  }\n\n  renderActions(): HTMLElement { /* extra UI */ }\n  clear(): void { /* reset extra UI */ }\n}\n```\n\n#### After (Blok)\n\n```typescript\nimport type { InlineTool, MenuConfig } from '@bloklabs/core';\n\nclass MarkerTool implements InlineTool {\n  static isInline = true;\n  static title = 'Marker';\n  static titleKey = 'marker'; // optional i18n key\n\n  // render() now returns a MenuConfig object, not an HTMLElement\n  render(): MenuConfig {\n    return {\n      icon: '<svg>...</svg>',\n      name: 'marker',\n      // surround(range) logic moves here\n      onActivate: () => {\n        document.execCommand('backColor', false, '#ffd700');\n      },\n      // checkState(selection) logic moves here\n      isActive: () => {\n        const selection = window.getSelection();\n        return selection ? /* ...inspect selection... */ false : false;\n      },\n    };\n  }\n}\n```\n\n> See `src/components/inline-tools/inline-tool-bold.ts` for Blok's canonical inline tool. Its `render()` returns a `MenuConfig` with `onActivate` (apply/remove bold) and `isActive` (read the selection).\n\n#### Mapping reference\n\n| EditorJS | Blok |\n|----------|------|\n| `render()` returns an `HTMLElement` button | `render()` returns a `MenuConfig` `{ icon, name, onActivate, isActive }` |\n| `surround(range)` | logic moves into `onActivate()` |\n| `checkState(selection)` | logic moves into `isActive()` |\n| `renderActions()` / `clear()` | **removed** — no direct equivalent; use `MenuConfig` `children` for nested items |\n| `static get isInline()` / `static get title()` | still apply (plus optional `titleKey` for i18n) |\n\n#### Mark-shaped tools — skip the DOM plumbing entirely (`api.marks`)\n\nIf your inline tool wraps text in one element (a highlight `<span>`, a colour\n`<mark>`, a comment anchor), you no longer need to write any range logic.\nDescribe the wrapper as a `MarkSpec` and drive it through `api.marks`\n(`has` / `find` / `read` / `apply` / `remove` / `toggle`, all range-aware):\n\n```typescript\nclass HighlightTool {\n  static isInline = true;\n  static title = 'Highlight';\n  static sanitize = markSanitizerConfig(HIGHLIGHT); // derived, stays in sync\n\n  constructor({ api }) {\n    this.api = api;\n  }\n\n  render() {\n    return {\n      icon: '<svg>…</svg>',\n      name: 'highlight',\n      onActivate: () => this.api.marks.toggle(HIGHLIGHT),\n      isActive: () => this.api.marks.has(HIGHLIGHT),\n    };\n  }\n}\n\nconst HIGHLIGHT = { tag: 'span', className: 'my-highlight' };\n```\n\n(React consumers get the same thing as a single spec field:\n`createReactInlineTool({ …, mark: { tag: 'span', className: 'my-highlight' } })`.)\n\n**Behavioural note when porting hand-rolled range code onto `api.marks`.** The\nengine is *more correct* than typical hand-rolled implementations on\nselections that span a wrapper boundary — expect these deltas:\n\nBefore (typical hand-rolled tool):\n\n- A selection covering half a wrapper plus outside text unwrapped or re-wrapped\n  the WHOLE wrapper (formatting outside the selection was lost).\n- Toggling \"off\" on a partially covered wrapper removed the whole run.\n- `Ctrl+A` selections silently dropped trailing spaces from the formatted run\n  (Chromium/WebKit place the range end before trailing whitespace).\n\nAfter (`api.marks`):\n\n- Partially covered wrappers are split at the selection boundaries; text\n  outside the selection keeps its formatting.\n- `apply` and `remove` extend the range over browser-excluded trailing\n  whitespace, so the visible selection and the formatted run agree (and\n  toggling off never strands a whitespace-only wrapper).\n- Two specs sharing a wrapper family (same tag/classes, different declared\n  style property — e.g. text colour and background) compose on ONE element\n  instead of nesting or cancelling each other.\n- Legacy tag variants can be declared as the SAME mark via `aliasTags`\n  (e.g. `{ tag: 'strong', aliasTags: ['b'] }`): alias-tagged wrappers are\n  recognized, split and stripped like canonical ones, while newly created\n  wrappers always use `tag`. Blok's own Bold (`strong`+`b`) and Italic\n  (`i`+`em`) run on exactly this.\n\n---\n\n## Saved Content / Data Migration\n\nExisting EditorJS output data keeps working. Blok converts legacy block shapes to its own format **automatically when the block renders** — no migration script needed.\n\n### Auto-Migrated on Load\n\nThese EditorJS block types and data shapes are recognized and converted on `render()`:\n\n| EditorJS block / shape | Becomes in Blok |\n|------------------------|-----------------|\n| `list` (nested items **and** string-array items) | Blok `list` |\n| `checklist` (standalone tool) | Blok `list` (checklist style) |\n| `image` `{ file: { url }, withBorder, stretched }` | Blok `image` |\n| `table` (HTML-string cells) | Blok `table` |\n| `header` | Blok `header` |\n| `code` | Blok `code` |\n| `delimiter` | Blok `divider` |\n| `linkTool` | Blok `bookmark` |\n\nNo action is required — load your existing data and it renders correctly.\n\n### Dropped Fields\n\nA few EditorJS fields have no Blok equivalent and are **dropped** on load. The block still renders; only these specific fields are lost:\n\n| Block | Dropped field(s) |\n|-------|------------------|\n| `quote` | `caption`, `alignment` |\n| `image` | `withBackground` |\n| `linkTool` | `meta.site_name` |\n| `list` | `meta.counterType` (ordered-list marker style) |\n\nWhen migration drops one of these, Blok emits a `console.warn` (prefixed `[Blok migration]`) naming the block type and field, so the loss is visible in the console rather than silent. If you depend on any of these, capture them before migrating.\n\nFor an offline batch upgrade, take delivery of that report instead of reading the console — every dropped field arrives as data:\n\n```javascript\nimport { migrate } from '@bloklabs/core/migrate';\n\nconst { data, report } = migrate(storedDocument);\n\nreport.lossyFields; // [{ blockType: 'linkTool', field: 'meta.site_name', verb: 'dropped' }, …]\n```\n\n### Migrating Explicitly (`@bloklabs/core/migrate`)\n\nThe same transform the renderer runs at load is exported, so you can upgrade persisted records without opening an editor:\n\n```javascript\nimport {\n  migrate,\n  migrateLegacyBlocks,\n  migrateLegacyOutputData,\n  needsLegacyMigration,\n  matchLegacyRule,\n  LEGACY_GRAMMAR,\n} from '@bloklabs/core/migrate';\n```\n\nTwo kinds of rule compose here, and `migrate(data, options)` runs them in the one correct order:\n\n1. **Data rules** (`migrations`) rewrite a single block's `data` — old shape → new shape, keyed by block type. They run **first**.\n2. **Grammar rules** (`rules`) restructure the tree: change a block's `type`, split one block into several, absorb following siblings, recurse into container bodies.\n\nThat order is load-bearing, because data rules are keyed by block **type** and the grammar rewrites types (`linkTool` → `bookmark`) and explodes containers into many blocks. Run them the other way round and a rule keyed on a legacy type never fires — the type it named no longer exists — and the block stays silently unmigrated. Practically: data rules shape the grammar's **input** (repair a legacy field so a built-in rule can detect it); the grammar owns the **output** for types it rewrites, so extra fields a data rule adds are not merged into the target shape.\n\n```javascript\nlet n = 0;\nconst { data, report } = migrate(storedDocument, {\n  migrations: { myCard: (d) => ('name' in d ? { ...d, title: d.name } : d) },\n  rules: [alertRule],\n  // Supplying generateId makes the migration PURE: the same document migrates\n  // to an equal result every time, so you can compare stored vs. migrated.\n  generateId: () => `blk-${n++}`,\n});\n```\n\n#### Teaching it a legacy shape Blok doesn't know\n\nA grammar entry reuses the whole interpreter — container recursion, orphan re-parenting, 1:N splits, id minting — so you never re-implement the dispatch loop. Host entries are matched **before** the built-in table, so they can also override a built-in mapping.\n\n```javascript\nconst alertRule = {\n  legacyType: 'alert',\n  targetType: 'callout',\n  cardinality: '1:N',\n  contributesNesting: true,\n  lossyFields: [],\n  docNote: '`alert` → `callout` + message paragraph.',\n  detect: (block) => block.type === 'alert',\n  expand: (block, ctx) => {\n    const calloutId = block.id ?? ctx.generateId();\n    const childId = ctx.generateId();\n\n    return [\n      { id: calloutId, type: 'callout', data: { emoji: '🚨' }, content: [childId] },\n      { id: childId, type: 'paragraph', data: { text: block.data.message }, parent: calloutId },\n    ];\n  },\n};\n```\n\nFor a legacy container that stores its body as a **count of following siblings** (common in Editor.js-era tools), return `{ blocks, consumed }` — the interpreter skips exactly that many siblings, and `consumed` is clamped to what remains, so a truncated document can't over-consume:\n\n```javascript\nexpand: (block, ctx, { siblings, index }) => {\n  const id = block.id ?? ctx.generateId();\n  const followers = siblings.slice(index + 1, index + 1 + block.data.items);\n  const children = followers.map((child) => ({ ...child, id: child.id ?? ctx.generateId(), parent: id }));\n\n  return {\n    blocks: [{ id, type: 'toggle', data: { text: block.data.text }, content: children.map((c) => c.id) }, ...children],\n    consumed: followers.length,\n  };\n}\n```\n\n`matchLegacyRule(block, options?)` returns the entry claiming a single block (or `null`) — use it to dispatch per block instead of re-scanning the table each time. `LEGACY_GRAMMAR` is the built-in table itself, readable for coverage introspection.\n\n---\n\n## Rich Text Is Saved as Segments\n\n**Breaking.** Rich text fields such as `paragraph.text` used to save as an inline HTML string. They now save as an array of runs, called segments. There is no flag to turn this off.\n\n```javascript\nconst data = await editor.save();\n// data.blocks[0].data.text\n//=> [{ text: 'Hello ' }, { text: 'world', marks: { bold: true } }]\n```\n\nThis breaks you if your code reads `text` as a string. That includes server code that reads stored documents, search indexing, and previews. Read on for what to change.\n\n### The Shape\n\nThe types are `RichText`, `RichTextSegment` and `RichTextMarks`, exported from `@bloklabs/core`.\n\n- A text run is `{ text, marks? }`. Line breaks are `\"\\n\"`.\n- `marks` holds `bold`, `italic`, `underline`, `strikethrough`, `code`, `sup`, `sub` and `highlight` (a plain `<mark>`), each `true`.\n- `color` and `background` are separate keys. Each is a Blok preset name such as `'red'`, or any CSS colour.\n- `link` is `{ href, rel?, target? }`.\n- A custom inline tool's tag is stored as `\"tag:<name>\": { <attribute>: <value> }`.\n- An inline object is `{ embed: { equation: { expression } } }`, `{ embed: { page: { id } } }` or `{ embed: { html } }`. The `html` embed keeps markup that has no mark, such as an `<img>`, verbatim.\n\nThese fields become segments: `text` on `paragraph`, `header`, `list`, `toggle` and `quote`. Table cells and plain-text fields such as captions stay strings.\n\n### What Returns Segments\n\nEvery place that hands saved data to your code returns segments:\n\n- `editor.save()`, `onSave` and `onSubmit`.\n- `BlockAPI.save()`, including `target.save()` inside `onChange`.\n- `getBlockData` from `useBlocks` in the React, Vue and Angular adapters. Its `.data` can be a new object on each call, so do not use it as a memo dependency.\n- The value `importMarkdown()` returns.\n- `htmlToBlocks()` from `@bloklabs/core/view` and `markdownToBlocks()` from `@bloklabs/core/markdown`.\n- The C# `FromHtmlAsync` and `FromMarkdownAsync`.\n- Collaboration: what the editor saves, what the server writes to your document endpoint, and `GET /sync/{doc}/state`.\n\nWith `dataModel: 'legacy'` (or `'auto'` with legacy input), the legacy shapes hold segments too: list `items[].content`, `toggleList.title` and the blocks in `body.blocks`. Blok and `@bloklabs/core/view` read them back without loss.\n\n`exportMarkdown()` is unchanged. `@bloklabs/core/view` (`blocksToHtml`, plain text, markdown, outline) reads both shapes in built-in block types. A custom block type's fields reach your renderer as stored. The C# server runtime reads both shapes.\n\n### What Stays HTML\n\n- `BlockAPI.preservedData` and `target.preservedData` in `onChange`. They are an internal snapshot.\n- The database `rowPages` `body` and `acceptedBody` sent to your host. Store and echo them unchanged.\n- `extractTexts()` returns HTML strings. `injectTexts()` writes each field back in the shape it found.\n- Fields of custom block tools that do not declare `static richTextFields`.\n\n### Input Takes Both Shapes\n\nBlok reads HTML and segments on every input path, and it will keep reading HTML. That covers the `data` config, `render()`, `blocks.insert()`, `insertMany()`, `update()`, `splitBlock()` and `convert()`. You do not have to convert stored documents before you upgrade.\n\nAn old document turns into segments the next time the editor saves it. Until then your database holds both shapes. To convert everything at once, see [Converting Stored Documents](#converting-stored-documents).\n\nA mark key Blok does not know, such as `\"acme:x\"`, is dropped on input with one console warning per key. A `tag:<name>` mark survives only if an enabled inline tool allows that tag.\n\n### Custom Block Tools\n\nA custom block tool takes part only when it lists its rich fields in `static richTextFields`:\n\n```javascript\nclass MyCard {\n  static richTextFields = ['title'];\n}\n```\n\nWithout it, the tool's fields stay as the tool stores them, on input and on output. A sanitize rule does not count.\n\nA tool that reads another block through `BlockAPI.save()` receives segments. For a `database-row` block, that includes the nested documents in `properties.*.blocks`. Blok's built-in tools handle this. Check any third-party tool that reads other blocks.\n\nThe tool class itself still reads and writes HTML. Its constructor, `merge()`, `validate()` and `save()` see HTML strings. Blok converts at the edge.\n\nIf you run the C# collaboration server, list the same fields in `BlokServerOptions.RichTextFields`, for example `{ \"my-card\": [\"title\"] }`. List exactly what the client declares, or the two write the field in different shapes.\n\n### Types\n\n- `ParagraphData`, `HeaderData`, `ListData`, `ToggleData` and `QuoteData` now type `text` as `RichText`. These are the saved shapes.\n- `ParagraphToolData`, `HeaderToolData`, `ListToolData`, `ToggleToolData` and `QuoteToolData` type `text` as `string`. Use them in a tool's constructor, `merge()`, `validate()` and `save()`.\n- For data you write by hand as input, use the `*ToolData` types or `BlockToolData`. Input accepts HTML and segments.\n\n`isBlockType` and `blocksOfType` narrow to the `RichText` types. That is only true for documents saved by this version, or converted with `migrateToRichText`. Convert an older document before a typed read.\n\n### Controlled Components\n\nFeed the `onSave` output back into the editor, not your original HTML.\n\n- Original HTML re-renders once, because Blok turns it into segments.\n- A raw hex colour and a link without `target` or `rel` also re-render once, because Blok normalises them on render.\n- After that the output is stable and the caret stays put.\n\nAfter a round trip, the HTML spelling is canonical. For example `<em>` becomes `<i>` and `&nbsp;` becomes a plain U+00A0 character. The meaning does not change.\n\n### Collaboration\n\nCollaboration rooms move to format 2, which stores rich text as formatted text.\n\n- Upgrade the client and the server together. An old client gets `unsupported-format`.\n- A format-1 room is converted the first time the new server opens it. Each conversion step gets up to 60 seconds. Building a room from an HTML host record gets the same 60 seconds. If one fails, the server answers \"unavailable\" and waits longer before each new try.\n- The client retries the handshake by itself. If the room is still not ready after about 33 seconds (3 tries of 10 seconds), the session ends with `handshake-timeout`. This can happen on the first open of a very large document. Reload to try again.\n- Offline edits made in format 1 are set aside and never sent.\n- The tab sync protocol changed too, so all tabs need the new version.\n- A third-party collaboration server must speak format 2.\n\nOne limitation is accepted. When two people format overlapping text at the same time, one person's formatting can be lost.\n\n### Converting Stored Documents\n\n`migrateToRichText` converts the HTML fields of a stored document offline. Run it to convert your database in bulk, and before typed reads such as `blocksOfType`:\n\n```javascript\nimport { migrateToRichText, richTextToHtml, richTextToPlainText } from '@bloklabs/core/migrate';\n\nconst converted = migrateToRichText(storedDocument, {\n  onLossy: ({ blockId, blockType, field, reason }) => log(blockId, blockType, field, reason),\n});\n\nrichTextToHtml([{ text: 'Hi ' }, { text: 'there', marks: { bold: true } }]);\n//=> 'Hi <strong>there</strong>'\nrichTextToPlainText([{ text: 'Hi ' }, { text: 'there', marks: { bold: true } }]);\n//=> 'Hi there'\n```\n\n- It converts Editor.js shapes too: list items, `toggleList` and callout titles and bodies, quote captions and warnings. You can run `migrate()` before or after it. Table string cells, `raw.html` and `attaches.title` stay strings.\n- It converts only built-in block types. A custom tool's fields are left as they are.\n- Fields that already hold segments pass through, so running it twice is safe.\n- `onLossy` reports `'html-embed'` for markup kept as an `{ embed: { html } }` segment, and `'custom-mark'` for an unknown tag kept as a `tag:<name>` mark.\n- It runs in Node without a DOM. The `@bloklabs/core/migrate` bundle now includes parse5, about 70 KB gzip.\n\nTo display segments outside the editor, use `blocksToHtml` from `@bloklabs/core/view`. It sanitizes its output.\n\n`richTextToHtml` does not sanitize. It is a raw converter. Segments can come from collaborators, the server or a host, so do not put its output into a page as is. `richTextToPlainText` returns plain text.\n\n---\n\n## Configuration Defaults\n\n| Option | EditorJS | Blok |\n|--------|----------|------|\n| `holder` | `\"editorjs\"` | `\"blok\"` |\n| `defaultBlock` | `\"paragraph\"` | `\"paragraph\"` |\n\n---\n\n## New API Methods\n\nBlok exposes shorthand methods directly on the instance:\n\n```javascript\nconst editor = new Blok({ ... });\n\n// Shorthand methods\nawait editor.save();      // Same as editor.saver.save()\neditor.clear();           // Same as editor.blocks.clear()\nawait editor.render(data);// Same as editor.blocks.render(data)\neditor.focus();           // Same as editor.caret.focus()\n\n// Event methods\neditor.on('change', handler);   // Same as editor.events.on()\neditor.off('change', handler);  // Same as editor.events.off()\neditor.emit('custom', data);    // Same as editor.events.emit()\n```\n\n---\n\n## DOM Selectors\n\nBlok uses consistent `data-blok-interface` attributes for major UI components:\n\n```javascript\n// Find the editor wrapper\nconst editorWrapper = document.querySelector('[data-blok-interface=\"blok\"]');\n\n// Find inline toolbar\nconst inlineToolbar = document.querySelector('[data-blok-interface=\"inline-toolbar\"]');\n\n// Find tooltip\nconst tooltip = document.querySelector('[data-blok-interface=\"tooltip\"]');\n```\n\nThese selectors are stable and recommended for programmatic access to Blok's UI components.\n\n### Key Changes\n\n1. **Prefix custom classes** with `blok-` instead of `ce-` or `cdx-`\n2. **Use `data-blok-*`** attributes instead of `data-*`\n\n---\n\n## E2E Test Selectors\n\nUpdate your test selectors to use Blok's `data-blok-testid` attributes:\n\n| EditorJS | Blok |\n|----------|------|\n| `[data-cy=editorjs]` | `[data-blok-testid=\"blok-editor\"]` |\n| `.ce-block` | `[data-blok-element]` |\n| `.ce-block__content` | `[data-blok-element-content]` |\n| `.ce-toolbar` | `[data-blok-toolbar]` |\n| `.ce-toolbar__plus` | `[data-blok-testid=\"plus-button\"]` |\n| `.ce-toolbar__settings-btn` | `[data-blok-settings-toggler]` |\n| `.ce-toolbar__actions` | `[data-blok-testid=\"toolbar-actions\"]` |\n| `.ce-toolbox` | `[data-blok-toolbox]` |\n| `.ce-inline-toolbar` | `[data-blok-testid=\"inline-toolbar\"]` |\n| `.ce-popover` | `[data-blok-popover]` |\n| `.ce-popover-item` | `[data-blok-testid=\"popover-item\"]` |\n| `[data-item-name=\"...\"]` | `[data-blok-item-name=\"...\"]` |\n\n### Playwright Example\n\n```diff\n// EditorJS\n- await page.locator('[data-cy=editorjs] .ce-block').click();\n- await page.locator('.ce-toolbar__settings-btn').click();\n- await page.locator('[data-item-name=\"delete\"]').click();\n\n// Blok\n+ await page.locator('[data-blok-element]').click();\n+ await page.locator('[data-blok-settings-toggler]').click();\n+ await page.locator('[data-blok-item-name=\"delete\"]').click();\n```\n\n### Additional Test Selectors\n\n| Element | Selector |\n|---------|----------|\n| Block tunes popover | `[data-blok-testid=\"block-tunes-popover\"]` |\n| Popover search input | `[data-blok-testid=\"popover-search-input\"]` |\n| Popover item title | `[data-blok-testid=\"popover-item-title\"]` |\n| Popover overlay | `[data-blok-testid=\"popover-overlay\"]` |\n| Inline tool input | `[data-blok-testid=\"inline-tool-input\"]` |\n| Tooltip | `[data-blok-testid=\"tooltip\"]` |\n| Redactor | `[data-blok-testid=\"redactor\"]` |\n| Toolbox | `[data-blok-testid=\"toolbox\"]` |\n| Toolbox popover | `[data-blok-testid=\"toolbox-popover\"]` |\n| Selection overlay | `[data-blok-testid=\"overlay\"]` |\n| Selection rectangle | `[data-blok-testid=\"overlay-rectangle\"]` |\n\n---\n\n### State Selectors\n\n| State | Selector |\n|-------|----------|\n| Toolbar opened | `[data-blok-opened=\"true\"]` |\n| Block selected | `[data-blok-selected=\"true\"]` |\n| Popover opened | `[data-blok-popover-opened=\"true\"]` |\n| Item focused | `[data-blok-focused=\"true\"]` |\n| Item disabled | `[data-blok-disabled=\"true\"]` |\n| Nested popover | `[data-blok-nested=\"true\"]` |\n| Toolbox opened | `[data-blok-toolbox-opened=\"true\"]` |\n| Block dragging | `[data-blok-dragging=\"true\"]` |\n| Element hidden | `[data-blok-hidden=\"true\"]` |\n| RTL mode | `[data-blok-rtl=\"true\"]` |\n\n---\n\n## Quick Checklist\n\n- [ ] Replace `new EditorJS` with `new Blok`\n- [ ] Update imports from `@editorjs/*` to `@bloklabs/core`\n- [ ] Change holder from `editorjs` to `blok` (or specify explicitly)\n- [ ] Use bundled tools: `Blok.Header`, `Blok.Paragraph`\n- [ ] Replace `@editorjs/delimiter` with built-in `Blok.Divider`\n- [ ] Update `EditorConfig` type to `BlokConfig`\n- [ ] Replace `data-id` with `data-blok-id` in queries\n- [ ] Replace `data-item-name` with `data-blok-item-name`\n- [ ] Replace `.ce-*` selectors with `[data-blok-*]` attributes\n- [ ] Replace `.cdx-*` selectors with `[data-blok-*]` attributes\n- [ ] Update E2E test selectors\n", n = (e) => [
 	"# Blok Migration Guide (for LLM-assisted migration)",
 	"",
 	"> This document contains everything needed to migrate a project from EditorJS to Blok.",
@@ -35,29 +35,30 @@ var t = "# Migrating from EditorJS to Blok\n\nThis guide covers the breaking cha
 		};
 	}
 	return { command: null };
-}, o = async (e, t) => {
-	let { command: o, output: s } = a(e);
-	switch (o) {
+}, o = (e) => {
+	let t = globalThis;
+	t.DOMParser = e.DOMParser, t.Node = e.Node, t.document = e.document, t.HTMLElement = e.HTMLElement, t.HTMLInputElement = e.HTMLInputElement;
+}, s = async (e, t) => {
+	let { command: s, output: c } = a(e);
+	switch (s) {
 		case "convert-html": {
-			let e = new (await (import("jsdom"))).JSDOM("");
-			globalThis.DOMParser = e.window.DOMParser, globalThis.Node = e.window.Node;
-			let { convertHtml: t } = await import("./convert-html-Oocfb7JD.mjs");
-			r(t((await import("node:fs")).readFileSync(0, "utf-8")), s);
+			o(new (await (import("jsdom"))).JSDOM("").window);
+			let { convertHtml: e } = await import("./convert-html-RCkTt7d_.mjs");
+			r(e((await import("node:fs")).readFileSync(0, "utf-8")), c);
 			break;
 		}
 		case "convert-gdocs": {
-			let e = new (await (import("jsdom"))).JSDOM("");
-			globalThis.DOMParser = e.window.DOMParser, globalThis.Node = e.window.Node, globalThis.document = e.window.document;
-			let { convertGdocs: t } = await import("./convert-gdocs-CizVIpiR.mjs");
-			r(t((await import("node:fs")).readFileSync(0, "utf-8")), s);
+			o(new (await (import("jsdom"))).JSDOM("").window);
+			let { convertGdocs: e } = await import("./convert-gdocs-ZqRLNT9X.mjs");
+			r(e((await import("node:fs")).readFileSync(0, "utf-8")), c);
 			break;
 		}
 		case "migration":
-			r(n(t), s);
+			r(n(t), c);
 			break;
 		case "help":
 		case null: process.stdout.write(i);
 	}
 };
 //#endregion
-export { o as run };
+export { s as run };

package/dist/convert-gdocs-ZqRLNT9X.mjs

@@ -0,0 +1,13 @@
+import { i as e, n as t, o as n, r, t as i } from "./block-builder-Cg5bL2dS.mjs";
+//#region src/cli/commands/convert-gdocs/index.ts
+function a(a) {
+	let o = n(e(a)), s = new DOMParser().parseFromString(o, "text/html").body;
+	r(s), t(s);
+	let c = {
+		version: "1.16.0",
+		blocks: i(s)
+	};
+	return JSON.stringify(c);
+}
+//#endregion
+export { a as convertGdocs };

package/dist/convert-html-RCkTt7d_.mjs

@@ -0,0 +1,13 @@
+import { a as e, i as t, n, r, s as i, t as a } from "./block-builder-Cg5bL2dS.mjs";
+//#region src/cli/commands/convert-html/index.ts
+function o(o) {
+	let s = new DOMParser().parseFromString(t(o), "text/html").body;
+	s.querySelectorAll("td, th").forEach(e), r(s), n(s), i(s);
+	let c = {
+		version: "1.16.0",
+		blocks: a(s)
+	};
+	return JSON.stringify(c);
+}
+//#endregion
+export { o as convertHtml };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/cli",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "CLI tools for Blok — convert HTML to Blok JSON, generate migration guides",
   "bin": {
     "blok-cli": "bin/blok-cli.mjs"