magic-editor-x 1.6.0 → 2.1.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 +322 -0
  2. package/LICENSE +1 -7
  3. package/README.md +398 -969
  4. package/dist/admin/ConfigurationPage-CK2AbfGW.mjs +886 -0
  5. package/dist/admin/ConfigurationPage-CzsT_dO_.js +888 -0
  6. package/dist/admin/CustomBlocksPage-B2A8S5MV.mjs +1741 -0
  7. package/dist/admin/CustomBlocksPage-CvLrsBds.js +1743 -0
  8. package/dist/admin/EditorField-7YCdXx-v.mjs +6829 -0
  9. package/dist/admin/EditorField-BdBCW15Q.js +6864 -0
  10. package/dist/admin/api-CmccMxlN.js +36 -0
  11. package/dist/admin/api-D5CAH0nh.mjs +37 -0
  12. package/dist/admin/de-BHPyA2S-.mjs +103 -0
  13. package/dist/admin/de-Bt6pYIWi.mjs +246 -0
  14. package/dist/admin/de-CVbi685U.js +246 -0
  15. package/dist/admin/de-CkUYGb7U.js +176 -0
  16. package/dist/admin/de-DBR893G4.js +13 -0
  17. package/dist/admin/de-RMs-_SCK.js +103 -0
  18. package/dist/admin/de-fBFh09Wl.mjs +13 -0
  19. package/dist/admin/de-rRIutpYJ.mjs +176 -0
  20. package/dist/admin/en-BX362fTp.js +246 -0
  21. package/dist/admin/en-B_HltUxZ.mjs +246 -0
  22. package/dist/admin/en-BluCStLw.mjs +103 -0
  23. package/dist/admin/en-C81faOHP.js +103 -0
  24. package/dist/admin/en-D9Nfccux.mjs +13 -0
  25. package/dist/admin/en-DulOcmXb.js +176 -0
  26. package/dist/admin/en-Puup8TFi.mjs +176 -0
  27. package/dist/admin/en-gueRT44P.js +13 -0
  28. package/dist/admin/es-257SSB7f.mjs +176 -0
  29. package/dist/admin/es-B0Zy8DVg.mjs +13 -0
  30. package/dist/admin/es-BoQZC86B.js +176 -0
  31. package/dist/admin/es-CHHEZi44.js +246 -0
  32. package/dist/admin/es-CQRI2Prp.mjs +103 -0
  33. package/dist/admin/es-CrhwOq-5.mjs +246 -0
  34. package/dist/admin/es-D1QzY0JW.js +103 -0
  35. package/dist/admin/es-DRGs7meF.js +13 -0
  36. package/dist/admin/fr-5djKfQ3s.mjs +246 -0
  37. package/dist/admin/fr-B3SL0TBV.js +246 -0
  38. package/dist/admin/fr-B8rdLAIL.js +13 -0
  39. package/dist/admin/fr-C5rSdKU4.mjs +176 -0
  40. package/dist/admin/fr-Di3R6gOX.mjs +103 -0
  41. package/dist/admin/fr-HxFcPpv4.js +176 -0
  42. package/dist/admin/fr-R3_MbzT5.js +103 -0
  43. package/dist/admin/fr-oiUb2bb_.mjs +13 -0
  44. package/dist/admin/index-0_b1iroK.mjs +156 -0
  45. package/dist/admin/index-6SZLli70.js +155 -0
  46. package/dist/admin/index.js +1 -1
  47. package/dist/admin/index.mjs +2 -2
  48. package/dist/admin/pt-B3Jce6uT.mjs +13 -0
  49. package/dist/admin/pt-BCW1u_Hp.js +103 -0
  50. package/dist/admin/pt-BdnY2Cth.mjs +246 -0
  51. package/dist/admin/pt-BiWuSBcH.js +13 -0
  52. package/dist/admin/pt-Cjn2Sc9k.js +176 -0
  53. package/dist/admin/pt-Cr9AL408.mjs +103 -0
  54. package/dist/admin/pt-D6UuEtPy.mjs +176 -0
  55. package/dist/admin/pt-EVwCuBUK.js +246 -0
  56. package/dist/admin/sanitize-DP5aeU7V.js +597 -0
  57. package/dist/admin/sanitize-jjCot5PM.mjs +596 -0
  58. package/dist/admin/useT-91ruePzq.js +130 -0
  59. package/dist/admin/useT-vgY88N_H.mjs +131 -0
  60. package/dist/server/index.js +5373 -64722
  61. package/dist/server/index.mjs +5373 -64731
  62. package/package.json +90 -66
  63. package/strapi-admin.js +3 -0
  64. package/strapi-server.js +3 -0
  65. package/COPYRIGHT_NOTICE.txt +0 -20
  66. package/dist/admin/App-BwMEZnS-.mjs +0 -2144
  67. package/dist/admin/App-HNr2tizR.js +0 -2147
  68. package/dist/admin/CustomBlocksPage-BjcA7MGz.js +0 -1519
  69. package/dist/admin/CustomBlocksPage-COPOZ2-_.mjs +0 -1517
  70. package/dist/admin/LicensePage-D0DMTF41.mjs +0 -392
  71. package/dist/admin/LicensePage-D0_9yPkw.js +0 -394
  72. package/dist/admin/LiveCollaborationPanel-CZAbgAVr.js +0 -223
  73. package/dist/admin/LiveCollaborationPanel-D8z72afw.mjs +0 -221
  74. package/dist/admin/Settings-DRenvRcG.js +0 -441
  75. package/dist/admin/Settings-DjyNURlS.mjs +0 -439
  76. package/dist/admin/de-C_0Mj-Zo.mjs +0 -296
  77. package/dist/admin/de-DVNVpAt9.js +0 -296
  78. package/dist/admin/en-B7AAf1ie.mjs +0 -296
  79. package/dist/admin/en-C2hv5GsA.js +0 -296
  80. package/dist/admin/es-BzJqcIST.js +0 -274
  81. package/dist/admin/es-zdP8sd-f.mjs +0 -274
  82. package/dist/admin/fr-CtAgOgH1.mjs +0 -274
  83. package/dist/admin/fr-D3GwqAAJ.js +0 -274
  84. package/dist/admin/getTranslation-2OiEgVGt.mjs +0 -49459
  85. package/dist/admin/getTranslation-DQ_WJ-7M.js +0 -49475
  86. package/dist/admin/index-Bn2tfJrC.js +0 -2186
  87. package/dist/admin/index-DAtClhqy.js +0 -6956
  88. package/dist/admin/index-FVEbTfqO.mjs +0 -2187
  89. package/dist/admin/index-gjWl-6E2.mjs +0 -6934
  90. package/dist/admin/magic-editor-x.css +0 -1103
  91. package/dist/admin/pt-BmUw6YMP.mjs +0 -274
  92. package/dist/admin/pt-CFo0nTbj.js +0 -274
  93. package/dist/admin/tools-CzHTZaY_.mjs +0 -2268
  94. package/dist/admin/tools-DALFhvPO.js +0 -2299
  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,1073 +1,502 @@
1
- # Magic Editor X
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
- Project site: https://schero94.github.io/Magic-Editor-X/
13
-
14
- ---
15
-
16
- ## What's New in v1.4.0-alpha.1
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/Schero94/Magic-Editor-X/main/docs/site/img/icon.svg" alt="Magic Editor X" width="96" height="96" />
3
+ </p>
17
4
 
18
- ### Custom Blocks (Contentful-style)
19
-
20
- Create custom editor blocks directly from the Admin UI - no code required!
21
-
22
- - **Simple Blocks** - Text/HTML blocks with configurable fields (text, textarea, select, color, checkbox)
23
- - **Embedded Entry Blocks** - Reference other Strapi content types with preview fields (like Contentful Inline Entries)
24
- - **HTML Templates** - Define custom templates with `{{fieldName}}` placeholders
25
- - **Replaces Dynamic Zones** - Simpler alternative for structured content within the editor
26
-
27
- ### Tier-Based Limits
28
-
29
- | Feature | FREE | PREMIUM | ADVANCED |
30
- |---------|------|---------|----------|
31
- | Simple Blocks | 3 | 10 (combined) | Unlimited |
32
- | Embedded Entry | - | 10 (combined) | Unlimited |
33
- | Export/Import | - | - | Yes |
34
- | API Access | - | - | Yes |
35
-
36
- ### Previous Updates (v1.2.0)
5
+ # Magic Editor X
37
6
 
