@focus-reactive/payload-plugin-visual-editing 1.1.0 → 1.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 (325) hide show
  1. package/README.md +365 -95
  2. package/dist/admin/InstantPreviewBroadcaster.d.ts +3 -0
  3. package/dist/admin/InstantPreviewBroadcaster.js +64 -0
  4. package/dist/admin/InstantPreviewBroadcaster.js.map +1 -0
  5. package/dist/admin/VisualEditingBridgeProvider.js +28 -27
  6. package/dist/admin/VisualEditingBridgeProvider.js.map +1 -1
  7. package/dist/admin/expandAndFocus.d.ts +0 -1
  8. package/dist/admin/expandAndFocus.js +19 -61
  9. package/dist/admin/expandAndFocus.js.map +1 -1
  10. package/dist/admin/fieldDomId.d.ts +5 -0
  11. package/dist/admin/fieldDomId.js +11 -0
  12. package/dist/admin/fieldDomId.js.map +1 -0
  13. package/dist/admin/index.d.ts +2 -0
  14. package/dist/admin/index.js +2 -0
  15. package/dist/admin/index.js.map +1 -1
  16. package/dist/admin/instantPreview/fieldMessages.d.ts +26 -0
  17. package/dist/admin/instantPreview/fieldMessages.js +90 -0
  18. package/dist/admin/instantPreview/fieldMessages.js.map +1 -0
  19. package/dist/admin/instantPreview/formFields.d.ts +9 -0
  20. package/dist/admin/instantPreview/formFields.js +54 -0
  21. package/dist/admin/instantPreview/formFields.js.map +1 -0
  22. package/dist/admin/instantPreview/previewSession.d.ts +18 -0
  23. package/dist/admin/instantPreview/previewSession.js +157 -0
  24. package/dist/admin/instantPreview/previewSession.js.map +1 -0
  25. package/dist/admin/instantPreview/richTextReads.d.ts +29 -0
  26. package/dist/admin/instantPreview/richTextReads.js +67 -0
  27. package/dist/admin/instantPreview/richTextReads.js.map +1 -0
  28. package/dist/admin/instantPreview/unsavedStructures.d.ts +16 -0
  29. package/dist/admin/instantPreview/unsavedStructures.js +71 -0
  30. package/dist/admin/instantPreview/unsavedStructures.js.map +1 -0
  31. package/dist/admin/instantPreview/useEditableSchema.d.ts +7 -0
  32. package/dist/admin/instantPreview/useEditableSchema.js +30 -0
  33. package/dist/admin/instantPreview/useEditableSchema.js.map +1 -0
  34. package/dist/admin/instantPreview/usePreviewPage.d.ts +3 -0
  35. package/dist/admin/instantPreview/usePreviewPage.js +50 -0
  36. package/dist/admin/instantPreview/usePreviewPage.js.map +1 -0
  37. package/dist/admin/instantPreview/usePreviewWindow.d.ts +7 -0
  38. package/dist/admin/instantPreview/usePreviewWindow.js +46 -0
  39. package/dist/admin/instantPreview/usePreviewWindow.js.map +1 -0
  40. package/dist/admin/openField/OpenFormAnnouncer.d.ts +1 -0
  41. package/dist/admin/openField/OpenFormAnnouncer.js +8 -0
  42. package/dist/admin/openField/OpenFormAnnouncer.js.map +1 -0
  43. package/dist/admin/openField/formPathOfKey.d.ts +11 -0
  44. package/dist/admin/openField/formPathOfKey.js +20 -0
  45. package/dist/admin/openField/formPathOfKey.js.map +1 -0
  46. package/dist/admin/openField/openDocument.d.ts +8 -0
  47. package/dist/admin/openField/openDocument.js +13 -0
  48. package/dist/admin/openField/openDocument.js.map +1 -0
  49. package/dist/admin/openField/openForms.d.ts +9 -0
  50. package/dist/admin/openField/openForms.js +20 -0
  51. package/dist/admin/openField/openForms.js.map +1 -0
  52. package/dist/admin/openField/useOpenFormAnnouncement.d.ts +1 -0
  53. package/dist/admin/openField/useOpenFormAnnouncement.js +29 -0
  54. package/dist/admin/openField/useOpenFormAnnouncement.js.map +1 -0
  55. package/dist/admin/parseFieldPath.js +7 -17
  56. package/dist/admin/parseFieldPath.js.map +1 -1
  57. package/dist/admin/resolveContainerChain.d.ts +3 -2
  58. package/dist/admin/resolveContainerChain.js +10 -33
  59. package/dist/admin/resolveContainerChain.js.map +1 -1
  60. package/dist/client/VisualEditingOverlay.js +24 -15
  61. package/dist/client/VisualEditingOverlay.js.map +1 -1
  62. package/dist/client/VisualEditingProvider.d.ts +5 -3
  63. package/dist/client/VisualEditingProvider.js +6 -6
  64. package/dist/client/VisualEditingProvider.js.map +1 -1
  65. package/dist/client/VisualEditingToggle.js +1 -11
  66. package/dist/client/VisualEditingToggle.js.map +1 -1
  67. package/dist/client/adminWindow.d.ts +2 -0
  68. package/dist/client/adminWindow.js +8 -0
  69. package/dist/client/adminWindow.js.map +1 -0
  70. package/dist/client/createOverlay.d.ts +17 -0
  71. package/dist/client/createOverlay.js +30 -0
  72. package/dist/client/createOverlay.js.map +1 -0
  73. package/dist/client/index.d.ts +5 -1
  74. package/dist/client/index.js +3 -1
  75. package/dist/client/index.js.map +1 -1
  76. package/dist/client/instantPreview/LiveRichText.d.ts +16 -0
  77. package/dist/client/instantPreview/LiveRichText.js +18 -0
  78. package/dist/client/instantPreview/LiveRichText.js.map +1 -0
  79. package/dist/client/instantPreview/adminChannel.d.ts +14 -0
  80. package/dist/client/instantPreview/adminChannel.js +40 -0
  81. package/dist/client/instantPreview/adminChannel.js.map +1 -0
  82. package/dist/client/instantPreview/instantPreview.d.ts +8 -0
  83. package/dist/client/instantPreview/instantPreview.js +49 -0
  84. package/dist/client/instantPreview/instantPreview.js.map +1 -0
  85. package/dist/client/instantPreview/liveFields.d.ts +18 -0
  86. package/dist/client/instantPreview/liveFields.js +158 -0
  87. package/dist/client/instantPreview/liveFields.js.map +1 -0
  88. package/dist/client/instantPreview/liveMessages.d.ts +6 -0
  89. package/dist/client/instantPreview/liveMessages.js +39 -0
  90. package/dist/client/instantPreview/liveMessages.js.map +1 -0
  91. package/dist/client/instantPreview/liveRichTextOf.d.ts +6 -0
  92. package/dist/client/instantPreview/liveRichTextOf.js +23 -0
  93. package/dist/client/instantPreview/liveRichTextOf.js.map +1 -0
  94. package/dist/client/instantPreview/pageLoad.d.ts +6 -0
  95. package/dist/client/instantPreview/pageLoad.js +11 -0
  96. package/dist/client/instantPreview/pageLoad.js.map +1 -0
  97. package/dist/client/instantPreview/unsavedRender/UnsavedRenderBoundary.d.ts +19 -0
  98. package/dist/client/instantPreview/unsavedRender/UnsavedRenderBoundary.js +28 -0
  99. package/dist/client/instantPreview/unsavedRender/UnsavedRenderBoundary.js.map +1 -0
  100. package/dist/client/instantPreview/unsavedRender/announcer.d.ts +3 -0
  101. package/dist/client/instantPreview/unsavedRender/announcer.js +25 -0
  102. package/dist/client/instantPreview/unsavedRender/announcer.js.map +1 -0
  103. package/dist/client/instantPreview/unsavedRender/savedShapes.d.ts +6 -0
  104. package/dist/client/instantPreview/unsavedRender/savedShapes.js +20 -0
  105. package/dist/client/instantPreview/unsavedRender/savedShapes.js.map +1 -0
  106. package/dist/client/instantPreview/unsavedRender/unsavedRender.d.ts +40 -0
  107. package/dist/client/instantPreview/unsavedRender/unsavedRender.js +158 -0
  108. package/dist/client/instantPreview/unsavedRender/unsavedRender.js.map +1 -0
  109. package/dist/client/instantPreview/unsavedRender/useUnsavedRender.d.ts +10 -0
  110. package/dist/client/instantPreview/unsavedRender/useUnsavedRender.js +118 -0
  111. package/dist/client/instantPreview/unsavedRender/useUnsavedRender.js.map +1 -0
  112. package/dist/client/overlay/constants.d.ts +2 -2
  113. package/dist/client/overlay/constants.js +4 -12
  114. package/dist/client/overlay/constants.js.map +1 -1
  115. package/dist/client/overlay/editBadge.d.ts +2 -8
  116. package/dist/client/overlay/editBadge.js +0 -8
  117. package/dist/client/overlay/editBadge.js.map +1 -1
  118. package/dist/client/overlay/editTargets.d.ts +3 -0
  119. package/dist/client/overlay/editTargets.js +98 -0
  120. package/dist/client/overlay/editTargets.js.map +1 -0
  121. package/dist/client/overlay/fieldTracker.d.ts +20 -0
  122. package/dist/client/overlay/fieldTracker.js +194 -0
  123. package/dist/client/overlay/fieldTracker.js.map +1 -0
  124. package/dist/client/overlay/hoverController.d.ts +0 -5
  125. package/dist/client/overlay/hoverController.js +0 -16
  126. package/dist/client/overlay/hoverController.js.map +1 -1
  127. package/dist/client/overlay/markerExtractor.d.ts +4 -3
  128. package/dist/client/overlay/markerExtractor.js +12 -19
  129. package/dist/client/overlay/markerExtractor.js.map +1 -1
  130. package/dist/client/overlay/mutationPipeline.d.ts +2 -2
  131. package/dist/client/overlay/mutationPipeline.js +51 -35
  132. package/dist/client/overlay/mutationPipeline.js.map +1 -1
  133. package/dist/client/overlay/targetRegistry.d.ts +5 -11
  134. package/dist/client/overlay/targetRegistry.js +14 -7
  135. package/dist/client/overlay/targetRegistry.js.map +1 -1
  136. package/dist/client/overlay/targetSelector.js +0 -9
  137. package/dist/client/overlay/targetSelector.js.map +1 -1
  138. package/dist/client/overlayClickHandler.d.ts +1 -1
  139. package/dist/client/overlayClickHandler.js +7 -13
  140. package/dist/client/overlayClickHandler.js.map +1 -1
  141. package/dist/client/overlayContext.d.ts +3 -0
  142. package/dist/client/overlayContext.js +5 -0
  143. package/dist/client/overlayContext.js.map +1 -0
  144. package/dist/client/useIsomorphicLayoutEffect.d.ts +2 -0
  145. package/dist/client/useIsomorphicLayoutEffect.js +4 -0
  146. package/dist/client/useIsomorphicLayoutEffect.js.map +1 -0
  147. package/dist/client/useVisualEditingOverlay.d.ts +2 -2
  148. package/dist/client/useVisualEditingOverlay.js +21 -9
  149. package/dist/client/useVisualEditingOverlay.js.map +1 -1
  150. package/dist/client/visualEditingMode.d.ts +3 -0
  151. package/dist/client/visualEditingMode.js +8 -0
  152. package/dist/client/visualEditingMode.js.map +1 -0
  153. package/dist/client/withVisualEditingPath.d.ts +3 -1
  154. package/dist/client/withVisualEditingPath.js +17 -10
  155. package/dist/client/withVisualEditingPath.js.map +1 -1
  156. package/dist/excludeValues.d.ts +4 -0
  157. package/dist/excludeValues.js +4 -16
  158. package/dist/excludeValues.js.map +1 -1
  159. package/dist/index.d.ts +6 -1
  160. package/dist/index.js +40 -30
  161. package/dist/index.js.map +1 -1
  162. package/dist/readUnsavedRichText.d.ts +13 -0
  163. package/dist/readUnsavedRichText.js +75 -0
  164. package/dist/readUnsavedRichText.js.map +1 -0
  165. package/dist/server/hooks/readHooks.d.ts +14 -0
  166. package/dist/server/hooks/readHooks.js +67 -0
  167. package/dist/server/hooks/readHooks.js.map +1 -0
  168. package/dist/{internal → server/hooks}/stripStegaHook.js +11 -12
  169. package/dist/server/hooks/stripStegaHook.js.map +1 -0
  170. package/dist/server/localeCodesKeyingValues.d.ts +4 -0
  171. package/dist/server/localeCodesKeyingValues.js +15 -0
  172. package/dist/server/localeCodesKeyingValues.js.map +1 -0
  173. package/dist/server/markRead.d.ts +12 -0
  174. package/dist/server/markRead.js +220 -0
  175. package/dist/server/markRead.js.map +1 -0
  176. package/dist/server/markedReads.d.ts +28 -0
  177. package/dist/server/markedReads.js +58 -0
  178. package/dist/server/markedReads.js.map +1 -0
  179. package/dist/server/richText/markTextLeaves.d.ts +1 -0
  180. package/dist/server/richText/markTextLeaves.js +16 -0
  181. package/dist/server/richText/markTextLeaves.js.map +1 -0
  182. package/dist/server/schemaCache.d.ts +29 -0
  183. package/dist/server/schemaCache.js +35 -0
  184. package/dist/server/schemaCache.js.map +1 -0
  185. package/dist/server/unsavedRichText/hooks.d.ts +4 -0
  186. package/dist/server/unsavedRichText/hooks.js +42 -0
  187. package/dist/server/unsavedRichText/hooks.js.map +1 -0
  188. package/dist/server/unsavedRichText/jsonBody.d.ts +1 -0
  189. package/dist/server/unsavedRichText/jsonBody.js +47 -0
  190. package/dist/server/unsavedRichText/jsonBody.js.map +1 -0
  191. package/dist/server/unsavedRichText/latestReads.d.ts +17 -0
  192. package/dist/server/unsavedRichText/latestReads.js +70 -0
  193. package/dist/server/unsavedRichText/latestReads.js.map +1 -0
  194. package/dist/server/unsavedRichText/placeUnsavedState.d.ts +8 -0
  195. package/dist/server/unsavedRichText/placeUnsavedState.js +12 -0
  196. package/dist/server/unsavedRichText/placeUnsavedState.js.map +1 -0
  197. package/dist/server/unsavedRichText/postedEditorState.d.ts +2 -0
  198. package/dist/server/unsavedRichText/postedEditorState.js +45 -0
  199. package/dist/server/unsavedRichText/postedEditorState.js.map +1 -0
  200. package/dist/server/unsavedRichText/postedRequest.d.ts +36 -0
  201. package/dist/server/unsavedRichText/postedRequest.js +96 -0
  202. package/dist/server/unsavedRichText/postedRequest.js.map +1 -0
  203. package/dist/server/unsavedRichText/readAsUser.d.ts +6 -0
  204. package/dist/server/unsavedRichText/readAsUser.js +60 -0
  205. package/dist/server/unsavedRichText/readAsUser.js.map +1 -0
  206. package/dist/server/unsavedRichText/readContext.d.ts +10 -0
  207. package/dist/server/unsavedRichText/readContext.js +9 -0
  208. package/dist/server/unsavedRichText/readContext.js.map +1 -0
  209. package/dist/server/unsavedRichText/relatedIds.d.ts +2 -0
  210. package/dist/server/unsavedRichText/relatedIds.js +30 -0
  211. package/dist/server/unsavedRichText/relatedIds.js.map +1 -0
  212. package/dist/server/unsavedRichText/savedNodeFields.d.ts +2 -0
  213. package/dist/server/unsavedRichText/savedNodeFields.js +47 -0
  214. package/dist/server/unsavedRichText/savedNodeFields.js.map +1 -0
  215. package/dist/server/withInstantPreview.d.ts +9 -0
  216. package/dist/server/withInstantPreview.js +41 -0
  217. package/dist/server/withInstantPreview.js.map +1 -0
  218. package/dist/{client → shared}/buildAdminEditUrl.d.ts +2 -2
  219. package/dist/{client → shared}/buildAdminEditUrl.js +2 -1
  220. package/dist/shared/buildAdminEditUrl.js.map +1 -0
  221. package/dist/shared/editableSchema/editableSchema.d.ts +26 -0
  222. package/dist/shared/editableSchema/editableSchema.js +165 -0
  223. package/dist/shared/editableSchema/editableSchema.js.map +1 -0
  224. package/dist/shared/editableSchema/schemaOfFields.d.ts +16 -0
  225. package/dist/shared/editableSchema/schemaOfFields.js +106 -0
  226. package/dist/shared/editableSchema/schemaOfFields.js.map +1 -0
  227. package/dist/shared/fieldKey.d.ts +23 -0
  228. package/dist/shared/fieldKey.js +44 -0
  229. package/dist/shared/fieldKey.js.map +1 -0
  230. package/dist/shared/messageSource.d.ts +1 -0
  231. package/dist/shared/messageSource.js +3 -0
  232. package/dist/shared/messageSource.js.map +1 -0
  233. package/dist/shared/packageName.d.ts +1 -0
  234. package/dist/shared/packageName.js +3 -0
  235. package/dist/shared/packageName.js.map +1 -0
  236. package/dist/shared/plainObject.d.ts +2 -0
  237. package/dist/shared/plainObject.js +3 -0
  238. package/dist/shared/plainObject.js.map +1 -0
  239. package/dist/shared/protocol.d.ts +80 -0
  240. package/dist/shared/protocol.js +26 -0
  241. package/dist/shared/protocol.js.map +1 -0
  242. package/dist/shared/richText/blockNodes.d.ts +3 -0
  243. package/dist/shared/richText/blockNodes.js +35 -0
  244. package/dist/shared/richText/blockNodes.js.map +1 -0
  245. package/dist/shared/richText/editorNodes.d.ts +6 -0
  246. package/dist/shared/richText/editorNodes.js +25 -0
  247. package/dist/shared/richText/editorNodes.js.map +1 -0
  248. package/dist/shared/richText/nodeKey.d.ts +13 -0
  249. package/dist/shared/richText/nodeKey.js +22 -0
  250. package/dist/shared/richText/nodeKey.js.map +1 -0
  251. package/dist/shared/richText/nodeTypes.d.ts +5 -0
  252. package/dist/shared/richText/nodeTypes.js +20 -0
  253. package/dist/shared/richText/nodeTypes.js.map +1 -0
  254. package/dist/shared/richText/shapeOf.d.ts +1 -0
  255. package/dist/shared/richText/shapeOf.js +24 -0
  256. package/dist/shared/richText/shapeOf.js.map +1 -0
  257. package/dist/shared/richText/textLeaves.d.ts +14 -0
  258. package/dist/shared/richText/textLeaves.js +32 -0
  259. package/dist/shared/richText/textLeaves.js.map +1 -0
  260. package/dist/shared/rowWithId.d.ts +2 -0
  261. package/dist/shared/rowWithId.js +7 -0
  262. package/dist/shared/rowWithId.js.map +1 -0
  263. package/dist/{internal → shared}/shared.d.ts +5 -13
  264. package/dist/shared/shared.js +38 -0
  265. package/dist/shared/shared.js.map +1 -0
  266. package/dist/shared/stegaText.d.ts +2 -0
  267. package/dist/shared/stegaText.js +6 -0
  268. package/dist/shared/stegaText.js.map +1 -0
  269. package/dist/shared/veDocument.d.ts +15 -0
  270. package/dist/shared/veDocument.js +31 -0
  271. package/dist/shared/veDocument.js.map +1 -0
  272. package/dist/stripMarkers.d.ts +1 -0
  273. package/dist/stripMarkers.js +19 -0
  274. package/dist/stripMarkers.js.map +1 -0
  275. package/package.json +8 -9
  276. package/dist/client/buildAdminEditUrl.js.map +0 -1
  277. package/dist/client/overlay/createOverlay.d.ts +0 -11
  278. package/dist/client/overlay/createOverlay.js +0 -80
  279. package/dist/client/overlay/createOverlay.js.map +0 -1
  280. package/dist/client/overlay/stegaBookkeeper.d.ts +0 -11
  281. package/dist/client/overlay/stegaBookkeeper.js +0 -36
  282. package/dist/client/overlay/stegaBookkeeper.js.map +0 -1
  283. package/dist/client/overlay/stegaScanner.d.ts +0 -11
  284. package/dist/client/overlay/stegaScanner.js +0 -54
  285. package/dist/client/overlay/stegaScanner.js.map +0 -1
  286. package/dist/constants.d.ts +0 -16
  287. package/dist/constants.js +0 -15
  288. package/dist/constants.js.map +0 -1
  289. package/dist/internal/afterOperationHook.d.ts +0 -12
  290. package/dist/internal/afterOperationHook.js +0 -28
  291. package/dist/internal/afterOperationHook.js.map +0 -1
  292. package/dist/internal/afterReadHook.d.ts +0 -3
  293. package/dist/internal/afterReadHook.js +0 -16
  294. package/dist/internal/afterReadHook.js.map +0 -1
  295. package/dist/internal/beforeOperationHook.d.ts +0 -4
  296. package/dist/internal/beforeOperationHook.js +0 -16
  297. package/dist/internal/beforeOperationHook.js.map +0 -1
  298. package/dist/internal/buildFieldSchema.d.ts +0 -3
  299. package/dist/internal/buildFieldSchema.js +0 -67
  300. package/dist/internal/buildFieldSchema.js.map +0 -1
  301. package/dist/internal/encodeStega.d.ts +0 -7
  302. package/dist/internal/encodeStega.js +0 -171
  303. package/dist/internal/encodeStega.js.map +0 -1
  304. package/dist/internal/enrichWithPathMeta.d.ts +0 -4
  305. package/dist/internal/enrichWithPathMeta.js +0 -76
  306. package/dist/internal/enrichWithPathMeta.js.map +0 -1
  307. package/dist/internal/filterEditableFields.d.ts +0 -2
  308. package/dist/internal/filterEditableFields.js +0 -88
  309. package/dist/internal/filterEditableFields.js.map +0 -1
  310. package/dist/internal/gate.d.ts +0 -3
  311. package/dist/internal/gate.js +0 -16
  312. package/dist/internal/gate.js.map +0 -1
  313. package/dist/internal/globalAfterReadHook.d.ts +0 -12
  314. package/dist/internal/globalAfterReadHook.js +0 -19
  315. package/dist/internal/globalAfterReadHook.js.map +0 -1
  316. package/dist/internal/markTerminalUploads.d.ts +0 -13
  317. package/dist/internal/markTerminalUploads.js +0 -79
  318. package/dist/internal/markTerminalUploads.js.map +0 -1
  319. package/dist/internal/schemaCache.d.ts +0 -10
  320. package/dist/internal/schemaCache.js +0 -29
  321. package/dist/internal/schemaCache.js.map +0 -1
  322. package/dist/internal/shared.js +0 -55
  323. package/dist/internal/shared.js.map +0 -1
  324. package/dist/internal/stripStegaHook.js.map +0 -1
  325. /package/dist/{internal → server/hooks}/stripStegaHook.d.ts +0 -0
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @focus-reactive/payload-plugin-visual-editing
2
2
 
