magic-editor-x 1.5.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/CHANGELOG.md +268 -0
  2. package/LICENSE +1 -7
  3. package/README.md +317 -1078
  4. package/dist/admin/ConfigurationPage-B1uCIE3J.js +767 -0
  5. package/dist/admin/ConfigurationPage-DvAifELO.mjs +767 -0
  6. package/dist/admin/CustomBlocksPage-6-OQwpXQ.mjs +1741 -0
  7. package/dist/admin/CustomBlocksPage-6eWCOreU.js +1743 -0
  8. package/dist/admin/EditorField-DocyD2Q3.js +5506 -0
  9. package/dist/admin/EditorField-ThSoOCPm.mjs +5471 -0
  10. package/dist/admin/api-B-RsxJCs.js +34 -0
  11. package/dist/admin/api-C4XsDZxd.mjs +35 -0
  12. package/dist/admin/de-B8XFFhHh.js +95 -0
  13. package/dist/admin/de-BMxADn2Z.mjs +231 -0
  14. package/dist/admin/de-DBR893G4.js +13 -0
  15. package/dist/admin/de-DcDPRzV4.js +155 -0
  16. package/dist/admin/de-Dx7vUW0Z.js +231 -0
  17. package/dist/admin/de-RAxzvrwm.mjs +95 -0
  18. package/dist/admin/de-fBFh09Wl.mjs +13 -0
  19. package/dist/admin/de-n5V6c5RT.mjs +155 -0
  20. package/dist/admin/en-BQ5Pxe2o.mjs +231 -0
  21. package/dist/admin/en-BqNm3nMQ.mjs +155 -0
  22. package/dist/admin/en-BzfyifEU.mjs +95 -0
  23. package/dist/admin/en-D-DGftl0.js +155 -0
  24. package/dist/admin/en-D9Nfccux.mjs +13 -0
  25. package/dist/admin/en-DcWUTE2J.js +95 -0
  26. package/dist/admin/en-gueRT44P.js +13 -0
  27. package/dist/admin/en-sNn4z9lA.js +231 -0
  28. package/dist/admin/es-B0Zy8DVg.mjs +13 -0
  29. package/dist/admin/es-B6NYq0VH.mjs +231 -0
  30. package/dist/admin/es-BOtVc9qv.js +95 -0
  31. package/dist/admin/es-C2OJVYkV.mjs +95 -0
  32. package/dist/admin/es-DRGs7meF.js +13 -0
  33. package/dist/admin/es-DVsXnS0N.js +231 -0
  34. package/dist/admin/es-Di0pyQCh.js +155 -0
  35. package/dist/admin/es-SzeTV4q8.mjs +155 -0
  36. package/dist/admin/fr-B8rdLAIL.js +13 -0
  37. package/dist/admin/fr-Bpo5Uq1f.mjs +95 -0
  38. package/dist/admin/fr-D6F--jIB.js +155 -0
  39. package/dist/admin/fr-DfxKaOc_.js +95 -0
  40. package/dist/admin/fr-DhgPYHIH.mjs +155 -0
  41. package/dist/admin/fr-DmG3_Cn-.mjs +231 -0
  42. package/dist/admin/fr-Fwxcj4SM.js +231 -0
  43. package/dist/admin/fr-oiUb2bb_.mjs +13 -0
  44. package/dist/admin/index-CwfaB5-e.js +155 -0
  45. package/dist/admin/index-D1Q5Rlt6.mjs +156 -0
  46. package/dist/admin/index.js +3 -2
  47. package/dist/admin/index.mjs +1 -1
  48. package/dist/admin/pt-B3Jce6uT.mjs +13 -0
  49. package/dist/admin/pt-BPo0ex21.js +155 -0
  50. package/dist/admin/pt-BbdwHlWF.mjs +231 -0
  51. package/dist/admin/pt-BiWuSBcH.js +13 -0
  52. package/dist/admin/pt-BvSl1btT.mjs +155 -0
  53. package/dist/admin/pt-C6nr71Yw.js +231 -0
  54. package/dist/admin/pt-DqCXuI4S.mjs +95 -0
  55. package/dist/admin/pt-LCvjwk0y.js +95 -0
  56. package/dist/admin/sanitize-9UVcXFfc.js +552 -0
  57. package/dist/admin/sanitize-D4kfZ_ly.mjs +551 -0
  58. package/dist/admin/useT-B5M49wGH.js +130 -0
  59. package/dist/admin/useT-CjX6fL2m.mjs +131 -0
  60. package/dist/server/index.js +4531 -39542
  61. package/dist/server/index.mjs +4534 -39527
  62. package/package.json +111 -74
  63. package/strapi-admin.js +3 -0
  64. package/strapi-server.js +3 -0
  65. package/COPYRIGHT_NOTICE.txt +0 -20
  66. package/dist/_chunks/App-DImBvISP.js +0 -2146
  67. package/dist/_chunks/App-iNfbV7cz.mjs +0 -2143
  68. package/dist/_chunks/CustomBlocksPage-COPOZ2-_.mjs +0 -1517
  69. package/dist/_chunks/CustomBlocksPage-Cj-0TTUs.js +0 -1519
  70. package/dist/_chunks/LicensePage-CmvILX9m.js +0 -393
  71. package/dist/_chunks/LicensePage-gLRoo8WJ.mjs +0 -391
  72. package/dist/_chunks/LiveCollaborationPanel-BFybu8h0.js +0 -222
  73. package/dist/_chunks/LiveCollaborationPanel-CVgl4IyR.mjs +0 -220
  74. package/dist/_chunks/Settings-ButYcfrm.mjs +0 -438
  75. package/dist/_chunks/Settings-BzGqgrxD.js +0 -440
  76. package/dist/_chunks/de-C_0Mj-Zo.mjs +0 -296
  77. package/dist/_chunks/de-DVNVpAt9.js +0 -296
  78. package/dist/_chunks/en-B7AAf1ie.mjs +0 -296
  79. package/dist/_chunks/en-C2hv5GsA.js +0 -296
  80. package/dist/_chunks/es-BzJqcIST.js +0 -274
  81. package/dist/_chunks/es-zdP8sd-f.mjs +0 -274
  82. package/dist/_chunks/fr-CtAgOgH1.mjs +0 -274
  83. package/dist/_chunks/fr-D3GwqAAJ.js +0 -274
  84. package/dist/_chunks/getTranslation-BADoesEn.js +0 -57807
  85. package/dist/_chunks/getTranslation-D3h3Z3gU.mjs +0 -57791
  86. package/dist/_chunks/index-BXBnwuRw.js +0 -2158
  87. package/dist/_chunks/index-BvEdg518.mjs +0 -2159
  88. package/dist/_chunks/index-DDFAuQNT.js +0 -6955
  89. package/dist/_chunks/index-DEi6nwfM.mjs +0 -6933
  90. package/dist/_chunks/pt-BmUw6YMP.mjs +0 -274
  91. package/dist/_chunks/pt-CFo0nTbj.js +0 -274
  92. package/dist/_chunks/tools-BXzd0lx5.mjs +0 -2265
  93. package/dist/_chunks/tools-Q0uwDS9E.js +0 -2296
  94. package/dist/style.css +0 -1103
  95. package/pics/collab-magiceditorX.png +0 -0
  96. package/pics/editorX.png +0 -0
  97. package/pics/liveCollabwidget1.png +0 -0
package/README.md CHANGED
@@ -1,1177 +1,416 @@
1
1
  # Magic Editor X
2
2
 