38
- - **Character-Level Collaboration** - Multiple users can now type in the same paragraph simultaneously without conflicts
39
- - **Webtools Links Integration** - Optional integration with PluginPal's Webtools Links addon for internal/external link management
40
- - **Direct Link Editing** - Click on any link to instantly open the link editor modal
41
- - **Improved Fullscreen Mode** - Blocks now stretch to full width, Media Library modal works correctly
7
+ 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.
8
+
9
+ [![npm](https://img.shields.io/npm/v/magic-editor-x)](https://www.npmjs.com/package/magic-editor-x)
10
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
11
+
12
+ Live docs: <https://schero94.github.io/Magic-Editor-X/>
13
+
14
+ ## Contents
15
+
16
+ - [Features](#features)
17
+ - [Screenshots](#screenshots)
18
+ - [Core concepts](#core-concepts)
19
+ - [Screens](#screens)
20
+ - [Compatibility](#compatibility)
21
+ - [Install](#install)
22
+ - [Configuration](#configuration)
23
+ - [Live collaboration](#live-collaboration)
24
+ - [Running several instances](#running-several-instances)
25
+ - [AI assistant](#ai-assistant)
26
+ - [Data format](#data-format)
27
+ - [Admin API and permissions](#admin-api-and-permissions)
28
+ - [Security and privacy](#security-and-privacy)
29
+ - [Troubleshooting](#troubleshooting)
30
+ - [Migrating from 1.x](#migrating-from-1x)
31
+ - [Development and tests](#development-and-tests)
32
+ - [Maintenance status](#maintenance-status)
33
+ - [Languages](#languages)
34
+ - [License](#license)
35
+
36
+ ## Features
37
+
38
+ 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).
39
+
40
+ - **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.
41
+ - **Block tools** (block name in brackets, the same names 1.x used):
42
+ - 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`);
43
+ - 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);
44
+ - 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`);
45
+ - other: link preview card (`linkTool`), person card (`personality`), call-to-action button (`button`), raw HTML (`raw`).
46
+ - **Inline tools:** bold, italic, link with target and rel (`hyperlink`, with a built-in picker that links an entry of your content types, see [Internal links](#internal-links)), marker, underline, strikethrough, inline code, tooltip, and the AI assistant when it is enabled.
47
+ - **Block tunes:** alignment (`alignmentTune`), text variant call-out / citation / details (`textVariant`), indent (`indentTune`).
48
+ - **Editing:** undo and redo, drag and drop of blocks, full screen mode, block and word count.
49
+ - **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.
50
+ - **Version history:** save versions of a field, preview and restore them; automatic versions during live sessions.
51
+ - **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.
52
+ - **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.
53
+ - **Strapi-native admin:** built with the Strapi Design System, light and dark mode, keyboard accessible, admin in English, German, French, Spanish and Portuguese.
54
+ - **Safe content:** every value is normalised and sanitised on the server when it is saved, from the Content Manager, the Content API or code.
42
55
 
43
- ---
56
+ ## Screenshots
44
57
 
45
- ## Introduction
58
+ | | |
59
+ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
60
+ | ![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) |
61
+ | ![Two admins editing the same field](docs/site/img/collaboration-1440.png) | ![Version history dialog](docs/site/img/history-1440.png) |
62
+ | ![AI assistant dialog](docs/site/img/ai-1440.png) | ![Settings, configuration page](docs/site/img/settings-configuration-1440.png) |
63
+ | ![Settings, custom blocks list](docs/site/img/settings-custom-blocks-1440.png) | ![Custom block form](docs/site/img/custom-block-modal-1440.png) |
46
64
 
47
- 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.
65
+ ![Editor on a 390 px wide screen](docs/site/img/editor-mobile-390.png)
48
66
 
49
- 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.
67
+ All screenshots use synthetic data.
50
68
 
51
- ### Why Magic Editor X? :)
69
+ ## Core concepts
52
70
 
53
- **For Developers:**
54
- - Clean JSON output instead of unstructured HTML
55
- - 25+ pre-configured Editor.js tools out of the box
56
- - Type-safe content structure with versioned schemas
57
- - Real-time collaboration with CRDT (Conflict-free Replicated Data Types)
58
- - Full TypeScript support with proper type definitions
59
- - Extensible architecture for custom block types
71
+ | Term | Meaning |
72
+ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
73
+ | Field | One Magic Editor X attribute of a content type or component. Its value is an Editor.js document. |
74
+ | 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`. |
75
+ | Custom block | A block type defined in Settings > Magic Editor X > Custom blocks. Its name becomes the block `type`. |
76
+ | Version | A stored copy (snapshot) of one field of one document in one locale, listed in the version history. |
77
+ | 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. |
78
+ | Viewer | Someone in a room who can read the document but not update it. Viewers see changes live but cannot type. |
60
79
 
61
- **For Content Teams:**
62
- - Familiar Medium-style block editor experience
63
- - Live collaborative editing with presence indicators
64
- - Keyboard shortcuts for fast content creation
65
- - Inline formatting without toolbar clutter
66
- - Media Library integration for asset management
67
- - AI-powered content suggestions (premium)
80
+ ## Screens
68
81
 
69
- ---
82
+ | Screen | Where | Who can open it |
83
+ | --------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
84
+ | 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). |
85
+ | 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. |
86
+ | AI assistant | Inline toolbar (select text) | `access` and `ai.use`, when an administrator turned the assistant on. |
87
+ | Configuration | Settings > Magic Editor X > Configuration | `settings.read` (view), `settings.update` (edit). |
88
+ | Custom blocks | Settings > Magic Editor X > Custom blocks | `custom-blocks.manage`. |
70
89
 
71
- ## Screenshots
90
+ ## Compatibility
72
91
 
73
- ### Editor Interface
74
- ![Magic Editor X Interface](https://raw.githubusercontent.com/Schero94/magic-editor-x/main/pics/editorX.png)
92
+ | Plugin | Strapi | Node | Notes |
93
+ | ------ | ---------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
94
+ | 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. |
95
+ | 1.x | 5.x | 22 | No longer developed. |
75
96
 
76
- ### Real-Time Collaboration
77
- ![Live Collaboration](https://raw.githubusercontent.com/Schero94/magic-editor-x/main/pics/collab-magiceditorX.png)
97
+ 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).
78
98
 
79
- ### Collaboration Widget
80
- ![Collaboration Panel](https://raw.githubusercontent.com/Schero94/magic-editor-x/main/pics/liveCollabwidget1.png)
99
+ ## Install
81
100
 
82
- ---
101
+ ```bash
102
+ npm install magic-editor-x
103
+ ```
83
104
 
84
- ## Architecture Overview
105
+ Enable the plugin in `config/plugins.ts` (or `config/plugins.js`):
85
106
 
86
- Magic Editor X follows a clean client-server architecture with three main components:
107
+ ```ts
108
+ export default ({ env }) => ({
109
+ 'magic-editor-x': {
110
+ enabled: true,
111
+ config: {
112
+ // optional, see Configuration
113
+ },
114
+ },
115
+ });
116
+ ```
87
117
 
88
- ### Client-Side (Admin Panel)
118
+ Then rebuild the admin and restart:
89
119
 
120
+ ```bash
121
+ npm run build
122
+ npm run develop
90
123
  ```
91
- admin/
92
- ├── src/
93
- │ ├── components/
94
- │ │ ├── EditorJS/ # Main editor component
95
- │ │ ├── EditorTools/ # Custom tools (Button, Hyperlink, AI, WebtoolsLink)
96
- │ │ ├── MediaLib/ # Strapi Media Library adapter
97
- │ │ └── LiveCollaborationPanel.jsx # Collaboration UI
98
- │ ├── hooks/
99
- │ │ ├── useMagicCollaboration.js # Y.js & Socket.io integration
100
- │ │ ├── useWebtoolsLinks.js # 🆕 Webtools Links addon integration
101
- │ │ ├── useAIAssistant.js # AI features
102
- │ │ └── useLicense.js # License management
103
- │ ├── utils/
104
- │ │ └── YTextBinding.js # 🆕 Y.Text <-> contenteditable binding
105
- │ ├── config/
106
- │ │ └── tools.js # Editor.js tools configuration
107
- │ └── index.js # Plugin registration
108
- ```
109
-
110
- **Key Technologies:**
111
- - **React 18** - UI components with hooks
112
- - **Editor.js 2.31** - Block-based editor core
113
- - **Y.js 13.6** - CRDT for real-time sync
114
- - **Socket.io-client 4.8** - WebSocket communication
115
- - **IndexedDB** - Local persistence via y-indexeddb
116
124
 
117
- ### Server-Side (Strapi Backend)
125
+ 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).
118
126
 
119
- ```
120
- server/
121
- ├── src/
122
- │ ├── controllers/
123
- │ │ ├── editor-controller.js # Image upload, link previews
124
- │ │ ├── collaboration-controller.js # Permission management
125
- │ │ ├── realtime-controller.js # Session tokens
126
- │ │ └── license-controller.js # License validation
127
- │ ├── services/
128
- │ │ ├── realtime-service.js # Y.js document management
129
- │ │ ├── access-service.js # Permission checks
130
- │ │ ├── license-service.js # License API
131
- │ │ └── snapshot-service.js # Document snapshots
132
- │ ├── routes/
133
- │ │ ├── admin.js # Admin panel routes
134
- │ │ └── content-api.js # Public API routes
135
- │ └── config/
136
- │ └── index.js # Plugin configuration
137
- ```
127
+ 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).
138
128
 
139
- **Key Technologies:**
140
- - **Socket.io 4.8** - WebSocket server
141
- - **Y.js 13.6** - Server-side CRDT state
142
- - **Open Graph Scraper** - Link metadata extraction
143
- - **Strapi 5.57 or later in the 5.x line** - Backend framework
129
+ ## Configuration
144
130
 
145
- ### Data Flow
131
+ ### Reference
146
132
 
147
- 1. **Editor Changes** → Y.js Document (CRDT) → Socket.io → Server → Other Clients
148
- 2. **Image Upload** → Strapi Controller → Strapi Upload Service → Media Library
149
- 3. **Link Preview** → Backend Scraper → OpenGraph Metadata → Client
150
- 4. **Collaboration** → Permission Check → Session Token → WebSocket Connection
133
+ All keys are optional. Infrastructure options live in `config/plugins`; the AI provider is edited at runtime in Settings > Magic Editor X > Configuration.
151
134
 
152
- ---
135
+ | Key | Type | Default | Effect |
136
+ | --------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
137
+ | `debug` | boolean | `false` | Writes debug log lines (never content or personal data). |
138
+ | `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. |
139
+ | `sanitizeOnSave` | boolean | `true` | Normalise and sanitise Magic Editor X values on every Document Service write. Turning this off is not recommended. |
140
+ | `encryptionKey` | string (32+ characters) | unset | Key for the stored AI provider key. Prefer the `MAGIC_EDITOR_X_ENCRYPTION_KEY` environment variable. |
141
+ | `uploads.maxImageBytes` | integer | `10485760` (10 MiB) | Largest image accepted by file or URL (hard cap 500 MiB). |
142
+ | `uploads.maxFileBytes` | integer | `20971520` (20 MiB) | Largest attachment. |
143
+ | `linkPreview.enabled` | boolean | `true` | Link preview cards. When `false`, `GET /magic-editor-x/link` answers 404. |
144
+ | `linkPreview.timeoutMs` | integer | `8000` | Time limit for fetching a page (1000 to 30000). |
145
+ | `api.autoParseJSON` | boolean | `true` | Turn 1.x JSON strings into objects in Content API GET responses. |
146
+ | `ai.allowPrivateBaseUrl` | boolean | `false` | Allow AI base URLs on loopback or private networks (for local models). Owner decision; not editable in the admin. |
147
+ | `ai.apiKey` | string | unset | Provider key from the environment. When set it wins over a key stored in the settings. |
148
+ | `ai.requestsPerMinute` | integer | `20` | AI requests per admin per minute, counted per process. |
149
+ | `ai.timeoutMs` | integer | `60000` | Time limit for one provider request. |
150
+ | `collaboration.enabled` | boolean | `true` | Live collaboration and its Socket.IO server. |
151
+ | `collaboration.path` | string | `'/magic-editor-x/realtime'` | Socket.IO path on the Strapi HTTP server. |
152
+ | `collaboration.allowedOrigins` | string[] | `[]` | Extra browser origins allowed to open the socket. The admin URL and the server URL are always allowed. |
153
+ | `collaboration.pollIntervalMs` | integer | `400` | How often each process reads updates written by other processes (50 to 10000). |
154
+ | `collaboration.roomTtlMinutes` | integer | `30` | Keep a room's live state this long after the last person left. |
155
+ | `collaboration.maxMessageBytes` | integer | `2097152` (2 MiB) | Largest accepted socket message. |
156
+ | `collaboration.snapshotIntervalMinutes` | integer | `10` | Automatic version while people edit live. `0` turns it off. |
157
+ | `collaboration.tokenTtlSeconds` | integer | `60` | Lifetime of the one-time token that opens the socket. |
158
+ | `collaboration.maxConnectionsPerAdmin` | integer | `20` | Open live sockets per admin across all processes. |
159
+ | `collaboration.maxRoomsPerAdmin` | integer | `20` | Different fields one admin may have open live at the same time, across all processes. |
160
+ | `collaboration.revalidateSeconds` | integer | `60` | Full permission re-check of open sockets. Role, permission and user changes are applied within about a second anyway. |
161
+ | `collaboration.rateLimit` | object | `{ sessionsPerMinute: 60, updatesPer10s: 300, bytesPer10s: 8388608 }` | Session tokens per admin and minute (shared by all processes), updates and update bytes per socket in 10 seconds. |
162
+ | `history.maxSnapshotsPerField` | integer | `50` | Versions kept per field and locale; older ones are deleted. |
163
+ | `links.urlPattern` | string | `''` | `href` of internal links, for example `'/{locale}/{collection}/{slug}'` or `'https://www.example.com/{collection}/{documentId}'`. Placeholders: `{documentId}`, `{locale}`, `{slug}`, `{collection}`, `{singular}`. Empty means `'/{collection}/{documentId}'`. See [Internal links](#internal-links). |
153
164
 
154
- ## Features Deep Dive
165
+ 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).
155
166
 
156
- ### 1. Block-Based Content Structure
167
+ ### Environment variables
157
168
 
158
- Magic Editor X stores content as structured JSON, not HTML. Each block has a unique ID, type, and data object:
169
+ | Name | Required | Default | Effect |
170
+ | ------------------------------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
171
+ | `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. |
159
172
 
160
- ```json
161
- {
162
- "time": 1699999999999,
163
- "blocks": [
164
- {
165
- "id": "abc123",
166
- "type": "header",
167
- "data": {
168
- "text": "Hello World",
169
- "level": 2
170
- }
171
- },
172
- {
173
- "id": "def456",
174
- "type": "paragraph",
175
- "data": {
176
- "text": "This is <b>bold</b> and <i>italic</i> text."
177
- }
178
- },
179
- {
180
- "id": "ghi789",
181
- "type": "list",
182
- "data": {
183
- "style": "unordered",
184
- "items": [
185
- {
186
- "content": "First item",
187
- "items": []
188
- },
189
- {
190
- "content": "Second item with nested list",
191
- "items": [
192
- {
193
- "content": "Nested item",
194
- "items": []
195
- }
196
- ]
197
- }
198
- ]
199
- }
200
- }
201
- ],
202
- "version": "2.31.0"
203
- }
204
- ```
173
+ 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.
205
174
 
206
- **Benefits:**
207
- - Predictable, type-safe content structure
208
- - Easy to parse, transform, and render
209
- - Version control friendly (no HTML diffs)
210
- - Can be validated against JSON schemas
211
- - Simple to migrate between systems
175
+ ### AI settings (admin)
212
176
 
213
- ### 2. Real-Time Collaboration (CRDT Technology)
177
+ Settings > Magic Editor X > Configuration stores these values in the Strapi store:
214
178
 
215
- Magic Editor X uses Y.js, a battle-tested CRDT implementation, to enable true real-time collaboration without conflicts:
179
+ | Setting | Default | Range |
180
+ | -------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
181
+ | Enabled | off | |
182
+ | Provider | `anthropic` | `anthropic`, `openai`, `openai-compatible` |
183
+ | 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 |
184
+ | Model | `claude-opus-5-5` (Anthropic), `gpt-6-luna` (OpenAI) | letters, digits and `._:/@-` |
185
+ | API key | none | never returned; changing the provider or base URL requires entering it again |
186
+ | Max input characters | 8000 | 200 to 50000 |
187
+ | Max output tokens | 4096 | 64 to 16000 |
216
188
 
217
- **How It Works:**
189
+ ## Live collaboration
218
190
 
219
- 1. **Y.Doc Creation** - Each content entry gets a shared Y.js document
220
- 2. **Local Changes** - Edits create CRDT operations (not plain text diffs)
221
- 3. **Sync Protocol** - Operations are sent via Socket.io to the server
222
- 4. **Server Broadcast** - Server distributes operations to all connected clients
223
- 5. **Automatic Merge** - Y.js guarantees conflict-free merges (no "last write wins")
224
- 6. **Persistence** - Changes are stored in IndexedDB for offline capability
191
+ 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.
225
192
 
226
- **🆕 Character-Level Collaboration (v1.2.0)**
193
+ How it works:
227
194
 
228
- 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:
195
+ - **Conflict-free structure.** The field is shared as a Yjs document in which every block has a stable id and every part of its data has its own shared type: texts merge character by character, and every table cell, list item, checklist entry, tune (alignment, text variant, indent) and custom block field is merged separately. Two people can edit different cells of one table, different items of one list, or the text and the alignment of one paragraph at the same time and both changes are kept. When two people change the same number, switch or option at the same moment, one value wins on every screen. The stored Editor.js JSON does not change.
196
+ - **Presence.** Avatars with first name and last initial (never e-mail addresses), coloured carets and selections of the others in the text, a coloured marker at the block someone is editing and an "away" state after a minute without activity or when the tab is hidden. Joins and leaves are announced politely to screen readers. Colours follow the light and dark theme; the caret does not blink when reduced motion is requested.
197
+ - **Connection state** in the toolbar: Connecting, Syncing, Live, Reconnecting, Offline, View only, or Live editing unavailable.
198
+ - **Offline and reconnects.** You can keep typing while the connection is gone. Unsent changes are kept, sent again after the reconnect and merged with what others did meanwhile, without duplicates. Reconnects use exponential backoff with jitter and a new one-time token; waking a laptop or returning to a tab reconnects at once. Closing the tab leaves the room immediately.
199
+ - **Undo and redo** (toolbar, Cmd/Ctrl+Z, Shift+Cmd/Ctrl+Z) only revert your own changes, never what others typed (the last 200 steps).
200
+ - **Saving.** Changes made by others become part of your form. Save, publish and discard work as usual. Version history restores into the live room, so everyone sees the restored content. Each locale has its own room.
201
+ - **Permissions** are checked when you join, re-checked within about a second when roles, permissions or users change (on every process), and every `collaboration.revalidateSeconds`. An admin who loses update access becomes a viewer; one who loses read access is disconnected.
202
+ - **Nothing typed is lost.** Edits are stored in the database before they are confirmed. When a room is cleaned up `collaboration.roomTtlMinutes` after the last person left and contains edits nobody saved, a version is created first, so they can be restored from the history.
229
203
 
230
- ```
231
- ┌─────────────────────────────────────────────────────────┐
232
- │ Before v1.2.0: Block-Level Sync │
233
- │ User A edits Block 1 → User B's Block 1 changes lost │
234
- ├─────────────────────────────────────────────────────────┤
235
- │ After v1.2.0: Character-Level Sync │
236
- │ User A types "Hello" → User B types "World" → "HelloWorld" │
237
- │ Both changes merge seamlessly! │
238
- └─────────────────────────────────────────────────────────┘
239
- ```
204
+ Limits:
240
205
 
241
- **Hybrid Data Structure:**
242
- - `Y.Map` for block metadata (type, tunes, order)
243
- - `Y.Text` for character-level content (rich text with formatting)
244
- - `Y.Map` for document metadata (blockOrder, timestamps)
206
+ - A new entry that has not been saved yet has no room.
207
+ - Text formatting (bold, links, …) is part of the text; two people formatting the same word at the same moment can produce nested tags, which the sanitiser keeps valid.
208
+ - Up to 5000 blocks per field (the stored-content limit); rooms above 64 MiB of history refuse further edits until they are compacted.
245
209
 
246
- **Example: Collaborative Editing Flow**
210
+ ## Running several instances
247
211
 
248
- ```javascript
249
- // Client A types "Hello" at position 0
250
- const update = Y.encodeStateAsUpdate(yDoc);
251
- socket.emit('collab:update', update);
212
+ 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.
252
213
 
253
- // Server broadcasts to all clients
254
- socket.broadcast.to(roomId).emit('collab:update', update);
214
+ How it works:
255
215
 
256
- // Client B applies the update
257
- Y.applyUpdate(yDoc, update);
258
- // Editor automatically re-renders with "Hello"
259
- ```
216
+ - 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.
217
+ - 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`.
218
+ - 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.
219
+ - 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.
220
+ - Every process keeps the active rooms in memory, checks every update before it is stored (only the structures the editor uses, every dependency present, every touched block valid within the content limits) and relays it.
221
+ - Clients resynchronise their state every 20 seconds and after each reconnect, so a process restart or deploy loses nothing that was acknowledged.
222
+ - Permission changes set a signal in `magic_editor_x_locks` that every process checks every second. Session and AI rate limits are counted in `magic_editor_x_counters`, so they apply to the whole cluster.
260
223
 
261
- **Presence & Cursors:**
262
-
263
- ```javascript
264
- // Awareness protocol for presence
265
- awareness.setLocalStateField('cursor', {
266
- blockId: 'abc123',
267
- position: 42,
268
- user: {
269
- id: 'user-1',
270
- name: 'John Doe',
271
- color: '#FF6B6B'
272
- }
273
- });
224
+ The plugin creates these four tables on startup. They are not content types, so Strapi's schema sync leaves them alone.
274
225
 
275
- // Other clients receive cursor updates
276
- awareness.on('change', ({ added, updated, removed }) => {
277
- // Render remote cursor indicators
278
- renderCursors(awareness.getStates());
279
- });
280
- ```
226
+ 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.
281
227
 
282
- ### 3. 25+ Editor.js Tools
283
-
284
- Magic Editor X comes with a comprehensive collection of tools, categorized for easy reference:
285
-
286
- #### Block Tools (21 Tools)
287
-
288
- | Tool | Description | Package | Shortcut |
289
- |------|-------------|---------|----------|
290
- | **Header** | H1-H6 headings with alignment | `@editorjs/header` | `CMD+SHIFT+H` |
291
- | **Paragraph** | Text blocks with inline formatting | `@editorjs/paragraph` | - |
292
- | **Nested List** | Multi-level ordered/unordered lists | `@editorjs/nested-list` | `CMD+SHIFT+L` |
293
- | **Checklist** | Interactive todo lists | `@editorjs/checklist` | `CMD+SHIFT+C` |
294
- | **Quote** | Blockquotes with caption | `@editorjs/quote` | `CMD+SHIFT+Q` |
295
- | **Warning** | Alert boxes | `@editorjs/warning` | `CMD+SHIFT+W` |
296
- | **Code** | Basic code blocks | `@editorjs/code` | `CMD+SHIFT+P` |
297
- | **Code (Highlight)** | Syntax-highlighted code | `@calumk/editorjs-codeflask` | - |
298
- | **Delimiter** | Visual section separator | `@editorjs/delimiter` | `CMD+SHIFT+D` |
299
- | **Table** | Create/edit tables | `@editorjs/table` | `CMD+SHIFT+T` |
300
- | **Embed** | YouTube, Vimeo, Twitter, etc. | `@editorjs/embed` | - |
301
- | **Raw HTML** | Insert raw HTML | `@editorjs/raw` | - |
302
- | **Image** | Upload by file or URL | `@editorjs/image` | - |
303
- | **Simple Image** | Image by URL only | `@editorjs/simple-image` | - |
304
- | **Link Preview** | Rich link cards with metadata | `@editorjs/link` | - |
305
- | **Attaches** | File attachments | `@editorjs/attaches` | - |
306
- | **Media Library** | Strapi Media Library picker | Custom | - |
307
- | **Personality** | Author/person cards | `@editorjs/personality` | - |
308
- | **Alert** | Colored alert messages | `editorjs-alert` | `CMD+SHIFT+A` |
309
- | **Toggle** | Collapsible content blocks | `editorjs-toggle-block` | - |
310
- | **Button** | CTA buttons | Custom | - |
311
-
312
- #### Inline Tools (7 Tools)
313
-
314
- | Tool | Description | Package | Shortcut |
315
- |------|-------------|---------|----------|
316
- | **Bold** | Bold text | Built-in | `CMD+B` |
317
- | **Italic** | Italic text | Built-in | `CMD+I` |
318
- | **Marker** | Highlight text | `@editorjs/marker` | `CMD+SHIFT+M` |
319
- | **Inline Code** | Code formatting | `@editorjs/inline-code` | `CMD+SHIFT+I` |
320
- | **Underline** | Underline text | `@editorjs/underline` | `CMD+U` |
321
- | **Strikethrough** | Strike through text | `@sotaproject/strikethrough` | `CMD+SHIFT+S` |
322
- | **Hyperlink** | Links with target/rel | Custom | `CMD+K` |
323
- | **Tooltip** | Add tooltips to text | `editorjs-tooltip` | - |
324
-
325
- #### Block Tunes (3 Tunes)
326
-
327
- | Tune | Description | Package |
328
- |------|-------------|---------|
329
- | **Alignment** | Left, center, right, justify | `editorjs-text-alignment-blocktune` |
330
- | **Indent** | Multi-level indentation | `editorjs-indent-tune` |
331
- | **Text Variant** | Call-out, citation, details styles | `@editorjs/text-variant-tune` |
332
-
333
- #### Plugins (2 Plugins)
334
-
335
- | Plugin | Description | Package |
336
- |--------|-------------|---------|
337
- | **Undo/Redo** | History management | `editorjs-undo` |
338
- | **Drag & Drop** | Reorder blocks by dragging | `editorjs-drag-drop` |
339
-
340
- ### Custom Blocks (User-Defined)
341
-
342
- 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.
343
-
344
- #### Creating Custom Blocks via Admin UI
345
-
346
- 1. Go to **Settings > Magic Editor X > Custom Blocks**
347
- 2. Click **Create Block**
348
- 3. Fill in the form:
349
- - **Block Name** - Unique identifier (e.g., `productCard`)
350
- - **Display Label** - Shown in the editor toolbox
351
- - **Block Type**:
352
- - **Simple Block** - Text/HTML content with custom fields
353
- - **Embedded Entry** - Links to existing Strapi content
354
- 4. Configure additional options (fields, template, icon)
355
- 5. Click **Create Block**
356
-
357
- The new block appears immediately in the editor toolbox!
358
-
359
- #### Block Types
360
-
361
- **Simple Blocks:**
362
- Custom text/HTML blocks with configurable fields.
363
-
364
- | Option | Description |
365
- |--------|-------------|
366
- | Placeholder | Hint text for empty content |
367
- | Template | Custom HTML with `{{fieldName}}` placeholders |
368
- | Fields | Add custom fields (text, select, color, checkbox) |
369
- | Styles | Custom CSS as JSON object |
370
-
371
- **Embedded Entry Blocks:**
372
- Embed existing Strapi content directly in your editor.
373
-
374
- | Option | Description |
375
- |--------|-------------|
376
- | Content Type | Target content type (e.g., `api::product.product`) |
377
- | Title Field | Field to display as entry title |
378
- | Display Fields | Fields shown in preview |
379
-
380
- #### Creating Custom Blocks via Config (Developers)
381
-
382
- For developers who prefer code-based configuration:
383
-
384
- ```javascript
385
- // config/plugins.js
386
- 'magic-editor-x': {
387
- enabled: true,
388
- config: {
389
- customBlocks: [
390
- {
391
- name: 'productCard',
392
- label: 'Product Card',
393
- blockType: 'embedded-entry',
394
- contentType: 'api::product.product',
395
- displayFields: ['title', 'price', 'thumbnail'],
396
- titleField: 'title',
397
- icon: '<svg>...</svg>',
398
- },
399
- {
400
- name: 'callToAction',
401
- label: 'Call to Action',
402
- blockType: 'simple',
403
- placeholder: 'Enter CTA text...',
404
- fields: [
405
- { name: 'buttonText', label: 'Button Text', type: 'text' },
406
- { name: 'buttonUrl', label: 'Button URL', type: 'text' },
407
- { name: 'variant', label: 'Style', type: 'select', options: ['primary', 'secondary'] },
408
- ],
409
- template: `
410
- <div class="cta-block">
411
- <p data-field="content">{{content}}</p>
412
- <a href="{{buttonUrl}}" class="btn btn-{{variant}}">{{buttonText}}</a>
413
- </div>
414
- `,
415
- },
416
- ],
417
- },
418
- },
419
- ```
228
+ The acceptance run with several processes is described in [CONTRIBUTING.md](./CONTRIBUTING.md).
420
229
 
421
- #### Import/Export Custom Blocks
230
+ ## AI assistant
422
231
 
423
- Custom blocks can be exported and imported between environments:
232
+ The assistant is off until an administrator turns it on in Settings > Magic Editor X > Configuration and gives it a provider:
233
+
234
+ | Provider | Request | Default model (2026-11-11) |
235
+ | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------- |
236
+ | Anthropic | `POST {base}/v1/messages`, headers `x-api-key` and `anthropic-version: 2026-10-21` | `claude-opus-5-5` |
237
+ | OpenAI | `POST {base}/v1/chat/completions`, `Authorization: Bearer`, `max_completion_tokens` | `gpt-6-luna` |
238
+ | OpenAI-compatible (Ollama, vLLM, LM Studio and similar) | `POST {base}/v1/chat/completions`, optional bearer key, `max_tokens` | none; you name the model |
424
239
 
425
- 1. Go to **Settings > Magic Editor X > Custom Blocks**
426
- 2. Click **Export** to download a JSON file
427
- 3. On another instance, click **Import** and select the file
240
+ - 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.
241
+ - 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.
242
+ - 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.
243
+ - Input is limited by "Max input characters", output by "Max output tokens". Each admin can send `ai.requestsPerMinute` requests per minute; the counter is shared by all processes.
244
+ - 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.
428
245
 
429
- #### Custom Block Output Format
246
+ ## Data format
430
247
 
431
- Custom blocks save their data in the standard Editor.js format:
248
+ The field stores an Editor.js document as JSON:
432
249
 
433
250
  ```json
434
251
  {
435
- "type": "productCard",
436
- "data": {
437
- "entry": {
438
- "id": 42,
439
- "documentId": "abc123",
440
- "title": "Product Name",
441
- "price": 99.99
442
- },
443
- "contentType": "api::product.product"
444
- }
252
+ "time": 1762866000000,
253
+ "version": "2.31.7",
254
+ "blocks": [
255
+ { "id": "kq1x9w0abc", "type": "header", "data": { "text": "Release notes", "level": 2 } },
256
+ {
257
+ "id": "kq1x9w0abd",
258
+ "type": "paragraph",
259
+ "data": { "text": "Read the <a href=\"https://example.test\">guide</a>." },
260
+ "tunes": { "alignmentTune": { "alignment": "left" } }
261
+ }
262
+ ]
445
263
  }
446
264
  ```
447
265
 
448
- ### 4. Media Library Integration
449
-
450
- Seamless integration with Strapi's built-in Media Library:
451
-
452
- ```javascript
453
- // Custom MediaLibAdapter bridges Editor.js and Strapi
454
- class MediaLibAdapter {
455
- static get toolbox() {
456
- return {
457
- title: 'Media Library',
458
- icon: '<svg>...</svg>'
459
- };
460
- }
461
-
462
- render() {
463
- const button = document.createElement('button');
464
- button.textContent = 'Choose from Media Library';
465
- button.onclick = () => {
466
- // Opens Strapi's Media Library modal
467
- this.config.mediaLibToggleFunc();
468
- };
469
- return button;
470
- }
471
-
472
- save(blockContent) {
473
- return {
474
- url: blockContent.url,
475
- caption: blockContent.caption,
476
- alt: blockContent.alt
477
- };
478
- }
479
- }
266
+ Data of each block type as stored after sanitising (`shared/sanitize-policy.mjs`):
267
+
268
+ | Block | `data` |
269
+ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
270
+ | `paragraph` | `{ text }` (inline HTML) |
271
+ | `header` | `{ text, level: 1-6 }` |
272
+ | `list` | `{ style: 'ordered' \| 'unordered' \| 'checklist', meta?: { start?, counterType? }, items: [{ content, meta?, items: [...] }] }` |
273
+ | `checklist` | `{ items: [{ text, checked }] }` |
274
+ | `quote` | `{ text, caption, alignment: 'left' \| 'center' }` |
275
+ | `warning` | `{ title, message }` |
276
+ | `alert` | `{ type: 'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'light' \| 'dark', align: 'left' \| 'center' \| 'right', message }` |
277
+ | `toggle` | `{ text, status: 'open' \| 'closed', fk?, items }` (the next `items` blocks are its content) |
278
+ | `code` | `{ code }` (plain text) |
279
+ | `codeFlask` | `{ code, language, showlinenumbers? }` |
280
+ | `raw` | `{ html }` (see `rawHtml`) |
281
+ | `table` | `{ withHeadings, stretched, content: string[][] }` |
282
+ | `image` | `{ file: { url, mime?, alt?, width?, height?, size?, formats?, id?, documentId? }, caption, withBorder, withBackground, stretched }` |
283
+ | `simpleImage` | `{ url, caption, withBorder, withBackground, stretched }` |
284
+ | `linkTool` | `{ link, meta: { title, description, site_name?, image?: { url } } }` |
285
+ | `attaches` | `{ file: { url, name?, extension?, size?, title? }, title }` |
286
+ | `embed` | `{ service, source, embed, width?, height?, caption }` (`embed` is always https) |
287
+ | `personality` | `{ name, description, link, photo }` |
288
+ | `button` | `{ text, link, style, openInNewTab }` |
289
+ | `delimiter` | `{}` |
290
+ | custom simple block | `{ content, <field values>, blockType: 'simple', blockName }` |
291
+ | custom embedded-entry block | `{ entry: { id, documentId, title, <display fields> }, contentType, displayMode }` |
292
+
293
+ Inline HTML may contain `b`, `strong`, `i`, `em`, `u`, `s`, `mark`, `code`, `a` (`href`, `target`, `rel`, `title`, and for internal links `data-mex-uid`, `data-mex-document-id`, `data-mex-locale`), `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.
294
+
295
+ ### Internal links
296
+
297
+ The link tool (`CMD+K`) has a **Link to an entry** button: choose a content type, search by title (arrow keys move through the results, Enter picks, Escape closes) and the selected text becomes a link to that entry. The picker lists only the content types and entries you can read in the Content Manager, with its conditions and field permissions. The link is stored as plain HTML:
298
+
299
+ ```html
300
+ <a
301
+ href="/articles/x7k2m9q4p1v8"
302
+ data-mex-uid="api::article.article"
303
+ data-mex-document-id="x7k2m9q4p1v8"
304
+ data-mex-locale="en"
305
+ >our guide</a
306
+ >
480
307
  ```
481
308
 
482
- ### 5. Webtools Links Integration (Optional)
483
-
484
- Magic Editor X integrates seamlessly with the [Webtools Links addon](https://www.pluginpal.io/plugin/webtools) by PluginPal for enhanced link management:
485
-
486
- **Features:**
487
- - 🔗 **Internal Link Picker** - Select pages/entries from your Strapi content
488
- - 🌐 **External URL Support** - Paste external URLs with validation
489
- - ✏️ **Edit Existing Links** - Click on a link to edit its URL and text
490
- - 🔍 **Link Detection** - Automatically detects when cursor is inside a link
491
-
492
- **Setup:**
493
-
494
- 1. Install the Webtools Links addon (requires Webtools license)
495
- 2. Magic Editor X auto-detects the addon and enables the Link Picker button
496
-
497
- **Usage:**
498
-
499
- ```javascript
500
- // The integration uses Strapi's plugin API
501
- const getPlugin = useStrapiApp('WebtoolsLinks', (state) => state.getPlugin);
502
- const linksPlugin = getPlugin('webtools-addon-links');
503
- const { openLinkPicker } = linksPlugin?.apis;
504
-
505
- // Open picker with existing link data (for editing)
506
- const result = await openLinkPicker({
507
- linkType: 'both', // 'internal', 'external', or 'both'
508
- initialHref: existingUrl, // Pre-fill for editing
509
- initialText: selectedText // Pre-fill link text
510
- });
309
+ - `href` is always a normal URL, so every frontend can render the link as it is. It is built on the server from `links.urlPattern` when the link is inserted: `{documentId}`, `{locale}` (empty for types without i18n; empty path segments are removed), `{slug}` (the first `uid` attribute of the type, or the documentId when there is none), `{collection}` (plural API name) and `{singular}` (singular API name). Values are URL-encoded. The pattern must be a site-relative path or an `http(s)` URL with a fixed host. Without a pattern the link is `/{collection}/{documentId}`.
310
+ - `data-mex-uid`, `data-mex-document-id` and `data-mex-locale` identify the entry, so a frontend can resolve the current URL itself (for example when a slug changed after the link was inserted). They are kept only when they are valid and only on `<a>`; a link whose address you edit by hand becomes a normal link.
311
+
312
+ Tunes are stored per block in `tunes`: `alignmentTune: { alignment }`, `textVariant: '' | 'call-out' | 'citation' | 'details'`, `indentTune: { indentLevel }`.
313
+
314
+ 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.
315
+
316
+ ## Admin API and permissions
317
+
318
+ ### Permissions
319
+
320
+ | Action | Label in Roles | Gates |
321
+ | --------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
322
+ | `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, internal-link search, custom block list, version history, collaboration and AI routes |
323
+ | `plugin::magic-editor-x.collaborate` | Edit together in real time | Joining live rooms |
324
+ | `plugin::magic-editor-x.ai.use` | Use the AI assistant | AI requests |
325
+ | `plugin::magic-editor-x.custom-blocks.manage` | Manage custom blocks | Settings > Custom blocks and its routes |
326
+ | `plugin::magic-editor-x.settings.read` | Read settings | Settings > Configuration (read) |
327
+ | `plugin::magic-editor-x.settings.update` | Update settings | Saving settings, testing the AI connection |
328
+
329
+ 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.
330
+
331
+ Super Admins have all actions. The `access` action keeps its 1.x id, so roles that had it keep using the editor.
332
+
333
+ ### Routes
334
+
335
+ 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.
336
+
337
+ | Method | Path | Actions | Body / query | Response |
338
+ | ------ | --------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
339
+ | GET | `/magic-editor-x/config` | access | | `{ data: { collaboration, ai, uploads, linkPreview, rawHtml, permissions } }` |
340
+ | GET | `/magic-editor-x/link` | access | `?url=` | `{ success: 1, link, meta }` |
341
+ | POST | `/magic-editor-x/image/byFile` | access, upload | multipart `image` | `{ success: 1, file: { url, ... } }` |
342
+ | POST | `/magic-editor-x/image/byUrl` | access, upload | `{ url }` | `{ success: 1, file }` |
343
+ | POST | `/magic-editor-x/file/upload` | access, upload | multipart `file` | `{ success: 1, file: { url, name, title, size, extension } }` |
344
+ | GET | `/magic-editor-x/content-types` | access | | `{ data: [{ uid, kind, displayName, attributes }] }` (types you can read) |
345
+ | GET | `/magic-editor-x/links/types` | access | | `{ data: [{ uid, kind, displayName, localized }] }` (API types you can read) |
346
+ | GET | `/magic-editor-x/links/search` | access (+ Content Manager read) | `?uid=api::x.y&q=&locale=&page=` (`q` up to 100 characters) | `{ data: [{ documentId, uid, locale, title, href, status? }], meta: { pagination } }` (up to 20 readable entries; unknown or unreadable type 404) |
347
+ | GET | `/magic-editor-x/custom-blocks` | access (`?all=true` also needs custom-blocks.manage) | `?all=true` | `{ data: [block] }` |
348
+ | GET | `/magic-editor-x/custom-blocks/export` | custom-blocks.manage | | `{ data: { format: 'magic-editor-x/custom-blocks', version: 2, exportedAt, blocks } }` |
349
+ | POST | `/magic-editor-x/custom-blocks/import` | custom-blocks.manage | export document | `{ data: { created: [name], skipped: [{ name, reason }] } }` |
350
+ | PUT | `/magic-editor-x/custom-blocks/order` | custom-blocks.manage | `{ ids }` (every block once) | `{ data: [block] }` |
351
+ | POST | `/magic-editor-x/custom-blocks` | custom-blocks.manage | block definition | 201 `{ data: block }` |
352
+ | PUT | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage | full block definition | `{ data: block }` |
353
+ | DELETE | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage | | `{ data: { id } }` |
354
+ | POST | `/magic-editor-x/custom-blocks/:id/duplicate` | custom-blocks.manage | | 201 `{ data: block }` |
355
+ | POST | `/magic-editor-x/collaboration/session` | access, collaborate | `{ uid, documentId, locale?, field, initialValue? }` | `{ data: { token, path, canEdit, expiresAt } }` |
356
+ | GET | `/magic-editor-x/history` | access | `?uid&documentId&locale&field` | `{ data: [version], meta: { canRestore, canCreate } }` |
357
+ | GET | `/magic-editor-x/history/:id` | access | | `{ data: { ...version, content } }` |
358
+ | POST | `/magic-editor-x/history` | access | `{ uid, documentId, locale?, field, content }` | 201 new version, 200 with `meta.created: false` when unchanged |
359
+ | POST | `/magic-editor-x/ai/:action` | access, ai.use | `{ text, language?, tone? }` | `{ data: { text } }` |
360
+ | GET | `/magic-editor-x/settings` | settings.read | | `{ data: { ai, environment } }` (no secrets) |
361
+ | PUT | `/magic-editor-x/settings` | settings.read, settings.update | `{ ai: { enabled, provider, baseUrl, model, maxInputChars, maxOutputTokens, apiKey? } }` | `{ data: { ai, environment } }` |
362
+ | POST | `/magic-editor-x/settings/ai/test` | settings.read, settings.update | `{ ai: {...} }` | `{ data: { ok: true } }` |
363
+
364
+ `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.
365
+
366
+ Example: save a version.
367
+
368
+ ```http
369
+ POST /magic-editor-x/history
370
+ Authorization: Bearer <admin JWT>
371
+ Content-Type: application/json
372
+
373
+ { "uid": "api::article.article", "documentId": "k9d2w4xq8m1n0p3r5t7v9b1c", "locale": "en", "field": "body",
374
+ "content": { "blocks": [{ "id": "a1", "type": "paragraph", "data": { "text": "Hello" } }] } }
511
375
  ```
512
376
 
513
- **Without Webtools:**
514
-
515
- If Webtools is not installed, a subtle promo link appears in the editor footer pointing to the addon store page.
516
-
517
- ---
518
-
519
- ### 6. AI-Powered Features (Premium)
520
-
521
- Built-in AI assistant for content enhancement:
522
-
523
- **Grammar Check:**
524
- ```javascript
525
- // Automatically fix grammar and spelling
526
- aiAssistant.check(text) → corrected text
377
+ ```json
378
+ {
379
+ "data": {
380
+ "id": "s8f2k1x0w9q7e5r3t1y6u4i2",
381
+ "version": 3,
382
+ "trigger": "manual",
383
+ "createdAt": "2026-11-11T09:30:00.000Z",
384
+ "createdBy": "Anna Beispiel",
385
+ "stats": { "blocks": 1, "words": 1, "characters": 5 },
386
+ "restorable": true
387
+ },
388
+ "meta": { "created": true }
389
+ }
527
390
  ```
528
391
 
529
- **Style Improvement:**
530
- ```javascript
531
- // Make text more professional, casual, or friendly
532
- aiAssistant.rewrite(text, style: 'professional') → improved text
533
- ```
392
+ ## Security and privacy
534
393
 
535
- **Content Generation:**
536
- ```javascript
537
- // Generate content based on prompts
538
- aiAssistant.generate(prompt) → generated content
539
- ```
394
+ - **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).
395
+ - **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.
396
+ - **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.
397
+ - **Collaboration:** tokens are signed, bound to admin, document, locale and field, expire after `collaboration.tokenTtlSeconds` and work once on any process; the socket accepts the admin and server origins and `collaboration.allowedOrigins` and only clients of the current protocol; every update is checked (allowed structures only, no prototype keys, dependencies present, touched blocks valid) before it is stored or relayed, and a socket that keeps sending invalid updates is closed; names and colours of other people come from the server, never from a client; remote content is sanitised before the editor renders it; updates, sessions, sockets and rooms per admin are rate limited; viewers cannot write. See [docs/security-audit-2.1.md](./docs/security-audit-2.1.md).
398
+ - **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.
399
+ - **Logs** contain operation names and error codes only, never content, URLs with queries, tokens, user ids or email addresses.
400
+ - **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).
401
+ - **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. Embeds and external images in the editor preview need `frame-src` and `img-src` sources; see [Content Security Policy](#content-security-policy) below.
540
402
 
541
- ---
403
+ Report vulnerabilities privately through GitHub security advisories on the repository.
542
404
 
543
- ## Installation & Setup
405
+ ### Content Security Policy
544
406
 
545
- ### 1. Install Package
407
+ Strapi's default admin CSP (`strapi::security`) has no `frame-src`, so embed iframes fall back to `default-src 'self'`, and its `img-src` allows only `'self'`, `data:`, `blob:` and `market-assets.strapi.io`. YouTube, Vimeo and the other embeds, and images from other hosts (for example link preview images), are therefore blocked in the editor preview. The stored content is not affected and your frontend has its own CSP.
546
408
 
547
- ```bash
548
- npm install magic-editor-x
549
- # or
550
- yarn add magic-editor-x
551
- # or
552
- pnpm add magic-editor-x
553
- ```
409
+ The plugin never changes the CSP. Instead:
554
410
 
555
- ### 2. Enable Plugin
411
+ - **Settings > Magic Editor X > Configuration** shows a "Content Security Policy" notice when sources are missing: what is blocked and the exact `config/middlewares.js` snippet, with a copy button. The server reads the effective `strapi::security` configuration once at startup (string and object entries, `useDefaults`, `frame-src`, `child-src`, `default-src`, `img-src`) and returns it in `GET /magic-editor-x/settings` as `data.environment.csp` (`{ active, frameSrcMissing, imgSrcMissing, snippet }`). Only CSP sources are returned; browsers receive them in every response header anyway.
412
+ - **In the editor**, a blocked embed or image is replaced by a placeholder inside the block ("This embed is blocked by your Content Security Policy.") with a link to the settings page for admins who can read the settings. The block data is saved unchanged.
556
413
 
557
- Create or update `config/plugins.ts` (or `.js`):
414
+ The snippet for Strapi's defaults (merge it into your existing `strapi::security` entry and keep your other directives, for example the hosts of your upload provider; Strapi merges arrays with its defaults by position):
558
415
 
559
- ```typescript
560
- export default () => ({
561
- 'magic-editor-x': {
562
- enabled: true,
563
- config: {
564
- // Editor Configuration
565
- enabledTools: [
566
- 'header', 'paragraph', 'list', 'checklist', 'quote',
567
- 'warning', 'code', 'delimiter', 'table', 'embed',
568
- 'raw', 'image', 'mediaLib', 'linkTool'
569
- ],
570
-
571
- // Upload Limits
572
- maxImageSize: 10 * 1024 * 1024, // 10MB
573
- allowedImageTypes: [
574
- 'image/jpeg', 'image/png', 'image/gif',
575
- 'image/webp', 'image/svg+xml'
576
- ],
577
-
578
- // Link Previews
579
- linkPreviewTimeout: 10000, // 10 seconds
580
-
581
- // Real-Time Collaboration
582
- collaboration: {
583
- enabled: true,
584
- sessionTTL: 2 * 60 * 1000, // 2 minutes
585
- wsPath: '/magic-editor-x/realtime',
586
- wsUrl: null, // Auto-detect or set custom URL
587
- allowedOrigins: ['http://localhost:1337'],
588
- allowedAdminRoles: ['strapi-super-admin'],
589
- allowedAdminUserIds: [],
590
- },
591
-
592
- // API Response Settings
593
- api: {
594
- autoParseJSON: true, // Auto-parse JSON strings to objects in API responses
595
- },
596
- },
597
- },
598
- });
599
- ```
600
-
601
- ### 3. Content Security Policy (Optional)
602
-
603
- For link previews with external images, update `config/middlewares.ts`:
604
-
605
- ```typescript
606
- export default [
607
- 'strapi::logger',
608
- 'strapi::errors',
416
+ ```js
417
+ // config/middlewares.js
418
+ module.exports = [
419
+ // ...other middlewares
609
420
  {
610
421
  name: 'strapi::security',
611
422
  config: {
612
423
  contentSecurityPolicy: {
613
424
  useDefaults: true,
614
425
  directives: {
615
- 'connect-src': ["'self'", 'https:'],
616
- 'img-src': [
426
+ 'frame-src': [
617
427
  "'self'",
618
- 'data:',
619
- 'blob:',
620
- 'market-assets.strapi.io',
621
- '*', // Allow external images for link previews
428
+ 'https://www.youtube.com',
429
+ 'https://player.vimeo.com',
430
+ 'https://platform.twitter.com',
431
+ 'https://www.instagram.com',
432
+ 'https://codepen.io',
433
+ 'https://imgur.com',
434
+ 'https://assets.pinterest.com',
435
+ 'https://miro.com',
436
+ 'https://www.figma.com',
437
+ 'https://www.facebook.com',
622
438
  ],
623
- 'media-src': [
624
- "'self'",
625
- 'data:',
626
- 'blob:',
627
- 'market-assets.strapi.io',
628
- ],
629
- upgradeInsecureRequests: null,
439
+ 'img-src': ["'self'", 'data:', 'blob:', 'https://market-assets.strapi.io', 'https:'],
630
440
  },
631
441
  },
632
442
  },
633
443
  },
634
- 'strapi::cors',
635
- 'strapi::poweredBy',
636
- 'strapi::query',
637
- 'strapi::body',
638
- 'strapi::session',
639
- 'strapi::favicon',
640
- 'strapi::public',
444
+ // ...other middlewares
641
445
  ];
642
446
  ```
643
447
 
644
- ### 4. Build & Start
645
-
646
- ```bash
647
- # Build admin panel with plugin
648
- npm run build
649
-
650
- # Start in development mode
651
- npm run develop
652
-
653
- # Or in production
654
- npm run start
655
- ```
656
-
657
- ### 5. Add Field to Content Type
658
-
659
- 1. Navigate to **Content-Type Builder**
660
- 2. Select a content type or create a new one
661
- 3. Click **Add another field**
662
- 4. Go to the **Custom** tab
663
- 5. Select **Magic Editor X**
664
- 6. Configure field name and options
665
- 7. Click **Finish** and save the content type
666
-
667
- ---
668
-
669
- ## Configuration Reference
670
-
671
- ### Plugin Configuration
672
-
673
- All options for `config/plugins.ts`:
674
-
675
- ```typescript
676
- interface MagicEditorXConfig {
677
- // Tool Selection
678
- enabledTools?: string[]; // Default: all tools
679
-
680
- // Upload Settings
681
- maxImageSize?: number; // Bytes, default: 10MB
682
- allowedImageTypes?: string[]; // MIME types
683
-
684
- // Link Preview Settings
685
- linkPreviewTimeout?: number; // Milliseconds, default: 10000
686
-
687
- // API Response Settings
688
- api?: {
689
- autoParseJSON: boolean; // Auto-parse JSON strings to objects, default: true
690
- };
691
-
692
- // Collaboration Settings
693
- collaboration?: {
694
- enabled: boolean; // Default: true
695
- sessionTTL: number; // Milliseconds, default: 120000 (2 min)
696
- wsPath: string; // WebSocket path, default: '/magic-editor-x/realtime'
697
- wsUrl: string | null; // Custom WebSocket URL (for proxies)
698
- allowedOrigins: string[]; // CORS origins
699
- allowedAdminRoles: string[]; // Roles that can collaborate
700
- allowedAdminUserIds: number[]; // Specific user IDs
701
- };
702
- }
703
- ```
704
-
705
- ### Field Options
706
-
707
- When adding the field in Content-Type Builder:
708
-
709
- **Base Settings:**
710
- - **Placeholder** - Placeholder text (default: "Start writing or press Tab...")
711
- - **Required** - Make field mandatory
712
- - **Private** - Exclude from API responses
713
-
714
- **Advanced Settings:**
715
- - **Minimum Height** - Editor height in pixels (default: 300)
716
- - **Max Length** - Maximum characters (optional)
717
- - **Min Length** - Minimum characters (optional)
718
-
719
- ---
720
-
721
- ## API Response Format
722
-
723
- ### Automatic JSON Parsing
724
-
725
- Magic Editor X automatically transforms JSON string fields into structured objects in API responses for better developer experience.
726
-
727
- **Without auto-parsing (raw Strapi response):**
728
- ```json
729
- {
730
- "data": {
731
- "id": 1,
732
- "documentId": "abc123",
733
- "editorX": "{\"time\":1699999999999,\"blocks\":[{\"id\":\"xyz\",\"type\":\"paragraph\",\"data\":{\"text\":\"Hello\"}}],\"version\":\"2.31.0\"}"
734
- }
735
- }
736
- ```
737
-
738
- **With auto-parsing (Magic Editor X middleware active):**
739
- ```json
740
- {
741
- "data": {
742
- "id": 1,
743
- "documentId": "abc123",
744
- "editorX": {
745
- "time": 1699999999999,
746
- "blocks": [
747
- {
748
- "id": "xyz",
749
- "type": "paragraph",
750
- "data": {
751
- "text": "Hello"
752
- }
753
- }
754
- ],
755
- "version": "2.31.0"
756
- }
757
- }
758
- }
759
- ```
760
-
761
- **Configuration:**
762
-
763
- Auto-parsing is enabled by default. To disable it, add to `config/plugins.ts`:
764
-
765
- ```typescript
766
- {
767
- 'magic-editor-x': {
768
- config: {
769
- api: {
770
- autoParseJSON: false // Disable automatic JSON parsing
771
- }
772
- }
773
- }
774
- }
775
- ```
776
-
777
- **Manual Parsing (if auto-parse is disabled):**
778
-
779
- ```javascript
780
- // Client-side parsing
781
- const response = await fetch('/api/articles/1');
782
- const data = await response.json();
783
-
784
- // Parse Editor.js field manually
785
- const editorContent = JSON.parse(data.data.editorX);
786
- console.log(editorContent.blocks); // Array of blocks
787
- ```
788
-
789
- ---
790
-
791
- ## API Reference
792
-
793
- The plugin currently registers admin routes only. It does not register public Content API routes. Admin routes use Strapi's admin API base and require authentication and the route-specific permissions defined in `server/src/routes/admin.js`.
794
-
795
- Editor routes include `GET /magic-editor-x/link`, `POST /magic-editor-x/image/byFile`, `POST /magic-editor-x/image/byUrl`, and `POST /magic-editor-x/file/upload`. Link preview and URL upload accept remote URLs; the implementation restricts these requests to public HTTP(S) destinations and applies response size, MIME-type, redirect, and timeout limits. Upload routes require the admin plugin access and Strapi upload-create permissions.
796
-
797
- Other admin route groups manage collaboration sessions and permissions, license status and limits, snapshots, and custom blocks. Collaboration session creation checks the configured collaboration access rules. See `server/src/routes/admin.js` for the current route and policy definitions.
798
-
799
- ---
800
-
801
- ## Collaboration System
802
-
803
- ### Permission Model
804
-
805
- Magic Editor X uses a flexible role-based permission system:
806
-
807
- **Roles:**
808
- - **Owner** - Full control (edit, delete, manage permissions)
809
- - **Editor** - Can edit content
810
- - **Viewer** - Read-only access
811
-
812
- **Permission Scope:**
813
- - Per content type (e.g., `api::article.article`)
814
- - Per user or role
815
- - Inherits from Strapi's built-in RBAC
816
-
817
- ### Managing Collaborators
818
-
819
- Navigate to **Plugins > Magic Editor X > Collaboration** to:
820
-
821
- 1. **Add Collaborator**
822
- - Select user
823
- - Choose content type
824
- - Assign role (Viewer, Editor, Owner)
825
-
826
- 2. **Update Permission**
827
- - Change role
828
- - Modify content type access
829
-
830
- 3. **Remove Collaborator**
831
- - Revoke access
832
-
833
- ### Collaboration Limits
834
-
835
- Limits are enforced based on your license:
836
-
837
- | License | Concurrent Collaborators |
838
- |---------|-------------------------|
839
- | FREE | 2 |
840
- | PREMIUM | 10 |
841
- | ADVANCED | Unlimited |
842
-
843
- **Note:** The editor itself is completely free. You only pay for extended collaboration features.
844
-
845
- ---
846
-
847
- ## Pricing
848
-
849
- Magic Editor X follows a freemium model:
850
-
851
- | Feature | FREE | PREMIUM | ADVANCED |
852
- |---------|------|---------|----------|
853
- | **Price** | $0 | $9.90/mo | $24.90/mo |
854
- | Full Editor | Yes | Yes | Yes |
855
- | All 25+ Tools | Yes | Yes | Yes |
856
- | Real-Time Sync | Yes | Yes | Yes |
857
- | Collaborators | 2 | 10 | Unlimited |
858
- | Version History | - | Yes | Yes |
859
- | AI Assistant | - | Pay-per-use | Included |
860
- | Priority Support | - | Email | Email + Chat |
861
- | Custom Blocks | - | - | Yes |
862
-
863
- **Get started:** https://store.magicdx.dev/
864
-
865
- ---
866
-
867
- ## Development & Extension
868
-
869
- ### Custom Block Types
870
-
871
- Create your own block tools:
872
-
873
- ```javascript
874
- // custom-tools/MyCustomTool.js
875
- export default class MyCustomTool {
876
- static get toolbox() {
877
- return {
878
- title: 'My Tool',
879
- icon: '<svg>...</svg>'
880
- };
881
- }
882
-
883
- constructor({ data, api, config }) {
884
- this.data = data;
885
- this.api = api;
886
- this.config = config;
887
- }
888
-
889
- render() {
890
- const wrapper = document.createElement('div');
891
- wrapper.classList.add('my-custom-tool');
892
- // Add your UI
893
- return wrapper;
894
- }
895
-
896
- save(blockContent) {
897
- return {
898
- // Your data structure
899
- text: blockContent.querySelector('input').value
900
- };
901
- }
902
-
903
- static get sanitize() {
904
- return {
905
- text: {} // Sanitizer config
906
- };
907
- }
908
- }
909
- ```
910
-
911
- **Register in `config/tools.js`:**
912
-
913
- ```javascript
914
- import MyCustomTool from './custom-tools/MyCustomTool';
915
-
916
- export const getTools = ({ mediaLibToggleFunc, pluginId }) => {
917
- return {
918
- // ... existing tools
919
- myCustomTool: {
920
- class: MyCustomTool,
921
- config: {
922
- // Your config
923
- }
924
- }
925
- };
926
- };
927
- ```
928
-
929
- ### Extending Collaboration
930
-
931
- Hook into collaboration events:
932
-
933
- ```javascript
934
- // In your component
935
- const { awareness } = useMagicCollaboration({
936
- enabled: true,
937
- roomId: 'my-room',
938
- onRemoteUpdate: () => {
939
- console.log('Remote update received');
940
- }
941
- });
942
-
943
- // Listen to presence changes
944
- awareness.on('change', ({ added, updated, removed }) => {
945
- console.log('Users joined:', added);
946
- console.log('Users updated:', updated);
947
- console.log('Users left:', removed);
948
- });
949
- ```
950
-
951
- ---
448
+ Add only the services you use. Instead of `https:` in `img-src` you can list your image hosts; the notice then counts external images as allowed. GitHub gist embeds load a `data:` iframe that inherits the admin CSP and needs a remote script, so they stay blocked under a strict policy, and Imgur's embed URL uses `http:`, which an `https` admin blocks as mixed content.
952
449
 
953
450
  ## Troubleshooting
954
451
 
955
- ### Common Issues
956
-
957
- **1. Editor Not Loading**
958
-
959
- Check browser console for errors. Common causes:
960
- - Plugin not enabled in `config/plugins.ts`
961
- - Build not run after installation (`npm run build`)
962
- - CSP blocking external resources
963
-
964
- **2. Image Upload Failing**
452
+ | Symptom | Cause | Fix |
453
+ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
454
+ | 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. |
455
+ | 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. |
456
+ | No version history (clock) button | The entry was never saved | Save the entry once. |
457
+ | 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. |
458
+ | 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. |
459
+ | "Reload the page to keep editing live" | The browser still runs the admin of an older version after an update | Reload the page. |
460
+ | 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`. |
461
+ | Settings say the stored key is unreadable | The encryption key changed | Enter the provider key again. |
462
+ | AI error "The AI provider rejected the key." | Wrong key for this provider | Enter the key again and use Test connection. |
463
+ | Startup error `[magic-editor-x] invalid configuration for: <key>` | Wrong type or range in `config/plugins` | Fix the named key (see the reference table). |
464
+ | 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. |
965
465
 
966
- Verify:
967
- - Strapi Upload plugin is enabled
968
- - File size within limits (default 10MB)
969
- - File type is allowed
970
- - User has upload permissions
466
+ ## Migrating from 1.x
971
467
 
972
- **3. Collaboration Not Working**
468
+ 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:
973
469
 
974
- Debug checklist:
975
- - WebSocket connection established (check Network tab)
976
- - Session token valid (check `/realtime/session-token` response)
977
- - User has collaboration permissions
978
- - Firewall/proxy allows WebSocket connections
470
+ 1. Update the package and rebuild the admin: `npm install magic-editor-x@2 && npm run build`.
471
+ 2. Remove 1.x configuration keys (`enabledTools`, `linkPreviewTimeout`, `maxImageSize`, `maxFileSize`, `allowedImageTypes`, `collaboration.wsPath`, `wsUrl`, `sessionTTL`, `allowedAdminRoles`, `allowedAdminUserIds`, `cors`) and use the new keys above.
472
+ 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.
473
+ 4. If you used the AI assistant, configure your own provider in Settings > Magic Editor X > Configuration.
474
+ 5. If your raw HTML blocks need scripts or iframes, set `rawHtml: 'allow'`.
979
475
 
980
- **4. Link Previews Not Showing**
476
+ 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.
981
477
 
982
- Ensure:
983
- - CSP allows `img-src: '*'` in middlewares config
984
- - Target site returns OpenGraph metadata
985
- - Link preview timeout not too short (default: 10s)
986
-
987
- ### Enable Debug Logging
988
-
989
- Add to `config/plugins.ts`:
990
-
991
- ```typescript
992
- {
993
- 'magic-editor-x': {
994
- config: {
995
- debug: true // Enable verbose logging
996
- }
997
- }
998
- }
999
- ```
1000
-
1001
- ---
1002
-
1003
- ## Roadmap
1004
-
1005
- ### ✅ Completed
1006
- - **Version History** - Track all content changes with snapshot restore (v1.1.0)
1007
- - **Character-Level Collaboration** - Simultaneous editing in same block (v1.2.0)
1008
- - **Webtools Links Integration** - Internal/external link picker (v1.2.0)
1009
-
1010
- ### 🚧 In Progress
1011
- - **Comments & Annotations** - Inline comments for editorial workflow
1012
- - **Custom Blocks API** - Simplified API for creating custom tools
1013
-
1014
- ### 📋 Planned
1015
- - **Advanced AI** - Content suggestions, auto-completion, tone analysis
1016
- - **Offline Mode** - Full offline editing with sync on reconnect
1017
- - **Import/Export** - Markdown, HTML, DOCX conversion
1018
- - **Templates** - Pre-built content templates
1019
- - **Block Permissions** - Per-block editing restrictions
1020
-
1021
- ---
1022
-
1023
- ## Resources
1024
-
1025
- - **Documentation:** https://docs.magicdx.dev/
1026
- - **Store:** https://store.magicdx.dev/
1027
- - **GitHub:** https://github.com/Schero94/magic-editor-x
1028
- - **Strapi Custom Fields:** https://docs.strapi.io/cms/features/custom-fields
1029
- - **Editor.js:** https://editorjs.io/
1030
- - **Y.js:** https://docs.yjs.dev/
1031
-
1032
- ---
1033
-
1034
- ## Contributing
1035
-
1036
- Contributions are welcome! Please:
1037
-
1038
- 1. Fork the repository
1039
- 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
1040
- 3. Commit your changes (`git commit -m 'Add amazing feature'`)
1041
- 4. Push to the branch (`git push origin feature/amazing-feature`)
1042
- 5. Open a Pull Request
1043
-
1044
- **Development Setup:**
478
+ ## Development and tests
1045
479
 
1046
480
  ```bash
1047
- git clone https://github.com/Schero94/magic-editor-x.git
1048
- cd magic-editor-x
1049
- npm install
1050
- npm run watch:link
481
+ npm ci
482
+ npm run lint
483
+ npm run format:check
484
+ npm test # unit tests, no Strapi host needed
485
+ npm run build # admin and server bundles, then a runtime check
486
+ npm run verify
487
+ MEX_HOST_URL=http://127.0.0.1:1421 MEX_CREDS=/path/to/creds.json npm run test:integration
1051
488
  ```
1052
489
 
1053
- ---
1054
-
1055
- ## License
1056
-
1057
- MIT License - See [LICENSE](LICENSE) for details
1058
-
1059
- Copyright (c) 2024-2025 Schero D.
490
+ [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.
1060
491
 
1061
- ---
492
+ ## Maintenance status
1062
493
 
1063
- ## Support
494
+ 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.
1064
495
 
1065
- - **Email:** support@magicdx.dev
1066
- - **Issues:** https://github.com/Schero94/magic-editor-x/issues
1067
- - **Discord:** https://discord.gg/magicdx
496
+ ## Languages
1068
497
 
1069
- ---
498
+ The admin is translated into English, German (formal Sie), French, Spanish and Portuguese.
1070
499
 
1071
- **Built with dedication by [Schero D.](https://github.com/Schero94)**
500
+ ## License
1072
501
 
1073
- Part of the MagicDX Plugin Suite for Strapi
502
+ [MIT](./LICENSE) © 2025-2026 Schero D.