3
- Visual editing plugin for Payload CMS. Embeds field-path markers into draft content via Vercel stega, then renders in-place edit overlays on the frontend that deep-link back into Payload admin via a postMessage bridge.
3
+ Click-to-edit for Payload CMS. On draft reads the plugin writes an invisible marker into every text value. The frontend overlay finds those markers in the rendered page, outlines the elements and adds an **Edit** badge. A click focuses the field in the Payload admin. With the optional instant preview, text typed in the admin form appears in the Live Preview before it is saved.
4
4
 
5
5
  ## Installation
6
6
 
@@ -8,45 +8,29 @@ Visual editing plugin for Payload CMS. Embeds field-path markers into draft cont
8
8
  bun add @focus-reactive/payload-plugin-visual-editing
9
9
  ```
10
10
 
11
- Peer dependencies: `payload ^3.79`, `@payloadcms/ui ^3.79`, `react ^18 || ^19`. `next` is optional.
12
-
13
- ## Compatibility
14
-
15
- Requires Payload **3.79 or newer** (within the 3.x line), supplied by the host app. `@payloadcms/ui`, `payload`, and `react` are peer dependencies, so the plugin shares the host's single copy rather than bundling its own. Built and tested against Payload `3.84.1`.
11
+ Peer dependencies: `payload ^3.79`, `@payloadcms/ui ^3.79`, `react ^19` and `react-dom ^19`, the React that Payload 3 needs. The plugin does not import `next`; the setup below uses Next.js because the Payload admin runs on it. It is built and tested against Payload `3.90.1`.
16
12
 
17
13
  ## Setup
18
14
 
19
- The plugin has two halves: a **server half** (Payload hooks that embed stega path-markers into draft reads, register the admin bridge, and strip stega back out on write) and a **client half** (the frontend overlay that turns those markers into click-to-edit badges). Enrichment only happens for **draft** content served to the **frontend** — never the admin form or published reads — so the flow below wires Next.js draft mode end to end.
15
+ The plugin has a server half (Payload hooks that mark draft reads and strip markers from writes, plus an admin component) and a client half (the overlay on your frontend). Markers are written only into **draft** reads made with the **Local API** outside the admin, so the steps below wire Next.js draft mode end to end. `apps/cms` in this repository uses the plugin with `enrichment: 'explicit'`, instant preview and `LiveRichText`, and is the working reference.
20
16
 
21
- Steps 1–2 set up the server, steps 3–5 connect draft preview, steps 6–8 finish the client. The `apps/dev` app in this repo is a complete working reference.
22
-
23
- ### 1. Register the plugin — `payload.config.ts`
17
+ ### 1. Register the plugin
24
18
 
25
19
  ```ts
