@bloklabs/cli 1.3.0 → 1.4.0

package/README.md

@@ -0,0 +1,57 @@
+# @bloklabs/cli
+
+Command-line tools for [Blok](https://blokeditor.com) — the headless, Notion-like block editor whose content is JSON blocks, not HTML. Converts legacy HTML into Blok JSON and prints the Editor.js migration guide.
+
+## Install
+
+```bash
+npx @bloklabs/cli --help
+```
+
+Or install it locally:
+
+```bash
+npm install --save-dev @bloklabs/cli
+```
+
+## Usage
+
+```
+Usage: blok-cli [options]
+
+Options:
+  --convert-html       Convert legacy HTML from stdin to Blok JSON (stdout)
+  --convert-gdocs      Convert Google Docs HTML from stdin to Blok JSON (stdout)
+  --migration          Output the EditorJS to Blok migration guide (LLM-friendly)
+  --output <file>      Write output to a file instead of stdout
+  --help               Show this help message
+```
+
+### Convert existing HTML to Blok JSON
+
+```bash
+npx @bloklabs/cli --convert-html < article.html --output article.json
+```
+
+The result is an `OutputData` document you can hand straight to `new Blok({ data })`.
+
+### Convert a Google Docs export
+
+```bash
+npx @bloklabs/cli --convert-gdocs < gdocs-export.html --output doc.json
+```
+
+### Migrating from Editor.js
+
+```bash
+npx @bloklabs/cli --migration --output migration-guide.md
+```
+
+The guide is written to be pasted into an LLM alongside your codebase.
+
+## Docs
+
+- [Migration guide](https://blokeditor.com/migration)
+- [Output data reference](https://blokeditor.com/docs/output-data)
+
+Licensed under Apache-2.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. |\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---\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` item | `meta` |\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\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- [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. |\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` item | `meta` |\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\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.",
@@ -41,14 +41,14 @@ var t = "# Migrating from EditorJS to Blok\n\nThis guide covers the breaking cha
 		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-CtLOMx8H.mjs");
+			let { convertHtml: t } = await import("./convert-html-BE95-_tJ.mjs");
 			r(t((await import("node:fs")).readFileSync("/dev/stdin", "utf-8")), s);
 			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-DhqPnu2C.mjs");
+			let { convertGdocs: t } = await import("./convert-gdocs-6yY_wt82.mjs");
 			r(t((await import("node:fs")).readFileSync("/dev/stdin", "utf-8")), s);
 			break;
 		}

package/dist/{convert-gdocs-D8zi-ZHD.mjs → convert-gdocs-6yY_wt82.mjs}

@@ -173,7 +173,7 @@ function A(e) {
 	let t = s(e), r = new DOMParser().parseFromString(t, "text/html").body;
 	i(r), n(r);
 	let o = {
-		version: "1.2.6",
+		version: "1.4.0",
 		blocks: a(r)
 	};
 	return JSON.stringify(o);

package/dist/{convert-html-lcE4WDun.mjs → convert-html-BE95-_tJ.mjs}

@@ -4,7 +4,7 @@ function r(r) {
 	let i = new DOMParser().parseFromString(r, "text/html").body;
 	t(i), e(i);
 	let a = {
-		version: "1.2.6",
+		version: "1.4.0",
 		blocks: n(i)
 	};
 	return JSON.stringify(a);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "CLI tools for Blok — convert HTML to Blok JSON, generate migration guides",
   "bin": {
     "blok-cli": "bin/blok-cli.mjs"
@@ -19,17 +19,25 @@
     "blok",
     "cli",
     "html-to-json",
+    "block-editor",
+    "rich-text-editor",
     "editorjs",
+    "editorjs-migration",
     "migration",
+    "json",
     "rich-text"
   ],
   "author": "JackUait",
   "license": "Apache-2.0",
+  "homepage": "https://blokeditor.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/JackUait/blok.git",
     "directory": "packages/cli"
   },
+  "bugs": {
+    "url": "https://github.com/JackUait/blok/issues"
+  },
   "dependencies": {
     "jsdom": "29.1.1"
   }