magic-editor-x 2.1.0 → 2.2.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 (81) hide show
  1. package/CHANGELOG.md +53 -0
  2. package/README.md +215 -89
  3. package/bin/magic-editor-x.mjs +190 -0
  4. package/dist/admin/{ConfigurationPage-CK2AbfGW.mjs → ConfigurationPage-3Dir3dAf.mjs} +3 -3
  5. package/dist/admin/{ConfigurationPage-CzsT_dO_.js → ConfigurationPage-YvnPnna6.js} +3 -3
  6. package/dist/admin/{CustomBlocksPage-CvLrsBds.js → CustomBlocksPage-BiiL2ORG.js} +4 -4
  7. package/dist/admin/{CustomBlocksPage-B2A8S5MV.mjs → CustomBlocksPage-CR2BaP9O.mjs} +4 -4
  8. package/dist/admin/{EditorField-7YCdXx-v.mjs → EditorField-B8pyAxPE.mjs} +5384 -278
  9. package/dist/admin/{EditorField-BdBCW15Q.js → EditorField-Diq1j8kc.js} +5378 -272
  10. package/dist/admin/{api-CmccMxlN.js → api-Dsq53giv.js} +1 -0
  11. package/dist/admin/{api-D5CAH0nh.mjs → api-RZ0Fz0BD.mjs} +1 -0
  12. package/dist/admin/de-62Vxb2iw.js +250 -0
  13. package/dist/admin/de-BVvwSYYO.mjs +250 -0
  14. package/dist/admin/de-BmmLBJli.mjs +41 -0
  15. package/dist/admin/{de-CkUYGb7U.js → de-BteRx2iA.js} +7 -1
  16. package/dist/admin/{de-rRIutpYJ.mjs → de-CFX5atOk.mjs} +7 -1
  17. package/dist/admin/de-DaJwN6nk.js +41 -0
  18. package/dist/admin/en-Cg2Ak5Cr.mjs +250 -0
  19. package/dist/admin/en-Cn78RZs-.js +41 -0
  20. package/dist/admin/{en-DulOcmXb.js → en-CyjAcccB.js} +7 -1
  21. package/dist/admin/en-D7mZWLGp.mjs +41 -0
  22. package/dist/admin/en-VlkaIzrM.js +250 -0
  23. package/dist/admin/{en-Puup8TFi.mjs → en-ea0tfA5i.mjs} +7 -1
  24. package/dist/admin/es-BT9oAcHf.js +250 -0
  25. package/dist/admin/es-BmGtLkJD.js +41 -0
  26. package/dist/admin/{es-BoQZC86B.js → es-C8GZFGjv.js} +7 -1
  27. package/dist/admin/es-C9-cXdb6.mjs +250 -0
  28. package/dist/admin/{es-257SSB7f.mjs → es-CEi_ycX8.mjs} +7 -1
  29. package/dist/admin/es-joykG5I9.mjs +41 -0
  30. package/dist/admin/{fr-C5rSdKU4.mjs → fr-BAMSvQbR.mjs} +7 -1
  31. package/dist/admin/fr-CrzxGe5e.mjs +41 -0
  32. package/dist/admin/fr-Ct_uPqxV.js +41 -0
  33. package/dist/admin/fr-D6KJqPWi.js +250 -0
  34. package/dist/admin/fr-DpU_qiXR.mjs +250 -0
  35. package/dist/admin/{fr-HxFcPpv4.js → fr-oRCJNdeJ.js} +7 -1
  36. package/dist/admin/index-C-lyON1B.mjs +303 -0
  37. package/dist/admin/index-iA0lued_.js +302 -0
  38. package/dist/admin/index.js +1 -1
  39. package/dist/admin/index.mjs +1 -1
  40. package/dist/admin/pt-BOrl6x-r.js +250 -0
  41. package/dist/admin/{pt-D6UuEtPy.mjs → pt-CQrfqsCN.mjs} +7 -1
  42. package/dist/admin/pt-Ga-4Hsv0.mjs +41 -0
  43. package/dist/admin/pt-chN2jrXl.js +41 -0
  44. package/dist/admin/pt-jUqOR7Xh.mjs +250 -0
  45. package/dist/admin/{pt-Cjn2Sc9k.js → pt-tUeJ2Ywd.js} +7 -1
  46. package/dist/admin/{sanitize-DP5aeU7V.js → sanitize-Cb4jvBhj.js} +42 -11
  47. package/dist/admin/{sanitize-jjCot5PM.mjs → sanitize-ClkX823p.mjs} +45 -14
  48. package/dist/admin/{useT-91ruePzq.js → useT-BWZ_-Hel.js} +1 -1
  49. package/dist/admin/{useT-vgY88N_H.mjs → useT-pvHmgBFj.mjs} +1 -1
  50. package/dist/render/index.d.mts +75 -0
  51. package/dist/render/index.d.ts +75 -0
  52. package/dist/render/index.js +1420 -0
  53. package/dist/render/index.mjs +1398 -0
  54. package/dist/server/index.js +8081 -348
  55. package/dist/server/index.mjs +8084 -351
  56. package/package.json +21 -4
  57. package/schema/magic-editor-x.schema.json +967 -0
  58. package/types/index.d.ts +211 -0
  59. package/types/render.d.ts +75 -0
  60. package/dist/admin/de-BHPyA2S-.mjs +0 -103
  61. package/dist/admin/de-DBR893G4.js +0 -13
  62. package/dist/admin/de-RMs-_SCK.js +0 -103
  63. package/dist/admin/de-fBFh09Wl.mjs +0 -13
  64. package/dist/admin/en-BluCStLw.mjs +0 -103
  65. package/dist/admin/en-C81faOHP.js +0 -103
  66. package/dist/admin/en-D9Nfccux.mjs +0 -13
  67. package/dist/admin/en-gueRT44P.js +0 -13
  68. package/dist/admin/es-B0Zy8DVg.mjs +0 -13
  69. package/dist/admin/es-CQRI2Prp.mjs +0 -103
  70. package/dist/admin/es-D1QzY0JW.js +0 -103
  71. package/dist/admin/es-DRGs7meF.js +0 -13
  72. package/dist/admin/fr-B8rdLAIL.js +0 -13
  73. package/dist/admin/fr-Di3R6gOX.mjs +0 -103
  74. package/dist/admin/fr-R3_MbzT5.js +0 -103
  75. package/dist/admin/fr-oiUb2bb_.mjs +0 -13
  76. package/dist/admin/index-0_b1iroK.mjs +0 -156
  77. package/dist/admin/index-6SZLli70.js +0 -155
  78. package/dist/admin/pt-B3Jce6uT.mjs +0 -13
  79. package/dist/admin/pt-BCW1u_Hp.js +0 -103
  80. package/dist/admin/pt-BiWuSBcH.js +0 -13
  81. package/dist/admin/pt-Cr9AL408.mjs +0 -103