20
+ // payload.config.ts
26
21
  import { buildConfig } from 'payload'
27
22
  import { visualEditingPlugin } from '@focus-reactive/payload-plugin-visual-editing'
28
23
 
29
24
  export default buildConfig({
30
25
  // ...
31
- plugins: [
32
- visualEditingPlugin({
33
- // all optional:
34
- skipCollections: ['media'], // collection slugs to exclude from enrichment
35
- skipGlobals: [], // global slugs to exclude
36
- excludeFieldNames: ['tenant'], // extra field names to strip (merged with '_status', 'folder', 'slug')
37
- adminBasePath: '/admin', // Payload admin base path (default '/admin')
38
- enrichment: 'explicit', // which reads get stega (default 'auto') — see "Enrichment modes"
39
- }),
40
- ],
26
+ plugins: [visualEditingPlugin()],
41
27
  })
42
28
  ```
43
29
 
44
- This adds enrichment hooks to every non-skipped collection and global, registers the `VisualEditingBridgeProvider` admin component, and adds a `beforeChange` hook that strips intact stega markers from writes.
30
+ See [Options](#options) for what you can pass.
45
31
 
46
32
  ### 2. Enable drafts on editable collections
47
33
 
48
- The plugin only enriches **draft** reads, so each collection you want to edit visually needs Payload drafts turned on:
49
-
50
34
  ```ts