3
- **Advanced Block-Based Content Editor for Strapi v5 with Real-Time Collaboration**
4
-
5
- [![NPM Version](https://img.shields.io/npm/v/magic-editor-x.svg)](https://www.npmjs.com/package/magic-editor-x)
6
- [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
7
- [![Strapi v5](https://img.shields.io/badge/Strapi-v5-7C3AED.svg)](https://strapi.io)
8
- [![Editor.js](https://img.shields.io/badge/Editor.js-2.31.0-000.svg)](https://editorjs.io)
9
-
10
- > **ALPHA RELEASE v1.4.0-alpha.1** - Custom Blocks with Tier-based Limits now available! Create your own editor blocks without writing code.
11
-
12
- ---
13
-
14
- ## What's New in v1.4.0-alpha.1
15
-
16
- ### Custom Blocks (Contentful-style)
17
-
18
- Create custom editor blocks directly from the Admin UI - no code required!
19
-
20
- - **Simple Blocks** - Text/HTML blocks with configurable fields (text, textarea, select, color, checkbox)
21
- - **Embedded Entry Blocks** - Reference other Strapi content types with preview fields (like Contentful Inline Entries)
22
- - **HTML Templates** - Define custom templates with `{{fieldName}}` placeholders
23
- - **Replaces Dynamic Zones** - Simpler alternative for structured content within the editor
24
-
25
- ### Tier-Based Limits
26
-
27
- | Feature | FREE | PREMIUM | ADVANCED |
28
- |---------|------|---------|----------|
29
- | Simple Blocks | 3 | 10 (combined) | Unlimited |
30
- | Embedded Entry | - | 10 (combined) | Unlimited |
31
- | Export/Import | - | - | Yes |
32
- | API Access | - | - | Yes |
33
-
34
- ### Previous Updates (v1.2.0)
35
-
36
- - **Character-Level Collaboration** - Multiple users can now type in the same paragraph simultaneously without conflicts
37
- - **Webtools Links Integration** - Optional integration with PluginPal's Webtools Links addon for internal/external link management
38
- - **Direct Link Editing** - Click on any link to instantly open the link editor modal
39
- - **Improved Fullscreen Mode** - Blocks now stretch to full width, Media Library modal works correctly
40
-
41
- ---
42
-
43
- ## Introduction
44
-
45
- Magic Editor X is a production-ready Strapi v5 Custom Field that brings the power of Editor.js to your content management workflow. Unlike traditional WYSIWYG replacements or plugins that override Strapi's default editor, Magic Editor X integrates as a **proper Custom Field** in Strapi's Content-Type Builder, giving you complete control over when and where to use it.
46
-
47
- Built on proven technologies like Editor.js for the editing interface and Y.js for conflict-free real-time collaboration, this plugin provides a modern, extensible content editing experience that scales from solo developers to large editorial teams.
48
-
49
- ### Why Magic Editor X? :)
50
-
51
- **For Developers:**
52
- - Clean JSON output instead of unstructured HTML
53
- - 25+ pre-configured Editor.js tools out of the box
54
- - Type-safe content structure with versioned schemas
55
- - Real-time collaboration with CRDT (Conflict-free Replicated Data Types)
56
- - Full TypeScript support with proper type definitions
57
- - Extensible architecture for custom block types
58
-
59
- **For Content Teams:**
60
- - Familiar Medium-style block editor experience
61
- - Live collaborative editing with presence indicators
62
- - Keyboard shortcuts for fast content creation
63
- - Inline formatting without toolbar clutter
64
- - Media Library integration for asset management
65
- - AI-powered content suggestions (premium)
66
-
67
- ---
3
+ Block editor for Strapi 5: an [Editor.js](https://editorjs.io/) custom field with Media Library uploads, custom blocks, version history, live collaboration across several servers and an optional AI assistant that uses your own provider. Free and open source under the MIT license.
4
+
5
+ [![npm](https://img.shields.io/npm/v/magic-editor-x)](https://www.npmjs.com/package/magic-editor-x)
6
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
7
+
8
+ Live docs: <https://schero94.github.io/Magic-Editor-X/>
9
+
10
+ ## Contents
11
+
12
+ - [Features](#features)
13
+ - [Screenshots](#screenshots)
14
+ - [Core concepts](#core-concepts)
15
+ - [Screens](#screens)
16
+ - [Compatibility](#compatibility)
17
+ - [Install](#install)
18
+ - [Configuration](#configuration)
19
+ - [Live collaboration](#live-collaboration)
20
+ - [Running several instances](#running-several-instances)
21
+ - [AI assistant](#ai-assistant)
22
+ - [Data format](#data-format)
23
+ - [Admin API and permissions](#admin-api-and-permissions)
24
+ - [Security and privacy](#security-and-privacy)
25
+ - [Troubleshooting](#troubleshooting)
26
+ - [Migrating from 1.x](#migrating-from-1x)
27
+ - [Development and tests](#development-and-tests)
28
+ - [Maintenance status](#maintenance-status)
29
+ - [Languages](#languages)
30
+ - [License](#license)
31
+
32
+ ## Features
33
+
34
+ Every feature is available in every installation. There is nothing to activate, no tiers and no usage limits, and the plugin makes no outgoing requests unless you use a feature that needs one (link previews, image by URL, AI assistant).
35
+
36
+ - **Custom field** `plugin::magic-editor-x.richtext` (stored as JSON) for collection types, single types, components and dynamic zones, including localised fields and Draft & Publish.
37
+ - **Block tools** (block name in brackets, the same names 1.x used):
38
+ - text: paragraph (`paragraph`), heading H1 to H6 (`header`), list with nesting, ordered and unordered (`list`), checklist (`checklist`), quote (`quote`), warning (`warning`), alert in eight colours (`alert`), collapsible toggle (`toggle`), delimiter (`delimiter`), table (`table`);
39
+ - code: plain code (`code`), code with syntax highlighting (`codeFlask`; Prism with JavaScript, TypeScript, JSX/TSX, JSON, HTML, CSS/SCSS, PHP, Python, Ruby, Go, Rust, Java, Kotlin, Swift, C, C++, C#, SQL, Bash, YAML, Markdown, GraphQL, Docker and diff);
40
+ - media: image upload by file or URL into the Media Library (`image`), picking images from the Media Library (`mediaLib`, inserts `image` blocks), image by URL without upload (`simpleImage`), file attachments (`attaches`), embeds such as YouTube, Vimeo, CodePen, GitHub, Figma and others (`embed`);
41
+ - other: link preview card (`linkTool`), person card (`personality`), call-to-action button (`button`), raw HTML (`raw`).
42
+ - **Inline tools:** bold, italic, link with target and rel (`hyperlink`), marker, underline, strikethrough, inline code, tooltip, and the AI assistant when it is enabled.
43
+ - **Block tunes:** alignment (`alignmentTune`), text variant call-out / citation / details (`textVariant`), indent (`indentTune`).
44
+ - **Editing:** undo and redo, drag and drop of blocks, full screen mode, block and word count.
45
+ - **Custom blocks:** define your own blocks in Settings: simple blocks with fields (text, textarea, URL, number, select, checkbox, image, colour) and an optional HTML template, or embedded-entry blocks that link an entry of another content type. Import and export as JSON.
46
+ - **Version history:** save versions of a field, preview and restore them; automatic versions during live sessions.
47
+ - **Live collaboration:** several admins edit the same field at the same time with character-level merging, presence avatars and read-only viewers. Works with several Node processes behind a load balancer without sticky sessions.
48
+ - **AI assistant:** improve, fix grammar, shorten, expand, summarize, simplify, translate, change tone and continue writing, using Anthropic, OpenAI or any OpenAI-compatible server (for example a local model) with your own key.
49
+ - **Strapi-native admin:** built with the Strapi Design System, light and dark mode, keyboard accessible, admin in English, German, French, Spanish and Portuguese.
50
+ - **Safe content:** every value is normalised and sanitised on the server when it is saved, from the Content Manager, the Content API or code.
68
51
 
69
52
  ## Screenshots
70
53
 
71
- ### Editor Interface
72
- ![Magic Editor X Interface](https://raw.githubusercontent.com/Schero94/magic-editor-x/main/pics/editorX.png)
73
-
74
- ### Real-Time Collaboration
75
- ![Live Collaboration](https://raw.githubusercontent.com/Schero94/magic-editor-x/main/pics/collab-magiceditorX.png)
76
-
77
- ### Collaboration Widget
78
- ![Collaboration Panel](https://raw.githubusercontent.com/Schero94/magic-editor-x/main/pics/liveCollabwidget1.png)
79
-
80
- ---
81
-
82
- ## Architecture Overview
83
-
84
- Magic Editor X follows a clean client-server architecture with three main components:
85
-
86
- ### Client-Side (Admin Panel)
87
-
88
- ```
89
- admin/
90
- ├── src/
91
- │ ├── components/
92
- │ │ ├── EditorJS/ # Main editor component
93
- │ │ ├── EditorTools/ # Custom tools (Button, Hyperlink, AI, WebtoolsLink)
94
- │ │ ├── MediaLib/ # Strapi Media Library adapter
95
- │ │ └── LiveCollaborationPanel.jsx # Collaboration UI
96
- │ ├── hooks/
97
- │ │ ├── useMagicCollaboration.js # Y.js & Socket.io integration
98
- │ │ ├── useWebtoolsLinks.js # 🆕 Webtools Links addon integration
99
- │ │ ├── useAIAssistant.js # AI features
100
- │ │ └── useLicense.js # License management
101
- │ ├── utils/
102
- │ │ └── YTextBinding.js # 🆕 Y.Text <-> contenteditable binding
103
- │ ├── config/
104
- │ │ └── tools.js # Editor.js tools configuration
105
- │ └── index.js # Plugin registration
106
- ```
107
-
108
- **Key Technologies:**
109
- - **React 18** - UI components with hooks
110
- - **Editor.js 2.31** - Block-based editor core
111
- - **Y.js 13.6** - CRDT for real-time sync
112
- - **Socket.io-client 4.8** - WebSocket communication
113
- - **IndexedDB** - Local persistence via y-indexeddb
114
-
115
- ### Server-Side (Strapi Backend)
116
-
117
- ```
118
- server/
119
- ├── src/
120
- │ ├── controllers/
121
- │ │ ├── editor-controller.js # Image upload, link previews
122
- │ │ ├── collaboration-controller.js # Permission management
123
- │ │ ├── realtime-controller.js # Session tokens
124
- │ │ └── license-controller.js # License validation
125
- │ ├── services/
126
- │ │ ├── realtime-service.js # Y.js document management
127
- │ │ ├── access-service.js # Permission checks
128
- │ │ ├── license-service.js # License API
129
- │ │ └── snapshot-service.js # Document snapshots
130
- │ ├── routes/
131
- │ │ ├── admin.js # Admin panel routes
132
- │ │ └── content-api.js # Public API routes
133
- │ └── config/
134
- │ └── index.js # Plugin configuration
135
- ```
136
-
137
- **Key Technologies:**
138
- - **Socket.io 4.8** - WebSocket server
139
- - **Y.js 13.6** - Server-side CRDT state
140
- - **Open Graph Scraper** - Link metadata extraction
141
- - **Strapi 5.31** - Backend framework
142
-
143
- ### Data Flow
144
-
145
- 1. **Editor Changes** → Y.js Document (CRDT) → Socket.io → Server → Other Clients
146
- 2. **Image Upload** → Strapi Controller → Strapi Upload Service → Media Library
147
- 3. **Link Preview** → Backend Scraper → OpenGraph Metadata → Client
148
- 4. **Collaboration** → Permission Check → Session Token → WebSocket Connection
149
-
150
- ---
151
-
152
- ## Features Deep Dive
153
-
154
- ### 1. Block-Based Content Structure
155
-
156
- Magic Editor X stores content as structured JSON, not HTML. Each block has a unique ID, type, and data object:
157
-
158
- ```json
159
- {
160
- "time": 1699999999999,
161
- "blocks": [
162
- {
163
- "id": "abc123",
164
- "type": "header",
165
- "data": {
166
- "text": "Hello World",
167
- "level": 2
168
- }
169
- },
170
- {
171
- "id": "def456",
172
- "type": "paragraph",
173
- "data": {
174
- "text": "This is <b>bold</b> and <i>italic</i> text."
175
- }
176
- },
177
- {
178
- "id": "ghi789",
179
- "type": "list",
180
- "data": {
181
- "style": "unordered",
182
- "items": [
183
- {
184
- "content": "First item",
185
- "items": []
186
- },
187
- {
188
- "content": "Second item with nested list",
189
- "items": [
190
- {
191
- "content": "Nested item",
192
- "items": []
193
- }
194
- ]
195
- }
196
- ]
197
- }
198
- }
199
- ],
200
- "version": "2.31.0"
201
- }
202
- ```
203
-
204
- **Benefits:**
205
- - Predictable, type-safe content structure
206
- - Easy to parse, transform, and render
207
- - Version control friendly (no HTML diffs)
208
- - Can be validated against JSON schemas
209
- - Simple to migrate between systems
210
-
211
- ### 2. Real-Time Collaboration (CRDT Technology)
212
-
213
- Magic Editor X uses Y.js, a battle-tested CRDT implementation, to enable true real-time collaboration without conflicts:
214
-
215
- **How It Works:**
216
-
217
- 1. **Y.Doc Creation** - Each content entry gets a shared Y.js document
218
- 2. **Local Changes** - Edits create CRDT operations (not plain text diffs)
219
- 3. **Sync Protocol** - Operations are sent via Socket.io to the server
220
- 4. **Server Broadcast** - Server distributes operations to all connected clients
221
- 5. **Automatic Merge** - Y.js guarantees conflict-free merges (no "last write wins")
222
- 6. **Persistence** - Changes are stored in IndexedDB for offline capability
223
-
224
- **🆕 Character-Level Collaboration (v1.2.0)**
225
-
226
- Starting with v1.2.0, Magic Editor X supports **simultaneous editing within the same block**. Multiple users can type in the same paragraph at the same time without conflicts:
227
-
228
- ```
229
- ┌─────────────────────────────────────────────────────────┐
230
- │ Before v1.2.0: Block-Level Sync │
231
- │ User A edits Block 1 → User B's Block 1 changes lost │
232
- ├─────────────────────────────────────────────────────────┤
233
- │ After v1.2.0: Character-Level Sync │
234
- │ User A types "Hello" → User B types "World" → "HelloWorld" │
235
- │ Both changes merge seamlessly! │
236
- └─────────────────────────────────────────────────────────┘
237
- ```
238
-
239
- **Hybrid Data Structure:**
240
- - `Y.Map` for block metadata (type, tunes, order)
241
- - `Y.Text` for character-level content (rich text with formatting)
242
- - `Y.Map` for document metadata (blockOrder, timestamps)
243
-
244
- **Example: Collaborative Editing Flow**
245
-
246
- ```javascript
247
- // Client A types "Hello" at position 0
248
- const update = Y.encodeStateAsUpdate(yDoc);
249
- socket.emit('collab:update', update);
250
-
251
- // Server broadcasts to all clients
252
- socket.broadcast.to(roomId).emit('collab:update', update);
253
-
254
- // Client B applies the update
255
- Y.applyUpdate(yDoc, update);
256
- // Editor automatically re-renders with "Hello"
257
- ```
258
-
259
- **Presence & Cursors:**
260
-
261
- ```javascript
262
- // Awareness protocol for presence
263
- awareness.setLocalStateField('cursor', {
264
- blockId: 'abc123',
265
- position: 42,
266
- user: {
267
- id: 'user-1',
268
- name: 'John Doe',
269
- color: '#FF6B6B'
270
- }
271
- });
272
-
273
- // Other clients receive cursor updates
274
- awareness.on('change', ({ added, updated, removed }) => {
275
- // Render remote cursor indicators
276
- renderCursors(awareness.getStates());
277
- });
278
- ```
279
-
280
- ### 3. 25+ Editor.js Tools
281
-
282
- Magic Editor X comes with a comprehensive collection of tools, categorized for easy reference:
283
-
284
- #### Block Tools (21 Tools)
285
-
286
- | Tool | Description | Package | Shortcut |
287
- |------|-------------|---------|----------|
288
- | **Header** | H1-H6 headings with alignment | `@editorjs/header` | `CMD+SHIFT+H` |
289
- | **Paragraph** | Text blocks with inline formatting | `@editorjs/paragraph` | - |
290
- | **Nested List** | Multi-level ordered/unordered lists | `@editorjs/nested-list` | `CMD+SHIFT+L` |
291
- | **Checklist** | Interactive todo lists | `@editorjs/checklist` | `CMD+SHIFT+C` |
292
- | **Quote** | Blockquotes with caption | `@editorjs/quote` | `CMD+SHIFT+Q` |
293
- | **Warning** | Alert boxes | `@editorjs/warning` | `CMD+SHIFT+W` |
294
- | **Code** | Basic code blocks | `@editorjs/code` | `CMD+SHIFT+P` |
295
- | **Code (Highlight)** | Syntax-highlighted code | `@calumk/editorjs-codeflask` | - |
296
- | **Delimiter** | Visual section separator | `@editorjs/delimiter` | `CMD+SHIFT+D` |
297
- | **Table** | Create/edit tables | `@editorjs/table` | `CMD+SHIFT+T` |
298
- | **Embed** | YouTube, Vimeo, Twitter, etc. | `@editorjs/embed` | - |
299
- | **Raw HTML** | Insert raw HTML | `@editorjs/raw` | - |
300
- | **Image** | Upload by file or URL | `@editorjs/image` | - |
301
- | **Simple Image** | Image by URL only | `@editorjs/simple-image` | - |
302
- | **Link Preview** | Rich link cards with metadata | `@editorjs/link` | - |
303
- | **Attaches** | File attachments | `@editorjs/attaches` | - |
304
- | **Media Library** | Strapi Media Library picker | Custom | - |
305
- | **Personality** | Author/person cards | `@editorjs/personality` | - |
306
- | **Alert** | Colored alert messages | `editorjs-alert` | `CMD+SHIFT+A` |
307
- | **Toggle** | Collapsible content blocks | `editorjs-toggle-block` | - |
308
- | **Button** | CTA buttons | Custom | - |
309
-
310
- #### Inline Tools (7 Tools)
311
-
312
- | Tool | Description | Package | Shortcut |
313
- |------|-------------|---------|----------|
314
- | **Bold** | Bold text | Built-in | `CMD+B` |
315
- | **Italic** | Italic text | Built-in | `CMD+I` |
316
- | **Marker** | Highlight text | `@editorjs/marker` | `CMD+SHIFT+M` |
317
- | **Inline Code** | Code formatting | `@editorjs/inline-code` | `CMD+SHIFT+I` |
318
- | **Underline** | Underline text | `@editorjs/underline` | `CMD+U` |
319
- | **Strikethrough** | Strike through text | `@sotaproject/strikethrough` | `CMD+SHIFT+S` |
320
- | **Hyperlink** | Links with target/rel | Custom | `CMD+K` |
321
- | **Tooltip** | Add tooltips to text | `editorjs-tooltip` | - |
322
-
323
- #### Block Tunes (3 Tunes)
324
-
325
- | Tune | Description | Package |
326
- |------|-------------|---------|
327
- | **Alignment** | Left, center, right, justify | `editorjs-text-alignment-blocktune` |
328
- | **Indent** | Multi-level indentation | `editorjs-indent-tune` |
329
- | **Text Variant** | Call-out, citation, details styles | `@editorjs/text-variant-tune` |
330
-
331
- #### Plugins (2 Plugins)
332
-
333
- | Plugin | Description | Package |
334
- |--------|-------------|---------|
335
- | **Undo/Redo** | History management | `editorjs-undo` |
336
- | **Drag & Drop** | Reorder blocks by dragging | `editorjs-drag-drop` |
337
-
338
- ### Custom Blocks (User-Defined)
339
-
340
- Magic Editor X allows you to create your own custom blocks without writing code! This feature is similar to Contentful's embedded entries and can replace Strapi's Components + Dynamic Zones setup.
341
-
342
- #### Creating Custom Blocks via Admin UI
343
-
344
- 1. Go to **Settings > Magic Editor X > Custom Blocks**
345
- 2. Click **Create Block**
346
- 3. Fill in the form:
347
- - **Block Name** - Unique identifier (e.g., `productCard`)
348
- - **Display Label** - Shown in the editor toolbox
349
- - **Block Type**:
350
- - **Simple Block** - Text/HTML content with custom fields
351
- - **Embedded Entry** - Links to existing Strapi content
352
- 4. Configure additional options (fields, template, icon)
353
- 5. Click **Create Block**
354
-
355
- The new block appears immediately in the editor toolbox!
356
-
357
- #### Block Types
358
-
359
- **Simple Blocks:**
360
- Custom text/HTML blocks with configurable fields.
361
-
362
- | Option | Description |
363
- |--------|-------------|
364
- | Placeholder | Hint text for empty content |
365
- | Template | Custom HTML with `{{fieldName}}` placeholders |
366
- | Fields | Add custom fields (text, select, color, checkbox) |
367
- | Styles | Custom CSS as JSON object |
368
-
369
- **Embedded Entry Blocks:**
370
- Embed existing Strapi content directly in your editor.
371
-
372
- | Option | Description |
373
- |--------|-------------|
374
- | Content Type | Target content type (e.g., `api::product.product`) |
375
- | Title Field | Field to display as entry title |
376
- | Display Fields | Fields shown in preview |
377
-
378
- #### Creating Custom Blocks via Config (Developers)
379
-
380
- For developers who prefer code-based configuration:
381
-
382
- ```javascript
383
- // config/plugins.js
384
- 'magic-editor-x': {
385
- enabled: true,
386
- config: {
387
- customBlocks: [
388
- {
389
- name: 'productCard',
390
- label: 'Product Card',
391
- blockType: 'embedded-entry',
392
- contentType: 'api::product.product',
393
- displayFields: ['title', 'price', 'thumbnail'],
394
- titleField: 'title',
395
- icon: '<svg>...</svg>',
396
- },
397
- {
398
- name: 'callToAction',
399
- label: 'Call to Action',
400
- blockType: 'simple',
401
- placeholder: 'Enter CTA text...',
402
- fields: [
403
- { name: 'buttonText', label: 'Button Text', type: 'text' },
404
- { name: 'buttonUrl', label: 'Button URL', type: 'text' },
405
- { name: 'variant', label: 'Style', type: 'select', options: ['primary', 'secondary'] },
406
- ],
407
- template: `
408
- <div class="cta-block">
409
- <p data-field="content">{{content}}</p>
410
- <a href="{{buttonUrl}}" class="btn btn-{{variant}}">{{buttonText}}</a>
411
- </div>
412
- `,
413
- },
414
- ],
415
- },
416
- },
417
- ```
418
-
419
- #### Import/Export Custom Blocks
420
-
421
- Custom blocks can be exported and imported between environments:
422
-
423
- 1. Go to **Settings > Magic Editor X > Custom Blocks**
424
- 2. Click **Export** to download a JSON file
425
- 3. On another instance, click **Import** and select the file
426
-
427
- #### Custom Block Output Format
428
-
429
- Custom blocks save their data in the standard Editor.js format:
430
-
431
- ```json
432
- {
433
- "type": "productCard",
434
- "data": {
435
- "entry": {
436
- "id": 42,
437
- "documentId": "abc123",
438
- "title": "Product Name",
439
- "price": 99.99
440
- },
441
- "contentType": "api::product.product"
442
- }
443
- }
444
- ```
445
-
446
- ### 4. Media Library Integration
447
-
448
- Seamless integration with Strapi's built-in Media Library:
449
-
450
- ```javascript
451
- // Custom MediaLibAdapter bridges Editor.js and Strapi
452
- class MediaLibAdapter {
453
- static get toolbox() {
454
- return {
455
- title: 'Media Library',
456
- icon: '<svg>...</svg>'
457
- };
458
- }
459
-
460
- render() {
461
- const button = document.createElement('button');
462
- button.textContent = 'Choose from Media Library';
463
- button.onclick = () => {
464
- // Opens Strapi's Media Library modal
465
- this.config.mediaLibToggleFunc();
466
- };
467
- return button;
468
- }
469
-
470
- save(blockContent) {
471
- return {
472
- url: blockContent.url,
473
- caption: blockContent.caption,
474
- alt: blockContent.alt
475
- };
476
- }
477
- }
478
- ```
479
-
480
- ### 5. Webtools Links Integration (Optional)
54
+ | | |
55
+ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
56
+ | ![Editor in the Content Manager, light mode](docs/site/img/editor-light-1440.png) | ![Editor in dark mode](docs/site/img/editor-dark-1440.png) |
57
+ | ![Two admins editing the same field](docs/site/img/collaboration-1440.png) | ![Version history dialog](docs/site/img/history-1440.png) |
58
+ | ![AI assistant dialog](docs/site/img/ai-1440.png) | ![Settings, configuration page](docs/site/img/settings-configuration-1440.png) |
59
+ | ![Settings, custom blocks list](docs/site/img/settings-custom-blocks-1440.png) | ![Custom block form](docs/site/img/custom-block-modal-1440.png) |
481
60
 
482
- Magic Editor X integrates seamlessly with the [Webtools Links addon](https://www.pluginpal.io/plugin/webtools) by PluginPal for enhanced link management:
61
+ ![Editor on a 390 px wide screen](docs/site/img/editor-mobile-390.png)
483
62
 
484
- **Features:**
485
- - 🔗 **Internal Link Picker** - Select pages/entries from your Strapi content
486
- - 🌐 **External URL Support** - Paste external URLs with validation
487
- - ✏️ **Edit Existing Links** - Click on a link to edit its URL and text
488
- - 🔍 **Link Detection** - Automatically detects when cursor is inside a link
63
+ All screenshots use synthetic data.
489
64
 
490
- **Setup:**
65
+ ## Core concepts
491
66
 
492
- 1. Install the Webtools Links addon (requires Webtools license)
493
- 2. Magic Editor X auto-detects the addon and enables the Link Picker button
67
+ | Term | Meaning |
68
+ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
69
+ | Field | One Magic Editor X attribute of a content type or component. Its value is an Editor.js document. |
70
+ | Block | One entry of the document's `blocks` array, for example a paragraph or an image. Each block has an `id`, a `type` (the block name) and `data`. |
71
+ | Custom block | A block type defined in Settings > Magic Editor X > Custom blocks. Its name becomes the block `type`. |
72
+ | Version | A stored copy (snapshot) of one field of one document in one locale, listed in the version history. |
73
+ | Room | The live editing session of one field of one document in one locale. A room exists while people edit and for `collaboration.roomTtlMinutes` afterwards. |
74
+ | Viewer | Someone in a room who can read the document but not update it. Viewers see changes live but cannot type. |
494
75
 
495
- **Usage:**
76
+ ## Screens
496
77
 
497
- ```javascript
498
- // The integration uses Strapi's plugin API
499
- const getPlugin = useStrapiApp('WebtoolsLinks', (state) => state.getPlugin);
500
- const linksPlugin = getPlugin('webtools-addon-links');
501
- const { openLinkPicker } = linksPlugin?.apis;
78
+ | Screen | Where | Who can open it |
79
+ | --------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80
+ | Editor field | Content Manager, edit view | Everyone who can read the field. Uploads, version history and the AI assistant need the permissions in [Admin API and permissions](#admin-api-and-permissions). |
81
+ | Version history | Clock button in the editor toolbar of a saved document | `access` and Content Manager read on the document; saving and restoring need update. |
82
+ | AI assistant | Inline toolbar (select text) | `access` and `ai.use`, when an administrator turned the assistant on. |
83
+ | Configuration | Settings > Magic Editor X > Configuration | `settings.read` (view), `settings.update` (edit). |
84
+ | Custom blocks | Settings > Magic Editor X > Custom blocks | `custom-blocks.manage`. |
502
85
 
503
- // Open picker with existing link data (for editing)
504
- const result = await openLinkPicker({
505
- linkType: 'both', // 'internal', 'external', or 'both'
506
- initialHref: existingUrl, // Pre-fill for editing
507
- initialText: selectedText // Pre-fill link text
508
- });
509
- ```
510
-
511
- **Without Webtools:**
512
-
513
- If Webtools is not installed, a subtle promo link appears in the editor footer pointing to the addon store page.
514
-
515
- ---
516
-
517
- ### 6. AI-Powered Features (Premium)
518
-
519
- Built-in AI assistant for content enhancement:
520
-
521
- **Grammar Check:**
522
- ```javascript
523
- // Automatically fix grammar and spelling
524
- aiAssistant.check(text) → corrected text
525
- ```
526
-
527
- **Style Improvement:**
528
- ```javascript
529
- // Make text more professional, casual, or friendly
530
- aiAssistant.rewrite(text, style: 'professional') → improved text
531
- ```
532
-
533
- **Content Generation:**
534
- ```javascript
535
- // Generate content based on prompts
536
- aiAssistant.generate(prompt) → generated content
537
- ```
86
+ ## Compatibility
538
87
 
539
- ---
88
+ | Plugin | Strapi | Node | Notes |
89
+ | ------ | ---------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
90
+ | 2.x | 5.38 or later (acceptance host: Strapi 5.61.1) | 22 or 24 | SQLite, PostgreSQL and MySQL/MariaDB through the Strapi database connection. Acceptance runs used SQLite and PostgreSQL 16. |
91
+ | 1.x | 5.x | 22 | No longer developed. |
540
92
 
541
- ## Installation & Setup
93
+ The admin uses the React, React Router, react-intl, styled-components and Design System versions of the Strapi admin (React 18, Design System 2.2.4).
542
94
 
543
- ### 1. Install Package
95
+ ## Install
544
96
 
545
97
  ```bash
546
98
  npm install magic-editor-x
547
- # or
548
- yarn add magic-editor-x
549
- # or
550
- pnpm add magic-editor-x
551
99
  ```
552
100
 
553
- ### 2. Enable Plugin
554
-
555
- Create or update `config/plugins.ts` (or `.js`):
101
+ Enable the plugin in `config/plugins.ts` (or `config/plugins.js`):
556
102
 
557
- ```typescript
558
- export default () => ({
103
+ ```ts
104
+ export default ({ env }) => ({
559
105
  'magic-editor-x': {
560
106
  enabled: true,
561
107
  config: {
562
- // Editor Configuration
563
- enabledTools: [
564
- 'header', 'paragraph', 'list', 'checklist', 'quote',
565
- 'warning', 'code', 'delimiter', 'table', 'embed',
566
- 'raw', 'image', 'mediaLib', 'linkTool'
567
- ],
568
-
569
- // Upload Limits
570
- maxImageSize: 10 * 1024 * 1024, // 10MB
571
- allowedImageTypes: [
572
- 'image/jpeg', 'image/png', 'image/gif',
573
- 'image/webp', 'image/svg+xml'
574
- ],
575
-
576
- // Link Previews
577
- linkPreviewTimeout: 10000, // 10 seconds
578
-
579
- // Real-Time Collaboration
580
- collaboration: {
581
- enabled: true,
582
- sessionTTL: 2 * 60 * 1000, // 2 minutes
583
- wsPath: '/magic-editor-x/realtime',
584
- wsUrl: null, // Auto-detect or set custom URL
585
- allowedOrigins: ['http://localhost:1337'],
586
- allowedAdminRoles: ['strapi-super-admin'],
587
- allowedAdminUserIds: [],
588
- },
589
-
590
- // API Response Settings
591
- api: {
592
- autoParseJSON: true, // Auto-parse JSON strings to objects in API responses
593
- },
108
+ // optional, see Configuration
594
109
  },
595
110
  },
596
111
  });
597
112
  ```
598
113
 
599
- ### 3. Content Security Policy (Optional)
600
-
601
- For link previews with external images, update `config/middlewares.ts`:
602
-
603
- ```typescript
604
- export default [
605
- 'strapi::logger',
606
- 'strapi::errors',
607
- {
608
- name: 'strapi::security',
609
- config: {
610
- contentSecurityPolicy: {
611
- useDefaults: true,
612
- directives: {
613
- 'connect-src': ["'self'", 'https:'],
614
- 'img-src': [
615
- "'self'",
616
- 'data:',
617
- 'blob:',
618
- 'market-assets.strapi.io',
619
- '*', // Allow external images for link previews
620
- ],
621
- 'media-src': [
622
- "'self'",
623
- 'data:',
624
- 'blob:',
625
- 'market-assets.strapi.io',
626
- ],
627
- upgradeInsecureRequests: null,
628
- },
629
- },
630
- },
631
- },
632
- 'strapi::cors',
633
- 'strapi::poweredBy',
634
- 'strapi::query',
635
- 'strapi::body',
636
- 'strapi::session',
637
- 'strapi::favicon',
638
- 'strapi::public',
639
- ];
640
- ```
641
-
642
- ### 4. Build & Start
114
+ Then rebuild the admin and restart:
643
115
 
644
116
  ```bash
645
- # Build admin panel with plugin
646
117
  npm run build
647
-
648
- # Start in development mode
649
118
  npm run develop
650
-
651
- # Or in production
652
- npm run start
653
119
  ```
654
120
 
655
- ### 5. Add Field to Content Type
656
-
657
- 1. Navigate to **Content-Type Builder**
658
- 2. Select a content type or create a new one
659
- 3. Click **Add another field**
660
- 4. Go to the **Custom** tab
661
- 5. Select **Magic Editor X**
662
- 6. Configure field name and options
663
- 7. Click **Finish** and save the content type
664
-
665
- ---
666
-
667
- ## Configuration Reference
668
-
669
- ### Plugin Configuration
670
-
671
- All options for `config/plugins.ts`:
672
-
673
- ```typescript
674
- interface MagicEditorXConfig {
675
- // Tool Selection
676
- enabledTools?: string[]; // Default: all tools
677
-
678
- // Upload Settings
679
- maxImageSize?: number; // Bytes, default: 10MB
680
- allowedImageTypes?: string[]; // MIME types
681
-
682
- // Link Preview Settings
683
- linkPreviewTimeout?: number; // Milliseconds, default: 10000
684
-
685
- // API Response Settings
686
- api?: {
687
- autoParseJSON: boolean; // Auto-parse JSON strings to objects, default: true
688
- };
689
-
690
- // Collaboration Settings
691
- collaboration?: {
692
- enabled: boolean; // Default: true
693
- sessionTTL: number; // Milliseconds, default: 120000 (2 min)
694
- wsPath: string; // WebSocket path, default: '/magic-editor-x/realtime'
695
- wsUrl: string | null; // Custom WebSocket URL (for proxies)
696
- allowedOrigins: string[]; // CORS origins
697
- allowedAdminRoles: string[]; // Roles that can collaborate
698
- allowedAdminUserIds: number[]; // Specific user IDs
699
- };
700
- }
701
- ```
121
+ Add the field in the Content-Type Builder: **Add another field > Custom > Magic Editor X**. In its settings you can set a placeholder and a minimum height (120 to 2000 px).
702
122
 
703
- ### Field Options
123
+ After the first start, Super Admins can use everything. Other roles need the plugin actions listed in [Admin API and permissions](#admin-api-and-permissions) (Settings > Administration Panel > Roles > Plugins > Magic Editor X).
704
124
 
705
- When adding the field in Content-Type Builder:
125
+ ## Configuration
706
126
 
707
- **Base Settings:**
708
- - **Placeholder** - Placeholder text (default: "Start writing or press Tab...")
709
- - **Required** - Make field mandatory
710
- - **Private** - Exclude from API responses
127
+ ### Reference
711
128
 
712
- **Advanced Settings:**
713
- - **Minimum Height** - Editor height in pixels (default: 300)
714
- - **Max Length** - Maximum characters (optional)
715
- - **Min Length** - Minimum characters (optional)
129
+ All keys are optional. Infrastructure options live in `config/plugins`; the AI provider is edited at runtime in Settings > Magic Editor X > Configuration.
716
130
 
717
- ---
131
+ | Key | Type | Default | Effect |
132
+ | --------------------------------------- | ---------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
133
+ | `debug` | boolean | `false` | Writes debug log lines (never content or personal data). |
134
+ | `rawHtml` | `'sanitize'` \| `'allow'` \| `'disable'` | `'sanitize'` | Raw HTML block on save: `sanitize` removes scripts, event handlers, iframes and unsafe URLs; `allow` stores the HTML as typed; `disable` empties it. |
135
+ | `sanitizeOnSave` | boolean | `true` | Normalise and sanitise Magic Editor X values on every Document Service write. Turning this off is not recommended. |
136
+ | `encryptionKey` | string (32+ characters) | unset | Key for the stored AI provider key. Prefer the `MAGIC_EDITOR_X_ENCRYPTION_KEY` environment variable. |
137
+ | `uploads.maxImageBytes` | integer | `10485760` (10 MiB) | Largest image accepted by file or URL (hard cap 500 MiB). |
138
+ | `uploads.maxFileBytes` | integer | `20971520` (20 MiB) | Largest attachment. |
139
+ | `linkPreview.enabled` | boolean | `true` | Link preview cards. When `false`, `GET /magic-editor-x/link` answers 404. |
140
+ | `linkPreview.timeoutMs` | integer | `8000` | Time limit for fetching a page (1000 to 30000). |
141
+ | `api.autoParseJSON` | boolean | `true` | Turn 1.x JSON strings into objects in Content API GET responses. |
142
+ | `ai.allowPrivateBaseUrl` | boolean | `false` | Allow AI base URLs on loopback or private networks (for local models). Owner decision; not editable in the admin. |
143
+ | `ai.apiKey` | string | unset | Provider key from the environment. When set it wins over a key stored in the settings. |
144
+ | `ai.requestsPerMinute` | integer | `20` | AI requests per admin per minute, counted per process. |
145
+ | `ai.timeoutMs` | integer | `60000` | Time limit for one provider request. |
146
+ | `collaboration.enabled` | boolean | `true` | Live collaboration and its Socket.IO server. |
147
+ | `collaboration.path` | string | `'/magic-editor-x/realtime'` | Socket.IO path on the Strapi HTTP server. |
148
+ | `collaboration.allowedOrigins` | string[] | `[]` | Extra browser origins allowed to open the socket. The admin URL and the server URL are always allowed. |
149
+ | `collaboration.pollIntervalMs` | integer | `400` | How often each process reads updates written by other processes (50 to 10000). |
150
+ | `collaboration.roomTtlMinutes` | integer | `30` | Keep a room's live state this long after the last person left. |
151
+ | `collaboration.maxMessageBytes` | integer | `2097152` (2 MiB) | Largest accepted socket message. |
152
+ | `collaboration.snapshotIntervalMinutes` | integer | `10` | Automatic version while people edit live. `0` turns it off. |
153
+ | `collaboration.tokenTtlSeconds` | integer | `60` | Lifetime of the one-time token that opens the socket. |
154
+ | `history.maxSnapshotsPerField` | integer | `50` | Versions kept per field and locale; older ones are deleted. |
718
155
 
719
- ## API Response Format
156
+ The validator rejects wrong types and ranges at startup and names the key, never the value. Keys from 1.x that no longer exist are ignored with a warning; see [Migrating from 1.x](#migrating-from-1x).
720
157
 
721
- ### Automatic JSON Parsing
158
+ ### Environment variables
722
159
 
723
- Magic Editor X automatically transforms JSON string fields into structured objects in API responses for better developer experience.
160
+ | Name | Required | Default | Effect |
161
+ | ------------------------------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
162
+ | `MAGIC_EDITOR_X_ENCRYPTION_KEY` | Only to store an AI key in the settings | unset | 32 or more characters. Encrypts the AI provider key (AES-256-GCM). Without it the settings page cannot store a key; you can still pass one with `ai.apiKey`. Generate one with `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`. Keep it stable: a different key makes a stored provider key unreadable, and the settings page then asks you to enter it again. |
724
163
 
725
- **Without auto-parsing (raw Strapi response):**
726
- ```json
727
- {
728
- "data": {
729
- "id": 1,
730
- "documentId": "abc123",
731
- "editorX": "{\"time\":1699999999999,\"blocks\":[{\"id\":\"xyz\",\"type\":\"paragraph\",\"data\":{\"text\":\"Hello\"}}],\"version\":\"2.31.0\"}"
732
- }
733
- }
734
- ```
164
+ The plugin also uses Strapi's own `admin.auth.secret` (`ADMIN_JWT_SECRET`) to sign collaboration tokens. Every process of a cluster must use the same value.
735
165
 
736
- **With auto-parsing (Magic Editor X middleware active):**
737
- ```json
738
- {
739
- "data": {
740
- "id": 1,
741
- "documentId": "abc123",
742
- "editorX": {
743
- "time": 1699999999999,
744
- "blocks": [
745
- {
746
- "id": "xyz",
747
- "type": "paragraph",
748
- "data": {
749
- "text": "Hello"
750
- }
751
- }
752
- ],
753
- "version": "2.31.0"
754
- }
755
- }
756
- }
757
- ```
166
+ ### AI settings (admin)
758
167
 
759
- **Configuration:**
168
+ Settings > Magic Editor X > Configuration stores these values in the Strapi store:
760
169
 
761
- Auto-parsing is enabled by default. To disable it, add to `config/plugins.ts`:
170
+ | Setting | Default | Range |
171
+ | -------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
172
+ | Enabled | off | |
173
+ | Provider | `anthropic` | `anthropic`, `openai`, `openai-compatible` |
174
+ | Base URL | provider default (`https://api.anthropic.com`, `https://api.openai.com`); required for `openai-compatible` | https, or private hosts when `ai.allowPrivateBaseUrl` is on |
175
+ | Model | `claude-opus-5-5` (Anthropic), `gpt-6-luna` (OpenAI) | letters, digits and `._:/@-` |
176
+ | API key | none | never returned; changing the provider or base URL requires entering it again |
177
+ | Max input characters | 8000 | 200 to 50000 |
178
+ | Max output tokens | 4096 | 64 to 16000 |
762
179
 
763
- ```typescript
764
- {
765
- 'magic-editor-x': {
766
- config: {
767
- api: {
768
- autoParseJSON: false // Disable automatic JSON parsing
769
- }
770
- }
771
- }
772
- }
773
- ```
180
+ ## Live collaboration
774
181
 
775
- **Manual Parsing (if auto-parse is disabled):**
182
+ When a document has been saved once, the editor joins the room of its field. Everyone with Content Manager read access to that document, locale and field and the `collaborate` action can join; people with update access can type, others watch as viewers.
776
183
 
777
- ```javascript
778
- // Client-side parsing
779
- const response = await fetch('/api/articles/1');
780
- const data = await response.json();
184
+ - Edits merge at character level when two people type in the same text field of a block, and per block otherwise. Every client and server converge on the same document (Yjs CRDT).
185
+ - Presence avatars show who is in the room; the badge shows the connection state (Connecting, Syncing, Live, Reconnecting).
186
+ - Changes made by others become part of your form. Save the entry as usual to store them.
187
+ - Text typed during a short network or server interruption is kept and sent after the reconnect.
188
+ - A new entry that has not been saved yet has no room.
189
+ - Access is checked again every five minutes; an admin who loses access is disconnected.
781
190
 
782
- // Parse Editor.js field manually
783
- const editorContent = JSON.parse(data.data.editorX);
784
- console.log(editorContent.blocks); // Array of blocks
785
- ```
191
+ ## Running several instances
786
192
 
787
- ---
193
+ Collaboration works with several Node processes and several machines that share one database, for example Railway with 2 replicas and pm2 with 4 processes each, behind a load balancer **without sticky sessions**. No Redis is needed.
788
194
 
789
- ## API Reference
195
+ How it works:
790
196
 
791
- ### Public API Endpoints
197
+ - The browser connects with the WebSocket transport only. A WebSocket connection is one long-lived request, so it does not need sticky routing. Your proxy must allow WebSocket upgrades on `collaboration.path` (default `/magic-editor-x/realtime`) and send them to Strapi.
198
+ - The session token is signed with a key derived from `admin.auth.secret`, so any process can accept a token issued by another one. All processes must use the same `ADMIN_JWT_SECRET`.
199
+ - Every update is written to the table `magic_editor_x_collab_updates` before it is acknowledged. Other processes read new rows every `collaboration.pollIntervalMs` and send them to their own sockets.
200
+ - Presence is stored in `magic_editor_x_collab_presence` with heartbeats; leases and one-time keys in `magic_editor_x_locks`. Seeding a room, compaction, automatic versions and cleanup each run once across all processes.
201
+ - Clients resynchronise their state every 20 seconds and after each reconnect, so a process restart loses nothing that was acknowledged.
792
202
 
793
- These endpoints are available for content-api usage:
203
+ The plugin creates these three tables on startup. They are not content types, so Strapi's schema sync leaves them alone.
794
204
 
795
- #### Fetch Link Metadata
205
+ Behind a proxy, also set `server.proxy` in `config/server` (`koa: true` and the number of trusted hops in `maxIpsCount`) so Strapi sees the real client address.
796
206
 
797
- ```http
798
- GET /api/magic-editor-x/link?url=https://example.com
799
- ```
207
+ The acceptance run with several processes is described in [CONTRIBUTING.md](./CONTRIBUTING.md).
800
208
 
801
- **Response:**
802
- ```json
803
- {
804
- "success": 1,
805
- "meta": {
806
- "title": "Example Domain",
807
- "description": "Example domain for documentation",
808
- "image": {
809
- "url": "https://example.com/og-image.jpg"
810
- }
811
- }
812
- }
813
- ```
209
+ ## AI assistant
814
210
 
815
- #### Upload Image by File
211
+ The assistant is off until an administrator turns it on in Settings > Magic Editor X > Configuration and gives it a provider:
816
212
 
817
- ```http
818
- POST /api/magic-editor-x/image/byFile
819
- Content-Type: multipart/form-data
213
+ | Provider | Request | Default model (2026-11-11) |
214
+ | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------- |
215
+ | Anthropic | `POST {base}/v1/messages`, headers `x-api-key` and `anthropic-version: 2026-10-21` | `claude-opus-5-5` |
216
+ | OpenAI | `POST {base}/v1/chat/completions`, `Authorization: Bearer`, `max_completion_tokens` | `gpt-6-luna` |
217
+ | OpenAI-compatible (Ollama, vLLM, LM Studio and similar) | `POST {base}/v1/chat/completions`, optional bearer key, `max_tokens` | none; you name the model |
820
218
 
821
- files.image: <file>
822
- ```
219
+ - The key stays on the server. It is encrypted at rest with `MAGIC_EDITOR_X_ENCRYPTION_KEY` or read from `ai.apiKey`, and it is never sent to the browser or written to logs.
220
+ - The selected text (with its inline formatting) and a fixed instruction are sent to the provider. Nothing else from the document is sent. The text is never logged.
221
+ - Base URLs must be public https URLs. Loopback and private hosts are allowed only with `ai.allowPrivateBaseUrl: true` in `config/plugins`. Redirects are not followed.
222
+ - Input is limited by "Max input characters", output by "Max output tokens". Each admin can send `ai.requestsPerMinute` requests per minute per process.
223
+ - The answer is sanitised to the inline tags the editor uses before it reaches the browser. The admin reviews the suggestion and chooses Replace selection; nothing changes before that.
823
224
 
824
- **Response:**
825
- ```json
826
- {
827
- "success": 1,
828
- "file": {
829
- "url": "https://cdn.example.com/image.jpg",
830
- "name": "image.jpg",
831
- "size": 123456
832
- }
833
- }
834
- ```
835
-
836
- #### Upload Image by URL
225
+ ## Data format
837
226
 
838
- ```http
839
- POST /api/magic-editor-x/image/byUrl
840
- Content-Type: application/json
841
-
842
- {
843
- "url": "https://example.com/image.jpg"
844
- }
845
- ```
227
+ The field stores an Editor.js document as JSON:
846
228
 
847
- **Response:**
848
229
  ```json
849
230
  {
850
- "success": 1,
851
- "file": {
852
- "url": "https://cdn.example.com/image.jpg",
853
- "name": "image.jpg",
854
- "size": 123456
855
- }
231
+ "time": 1762866000000,
232
+ "version": "2.31.7",
233
+ "blocks": [
234
+ { "id": "kq1x9w0abc", "type": "header", "data": { "text": "Release notes", "level": 2 } },
235
+ {
236
+ "id": "kq1x9w0abd",
237
+ "type": "paragraph",
238
+ "data": { "text": "Read the <a href=\"https://example.test\">guide</a>." },
239
+ "tunes": { "alignmentTune": { "alignment": "left" } }
240
+ }
241
+ ]
856
242
  }
857
243
  ```
858
244
 
859
- ### Admin API Endpoints
860
-
861
- These endpoints require authentication and admin permissions:
862
-
863
- #### License Management
864
-
865
- ```http
866
- GET /magic-editor-x/license/status
867
- GET /magic-editor-x/license/limits
868
- POST /magic-editor-x/license/auto-create
869
- POST /magic-editor-x/license/store-key
870
- ```
871
-
872
- #### Collaboration Permissions
873
-
874
- ```http
875
- GET /magic-editor-x/collaboration/permissions
876
- POST /magic-editor-x/collaboration/permissions
877
- PUT /magic-editor-x/collaboration/permissions/:id
878
- DELETE /magic-editor-x/collaboration/permissions/:id
879
- ```
880
-
881
- #### Real-Time Sessions
245
+ Data of each block type as stored after sanitising (`shared/sanitize-policy.mjs`):
246
+
247
+ | Block | `data` |
248
+ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
249
+ | `paragraph` | `{ text }` (inline HTML) |
250
+ | `header` | `{ text, level: 1-6 }` |
251
+ | `list` | `{ style: 'ordered' \| 'unordered' \| 'checklist', meta?: { start?, counterType? }, items: [{ content, meta?, items: [...] }] }` |
252
+ | `checklist` | `{ items: [{ text, checked }] }` |
253
+ | `quote` | `{ text, caption, alignment: 'left' \| 'center' }` |
254
+ | `warning` | `{ title, message }` |
255
+ | `alert` | `{ type: 'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'light' \| 'dark', align: 'left' \| 'center' \| 'right', message }` |
256
+ | `toggle` | `{ text, status: 'open' \| 'closed', fk?, items }` (the next `items` blocks are its content) |
257
+ | `code` | `{ code }` (plain text) |
258
+ | `codeFlask` | `{ code, language, showlinenumbers? }` |
259
+ | `raw` | `{ html }` (see `rawHtml`) |
260
+ | `table` | `{ withHeadings, stretched, content: string[][] }` |
261
+ | `image` | `{ file: { url, mime?, alt?, width?, height?, size?, formats?, id?, documentId? }, caption, withBorder, withBackground, stretched }` |
262
+ | `simpleImage` | `{ url, caption, withBorder, withBackground, stretched }` |
263
+ | `linkTool` | `{ link, meta: { title, description, site_name?, image?: { url } } }` |
264
+ | `attaches` | `{ file: { url, name?, extension?, size?, title? }, title }` |
265
+ | `embed` | `{ service, source, embed, width?, height?, caption }` (`embed` is always https) |
266
+ | `personality` | `{ name, description, link, photo }` |
267
+ | `button` | `{ text, link, style, openInNewTab }` |
268
+ | `delimiter` | `{}` |
269
+ | custom simple block | `{ content, <field values>, blockType: 'simple', blockName }` |
270
+ | custom embedded-entry block | `{ entry: { id, documentId, title, <display fields> }, contentType, displayMode }` |
271
+
272
+ Inline HTML may contain `b`, `strong`, `i`, `em`, `u`, `s`, `mark`, `code`, `a` (`href`, `target`, `rel`, `title`), `br`, `span` (class `cdx-tooltip` with `data-tooltip`), `sub` and `sup`. Links allow `http`, `https`, `mailto`, `tel` and relative URLs. Escape plain-text fields (`code`, `personality`, `button.text`, link card text) when you render them.
273
+
274
+ Tunes are stored per block in `tunes`: `alignmentTune: { alignment }`, `textVariant: '' | 'call-out' | 'citation' | 'details'`, `indentTune: { indentLevel }`.
275
+
276
+ The Content API returns the object as stored. Entries saved with 1.x may still contain a JSON string until they are saved again; with `api.autoParseJSON` (default) the plugin parses such strings in Content API GET responses.
277
+
278
+ ## Admin API and permissions
279
+
280
+ ### Permissions
281
+
282
+ | Action | Label in Roles | Gates |
283
+ | --------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
284
+ | `plugin::magic-editor-x.access` | Use the editor (uploads, link previews, custom blocks, version history) | Editor configuration, link previews, uploads (with the Media Library permission), content type list, custom block list, version history, collaboration and AI routes |
285
+ | `plugin::magic-editor-x.collaborate` | Edit together in real time | Joining live rooms |
286
+ | `plugin::magic-editor-x.ai.use` | Use the AI assistant | AI requests |
287
+ | `plugin::magic-editor-x.custom-blocks.manage` | Manage custom blocks | Settings > Custom blocks and its routes |
288
+ | `plugin::magic-editor-x.settings.read` | Read settings | Settings > Configuration (read) |
289
+ | `plugin::magic-editor-x.settings.update` | Update settings | Saving settings, testing the AI connection |
290
+
291
+ Uploads also need the Media Library action `plugin::upload.assets.create`. Version history and collaboration also apply the Content Manager permissions of the document: read access (including conditions such as "is creator", locale and field permissions) to list versions and join a room, update access to save versions, restore and type. A document you cannot read answers 404, the same as a document that does not exist.
292
+
293
+ Super Admins have all actions. The `access` action keeps its 1.x id, so roles that had it keep using the editor.
294
+
295
+ ### Routes
296
+
297
+ All routes are admin routes served at `/magic-editor-x/...` and need an admin session (`Authorization: Bearer <admin JWT>`). There are no Content API routes. Errors use the Strapi envelope `{ "data": null, "error": { "status", "name", "message", "details" } }`; validation errors carry `details.fieldErrors` keyed by field path. Editor.js tool routes answer `{ "success": 0, "message" }` on errors, as the tools expect.
298
+
299
+ | Method | Path | Actions | Body / query | Response |
300
+ | ------ | --------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
301
+ | GET | `/magic-editor-x/config` | access | | `{ data: { collaboration, ai, uploads, linkPreview, rawHtml, permissions } }` |
302
+ | GET | `/magic-editor-x/link` | access | `?url=` | `{ success: 1, link, meta }` |
303
+ | POST | `/magic-editor-x/image/byFile` | access, upload | multipart `image` | `{ success: 1, file: { url, ... } }` |
304
+ | POST | `/magic-editor-x/image/byUrl` | access, upload | `{ url }` | `{ success: 1, file }` |
305
+ | POST | `/magic-editor-x/file/upload` | access, upload | multipart `file` | `{ success: 1, file: { url, name, title, size, extension } }` |
306
+ | GET | `/magic-editor-x/content-types` | access | | `{ data: [{ uid, kind, displayName, attributes }] }` (types you can read) |
307
+ | GET | `/magic-editor-x/custom-blocks` | access (`?all=true` also needs custom-blocks.manage) | `?all=true` | `{ data: [block] }` |
308
+ | GET | `/magic-editor-x/custom-blocks/export` | custom-blocks.manage | | `{ data: { format: 'magic-editor-x/custom-blocks', version: 2, exportedAt, blocks } }` |
309
+ | POST | `/magic-editor-x/custom-blocks/import` | custom-blocks.manage | export document | `{ data: { created: [name], skipped: [{ name, reason }] } }` |
310
+ | PUT | `/magic-editor-x/custom-blocks/order` | custom-blocks.manage | `{ ids }` (every block once) | `{ data: [block] }` |
311
+ | POST | `/magic-editor-x/custom-blocks` | custom-blocks.manage | block definition | 201 `{ data: block }` |
312
+ | PUT | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage | full block definition | `{ data: block }` |
313
+ | DELETE | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage | | `{ data: { id } }` |
314
+ | POST | `/magic-editor-x/custom-blocks/:id/duplicate` | custom-blocks.manage | | 201 `{ data: block }` |
315
+ | POST | `/magic-editor-x/collaboration/session` | access, collaborate | `{ uid, documentId, locale?, field, initialValue? }` | `{ data: { token, path, canEdit, expiresAt } }` |
316
+ | GET | `/magic-editor-x/history` | access | `?uid&documentId&locale&field` | `{ data: [version], meta: { canRestore, canCreate } }` |
317
+ | GET | `/magic-editor-x/history/:id` | access | | `{ data: { ...version, content } }` |
318
+ | POST | `/magic-editor-x/history` | access | `{ uid, documentId, locale?, field, content }` | 201 new version, 200 with `meta.created: false` when unchanged |
319
+ | POST | `/magic-editor-x/ai/:action` | access, ai.use | `{ text, language?, tone? }` | `{ data: { text } }` |
320
+ | GET | `/magic-editor-x/settings` | settings.read | | `{ data: { ai, environment } }` (no secrets) |
321
+ | PUT | `/magic-editor-x/settings` | settings.read, settings.update | `{ ai: { enabled, provider, baseUrl, model, maxInputChars, maxOutputTokens, apiKey? } }` | `{ data: { ai, environment } }` |
322
+ | POST | `/magic-editor-x/settings/ai/test` | settings.read, settings.update | `{ ai: {...} }` | `{ data: { ok: true } }` |
323
+
324
+ `upload` means `plugin::upload.assets.create`. AI actions: `improve`, `grammar`, `shorten`, `expand`, `summarize`, `simplify`, `translate` (with `language`), `tone` (with `tone`), `continue`. Provider problems answer with `name: 'AIProviderError'` and `details.code` (`DISABLED`, `NOT_CONFIGURED`, `NO_API_KEY`, `AUTH_FAILED`, `PROVIDER_RATE_LIMIT`, `TIMEOUT`, `REFUSED`, `PROVIDER_ERROR`). Too long text answers 413, too many requests 429.
325
+
326
+ Example: save a version.
882
327
 
883
328
  ```http
884
- POST /magic-editor-x/realtime/session-token
885
- ```
329
+ POST /magic-editor-x/history
330
+ Authorization: Bearer <admin JWT>
331
+ Content-Type: application/json
886
332
 
887
- **Request:**
888
- ```json
889
- {
890
- "roomId": "api::article.article|abc123|content",
891
- "fieldName": "content"
892
- }
333
+ { "uid": "api::article.article", "documentId": "k9d2w4xq8m1n0p3r5t7v9b1c", "locale": "en", "field": "body",
334
+ "content": { "blocks": [{ "id": "a1", "type": "paragraph", "data": { "text": "Hello" } }] } }
893
335
  ```
894
336
 
895
- **Response:**
896
337
  ```json
897
338
  {
898
- "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
899
- "expiresAt": 1699999999999
900
- }
901
- ```
902
-
903
- ---
904
-
905
- ## Collaboration System
906
-
907
- ### Permission Model
908
-
909
- Magic Editor X uses a flexible role-based permission system:
910
-
911
- **Roles:**
912
- - **Owner** - Full control (edit, delete, manage permissions)
913
- - **Editor** - Can edit content
914
- - **Viewer** - Read-only access
915
-
916
- **Permission Scope:**
917
- - Per content type (e.g., `api::article.article`)
918
- - Per user or role
919
- - Inherits from Strapi's built-in RBAC
920
-
921
- ### Managing Collaborators
922
-
923
- Navigate to **Plugins > Magic Editor X > Collaboration** to:
924
-
925
- 1. **Add Collaborator**
926
- - Select user
927
- - Choose content type
928
- - Assign role (Viewer, Editor, Owner)
929
-
930
- 2. **Update Permission**
931
- - Change role
932
- - Modify content type access
933
-
934
- 3. **Remove Collaborator**
935
- - Revoke access
936
-
937
- ### Collaboration Limits
938
-
939
- Limits are enforced based on your license:
940
-
941
- | License | Concurrent Collaborators |
942
- |---------|-------------------------|
943
- | FREE | 2 |
944
- | PREMIUM | 10 |
945
- | ADVANCED | Unlimited |
946
-
947
- **Note:** The editor itself is completely free. You only pay for extended collaboration features.
948
-
949
- ---
950
-
951
- ## Pricing
952
-
953
- Magic Editor X follows a freemium model:
954
-
955
- | Feature | FREE | PREMIUM | ADVANCED |
956
- |---------|------|---------|----------|
957
- | **Price** | $0 | $9.90/mo | $24.90/mo |
958
- | Full Editor | Yes | Yes | Yes |
959
- | All 25+ Tools | Yes | Yes | Yes |
960
- | Real-Time Sync | Yes | Yes | Yes |
961
- | Collaborators | 2 | 10 | Unlimited |
962
- | Version History | - | Yes | Yes |
963
- | AI Assistant | - | Pay-per-use | Included |
964
- | Priority Support | - | Email | Email + Chat |
965
- | Custom Blocks | - | - | Yes |
966
-
967
- **Get started:** https://store.magicdx.dev/
968
-
969
- ---
970
-
971
- ## Development & Extension
972
-
973
- ### Custom Block Types
974
-
975
- Create your own block tools:
976
-
977
- ```javascript
978
- // custom-tools/MyCustomTool.js
979
- export default class MyCustomTool {
980
- static get toolbox() {
981
- return {
982
- title: 'My Tool',
983
- icon: '<svg>...</svg>'
984
- };
985
- }
986
-
987
- constructor({ data, api, config }) {
988
- this.data = data;
989
- this.api = api;
990
- this.config = config;
991
- }
992
-
993
- render() {
994
- const wrapper = document.createElement('div');
995
- wrapper.classList.add('my-custom-tool');
996
- // Add your UI
997
- return wrapper;
998
- }
999
-
1000
- save(blockContent) {
1001
- return {
1002
- // Your data structure
1003
- text: blockContent.querySelector('input').value
1004
- };
1005
- }
1006
-
1007
- static get sanitize() {
1008
- return {
1009
- text: {} // Sanitizer config
1010
- };
1011
- }
339
+ "data": {
340
+ "id": "s8f2k1x0w9q7e5r3t1y6u4i2",
341
+ "version": 3,
342
+ "trigger": "manual",
343
+ "createdAt": "2026-11-11T09:30:00.000Z",
344
+ "createdBy": "Anna Beispiel",
345
+ "stats": { "blocks": 1, "words": 1, "characters": 5 },
346
+ "restorable": true
347
+ },
348
+ "meta": { "created": true }
1012
349
  }
1013
350
  ```
1014
351
 
1015
- **Register in `config/tools.js`:**
1016
-
1017
- ```javascript
1018
- import MyCustomTool from './custom-tools/MyCustomTool';
352
+ ## Security and privacy
1019
353
 
1020
- export const getTools = ({ mediaLibToggleFunc, pluginId }) => {
1021
- return {
1022
- // ... existing tools
1023
- myCustomTool: {
1024
- class: MyCustomTool,
1025
- config: {
1026
- // Your config
1027
- }
1028
- }
1029
- };
1030
- };
1031
- ```
1032
-
1033
- ### Extending Collaboration
1034
-
1035
- Hook into collaboration events:
1036
-
1037
- ```javascript
1038
- // In your component
1039
- const { awareness } = useMagicCollaboration({
1040
- enabled: true,
1041
- roomId: 'my-room',
1042
- onRemoteUpdate: () => {
1043
- console.log('Remote update received');
1044
- }
1045
- });
1046
-
1047
- // Listen to presence changes
1048
- awareness.on('change', ({ added, updated, removed }) => {
1049
- console.log('Users joined:', added);
1050
- console.log('Users updated:', updated);
1051
- console.log('Users left:', removed);
1052
- });
1053
- ```
354
+ - **Stored content:** every Magic Editor X value is normalised and sanitised on save by a Document Service middleware (Content Manager, Content API, imports and code). Unknown keys of known block types are dropped, URLs are checked, inline HTML is limited to the tags above and the raw HTML block follows `rawHtml`. Values over 5 MiB, with more than 5000 blocks or nested deeper than 24 levels are rejected with 400, never truncated. The admin sanitises again before rendering (DOMPurify with the same rules).
355
+ - **Outgoing requests:** link previews and images by URL only fetch public http(s) addresses: the host is resolved once, every address must be public, the connection is pinned to that address, redirects are re-checked (at most 3), and size, type and time are limited. The AI provider is called only when an administrator configured it.
356
+ - **Uploads** are checked by their first bytes (not by the file name or the browser's MIME type) and stored through the Media Library with the admin as creator.
357
+ - **Collaboration:** tokens are signed, expire after `collaboration.tokenTtlSeconds` and work once; the socket accepts the admin and server origins and `collaboration.allowedOrigins`; messages are size-limited and must be valid Yjs updates; viewers cannot write.
358
+ - **Secrets:** the AI key is encrypted with AES-256-GCM (random IV, versioned format) and never returned. Changing the provider or base URL requires entering the key again, so a stored key cannot be sent to another host.
359
+ - **Logs** contain operation names and error codes only, never content, URLs with queries, tokens, user ids or email addresses.
360
+ - **Stored data:** custom block definitions, versions (field content and the admin who saved it), live rooms (Yjs updates, removed `collaboration.roomTtlMinutes` after the last person left) and presence rows (admin display name, colour, caret position; removed when the socket closes or after missed heartbeats).
361
+ - **Content Security Policy:** Editor.js and the Design System add inline styles, which Strapi's default `style-src 'unsafe-inline'` allows. The socket connects to the same origin as the admin, which `connect-src 'self'` covers; add the `wss:` origin only when the admin runs on another host. Embed iframes need `frame-src` only on your frontend.
1054
362
 
1055
- ---
363
+ Report vulnerabilities privately through GitHub security advisories on the repository.
1056
364
 
1057
365
  ## Troubleshooting
1058
366
 
1059
- ### Common Issues
367
+ | Symptom | Cause | Fix |
368
+ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
369
+ | The field shows "The editor could not be loaded." | The role lacks `plugin::magic-editor-x.access`, or the server is unreachable | Grant the action; check the server log. |
370
+ | No upload or "You do not have permission to upload files" | The role lacks `plugin::upload.assets.create` | Grant Media Library create to the role. |
371
+ | No version history (clock) button | The entry was never saved | Save the entry once. |
372
+ | Badge shows "Live editing unavailable" | No `collaborate` action, no read access to the document, or `collaboration.enabled: false` | Grant the action or check the Content Manager permissions. |
373
+ | Badge stays at "Connecting" or "Reconnecting" | The proxy does not forward WebSocket upgrades on `collaboration.path`, or the origin is not allowed | Allow upgrades on the path; add the admin origin to `collaboration.allowedOrigins` when the admin runs on another host. |
374
+ | Settings say the API key cannot be stored | `MAGIC_EDITOR_X_ENCRYPTION_KEY` is missing or shorter than 32 characters | Set the variable and restart, or use `ai.apiKey`. |
375
+ | Settings say the stored key is unreadable | The encryption key changed | Enter the provider key again. |
376
+ | AI error "The AI provider rejected the key." | Wrong key for this provider | Enter the key again and use Test connection. |
377
+ | Startup error `[magic-editor-x] invalid configuration for: <key>` | Wrong type or range in `config/plugins` | Fix the named key (see the reference table). |
378
+ | 400 "A Magic Editor X field contains invalid content" | The value is not editor JSON, too large or too deep | Send an Editor.js object within the limits. |
1060
379
 
1061
- **1. Editor Not Loading**
380
+ ## Migrating from 1.x
1062
381
 
1063
- Check browser console for errors. Common causes:
1064
- - Plugin not enabled in `config/plugins.ts`
1065
- - Build not run after installation (`npm run build`)
1066
- - CSP blocking external resources
382
+ 2.0 is a major release. Stored content keeps working; routes, permissions and configuration changed. The full guide is in the [CHANGELOG](./CHANGELOG.md). In short:
1067
383
 
1068
- **2. Image Upload Failing**
384
+ 1. Update the package and rebuild the admin: `npm install magic-editor-x@2 && npm run build`.
385
+ 2. Remove 1.x configuration keys (`enabledTools`, `linkPreviewTimeout`, `maxImageSize`, `maxFileSize`, `allowedImageTypes`, `collaboration.wsPath`, `wsUrl`, `sessionTTL`, `allowedAdminRoles`, `allowedAdminUserIds`, `cors`) and use the new keys above.
386
+ 3. Grant the new actions to your roles: `collaborate`, `ai.use`, `custom-blocks.manage`, `settings.read`, `settings.update`. Collaboration grants from 1.x are replaced by Content Manager permissions; Strapi drops the old tables on the first start.
387
+ 4. If you used the AI assistant, configure your own provider in Settings > Magic Editor X > Configuration.
388
+ 5. If your raw HTML blocks need scripts or iframes, set `rawHtml: 'allow'`.
1069
389
 
1070
- Verify:
1071
- - Strapi Upload plugin is enabled
1072
- - File size within limits (default 10MB)
1073
- - File type is allowed
1074
- - User has upload permissions
390
+ On the first start the plugin converts 1.x versions that only contained collaboration state and cleans custom block icons and templates. Both run once across all processes.
1075
391
 
1076
- **3. Collaboration Not Working**
1077
-
1078
- Debug checklist:
1079
- - WebSocket connection established (check Network tab)
1080
- - Session token valid (check `/realtime/session-token` response)
1081
- - User has collaboration permissions
1082
- - Firewall/proxy allows WebSocket connections
1083
-
1084
- **4. Link Previews Not Showing**
1085
-
1086
- Ensure:
1087
- - CSP allows `img-src: '*'` in middlewares config
1088
- - Target site returns OpenGraph metadata
1089
- - Link preview timeout not too short (default: 10s)
1090
-
1091
- ### Enable Debug Logging
1092
-
1093
- Add to `config/plugins.ts`:
1094
-
1095
- ```typescript
1096
- {
1097
- 'magic-editor-x': {
1098
- config: {
1099
- debug: true // Enable verbose logging
1100
- }
1101
- }
1102
- }
1103
- ```
1104
-
1105
- ---
1106
-
1107
- ## Roadmap
1108
-
1109
- ### ✅ Completed
1110
- - **Version History** - Track all content changes with snapshot restore (v1.1.0)
1111
- - **Character-Level Collaboration** - Simultaneous editing in same block (v1.2.0)
1112
- - **Webtools Links Integration** - Internal/external link picker (v1.2.0)
1113
-
1114
- ### 🚧 In Progress
1115
- - **Comments & Annotations** - Inline comments for editorial workflow
1116
- - **Custom Blocks API** - Simplified API for creating custom tools
1117
-
1118
- ### 📋 Planned
1119
- - **Advanced AI** - Content suggestions, auto-completion, tone analysis
1120
- - **Offline Mode** - Full offline editing with sync on reconnect
1121
- - **Import/Export** - Markdown, HTML, DOCX conversion
1122
- - **Templates** - Pre-built content templates
1123
- - **Block Permissions** - Per-block editing restrictions
1124
-
1125
- ---
1126
-
1127
- ## Resources
1128
-
1129
- - **Documentation:** https://docs.magicdx.dev/
1130
- - **Store:** https://store.magicdx.dev/
1131
- - **GitHub:** https://github.com/Schero94/magic-editor-x
1132
- - **Strapi Custom Fields:** https://docs.strapi.io/cms/features/custom-fields
1133
- - **Editor.js:** https://editorjs.io/
1134
- - **Y.js:** https://docs.yjs.dev/
1135
-
1136
- ---
1137
-
1138
- ## Contributing
1139
-
1140
- Contributions are welcome! Please:
1141
-
1142
- 1. Fork the repository
1143
- 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
1144
- 3. Commit your changes (`git commit -m 'Add amazing feature'`)
1145
- 4. Push to the branch (`git push origin feature/amazing-feature`)
1146
- 5. Open a Pull Request
1147
-
1148
- **Development Setup:**
392
+ ## Development and tests
1149
393
 
1150
394
  ```bash
1151
- git clone https://github.com/Schero94/magic-editor-x.git
1152
- cd magic-editor-x
1153
- npm install
1154
- npm run watch:link
395
+ npm ci
396
+ npm run lint
397
+ npm run format:check
398
+ npm test # unit tests, no Strapi host needed
399
+ npm run build # admin and server bundles, then a runtime check
400
+ npm run verify
401
+ MEX_HOST_URL=http://127.0.0.1:1421 MEX_CREDS=/path/to/creds.json npm run test:integration
1155
402
  ```
1156
403
 
1157
- ---
1158
-
1159
- ## License
404
+ [CONTRIBUTING.md](./CONTRIBUTING.md) explains the isolated acceptance host, the integration suite on SQLite and PostgreSQL and the multi-process acceptance run. [AGENTS.md](./AGENTS.md) is the contract for coding agents.
1160
405
 
1161
- MIT License - See [LICENSE](LICENSE) for details
406
+ ## Maintenance status
1162
407
 
1163
- Copyright (c) 2024-2025 Schero D.
408
+ Actively maintained. Releases are made with semantic-release from `main`; every release runs lint, tests, build, package verification and a production dependency audit first. Supported line: Strapi 5.
1164
409
 
1165
- ---
410
+ ## Languages
1166
411
 
1167
- ## Support
412
+ The admin is translated into English, German (formal Sie), French, Spanish and Portuguese.
1168
413
 
1169
- - **Email:** support@magicdx.dev
1170
- - **Issues:** https://github.com/Schero94/magic-editor-x/issues
1171
- - **Discord:** https://discord.gg/magicdx
1172
-
1173
- ---
1174
-
1175
- **Built with dedication by [Schero D.](https://github.com/Schero94)**
414
+ ## License
1176
415
 
1177
- Part of the MagicDX Plugin Suite for Strapi
416
+ [MIT](./LICENSE) © 2025-2026 Schero D.