package/README.md CHANGED
@@ -23,7 +23,13 @@ Live docs: <https://schero94.github.io/Magic-Editor-X/>
23
23
  - [Live collaboration](#live-collaboration)
24
24
  - [Running several instances](#running-several-instances)
25
25
  - [AI assistant](#ai-assistant)
26
+ - [Field presets](#field-presets)
27
+ - [Writing tools](#writing-tools)
28
+ - [Paste, import and migration](#paste-import-and-migration)
29
+ - [Version history](#version-history)
30
+ - [Quality checks](#quality-checks)
26
31
  - [Data format](#data-format)
32
+ - [Rendering content](#rendering-content)
27
33
  - [Admin API and permissions](#admin-api-and-permissions)
28
34
  - [Security and privacy](#security-and-privacy)
29
35
  - [Troubleshooting](#troubleshooting)
@@ -45,9 +51,14 @@ Every feature is available in every installation. There is nothing to activate,
45
51
  - other: link preview card (`linkTool`), person card (`personality`), call-to-action button (`button`), raw HTML (`raw`).
46
52
  - **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
53
  - **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.
54
+ - **Field presets:** per field in the Content-Type Builder: allowed blocks and heading levels, character and block limits, required alternative text, allowed links, AI and live collaboration on or off, publishing guard. Enforced on every save and over the live channel, not only in the editor. See [Field presets](#field-presets).
55
+ - **Writing:** Markdown shortcuts (`#`, `-`, `1.`, `[]`, `>`, ` ``` `, `---`, `**bold**`, `_italic_`, `~~strike~~`, `` `code` ``), find and replace, keyboard shortcut help, focus mode, actions for several selected blocks, counts with reading time, undo and redo, drag and drop, full screen. See [Writing tools](#writing-tools).
56
+ - **Paste and import:** Word, Google Docs, LibreOffice, web pages and Markdown become real blocks; a CLI migrates Strapi Blocks, Markdown and HTML fields. See [Paste, import and migration](#paste-import-and-migration).
57
+ - **Media:** alternative text and "decorative image" on image blocks; images keep their Media Library id and responsive formats.
58
+ - **Quality checks:** accessibility lint (alternative texts, heading order, link texts, table headers, contrast of custom colours) and a link check, with an optional publishing guard. See [Quality checks](#quality-checks).
59
+ - **Renderers, schema and types:** `magic-editor-x/render` (HTML, plain text, Markdown; framework-free and XSS-safe), `magic-editor-x/schema` (JSON Schema) and `magic-editor-x/types` (TypeScript). See [Rendering content](#rendering-content).
49
60
  - **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.
61
+ - **Version history:** named versions, a word-level comparison with the current content, restore of the whole field or a single block; automatic versions during live sessions.
51
62
  - **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
63
  - **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
64
  - **Strapi-native admin:** built with the Strapi Design System, light and dark mode, keyboard accessible, admin in English, German, French, Spanish and Portuguese.
@@ -62,6 +73,11 @@ Every feature is available in every installation. There is nothing to activate,
62
73
  | ![AI assistant dialog](docs/site/img/ai-1440.png) | ![Settings, configuration page](docs/site/img/settings-configuration-1440.png) |
63
74
  | ![Settings, custom blocks list](docs/site/img/settings-custom-blocks-1440.png) | ![Custom block form](docs/site/img/custom-block-modal-1440.png) |
64
75
 
76
+ | ![Field presets in the Content-Type Builder](docs/site/img/field-presets-1440.png) | ![Content that does not match its field settings](docs/site/img/preset-problems-1440.png) |
77
+ | ![Find and replace](docs/site/img/find-replace-1440.png) | ![Quality checks and link check](docs/site/img/quality-panel-1440.png) |
78
+ | ![Version comparison with per-block restore](docs/site/img/history-diff-1440.png) | ![Image block with alternative text](docs/site/img/image-alt-1440.png) |
79
+ | ![Actions for several selected blocks](docs/site/img/block-actions-1440.png) | ![Keyboard shortcuts](docs/site/img/shortcuts-1440.png) |
80
+
65
81
  ![Editor on a 390 px wide screen](docs/site/img/editor-mobile-390.png)
66
82
 
67
83
  All screenshots use synthetic data.
@@ -79,13 +95,17 @@ All screenshots use synthetic data.
79
95
 
80
96
  ## Screens
81
97
 
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`. |
98
+ | Screen | Where | Who can open it |
99
+ | ------------------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
100
+ | 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). |
101
+ | Version history | Clock button in the editor toolbar of a saved document | `access` and Content Manager read on the document; saving, naming and restoring need update. |
102
+ | Find and replace | Magnifier button, or Ctrl/Cmd+Shift+F in the editor | Everyone who can read the field; replacing needs update. |
103
+ | Quality checks | Seal button in the editor toolbar (the number counts problems) | Everyone who can read the field; the link check needs `access`. |
104
+ | Keyboard shortcuts, focus mode | More (…) button, or Ctrl/Cmd+/ | Everyone who can read the field. |
105
+ | Field options | Content-Type Builder, Magic Editor X field, Basic and Advanced settings | Content-Type Builder access (development mode). |
106
+ | AI assistant | Inline toolbar (select text) | `access` and `ai.use`, when an administrator turned the assistant on. |
107
+ | Configuration | Settings > Magic Editor X > Configuration | `settings.read` (view), `settings.update` (edit). |
108
+ | Custom blocks | Settings > Magic Editor X > Custom blocks | `custom-blocks.manage`. |
89
109
 
90
110
  ## Compatibility
91
111
 
@@ -122,7 +142,7 @@ npm run build
122
142
  npm run develop
123
143
  ```
124
144
 
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).
145
+ Add the field in the Content-Type Builder: **Add another field > Custom > Magic Editor X**. In its settings you can set a placeholder, a preset and the other [field presets](#field-presets), and a minimum height (120 to 2000 px).
126
146
 
127
147
  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).
128
148
 
@@ -132,35 +152,40 @@ After the first start, Super Admins can use everything. Other roles need the plu
132
152
 
133
153
  All keys are optional. Infrastructure options live in `config/plugins`; the AI provider is edited at runtime in Settings > Magic Editor X > Configuration.
134
154
 
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). |
155
+ | Key | Type | Default | Effect |
156
+ | --------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
157
+ | `debug` | boolean | `false` | Writes debug log lines (never content or personal data). |
158
+ | `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. |
159
+ | `sanitizeOnSave` | boolean | `true` | Normalise and sanitise Magic Editor X values on every Document Service write. Turning this off is not recommended. |
160
+ | `encryptionKey` | string (32+ characters) | unset | Key for the stored AI provider key. Prefer the `MAGIC_EDITOR_X_ENCRYPTION_KEY` environment variable. |
161
+ | `uploads.maxImageBytes` | integer | `10485760` (10 MiB) | Largest image accepted by file or URL (hard cap 500 MiB). |
162
+ | `uploads.maxFileBytes` | integer | `20971520` (20 MiB) | Largest attachment. |
163
+ | `linkPreview.enabled` | boolean | `true` | Link preview cards. When `false`, `GET /magic-editor-x/link` answers 404. |
164
+ | `linkPreview.timeoutMs` | integer | `8000` | Time limit for fetching a page (1000 to 30000). |
165
+ | `api.autoParseJSON` | boolean | `true` | Turn 1.x JSON strings into objects in Content API GET responses. |
166
+ | `ai.allowPrivateBaseUrl` | boolean | `false` | Allow AI base URLs on loopback or private networks (for local models). Owner decision; not editable in the admin. |
167
+ | `ai.apiKey` | string | unset | Provider key from the environment. When set it wins over a key stored in the settings. |
168
+ | `ai.requestsPerMinute` | integer | `20` | AI requests per admin per minute, counted per process. |
169
+ | `ai.timeoutMs` | integer | `60000` | Time limit for one provider request. |
170
+ | `collaboration.enabled` | boolean | `true` | Live collaboration and its Socket.IO server. |
171
+ | `collaboration.path` | string | `'/magic-editor-x/realtime'` | Socket.IO path on the Strapi HTTP server. |
172
+ | `collaboration.allowedOrigins` | string[] | `[]` | Extra browser origins allowed to open the socket. The admin URL and the server URL are always allowed. |
173
+ | `collaboration.pollIntervalMs` | integer | `400` | How often each process reads updates written by other processes (50 to 10000). |
174
+ | `collaboration.roomTtlMinutes` | integer | `30` | Keep a room's live state this long after the last person left. |
175
+ | `collaboration.maxMessageBytes` | integer | `2097152` (2 MiB) | Largest accepted socket message. |
176
+ | `collaboration.snapshotIntervalMinutes` | integer | `10` | Automatic version while people edit live. `0` turns it off. |
177
+ | `collaboration.tokenTtlSeconds` | integer | `60` | Lifetime of the one-time token that opens the socket. |
178
+ | `collaboration.maxConnectionsPerAdmin` | integer | `20` | Open live sockets per admin across all processes. |
179
+ | `collaboration.maxRoomsPerAdmin` | integer | `20` | Different fields one admin may have open live at the same time, across all processes. |
180
+ | `collaboration.revalidateSeconds` | integer | `60` | Full permission re-check of open sockets. Role, permission and user changes are applied within about a second anyway. |
181
+ | `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. |
182
+ | `collaboration.compaction` | object | `{ enabled: true, idleSeconds: 60, minBytes: 262144, ratio: 4, checkIntervalSeconds: 30 }` | Rebuilds an idle room whose live state is `ratio` times larger than a fresh copy (and at least `minBytes`) as a new generation, once across all processes. Open editors switch without reconnecting; edits that had not reached the server yet are kept. Bounds: `idleSeconds` 15 to 86400, `minBytes` 1 KiB to 512 MiB, `ratio` 1.5 to 1000, `checkIntervalSeconds` 1 to 3600. |
183
+ | `history.maxSnapshotsPerField` | integer | `50` | Versions kept per field and locale; older ones are deleted. |
184
+ | `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). |
185
+ | `qualityChecks.externalLinks` | object | `{ enabled: false, timeoutMs: 5000, perMinute: 30 }` | External link check of the quality panel; keys below. |
186
+ | `qualityChecks.externalLinks.enabled` | boolean | `false` | Lets the quality panel check external links (outgoing requests through the SSRF-protected fetcher; owner opt-in). |
187
+ | `qualityChecks.externalLinks.timeoutMs` | integer | `5000` | Time limit per request and per redirect hop (1000 to 15000). |
188
+ | `qualityChecks.externalLinks.perMinute` | integer | `30` | External URLs one admin may check per minute, shared by all processes. |
164
189
 
165
190
  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).
166
191
 
@@ -243,6 +268,77 @@ The assistant is off until an administrator turns it on in Settings > Magic Edit
243
268
  - 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
269
  - 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.
245
270
 
271
+ ## Field presets
272
+
273
+ Each Magic Editor X field can have its own rules, set in the Content-Type Builder (field settings). They are stored as custom field options in the schema and enforced in three places with the same code (`shared/presets.mjs`): the editor offers only what the field allows, the realtime server refuses new blocks a preset does not allow, and every write (Content Manager, Content API, imports, code) is checked by the Document Service middleware.
274
+
275
+ | Option (`options.*`) | Where in the field settings | Values | Effect |
276
+ | ---------------------- | --------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
277
+ | `preset` | Basic | `full` (default), `article`, `basic`, `minimal` | Allowed blocks, inline tools and heading levels, see below. |
278
+ | `linkTargets` | Basic | `all` (default), `internal`, `external`, `none` | Which links are allowed: entries of the site (internal links), web addresses, both or none. Link blocks (`linkTool`, `button`, `personality`) count as web addresses. |
279
+ | `requireAlt` | Basic | checkbox | Images need an alternative text or the "decorative image" mark. |
280
+ | `allowedBlocks` | Advanced | comma-separated block names, for example `paragraph, header, list, image, myHero` | Replaces the preset's block list (custom blocks by name). `paragraph` is always allowed. |
281
+ | `headingLevels` | Advanced | `2-4`, `2,3`, `1, 3-5` | Replaces the preset's heading levels. |
282
+ | `maxBlocks` | Advanced | number, empty or 0 = no limit | Block limit, shown in the toolbar (`12 / 20 blocks`). |
283
+ | `maxCharacters` | Advanced | number, empty or 0 = no limit | Visible characters, counted like the toolbar (`380 / 400 characters`). |
284
+ | `disableAi` | Advanced | checkbox | No AI button in this field; the AI route answers 403 for requests from it. |
285
+ | `disableCollaboration` | Advanced | checkbox | No live editing in this field (the session route answers 403). |
286
+ | `publishGuard` | Advanced | checkbox | Publishing is refused while the [quality checks](#quality-checks) report errors in this field. |
287
+
288
+ | Preset | Blocks | Inline tools | Headings |
289
+ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------- |
290
+ | `full` | all, custom blocks included | all | H1-H6 |
291
+ | `article` | paragraph, header, list, checklist, quote, warning, alert, toggle, code, codeFlask, delimiter, table, embed, image (and the Media Library picker), linkTool, attaches, button | all | H2-H4 |
292
+ | `basic` | paragraph, header, list, quote, image, delimiter | bold, italic, underline, strikethrough, link | H2-H3 |
293
+ | `minimal` | paragraph, list | bold, italic, link | none |
294
+
295
+ How the rules apply:
296
+
297
+ - **Editor:** blocks that are not allowed leave the toolbox, the conversion menu and paste handling; heading levels and inline tools are limited; Markdown shortcuts and pasted content follow the preset (a pasted H1 becomes the nearest allowed level, a table becomes text). Existing content that no longer fits is kept, listed under "Field settings" in the quality panel with **Fix automatically** (changes heading levels, turns blocks that are not allowed into paragraphs, removes links that are not allowed), and a note under the field says that saving fails until it is fixed.
298
+ - **Save:** a value that breaks a rule is refused with 400 `ValidationError`, `details.code: 'PRESET_VIOLATION'`, `details.violations: [{ field, code, blockId, index, params }]` (codes `BLOCK_NOT_ALLOWED`, `HEADING_LEVEL`, `LINK_NOT_ALLOWED`, `ALT_REQUIRED`, `TOO_MANY_BLOCKS`, `TOO_MANY_CHARACTERS`) and `details.errors` with the field path, so the Content Manager shows the reason on the field. Errors carry rule codes and block ids only, never content. Inline formatting a preset leaves out (for example a marker in a `basic` field) is removed on save; the text stays.
299
+ - **Live editing:** the server refuses updates that add a block type or heading level the preset does not allow (blocks that existed before stay editable). Limits and alternative texts are checked on save only, so typing is never refused half-way.
300
+
301
+ Changing a preset never changes stored content by itself. Turning `sanitizeOnSave` off also turns the save check off.
302
+
303
+ ## Writing tools
304
+
305
+ | Tool | How |
306
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
307
+ | Markdown shortcuts | At the start of an empty paragraph: `#` to `######` + Space (heading), `-`, `*` or `+` + Space (bulleted list), `1.` + Space (numbered list, other numbers set the start), `[]` or `[x]` + Space (checklist), `>` + Space (quote), ` ``` ` (optionally with a language) + Enter (code block), `---` + Enter (delimiter). While typing: `**bold**`, `__bold__`, `*italic*`, `_italic_`, `~~strike~~`, `` `code` ``. Never inside code, raw HTML or tables; only blocks and marks the field allows. |
308
+ | Find and replace | Magnifier button or Ctrl/Cmd+Shift+F. Searches every text block, list item, table cell, caption and code block; keeps formatting; match case, whole words, regular expressions (off by default, patterns up to 200 characters). Enter / Shift+Enter move between matches, the current match is highlighted. Replacements are normal edits (undo, collaboration). A match cannot span differently formatted text. |
309
+ | Keyboard shortcuts | Ctrl/Cmd+/ or More > Keyboard shortcuts: editor, block and inline tool shortcuts and the Markdown shortcuts of this field. |
310
+ | Focus mode | More > Focus mode: full screen, narrower text column, other blocks dimmed. Escape leaves. |
311
+ | Several selected blocks | Select across blocks (Shift+Arrow at a block edge, Ctrl/Cmd+A twice, or drag across blocks): move up or down, duplicate, copy as Markdown, delete, convert to text, heading, list or quote. |
312
+ | Counts | Blocks, words, characters and reading time (200 words per minute) in the toolbar, with the field's limits. |
313
+ | Alternative text | Image and image-by-URL blocks: "Alternative text" field (prefilled from the Media Library) and "Decorative image (no alternative text)". Required when the field has `requireAlt`. |
314
+ | Language and direction | The editor gets the content locale as `lang` (spell checking) and writes right to left for Arabic, Hebrew, Persian, Urdu and other RTL locales. |
315
+
316
+ ## Paste, import and migration
317
+
318
+ **Paste.** Pasting from Word, Google Docs, LibreOffice, web pages (two or more blocks) or Markdown text creates real blocks: headings, nested lists, checklists, quotes, code, tables, links, bold, italic, underline and strikethrough. Styles, classes, comments and scripts are removed; the clipboard HTML is parsed into an inert document and never attached to the page. Images from the web are copied into the Media Library through the same SSRF-protected path as "image by URL" (at most 10 per paste) when you may upload; images Word keeps on your disk (`file:`) cannot be pasted and are counted in a message. Blocks the field does not allow become paragraphs. Ctrl/Cmd+Shift+V pastes plain text. Pastes into code, raw HTML and table cells are not changed.
319
+
320
+ **Migrate an existing field.** Add a Magic Editor X field next to the old one, then run from the project root (the old field is kept):
321
+
322
+ ```bash
323
+ npx magic-editor-x migrate --uid api::article.article --from body --to content # dry run, writes nothing
324
+ npx magic-editor-x migrate --uid api::article.article --from body --to content --apply # convert
325
+ ```
326
+
327
+ Options: `--format auto|blocks|markdown|html` (auto: Blocks fields as Strapi Blocks, Rich text as Markdown, text and string as HTML when they contain tags, else Markdown, JSON as Strapi Blocks or Editor.js), `--locale <code>` or `--locale '*'` (all locales), `--overwrite` (replace a target that already has content), `--batch 50`, `--limit <n>`, `--json` (machine-readable report on stdout; Strapi's own log lines go to stderr), `--out report.json`. Re-running skips converted documents (idempotent). The report counts scanned, converted, skipped and failed documents and lists lossy conversions (for example a skipped image) by document id and note, never content. Drafts are converted; publish afterwards. The same is available in code: `strapi.plugin('magic-editor-x').service('migrate').run({ uid, from, to, format, locale, dryRun, overwrite })`.
328
+
329
+ ## Version history
330
+
331
+ The clock button opens the versions of the field (per document and locale). **Save current version** stores the editor content, optionally with a name ("Before legal review", up to 120 characters); the pencil renames a version. Open a version with the eye button: **Preview** shows it, **Changes** compares it with the current editor content: added, removed, moved and changed blocks, changes marked word by word (`<ins>`/`<del>` with text labels, not colour alone) and formatting-only changes. **Restore this block** puts a single block back (at its old place, or over the current block); **Restore** replaces the whole field. Save the entry to keep a restore. Automatic versions are taken during live sessions (`collaboration.snapshotIntervalMinutes`).
332
+
333
+ ## Quality checks
334
+
335
+ The seal button opens the quality panel; its number counts problems. It never blocks editing.
336
+
337
+ - **Accessibility lint** (`shared/quality.mjs`): images without alternative text (an error when the field has `requireAlt`, otherwise a warning; decorative images are fine), skipped heading levels, more than one H1, empty headings, empty links (error), link texts such as "click here", "hier", "cliquez ici", "aquí", "clique aqui" (English, German, French, Spanish, Portuguese), tables without a header row, and custom-block colour pairs below 4.5:1. Click an issue to jump to its block.
338
+ - **Field settings:** content that breaks the field's [preset](#field-presets), with automatic fixes.
339
+ - **Check links** (`POST /magic-editor-x/quality/links`): internal links (entries you cannot read answer "Not checked", so nothing is revealed; "Not published" for drafts of Draft & Publish types), Media Library files (needs Media Library read) and, only when `qualityChecks.externalLinks.enabled` is true, external links through the SSRF-protected fetcher (public addresses only, pinned DNS, redirects re-checked, HEAD then a capped GET, rate limited per admin across processes, cached for 10 minutes). URLs are never logged.
340
+ - **Publishing guard:** with the field option `publishGuard`, publishing a document whose field has errors answers 400 `details.code: 'QUALITY_GATE'` with `details.issues: [{ field, rule, blockId, locale? }]` and `details.errors` for the form. Warnings never block.
341
+
246
342
  ## Data format
247
343
 
248
344
  The field stores an Editor.js document as JSON:
@@ -265,30 +361,30 @@ The field stores an Editor.js document as JSON:
265
361
 
266
362
  Data of each block type as stored after sanitising (`shared/sanitize-policy.mjs`):
267
363
 
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 }` |
364
+ | Block | `data` |
365
+ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
366
+ | `paragraph` | `{ text }` (inline HTML) |
367
+ | `header` | `{ text, level: 1-6 }` |
368
+ | `list` | `{ style: 'ordered' \| 'unordered' \| 'checklist', meta?: { start?, counterType? }, items: [{ content, meta?, items: [...] }] }` |
369
+ | `checklist` | `{ items: [{ text, checked }] }` |
370
+ | `quote` | `{ text, caption, alignment: 'left' \| 'center' }` |
371
+ | `warning` | `{ title, message }` |
372
+ | `alert` | `{ type: 'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'light' \| 'dark', align: 'left' \| 'center' \| 'right', message }` |
373
+ | `toggle` | `{ text, status: 'open' \| 'closed', fk?, items }` (the next `items` blocks are its content) |
374
+ | `code` | `{ code }` (plain text) |
375
+ | `codeFlask` | `{ code, language, showlinenumbers? }` |
376
+ | `raw` | `{ html }` (see `rawHtml`) |
377
+ | `table` | `{ withHeadings, stretched, content: string[][] }` |
378
+ | `image` | `{ file: { url, mime?, alt?, width?, height?, size?, formats?, id?, documentId? }, caption, withBorder, withBackground, stretched, decorative? }` (`id`/`documentId` reference the Media Library file, `formats` its responsive sizes; `decorative: true` = intentionally empty alternative text) |
379
+ | `simpleImage` | `{ url, caption, withBorder, withBackground, stretched, alt?, decorative? }` |
380
+ | `linkTool` | `{ link, meta: { title, description, site_name?, image?: { url } } }` |
381
+ | `attaches` | `{ file: { url, name?, extension?, size?, title? }, title }` |
382
+ | `embed` | `{ service, source, embed, width?, height?, caption }` (`embed` is always https) |
383
+ | `personality` | `{ name, description, link, photo }` |
384
+ | `button` | `{ text, link, style, openInNewTab }` |
385
+ | `delimiter` | `{}` |
386
+ | custom simple block | `{ content, <field values>, blockType: 'simple', blockName }` |
387
+ | custom embedded-entry block | `{ entry: { id, documentId, title, <display fields> }, contentType, displayMode }` |
292
388
 
293
389
  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
390
 
@@ -308,11 +404,35 @@ The link tool (`CMD+K`) has a **Link to an entry** button: choose a content type
308
404
 
309
405
  - `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
406
  - `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.
407
+ - **Links follow slug changes** because the entry reference is stored, not only the URL: render with `renderHtml(value, { links: ({ uid, documentId, locale, href }) => urlFor(uid, documentId, locale) })` (see [Rendering content](#rendering-content)), or in server code `await strapi.plugin('magic-editor-x').service('links').resolveHrefs(value, { status: 'published' })`, which re-renders every internal `href` from `links.urlPattern` and the entry's current slug (one query per type and locale; links to deleted entries keep their stored `href`; it does not check admin permissions, so use it for content the caller may already see).
311
408
 
312
409
  Tunes are stored per block in `tunes`: `alignmentTune: { alignment }`, `textVariant: '' | 'call-out' | 'citation' | 'details'`, `indentTune: { indentLevel }`.
313
410
 
314
411
  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
412
 
413
+ ## Rendering content
414
+
415
+ `npm i magic-editor-x` also gives you a framework-free renderer (ESM and CommonJS, no dependencies, no Node built-ins, so it runs in Node, browsers and edge runtimes), a JSON Schema and TypeScript types:
416
+
417
+ ```js
418
+ import { renderHtml, renderText, renderMarkdown } from 'magic-editor-x/render';
419
+
420
+ const html = renderHtml(entry.body, {
421
+ links: ({ uid, documentId, locale, href }) => `/${locale}/articles/${slugs.get(documentId)}`, // internal links follow slug changes
422
+ media: (file) => file, // refresh Media Library files by file.id / file.documentId if you like
423
+ overrides: { myHero: (block, h) => `<section class="hero">${h.escape(block.data.title)}</section>` },
424
+ });
425
+ const text = renderText(entry.body); // search index, meta description
426
+ const markdown = renderMarkdown(entry.body); // feeds, LLM context, export
427
+ ```
428
+
429
+ - **Safe by default:** stored inline HTML is re-parsed and only the editor's own tags and attributes survive (entities are decoded before URL checks, `javascript:`/`data:` links are dropped, `target="_blank"` gets `rel="noopener noreferrer"`), so the output is safe even for content that did not pass the server sanitiser. Raw HTML blocks are left out unless you pass `rawHtml: 'allow'` together with your own `sanitizeRaw` function. Embeds become iframes (`sandbox`, `loading="lazy"`, `referrerpolicy`) only for `embedHosts` (default: YouTube, youtube-nocookie, Vimeo player, CodePen, Twitch, Figma, Miro); other embeds become links.
430
+ - **Output:** HTML elements with stable `mex-` classes (tunes as `mex-align-*`, `mex-variant-*`, `mex-indent-N`), images with `srcset` from the Media Library `formats`, width, height and lazy loading (`imageSizes`, default `100vw`), decorative images with `alt=""`, toggles as `<details>`. Custom blocks render as `<div class="mex-block mex-<name>" data-mex-block>` with escaped values unless you pass an override. Markdown is CommonMark plus GFM tables and task lists; plain text uses blank lines between blocks.
431
+ - **Deterministic:** the same value always gives the same string.
432
+ - **Schema:** `magic-editor-x/schema` is a JSON Schema (draft 2020-12) of the stored value with one data schema per block type; validate content in CI. **Types:** `import type { MagicEditorXData, MagicEditorXBlock } from 'magic-editor-x/types'`.
433
+
434
+ React, Vue and Astro components on top of the renderer are planned for 2.3.
435
+
316
436
  ## Admin API and permissions
317
437
 
318
438
  ### Permissions
@@ -334,32 +454,34 @@ Super Admins have all actions. The `access` action keeps its 1.x id, so roles th
334
454
 
335
455
  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
456
 
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 } }` |
457
+ | Method | Path | Actions | Body / query | Response |
458
+ | ------ | --------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
459
+ | GET | `/magic-editor-x/config` | access | | `{ data: { collaboration, ai, uploads, linkPreview, rawHtml, permissions } }` |
460
+ | GET | `/magic-editor-x/link` | access | `?url=` | `{ success: 1, link, meta }` |
461
+ | POST | `/magic-editor-x/image/byFile` | access, upload | multipart `image` | `{ success: 1, file: { url, ... } }` |
462
+ | POST | `/magic-editor-x/image/byUrl` | access, upload | `{ url }` | `{ success: 1, file }` |
463
+ | POST | `/magic-editor-x/file/upload` | access, upload | multipart `file` | `{ success: 1, file: { url, name, title, size, extension } }` |
464
+ | GET | `/magic-editor-x/content-types` | access | | `{ data: [{ uid, kind, displayName, attributes }] }` (types you can read) |
465
+ | GET | `/magic-editor-x/links/types` | access | | `{ data: [{ uid, kind, displayName, localized }] }` (API types you can read) |
466
+ | 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) |
467
+ | GET | `/magic-editor-x/custom-blocks` | access (`?all=true` also needs custom-blocks.manage) | `?all=true` | `{ data: [block] }` |
468
+ | GET | `/magic-editor-x/custom-blocks/export` | custom-blocks.manage | | `{ data: { format: 'magic-editor-x/custom-blocks', version: 2, exportedAt, blocks } }` |
469
+ | POST | `/magic-editor-x/custom-blocks/import` | custom-blocks.manage | export document | `{ data: { created: [name], skipped: [{ name, reason }] } }` |
470
+ | PUT | `/magic-editor-x/custom-blocks/order` | custom-blocks.manage | `{ ids }` (every block once) | `{ data: [block] }` |
471
+ | POST | `/magic-editor-x/custom-blocks` | custom-blocks.manage | block definition | 201 `{ data: block }` |
472
+ | PUT | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage | full block definition | `{ data: block }` |
473
+ | DELETE | `/magic-editor-x/custom-blocks/:id` | custom-blocks.manage | | `{ data: { id } }` |
474
+ | POST | `/magic-editor-x/custom-blocks/:id/duplicate` | custom-blocks.manage | | 201 `{ data: block }` |
475
+ | POST | `/magic-editor-x/collaboration/session` | access, collaborate | `{ uid, documentId, locale?, field, initialValue? }` | `{ data: { token, path, canEdit, expiresAt } }` |
476
+ | GET | `/magic-editor-x/history` | access | `?uid&documentId&locale&field` | `{ data: [version], meta: { canRestore, canCreate } }` |
477
+ | GET | `/magic-editor-x/history/:id` | access | | `{ data: { ...version, content } }` |
478
+ | POST | `/magic-editor-x/history` | access | `{ uid, documentId, locale?, field, content, label? }` | 201 new version, 200 with `meta.created: false` when unchanged (a `label` then names the latest version) |
479
+ | PUT | `/magic-editor-x/history/:id` | access (+ Content Manager update) | `{ label }` (up to 120 characters, `''` or `null` clears) | `{ data: version }`; 403 for read-only access, 404 without read access |
480
+ | POST | `/magic-editor-x/quality/links` | access (+ Content Manager read per type, Media Library read) | `{ internal?: [{ uid, documentId, locale? }] (max 100), media?: [id] (max 100), external?: [url] (max 20) }` | `{ data: { internal: [{ uid, documentId, locale, status }], media: [{ id, status }], external: [{ url, status, code? }] } }`; 429 above `qualityChecks.externalLinks.perMinute` |
481
+ | POST | `/magic-editor-x/ai/:action` | access, ai.use | `{ text, language?, tone?, target: { uid, field } }` | `{ data: { text } }`; 403 when the field turns AI off |
482
+ | GET | `/magic-editor-x/settings` | settings.read | | `{ data: { ai, environment } }` (no secrets) |
483
+ | PUT | `/magic-editor-x/settings` | settings.read, settings.update | `{ ai: { enabled, provider, baseUrl, model, maxInputChars, maxOutputTokens, apiKey? } }` | `{ data: { ai, environment } }` |
484
+ | POST | `/magic-editor-x/settings/ai/test` | settings.read, settings.update | `{ ai: {...} }` | `{ data: { ok: true } }` |
363
485
 
364
486
  `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
487
 
@@ -395,6 +517,8 @@ Content-Type: application/json
395
517
  - **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
518
  - **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
519
  - **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).
520
+ - **Field presets** are enforced on the server (save middleware and realtime guard), not only in the editor; see [Field presets](#field-presets).
521
+ - **Paste, import and rendering:** pasted and imported HTML/Markdown is parsed into an inert document and rebuilt from the editor's own tags only, then sanitised again on save; `magic-editor-x/render` re-parses stored inline HTML and never trusts it. The link check fetches external URLs only when the owner turns it on, through the SSRF-protected fetcher, rate limited, without logging URLs. See [docs/security-audit-2.2.md](./docs/security-audit-2.2.md).
398
522
  - **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
523
  - **Logs** contain operation names and error codes only, never content, URLs with queries, tokens, user ids or email addresses.
400
524
  - **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).
@@ -462,6 +586,8 @@ Add only the services you use. Instead of `https:` in `img-src` you can list you
462
586
  | AI error "The AI provider rejected the key." | Wrong key for this provider | Enter the key again and use Test connection. |
463
587
  | 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
588
  | 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. |
589
+ | 400 "A Magic Editor X field does not match its field settings" | The content breaks the field's preset (`details.violations` lists rule codes and block ids) | Open the quality panel of the field and use Fix automatically, or change the content or the field options. |
590
+ | 400 "Quality checks failed for a Magic Editor X field" on publish | The field has `publishGuard` and the quality checks report errors | Fix the errors listed in the quality panel (missing alternative texts, empty links). |
465
591
 
466
592
  ## Migrating from 1.x
467
593