51
35
  export const Pages: CollectionConfig = {
52
36
  slug: 'pages',
@@ -55,9 +39,7 @@ export const Pages: CollectionConfig = {
55
39
  }
56
40
  ```
57
41
 
58
- ### 3. Add draft-mode preview routes
59
-
60
- Next.js draft mode is what flips a frontend read into a draft read. Add a route that enables it (and one that exits):
42
+ ### 3. Add draft-mode routes
61
43
 
62
44
  ```ts
63
45
  // app/(frontend)/next/preview/route.ts
@@ -66,7 +48,6 @@ import { redirect } from 'next/navigation'
66
48
 
67
49
  export async function GET(req: Request) {
68
50
  const path = new URL(req.url).searchParams.get('path')
69
- // same-origin relative paths only — block open redirects
70
51
  if (!path || !path.startsWith('/') || path.startsWith('//')) {
71
52
  return new Response('Invalid path', { status: 400 })
72
53
  }
@@ -89,8 +70,6 @@ export async function GET(req: Request) {
89
70
 
90
71
  ### 4. Point Live Preview at the preview route
91
72
 
92
- So the CMS side-by-side preview opens the frontend already in draft mode, set the collection's `admin.livePreview.url` to go through `/next/preview`:
93
-
94
73
  ```ts
95
74
  export const Pages: CollectionConfig = {
96
75
  slug: 'pages',
@@ -107,9 +86,9 @@ export const Pages: CollectionConfig = {
107
86
  }
108
87
  ```
109
88
 
110
- ### 5. Fetch drafts in the frontend page
89
+ The example assumes two things of your project: that `NEXT_PUBLIC_SERVER_URL` holds the origin of the frontend, and that a document has a `slug` field from which its route is built. Build the URL from whatever your routes use.
111
90
 
112
- Read the document with `draft` tied to draft mode — stega is only embedded on draft reads:
91
+ ### 5. Read drafts in the frontend page
113
92
 
114
93
  ```tsx
115
94
  // app/(frontend)/[slug]/page.tsx
@@ -125,19 +104,17 @@ export default async function Page({ params }: { params: Promise<{ slug: string
125
104
  const { docs } = await payload.find({
126
105
  collection: 'pages',
127
106
  draft,
128
- depth: 1, // ≥ 1 so uploads/relationships populate (see "Editable richText and upload fields")
107
+ depth: 1,
129
108
  where: { slug: { equals: slug } },
130
109
  })
131
110
  // render docs[0]
132
111
  }
133
112
  ```
134
113
 
135
- With `enrichment: 'explicit'`, also pass `context: { visualEditing: draft }` — see [Enrichment modes](#enrichment-modes).
114
+ A global is read the same way, `payload.findGlobal({ slug: 'header', draft })`, and is marked at every `depth`. With `enrichment: 'explicit'`, also pass `context: { visualEditing: draft }`, see [Enrichment modes](#enrichment-modes).
136
115
 
137
116
  ### 6. Wrap the frontend layout
138
117
 
139
- Mount the provider (gated on draft mode), the toggle, and the overlay:
140
-
141
118
  ```tsx
142
119
  // app/(frontend)/layout.tsx
143
120
  import { VisualEditing } from '@focus-reactive/payload-plugin-visual-editing/client'
@@ -159,81 +136,321 @@ export default async function Layout({ children }: { children: React.ReactNode }
159
136
  }
160
137
  ```
161
138
 
162
- - `available` enables the overlay only when draft mode is on; a user-level toggle (stored in `localStorage`) then gates whether badges actually render.
163
- - `framedOnly` (optional) restricts the overlay to the CMS preview iframe — omit it to also allow editing when the frontend is opened in a standalone tab.
164
- - `VisualEditing.Toggle` renders the floating off/hover/always control; `VisualEditing.Overlay` scans the DOM for markers and draws the edit badges.
139
+ - `VisualEditing.Toggle` is the floating Off / Hover / Always control. The chosen mode is kept in `localStorage`.
140
+ - `VisualEditing.Overlay` scans its children for markers. Content outside it is not touched.
165
141
 
166
- ### 7. Mark richText and upload fields
142
+ ### 7. Mark rich text, uploads and relationships
167
143
 
168
- `text` / `textarea` / `email` fields are picked up automatically. `richText` and `upload` values opt out of inline stega and need one line in your renderer — see [Editable richText and upload fields](#editable-richtext-and-upload-fields).
144
+ Text fields work on their own. Rich text, uploads and related documents need one spread in your renderer, see [Rich text, uploads and relationships](#rich-text-uploads-and-relationships).
169
145
 
170
146
  ### 8. Regenerate the admin import map
171
147
 
172
- The bridge is registered as an admin component, so refresh Payload's import map (re-run after config changes):
173
-
174
148
  ```bash
175
149
  bunx payload generate:importmap
176
150
  ```
177
151
 
178
152
  ### Using it
179
153
 
180
- Open a document in the admin, open the **Live Preview** side panel (it loads the frontend in draft mode), then flip the floating toggle to **Always** or **Hover**. Editable text shows an outline and an **Edit** badge; clicking it focuses that field in the admin form. To leave draft mode when viewing the frontend directly, hit `/next/exit-preview`.
154
+ Open a document in the admin, open **Live Preview** and set the toggle to **Always** or **Hover**. Editable text gets an outline and an **Edit** badge. A click on the badge or anywhere on the outlined element focuses the field in the admin form. A click with a modifier key and a text selection keep the page's own behaviour; a double click does nothing. A click on text of another document opens that document in a new admin tab.
181
155
 
182
- ## Editable richText and upload fields
156
+ To leave draft mode in a normal browser tab, open `/next/exit-preview`.
183
157
 
184
- Most fields (`text`, `textarea`, `email`, …) are edit-overlayable automatically — the plugin weaves zero-width stega characters into their rendered text and the client overlay picks them up. Two kinds of values opt out of stega and need one line in your renderer:
158
+ ## What gets a marker
185
159
 
186
- - **`richText`** — treated as a leaf-renderer black box; no stega is embedded into its rendered paragraphs.
187
- - **`upload:<slug>`** — its populated value is a different document whose `_meta` is preserved for wrapper-attr consumption instead of being re-encoded.
160
+ - Fields of type `text`, `textarea` and `email`, at any depth: in groups, tabs, rows, collapsibles, array rows and blocks (declared inline or through `blockReferences`).
161
+ - The name of a block (`blockName`), unless the block sets `admin.disableBlockName`. A click on a rendered block name focuses the name input in the block header.
162
+ - Not: empty values, and values that match `excludeValues` (by default URLs, slugs like `hello-world`, `#fragments` and ISO dates).
163
+ - Not: fields named `slug`, `folder`, `_status`, `apiKey` or anything in `excludeFieldNames`.
164
+ - Not: fields the editor cannot change in the admin, that is `hidden: true`, `admin.hidden`, `admin.readOnly` or `admin.disabled`, and everything inside a group, array or blocks field that has one of them.
165
+ - Not: `text` fields with `hasMany`, numbers, selects, dates and other non-text fields.
166
+ - With `instantPreview` only: every text node of a Lexical rich text field, see [Markers in rich text](#markers-in-rich-text).
188
167
 
189
- For both, spread `withVisualEditingPath(value)` onto the element you want to receive the Edit badge.
168
+ A populated document (a relationship or an upload read with `depth ≥ 1`) is marked as itself: its text carries its own collection, id and paths, wherever it appears. A populated document of a collection listed in `skipCollections` gets no markers.
190
169
 
191
- ```tsx
192
- import { withVisualEditingPath } from '@focus-reactive/payload-plugin-visual-editing/client'
193
- ```
170
+ If you render a marked value into an attribute, the overlay removes the marker from `alt`, `title`, `aria-label` and `placeholder`. In any other attribute (an anchor `id`, a `data-*` attribute) it stays, so exclude such a field with `excludeFieldNames`.
171
+
172
+ ## Rich text, uploads and relationships
194
173
 
195
- ### RichText
174
+ The text of a rich text field belongs to its renderer, and an image has no text node to carry a marker. For these values the plugin leaves a `_meta` object on the value that says which field of which document holds it. Spread `withVisualEditingPath(value)` on the element that should become the edit target:
196
175
 
197
176
  ```tsx
177
+ import { withVisualEditingPath } from '@focus-reactive/payload-plugin-visual-editing/client'
198
178
  import { RichText } from '@payloadcms/richtext-lexical/react'
199
179
 
200
180
  <div {...withVisualEditingPath(page.content)}>
201
181
  <RichText data={page.content} />
202
182
  </div>
183
+
184
+ <img src={page.image.url} alt={page.image.alt} {...withVisualEditingPath(page.image)} />
185
+
186
+ <article {...withVisualEditingPath(page.author)}>
187
+ <h3>{page.author.name}</h3>
188
+ </article>
203
189
  ```
204
190
 
205
- ### Upload — single relationTo
191
+ A click on such an element focuses the rich text, upload or relationship field **in the document that holds it** (`image` of the page), not the media or author document.
192
+
193
+ | Field | Where the `_meta` is |
194
+ |---|---|
195
+ | rich text | `page.content` |
196
+ | upload or relationship | `page.image`, the populated document |
197
+ | `hasMany` | every populated document: `page.gallery[0]`, `page.gallery[1]`. Each addresses the field `gallery` |
198
+ | several `relationTo` | `page.image` (the `{ relationTo, value }` object) and `page.image.value` |
199
+
200
+ Uploads and relationships need `depth ≥ 1`. At `depth: 0` the value of a field with one `relationTo` is an id and has no `_meta`. `withVisualEditingPath` returns `{}` for a value without `_meta`, so the spread is safe on published pages.
201
+
202
+ Text inside the populated document, such as `page.image.alt` or `page.author.name`, is a text field of that document. If its collection is not skipped it has its own marker, and a click on it opens the media or author document.
203
+
204
+ ## Instant preview
205
+
206
+ Without it the Live Preview shows an edit after Payload has saved it and the frontend has rendered again. With it, text typed in the admin form appears in the preview on the same keystroke. The save and the re-render still happen and stay the source of truth.
207
+
208
+ Turn it on in both halves and regenerate the import map:
209
+
210
+ ```ts
211
+ // payload.config.ts
212
+ visualEditingPlugin({ instantPreview: true })
213
+ ```
206
214
 
207
215
  ```tsx
208
- <img
209
- src={page.image.url}
210
- alt={page.image.alt}
211
- {...withVisualEditingPath(page.image)}
212
- />
216
+ // app/(frontend)/layout.tsx
217
+ <VisualEditing.Provider available={isEnabled} instantPreview adminBasePath="/admin">
213
218
  ```
214
219
 
215
- ### Upload — polymorphic (`relationTo: ['media', 'videos']`)
220
+ ### Requirements
221
+
222
+ - Live Preview is configured for the collection or global: `admin.livePreview` on it, or its slug in the root `admin.livePreview.collections` / `globals`.
223
+ - The frontend refreshes itself after a save, for example with `RefreshRouteOnSave` from `@payloadcms/live-preview-react`, see below.
224
+ - The admin posts to the origin of the Live Preview URL. The preview posts to `adminOrigin` on `VisualEditing.Provider`, its own origin by default.
225
+ - On a localized site, pass the locale of the page: `<VisualEditing.Overlay locale={locale}>`. The admin tags its messages with the locale it is editing, and the overlay can only ignore another locale when it knows its own.
226
+ - The admin bundle and the frontend overlay come from the same version of the plugin. An overlay of 1.1.1 or earlier leaves the markers of rich text in the page.
227
+ - Rich text is rendered inside an element that spreads `withVisualEditingPath(value)`, see [Rich text, uploads and relationships](#rich-text-uploads-and-relationships). Without that wrapper its text is not live.
216
228
 
217
- Spread on `value`, not the wrapper:
229
+ A refresh after every save, with Payload's own component:
230
+
231
+ ```bash
232
+ bun add @payloadcms/live-preview-react
233
+ ```
218
234
 
219
235
  ```tsx
220
- <img
221
- src={page.image.value.url}
222
- alt={page.image.value.alt}
223
- {...withVisualEditingPath(page.image.value)}
224
- />
236
+ // components/RefreshOnSave.tsx
237
+ 'use client'
238
+
239
+ import { RefreshRouteOnSave } from '@payloadcms/live-preview-react'
240
+ import { useRouter } from 'next/navigation'
241
+
242
+ export const RefreshOnSave = () => {
243
+ const router = useRouter()
244
+ const adminOrigin = typeof window === 'undefined' ? '' : window.location.origin
245
+ return <RefreshRouteOnSave refresh={() => router.refresh()} serverURL={adminOrigin} />
246
+ }
225
247
  ```
226
248
 
227
- Clicking the Edit badge on an upload opens the media document's admin page (not a field on the host doc).
249
+ ```tsx
250
+ // app/(frontend)/layout.tsx
251
+ {isEnabled && <RefreshOnSave />}
252
+ ```
253
+
254
+ `RefreshRouteOnSave` refreshes only on a message whose origin equals `serverURL` exactly, so with another value the page never refreshes and nothing reports it. The snippet is for an admin served from the same origin as the page, as in a Next.js app that hosts Payload; the component renders nothing, and its listener starts in the browser, where the origin is known. With the admin on another origin, pass that origin, without a trailing slash.
255
+
256
+ ### What updates instantly
257
+
258
+ - `text`, `textarea` and `email` fields that have a marker on the page, the block name included.
259
+ - Text typed, deleted or replaced inside existing text of a Lexical rich text field: in paragraphs, headings, list items, quotes, links and formatted text.
260
+ - With [`LiveRichText`](#unsaved-rich-text-structure): every edit that changes the structure of a Lexical rich text field, such as a new paragraph, a list, a heading, bold on a part of a text, a link, an upload or a new block, and the text typed after it.
261
+ - Only where the page renders the stored value unchanged.
262
+ - In every toggle position, also **Off**. The toggle controls outlines, badges and click-to-edit only.
263
+
264
+ ### What waits for the save
265
+
266
+ - Every other field type: numbers, uploads, relationships, selects, checkboxes, dates, `code`, `json`, `text` with `hasMany`.
267
+ - In rich text that is not wrapped in [`LiveRichText`](#unsaved-rich-text-structure), an edit that changes the structure: a paragraph, list, link, block or upload added or removed, or formatting applied to a part of a text, which splits it. From that edit on the preview keeps the structure of the last save, with the text it showed when the structure changed, until the autosave has landed and the page has rendered the new structure; then its text is live again. Autosave is debounced, so that happens after a pause in typing. An edit that returns to the saved structure is live again at once.
268
+ - Rich text whose stored tree Lexical normalises on the first edit, such as imported or seeded content with neighbouring texts of the same format, which Lexical merges on the first keystroke. That is an edit of the structure; the field is live after its first save from the editor.
269
+ - In rich text, formatting that does not change the structure. Bold on a whole text, another heading level, list type or link URL shows after the save, or with the next structural edit of a field in `LiveRichText`; the text keeps updating meanwhile.
270
+ - Text in the fields of a block inside rich text, Slate rich text, and a rich text field whose name contains `#`.
271
+ - Rows and blocks that are added, removed, duplicated or moved. Text typed into a new row appears with the save that creates the row. A moved row keeps its text; the order changes with the next refresh.
272
+ - A field that was empty in the last render. An empty value has no marker, so text typed into it appears with the next save.
273
+ - Values the page transforms: uppercased in JavaScript, truncated, formatted, parsed into markup. The overlay rewrites a text node only while it shows a value the field recently had.
274
+ - Localized fields, and all rich text, on a page that reads the document with `locale: 'all'`.
275
+
276
+ ### What is sent to the preview
277
+
278
+ The admin posts field values to the preview window with `postMessage`. Every script on the preview page can read them. A value is sent only when all of these hold:
279
+
280
+ 1. The field belongs to the document that is open in the admin form.
281
+ 2. The preview page has rendered that field, with a marker, at least once since it loaded. The page tells the admin which fields those are. From then on the admin sends the field's value on every change until the preview window loads another page, also while the field is not on screen.
282
+ 3. The field can carry a marker under the rules in [What gets a marker](#what-gets-a-marker), read from the collection or global config. Values that exist only in the form, such as a typed `password`, are never sent.
283
+ 4. The collection has no `auth`. Fields of auth collections are marked for click-to-edit but never sent.
284
+
285
+ Rule 3 is the boundary you control. The list in rule 2 comes from the preview page, so a script running there could ask for any field that passes rule 3. Keep a field away from the preview with `excludeFieldNames`, `admin.readOnly`, `admin.hidden` or `hidden`.
286
+
287
+ For a rich text field that passes these rules the admin sends the saved and the current text of single text nodes the page announced. It sends the editor state of the field only to a page that renders it in [`LiveRichText`](#unsaved-rich-text-structure), and only when the structure changes. While the editor holds another structure than the saved one it sends, in place of the current text, the last text those nodes had under the saved structure while this preview page was listening, or else their saved text.
288
+
289
+ The editor state of a rich text field holds its text, the ids of uploads, relationships and linked documents, and the fields of link and upload nodes. The admin posts it when the structure of the field changes, and only for a field the page announced as rendered in `LiveRichText`. That announcement also comes from the page, so the boundary is again rule 3 for the rich text field itself. Blocks in the state are posted with their id and type and without the values of their fields. The page hands the state to your Server Action, which answers only to a signed-in user who may read the document.
290
+
291
+ A page states the locale of its overlay when it reports its fields. The admin sends nothing to a page that states another locale than the one the form is in. A page whose overlay has no `locale` states none and is answered in every locale.
292
+
293
+ `excludeValues` is not applied in the admin. A value that matches it has no marker on the page and is not sent, unless the page rendered the same field with a marker earlier in this page load.
228
294
 
229
- **Uploads require `depth ≥ 1`** so Payload returns the populated media document alongside its `_meta`. At `depth: 0` the value is a bare id string and no overlay is drawn.
295
+ When the Live Preview iframe loads another page, the admin stops sending and waits for that page to report its fields. A page without the overlay is sent nothing. When the admin switches to another locale it stops sending as well, until the preview has loaded a page again; text typed in one locale is never sent to a page that was loaded for another, provided the overlay of that page was given its `locale`.
296
+
297
+ ### Unsaved rich text structure
298
+
299
+ Typing inside existing text needs nothing but the wrapper. A new paragraph, a list or a bold word changes the structure of the value, and the page cannot build that markup from text alone: it comes from your renderer. `LiveRichText` asks your app to render the unsaved editor state and shows the result until the saved render has the same structure. The reference setup uses a Server Action of the Next.js App Router.
300
+
301
+ Three pieces, all in your app. The component that renders rich text:
302
+
303
+ ```tsx
304
+ // components/RichText/Body.tsx
305
+ import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
306
+
307
+ import { withVisualEditingPath } from '@focus-reactive/payload-plugin-visual-editing/client'
308
+ import { RichText } from '@payloadcms/richtext-lexical/react'
309
+
310
+ export const RichTextBody = ({ content }: { content: SerializedEditorState }) => (
311
+ <div {...withVisualEditingPath(content)}>
312
+ <RichText data={content} />
313
+ </div>
314
+ )
315
+ ```
316
+
317
+ A Server Action that renders the unsaved state with that same component:
318
+
319
+ ```tsx
320
+ // components/RichText/renderUnsavedRichText.tsx
321
+ 'use server'
322
+
323
+ import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
324
+
325
+ import { readUnsavedRichText } from '@focus-reactive/payload-plugin-visual-editing'
326
+ import config from '@payload-config'
327
+ import { draftMode, headers } from 'next/headers'
328
+ import { getPayload } from 'payload'
329
+
330
+ import { RichTextBody } from './Body'
331
+
332
+ export async function renderUnsavedRichText(request: unknown) {
333
+ const { isEnabled } = await draftMode()
334
+ if (!isEnabled) return null
335
+
336
+ const content = await readUnsavedRichText<SerializedEditorState>({
337
+ headers: await headers(),
338
+ payload: await getPayload({ config }),
339
+ request,
340
+ })
341
+ return content && <RichTextBody content={content} />
342
+ }
343
+ ```
344
+
345
+ And the component your pages use:
346
+
347
+ ```tsx
348
+ // components/RichText/index.tsx
349
+ import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
350
+
351
+ import { LiveRichText, liveRichTextOf } from '@focus-reactive/payload-plugin-visual-editing/client'
352
+
353
+ import { RichTextBody } from './Body'
354
+ import { renderUnsavedRichText } from './renderUnsavedRichText'
355
+
356
+ export const RichText = ({ content }: { content: SerializedEditorState }) => {
357
+ const body = <RichTextBody content={content} />
358
+ const liveRichText = liveRichTextOf(content)
359
+ if (!liveRichText) return body
360
+
361
+ return (
362
+ <LiveRichText {...liveRichText} action={renderUnsavedRichText}>
363
+ {body}
364
+ </LiveRichText>
365
+ )
366
+ }
367
+ ```
368
+
369
+ - `liveRichTextOf(content)` returns the identity of the field and the structure of the saved value, about 150 bytes, or `null` for a value that is not a marked rich text: every published read, a read with `locale: 'all'`, a row without an `id`. A published page therefore gets no client component and no extra payload, and the value itself is never passed to the client.
370
+ - The action must render through the component the page uses, with the same wrapper element. React then swaps the two renders in place, and the text typed after the structural edit keeps updating through the markers.
371
+ - Props the renderer needs (a variant, a class name) can be bound: `action={renderUnsavedRichText.bind(null, { variant })}`. They arrive as the first argument of the action.
372
+ - `LiveRichText` renders no element of its own. Outside draft mode or with `instantPreview` off it only renders its children.
373
+ - Put it inside `VisualEditing.Overlay`. The overlay passes its `locale` on, and `LiveRichText` ignores the admin while it edits another locale.
374
+
375
+ `LiveRichText` makes one call at a time and only the latest state waits. When a call fails, takes longer than ten seconds or returns `null`, and when the returned elements throw while rendering, the preview shows the saved render, as it does without `LiveRichText`, and asks again a few times per structure, for about half a minute. A call that hangs is never joined by a second one.
376
+
377
+ **A Server Action shares a queue with `router.refresh()`.** While a render call is out, the refresh that brings the saved render waits for it. `readUnsavedRichText` answers `null` after `timeLimitMs` (three seconds by default), which bounds that wait per call within one server process. A slow server delays the saved render by up to one call; it never shows a wrong frame.
378
+
379
+ **Another transport.** Pass `render` in place of `action` to make the call yourself: `render(request, signal)` returns a promise of React nodes and gets an `AbortSignal` that `LiveRichText` aborts when it stops waiting. A route handler can answer a `fetch` with that signal with `readUnsavedRichText({ payload, request })` as JSON; that call stays off the router's queue and can be cancelled, but the page then renders the marked editor state in the browser, so your renderer and everything it renders for uploads, links and blocks must work as Client Components.
380
+
381
+ `readUnsavedRichText` is the only safe way to turn the posted state into something to render. Hand it the argument of the action untouched. It guarantees:
382
+
383
+ - **Nothing from the request is trusted.** It accepts a document of the config, a key that names a rich text field the plugin marks, a locale of the project and a Lexical editor state of at most `maxStateLength` characters of JSON (`DEFAULT_MAX_UNSAVED_STATE_LENGTH`, one million). The fields of blocks, uploads and links come from the saved document by node id, and related documents are reduced to their ids.
384
+ - **It reads as the signed-in user.** The user comes from the request headers through `payload.auth`. The argument of an action is checked before anyone is signed in; the body of a `Request` is read only for a signed-in user, with a size limit. The document is read as a draft, in the locale of the request, with `overrideAccess: false`, and Payload populates uploads, relationships and links with that user's access. Nothing is written.
385
+ - **The answer is the value of the field with the markers of a draft read, or `null`.** `null` for a malformed argument, no user, a user who may not read the document or field, an auth collection, a value whose structure is not the posted one, a request a newer one for the same field replaced, and an answer that took longer than `timeLimitMs`. It does not throw: a read that throws, for example in a hook of your project that cannot handle the unsaved state, goes to `payload.logger.error` and answers `null`.
386
+
387
+ Two cases never reach it: Next.js answers 500 itself for an action body over its limit (1 MB by default, `serverActions.bodySizeLimit`) and for a body it cannot decode.
388
+
389
+ | `readUnsavedRichText` argument | Purpose |
390
+ |---|---|
391
+ | `payload` | The Payload instance. |
392
+ | `request` | The argument `LiveRichText` passed to the action, or the `Request` a route handler received. Untrusted input: hand it over as it is. |
393
+ | `headers` | The headers of the request, with the argument of an action. The user is read from them. A `Request` brings its own. |
394
+ | `depth` | The `depth` your page reads the document with, so populated documents have the same shape: a number, or a function of the validated field (`{ collectionSlug, kind, docId?, key }`). Payload's default when omitted. |
395
+ | `maxStateLength` | Longest accepted editor state, in characters of JSON. |
396
+ | `timeLimitMs` | How long reading the body of a `Request`, signing in and reading may take before the answer is `null`. `DEFAULT_UNSAVED_READ_TIME_LIMIT_MS`, 3000. |
397
+
398
+ During that read your own hooks and access functions see the unsaved state as if it were stored: collection and field `afterRead` hooks, anything that caches by document id inside the read. `isUnsavedRichTextRead(req)`, exported from the main entry, tells such code that the read is one of these.
399
+
400
+ What this costs: one Server Action call per structural edit, never one per keystroke. Each call posts the editor state of that field and reads the document once. The draft mode check stays in your action because it is specific to Next.js; `readUnsavedRichText` does not depend on Next.
401
+
402
+ ### Markers in rich text
403
+
404
+ With `instantPreview` on, a draft read puts a marker of roughly 130 to 150 zero-width characters into every non-empty text node of every Lexical rich text field the editor can change. `excludeValues` does not apply to them. Reads with `locale: 'all'` and rich text in a row without an `id` get none.
405
+
406
+ The overlay removes these markers from the text inside `VisualEditing.Overlay`. Code that derives something else from rich text on a draft read (heading ids, slugs, excerpts, reading time, plain text, JSON-LD) receives them. Clean the value first with `stripMarkers`. It takes a string or any JSON value and returns a copy of the same shape in which no string carries a marker; a value without markers comes back with the same content, so it is safe on published reads too. It copies plain objects and arrays only: a `Map`, a `Set` or a class instance is returned as it is.
407
+
408
+ ```ts
409
+ import { stripMarkers } from '@focus-reactive/payload-plugin-visual-editing'
410
+
411
+ const minutes = readingTime(stripMarkers(post.content))
412
+ const excerpt = stripMarkers(post.excerpt)
413
+ ```
414
+
415
+ `vercelStegaClean` from `@vercel/stega` gives the same result for a JSON value without `_meta`. It serialises the value through JSON, so it turns a `Date` into a string and drops `undefined`. Or keep the field out with `excludeFieldNames`, which also ends click-to-edit for it.
416
+
417
+ ### Opting out
418
+
419
+ A render can transform a value and still output the stored text for some inputs, such as a lowercase transform on a title that is already lowercase. Put `data-ve-live="off"` on the element or an ancestor to keep instant preview away from it. Click-to-edit keeps working there.
420
+
421
+ ```tsx
422
+ <h1 data-ve-live="off">{title.toLowerCase()}</h1>
423
+ ```
424
+
425
+ ### Limitations
426
+
427
+ - Markup that the page turns into elements shows as typed until the save: if a heading renders `*accent*` as `<em>`, the asterisks appear as characters while you type.
428
+ - Payload's Lexical field passes its value to the form when the browser is idle, not on the keystroke itself, so rich text can reach the preview later than a text field. The plugin cannot shorten that.
429
+ - A renderer that joins several text nodes of rich text into one DOM text node, or changes their text, leaves that text to the save.
430
+ - Rich text that is not wrapped in `LiveRichText`:
431
+ - While a structural edit is unsaved, the preview shows the structure of the last save, with the text its text nodes had when the structure changed. Whatever is typed after that edit appears once the autosave has landed and the page has rendered it. A preview page that loads during that time shows the saved text.
432
+ - When a structural edit is undone before its save has landed (Enter, then Backspace, then more typing), the text typed after the undo is live at first. Then the save of the undone edit lands and the page renders it: the structure and the text of that save, which is older than what the editor holds. The preview shows that until the next autosave lands and is rendered, usually a few seconds. The plugin does not carry text from one structure of a field to another: a saved editor state identifies a text node by its position only, and matching nodes by position or by text could put text in the wrong place.
433
+ - Rich text in `LiveRichText`:
434
+ - The reference setup needs the App Router and a Server Action. The Pages Router and frontends that are not Next.js can use `render` with their own transport, or keep the behaviour above.
435
+ - While a Server Action call is out, `router.refresh()` waits for it, see [Unsaved rich text structure](#unsaved-rich-text-structure).
436
+ - The call is made with the cookies of the preview page. A preview on another origin than the admin has no Payload session there; the answer is `null` and the structure appears with the save.
437
+ - A structural edit is on screen one round trip after the admin sees it. Until then, and after a failed call, the preview shows the saved render. Text typed meanwhile is painted into the new render when it arrives.
438
+ - The fields of a block inside rich text are never posted: the admin has no schema of the blocks of an editor, so it cannot tell which of their fields may leave the form. A block that is already saved is rendered with its saved fields, a new block with none, and an edit of a block's fields shows with the save.
439
+ - The unsaved state is rendered as the editor holds it. Hooks that change a value on save (`beforeValidate`, `beforeChange`) have not run yet; their effect shows with the save. Hooks that run on read see the unsaved state, see `isUnsavedRichTextRead` above.
440
+ - An editor state longer than `maxStateLength` is not rendered before the save.
441
+ - A field the page renders twice makes two calls per structural edit, one per place.
442
+ - After the admin switches to another locale, instant preview resumes when the preview has loaded a page again. Payload reloads the Live Preview for the new locale; a popup preview window that was opened before the switch is sent nothing.
443
+ - After a client-side navigation inside the preview, fields of pages visited earlier stay on the admin's list until the preview does a full page load.
444
+ - In the popup preview window the admin cannot see a navigation. It keeps sending the listed fields to the popup until a page there reports its fields again or the popup is closed.
445
+ - The popup keeps unsaved text on screen after you leave the document without saving. It shows the saved content again when it reloads.
446
+ - While the preview shows fields of the open document, every change in the form reads the whole form state before the admin paints. On a form with several thousand fields this costs a few milliseconds per keystroke. With Live Preview closed it costs nothing.
230
447
 
231
448
  ## Enrichment modes
232
449
 
233
- The `enrichment` option decides which reads get stega.
450
+ `enrichment` decides which reads get markers.
234
451
 
235
- - **`'auto'`** (default) — every Local API read with `draft: true` outside the admin base path is enriched. The plugin can't tell a preview render from any other server code that reads drafts, so plugins, jobs, hooks and scripts receive stega too.
236
- - **`'explicit'`** — only reads that pass `context: { visualEditing: true }` are enriched. Everything else gets clean data.
452
+ - **`'auto'`** (default): every Local API read with `draft: true` outside the admin base path. The plugin cannot tell a preview render from other server code that reads drafts, so jobs, hooks and scripts get markers too.
453
+ - **`'explicit'`**: only reads that pass `context: { visualEditing: true }`.
237
454
 
238
455
  ```ts
239
456
  const { isEnabled: draft } = await draftMode()
@@ -246,44 +463,97 @@ await payload.find({
246
463
  })
247
464
  ```
248
465
 
249
- In either mode `context.visualEditing` wins when set: `true` always enriches, `false` never does. Server code that reads drafts for its own processing should pass `context: { visualEditing: false }` under `'auto'`. The plugin augments Payload's `RequestContext`, so the key is type-checked.
466
+ In both modes `context.visualEditing` wins when it is set: `true` marks the read, `false` leaves it clean.
250
467
 
251
- > **Why it matters.** The `beforeChange` strip only removes intact markers. If server code receives stega, transforms the text (an LLM translation, truncation, concatenation) and writes it back, fragments of a damaged marker survive the strip and end up in the database. Use `'explicit'` whenever server code reads drafts and writes derived content.
468
+ A `beforeChange` hook removes intact markers from every write. It cannot recognise a marker that a transformation damaged. If server code reads drafts, changes the text (a translation, a truncation) and writes it back, use `'explicit'` or pass `context: { visualEditing: false }` on those reads.
252
469
 
253
- ## How it works
470
+ ## Options
254
471
 
255
- ### Server pipeline
472
+ | Option | Type | Default | Purpose |
473
+ |---|---|---|---|
474
+ | `skipCollections` | `string[]` | `[]` | Collections the plugin does not mark. Payload's internal collections are always skipped. |
475
+ | `skipGlobals` | `string[]` | `[]` | Globals the plugin does not mark. |
476
+ | `excludeFieldNames` | `string[]` | `[]` | Field names that are never marked and never sent to the preview, in addition to `_status`, `folder`, `slug` and `apiKey`. |
477
+ | `excludeValues` | `((value: string) => boolean)[]` | `defaultExcludeValues` | Values that are not marked. Replaces the defaults (`isUrl`, `isSlug`, `isHash`, `isIsoDate`, all exported). |
478
+ | `adminBasePath` | `string` | `/admin` | Admin base path. Reads from below it are not marked; the bridge uses it to recognise the open document. |
479
+ | `enrichment` | `'auto' \| 'explicit'` | `'auto'` | See [Enrichment modes](#enrichment-modes). |
480
+ | `instantPreview` | `boolean` | `false` | See [Instant preview](#instant-preview). |
256
481
 
257
- 1. `beforeOperation` stamps `req.context` with the draft flag.
258
- 2. `afterRead` (gated by the [enrichment mode](#enrichment-modes) — under `'auto'`, draft reads served to the frontend Local API; admin-panel reads, identified by their admin pathname, and REST reads are skipped) walks the returned document, attaches `_meta.path` markers to leaf-ish objects, and for rich-text / primitive-terminal types sets `_meta.terminal = true` so outer collection walks don't clobber them.
259
- 3. `afterOperation` uses the collection's schema to embed Vercel stega into text fields, carrying the field path all the way through SSR into the client DOM.
260
- 4. Before stega is embedded, a small pre-pass walks each enriched doc's schema against its data. Populated `upload:<slug>` values are flipped to `_meta.terminal = true` so their identity is preserved for wrapper-attr consumption on the client (`<img {...withVisualEditingPath(upload)} />`), without embedding zero-width stega into `alt` or `filename`.
261
- 5. `beforeChange` strips intact stega markers from every write as a safety net. Markers damaged by a text transformation are not recognized — keep stega away from such code with the [enrichment mode](#enrichment-modes).
482
+ `LiveRichText` props:
262
483
 
263
- The schema cache (per slug, memoized) resolves relationship targets lazily so you don't pay for unused collections.
484
+ | Prop | Purpose |
485
+ |---|---|
486
+ | `field`, `shape` | From `liveRichTextOf(value)`: spread its result. |
487
+ | `action` | A Server Action that renders the unsaved state. It is called with the request only. |
488
+ | `render` | In place of `action`: `(request, signal) => Promise<ReactNode>`, a call you make yourself. |
489
+ | `children` | The saved render. |
264
490
 
265
- ### Client overlay
491
+ `VisualEditing.Provider` props:
266
492
 
267
- `VisualEditing.Overlay` mounts a MutationObserver inside its effect, scans existing DOM for stega-bearing text, and redraws edit badges on mount, lazy-mount, and DOM mutations. Clicking a badge reaches `VisualEditingBridgeProvider` (via `postMessage` to the parent admin when framed, or `window.opener` when opened from an admin tab) → schema walk → field focus.
493
+ | Prop | Default | Purpose |
494
+ |---|---|---|
495
+ | `available` | `false` | Turns the overlay on. Pass the draft mode flag. |
496
+ | `framedOnly` | `false` | Only run inside an iframe, that is the Live Preview. |
497
+ | `adminBasePath` | `/admin` | Must match the plugin option. |
498
+ | `adminOrigin` | the page's origin | Origin of the admin window. |
499
+ | `instantPreview` | `false` | See [Instant preview](#instant-preview). |
500
+ | `buildAdminEditUrl` | built in | Builds the link used when the page was not opened from the admin. |
268
501
 
269
- ## Options
502
+ ## Reads with every locale
270
503
 
271
- | Option | Type | Default | Purpose |
272
- |---|---|---|---|
273
- | `skipCollections` | `string[]` | `[]` | Exclude these collection slugs from enrichment. Payload internal collections are always skipped. |
274
- | `skipGlobals` | `string[]` | `[]` | Exclude these global slugs from enrichment. |
275
- | `excludeFieldNames` | `string[]` | `[]` | Extra field names to strip from the serialized schema. Always merged with `_status`, `folder`, `slug`. |
276
- | `adminBasePath` | `string` | `/admin` | Payload admin base path. Used to exclude admin reads from enrichment and by the bridge for URL parsing and admin-tab navigation. |
277
- | `enrichment` | `'auto' \| 'explicit'` | `'auto'` | Which reads get stega: any frontend draft read, or only reads passing `context: { visualEditing: true }`. See [Enrichment modes](#enrichment-modes). |
504
+ A draft read with `locale: 'all'` returns localized values keyed by locale (`title: { en, de }`). Each value is marked with the path of its field and its locale, so a click on the German title opens `title` in German when it opens a new admin tab. The `_meta` of a localized rich text, upload or relationship sits on the value of each locale: `withVisualEditingPath(page.content.en)`. Instant preview does not touch these values.
505
+
506
+ When the clicked document is already open in the admin, the bridge focuses the field in the locale the admin is showing. It does not switch the admin locale.
507
+
508
+ ## Upgrading from 1.1.1
509
+
510
+ No config change is needed. Regenerate the import map when you turn `instantPreview` on: it adds `InstantPreviewBroadcaster` and `OpenFormAnnouncer`.
511
+
512
+ Peer dependencies: `react` is narrowed from `^18 || ^19` to `^19`, `react-dom ^19` is a new peer, and `next` is no longer a peer. A project on React 18 could not run the admin of Payload 3 anyway: `@payloadcms/ui` 3.79 requires React 19.
513
+
514
+ Globals:
278
515
 
279
- The `VisualEditing.Provider` (client) also accepts `framedOnly` (restrict the overlay to the CMS preview iframe) and `adminBasePath` (must match the server option).
516
+ - **A Local API draft read of a global is marked at every `depth`.** The plugin used to take the draft flag of a global read from `req.query`, so `payload.findGlobal({ slug, draft: true })` was marked only when a populated relationship happened to set the flag. It now takes it from the `draft` argument of the read, through a `beforeOperation` hook that replaces the `beforeRead` hook globals had.
517
+ - **A published read is never marked by another read.** Only the read's own request can mark it: `draft: true` through the Local API, or `context: { visualEditing: true }`, which marks any read. Whether a read is marked is decided for that operation alone: a read inside it (a population, a read in an access function or a hook, also of the same collection or global, also one that fails), a read beside it on the same `req`, or a `context` object shared between calls cannot mark it. Version reads of collections and globals are not marked unless they pass `context: { visualEditing: true }`. A Local API read of a global without `draft: true` is not marked even inside a request whose URL has `?draft=true`.
518
+ - **One case leaves a draft read unmarked:** a draft and a published read of the same global that run at the same time on one `req`. Both come back without markers. Read them one after the other, or on separate requests, to get the markers of the draft read.
519
+ - **Collections get two hooks less.** Markers and `_meta` of a collection read are written in one `afterOperation` hook; the plugin no longer adds `beforeOperation` and `afterRead` hooks to collections. A collection `afterRead` hook that a later plugin or config adds after this one no longer sees the `_meta` of a draft read.
520
+
521
+ Markers:
522
+
523
+ - **Populated documents carry one marker per text.** Text below the top level of a populated document (in groups, array rows and blocks), and all text of a document in a `hasMany` field, used to carry two markers in one string: its own, which the overlay read, followed by a second one with a path through the outer document (`related.list.0.label`). The second one is gone and those strings are shorter. Click-to-edit behaves as before.
524
+ - **Populated documents of skipped collections are not marked.** Some of their text used to be marked as a field of the outer document (`author.links.0.label` on the page), a path that does not exist there. The `_meta` on the populated document, which addresses the relationship field, is still there.
525
+ - **Any document nested in a skipped one loses its `_meta`.** For page → skipped author → page, upload or any other populated document, the nested document used to carry a `_meta` with a path of the outer page (`author.favourite`). It has none now, so `withVisualEditingPath` returns `{}` for it. Text of a marked collection is still marked as its own.
526
+ - **`hasMany` relationships and uploads.** Each populated document now has a `_meta` that addresses the field (`gallery`). There was none, so `withVisualEditingPath(page.gallery[0])` used to return `{}`.
527
+ - **Fields with several `relationTo`.** The `_meta` on the `value` of an upload had the path `image.value`, which the admin could not focus. It is `image` now. The `value` of a relationship had no `_meta` and has one now. Every entry of a `hasMany` field is a `{ relationTo, value }` object and carries the `_meta` of the field at every `depth`, also at `depth: 0`, where `value` is an id.
528
+ - **Fields the editor cannot reach.** Fields with `hidden: true` or `admin.disabled` are no longer marked; `admin.hidden` and `admin.readOnly` already were not. A string that its own group, row or block does not make editable (text in a hidden, read-only or excluded group or in a block the config does not know, the value of a `select`) used to get the marker of a text field with the same name further up (`internal.label` opened `label`). It has no marker now. A field named `apiKey` is no longer marked.
529
+ - **Blocks declared through `blockReferences`.** Their text had no marker, or the marker of a top-level field of the same name. It is now marked with its own path (`sections.0.quote`), at every level of nesting.
530
+ - **Version reads that pass `context: { visualEditing: true }`.** The version of a collection version read is now marked like a document read of its parent: text in rows and blocks gets markers, rich text, relationship and upload values get a `_meta`, and every marker states the id of the parent document. Before, only its top-level text was marked, without a document id on SQL adapters.
531
+ - **`blockName`.** Still marked, except for a block with `admin.disableBlockName`. A click now focuses the name input in the block header.
532
+ - **Reads with `locale: 'all'`.** A localized text at the top level had no marker and rows of a localized array lost their index (`list.label`). Localized values are now marked at every depth with the path of a single-locale read plus `locale`. The `_meta` of a localized rich text, upload or relationship moved from the object that holds the locales to the value of each locale and states `locale`; `withVisualEditingPath` writes it as `data-ve-locale`.
533
+ - **Otherwise unchanged while `instantPreview` is off.** With the option on:
534
+ - Fields inside array rows and blocks also state a `key` (the path with row ids instead of indexes). For a rich text field in a row it is on the `_meta`, and `withVisualEditingPath` writes it as `data-ve-key`.
535
+ - The text nodes of rich text carry markers, see [Markers in rich text](#markers-in-rich-text). Check code that reads rich text from draft reads and clean it with `stripMarkers`.
536
+ - Upgrade the server and the frontend together: an overlay of 1.1.1 or earlier does not know these markers and leaves them in the text of the page, where they end up in copied text.
537
+
538
+ - The plugin adds the key `"@focus-reactive/payload-plugin-visual-editing/schemaCache"` to `config.custom`, next to your own keys. `readUnsavedRichText` reads it from there, so it must survive a later plugin or config that replaces `custom`: spread the `custom` it gets. Without the key `readUnsavedRichText` reads nothing and logs one warning. With the option off, `config.custom` is left as it is.
539
+ - Collections and globals get one more `beforeRead` hook. It does nothing unless `readUnsavedRichText` made the read. Structural edits of rich text reach the preview before the save only where you add [`LiveRichText`](#unsaved-rich-text-structure); every other page behaves as before.
540
+
541
+ Overlay:
542
+
543
+ - **Edit targets follow the page.** A target is bound again when React renders another field or document into the same element. An element that leaves the overlay, or a wrapper that loses its `data-ve-*` attributes, loses its outline and badge.
544
+ - **Click-to-edit after a row move** (with `instantPreview`): between a move in the form and the refresh, a click opens the row that was clicked, not the row that now has its index. A rich text wrapper does the same through its `data-ve-key`. For this the plugin adds an `OpenFormAnnouncer` to the document controls of every collection and global it marks, with or without Live Preview; it renders nothing and tells the bridge which row ids the open form has.
280
545
 
281
546
  ## Caveats
282
547
 
283
- - **`target="_blank"` must not carry `noopener`.** The postMessage bridge requires `window.opener` to be non-null. If you open the frontend from the admin tab with a plain anchor, browsers default `window.opener` to `null` on `target="_blank"` unless you explicitly opt out. Use `window.open(url, '_blank', 'noopener=no')` or cross-tab messaging will fail silently. (Not a concern in the side-by-side Live Preview, which messages the parent frame.)
284
- - **The overlay hook intentionally collapses effect deps to `[enabled]`** via `ctxRef`. Do not "fix" this — parent re-renders would teardown the MutationObserver and lazy-mounted content (React.lazy / Suspense) would stop getting outlined.
285
- - **`_meta.terminal = true` on rich-text is load-bearing** — prevents outer `afterRead` walks from clobbering inner markers when collections relate to other collections.
286
- - **`slug` is excluded from stega** — zero-width chars inside a slug corrupt URLs (become noisy `%E2%80%8B` sequences).
548
+ - **Click-to-edit needs the frontend and the admin on the same origin.** The admin bridge accepts `ve:open-field` only from its own origin.
549
+ - **`target="_blank"` must not carry `noopener`** when you open the frontend from the admin in a new tab. The overlay talks to `window.opener`. The Live Preview iframe is not affected.
550
+ - **`slug` is never marked.** Zero-width characters in a slug end up in URLs.
551
+ - **A value that starts to match `excludeValues`** (a heading that becomes `hello-world`) is rendered without a marker. The overlay stops patching that text node and does not write an earlier value back. Click-to-edit and instant preview return with the next marked render.
552
+ - **Do not transform marked text on the server and write it back**, see [Enrichment modes](#enrichment-modes).
553
+
554
+ ## Contributing
555
+
556
+ See [`CLAUDE.md`](./CLAUDE.md) for where things are, the rules that are easy to break and how to test.
287
557
 
288
558
  ## License
289
559