@focus-reactive/payload-plugin-visual-editing 1.1.1 → 1.3.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 (408) hide show
  1. package/README.md +600 -96
  2. package/dist/admin/InstantPreviewBroadcaster.d.ts +3 -0
  3. package/dist/admin/InstantPreviewBroadcaster.js +105 -0
  4. package/dist/admin/InstantPreviewBroadcaster.js.map +1 -0
  5. package/dist/admin/PreviewPageBridge.d.ts +1 -0
  6. package/dist/admin/PreviewPageBridge.js +50 -0
  7. package/dist/admin/PreviewPageBridge.js.map +1 -0
  8. package/dist/admin/VisualEditingBridgeProvider.js +76 -50
  9. package/dist/admin/VisualEditingBridgeProvider.js.map +1 -1
  10. package/dist/admin/expandAndFocus.d.ts +1 -1
  11. package/dist/admin/expandAndFocus.js +138 -157
  12. package/dist/admin/expandAndFocus.js.map +1 -1
  13. package/dist/admin/fieldDomId.d.ts +5 -0
  14. package/dist/admin/fieldDomId.js +11 -0
  15. package/dist/admin/fieldDomId.js.map +1 -0
  16. package/dist/admin/index.d.ts +3 -0
  17. package/dist/admin/index.js +3 -0
  18. package/dist/admin/index.js.map +1 -1
  19. package/dist/admin/instantPreview/fieldMessages.d.ts +26 -0
  20. package/dist/admin/instantPreview/fieldMessages.js +90 -0
  21. package/dist/admin/instantPreview/fieldMessages.js.map +1 -0
  22. package/dist/admin/instantPreview/formFields.d.ts +9 -0
  23. package/dist/admin/instantPreview/formFields.js +54 -0
  24. package/dist/admin/instantPreview/formFields.js.map +1 -0
  25. package/dist/admin/instantPreview/previewGrants.d.ts +14 -0
  26. package/dist/admin/instantPreview/previewGrants.js +62 -0
  27. package/dist/admin/instantPreview/previewGrants.js.map +1 -0
  28. package/dist/admin/instantPreview/previewSession.d.ts +18 -0
  29. package/dist/admin/instantPreview/previewSession.js +157 -0
  30. package/dist/admin/instantPreview/previewSession.js.map +1 -0
  31. package/dist/admin/instantPreview/richTextReads.d.ts +29 -0
  32. package/dist/admin/instantPreview/richTextReads.js +67 -0
  33. package/dist/admin/instantPreview/richTextReads.js.map +1 -0
  34. package/dist/admin/instantPreview/unsavedStructures.d.ts +16 -0
  35. package/dist/admin/instantPreview/unsavedStructures.js +71 -0
  36. package/dist/admin/instantPreview/unsavedStructures.js.map +1 -0
  37. package/dist/admin/instantPreview/useEditableSchema.d.ts +7 -0
  38. package/dist/admin/instantPreview/useEditableSchema.js +30 -0
  39. package/dist/admin/instantPreview/useEditableSchema.js.map +1 -0
  40. package/dist/admin/instantPreview/usePreviewPage.d.ts +4 -0
  41. package/dist/admin/instantPreview/usePreviewPage.js +59 -0
  42. package/dist/admin/instantPreview/usePreviewPage.js.map +1 -0
  43. package/dist/admin/instantPreview/usePreviewWindow.d.ts +7 -0
  44. package/dist/admin/instantPreview/usePreviewWindow.js +46 -0
  45. package/dist/admin/instantPreview/usePreviewWindow.js.map +1 -0
  46. package/dist/admin/openField/OpenFormAnnouncer.d.ts +1 -0
  47. package/dist/admin/openField/OpenFormAnnouncer.js +8 -0
  48. package/dist/admin/openField/OpenFormAnnouncer.js.map +1 -0
  49. package/dist/admin/openField/formPathOfKey.d.ts +11 -0
  50. package/dist/admin/openField/formPathOfKey.js +20 -0
  51. package/dist/admin/openField/formPathOfKey.js.map +1 -0
  52. package/dist/admin/openField/openDocument.d.ts +8 -0
  53. package/dist/admin/openField/openDocument.js +13 -0
  54. package/dist/admin/openField/openDocument.js.map +1 -0
  55. package/dist/admin/openField/openForms.d.ts +16 -0
  56. package/dist/admin/openField/openForms.js +60 -0
  57. package/dist/admin/openField/openForms.js.map +1 -0
  58. package/dist/admin/openField/useOpenFormAnnouncement.d.ts +1 -0
  59. package/dist/admin/openField/useOpenFormAnnouncement.js +29 -0
  60. package/dist/admin/openField/useOpenFormAnnouncement.js.map +1 -0
  61. package/dist/admin/parseFieldPath.js +7 -17
  62. package/dist/admin/parseFieldPath.js.map +1 -1
  63. package/dist/admin/previewPages.d.ts +7 -0
  64. package/dist/admin/previewPages.js +13 -0
  65. package/dist/admin/previewPages.js.map +1 -0
  66. package/dist/admin/resolveContainerChain.d.ts +3 -2
  67. package/dist/admin/resolveContainerChain.js +10 -33
  68. package/dist/admin/resolveContainerChain.js.map +1 -1
  69. package/dist/client/adminWindow.d.ts +2 -0
  70. package/dist/client/adminWindow.js +8 -0
  71. package/dist/client/adminWindow.js.map +1 -0
  72. package/dist/client/createOverlay.d.ts +17 -0
  73. package/dist/client/createOverlay.js +33 -0
  74. package/dist/client/createOverlay.js.map +1 -0
  75. package/dist/client/index.d.ts +9 -5
  76. package/dist/client/index.js +7 -5
  77. package/dist/client/index.js.map +1 -1
  78. package/dist/client/instantPreview/adminChannel.d.ts +14 -0
  79. package/dist/client/instantPreview/adminChannel.js +40 -0
  80. package/dist/client/instantPreview/adminChannel.js.map +1 -0
  81. package/dist/client/instantPreview/instantPreview.d.ts +8 -0
  82. package/dist/client/instantPreview/instantPreview.js +49 -0
  83. package/dist/client/instantPreview/instantPreview.js.map +1 -0
  84. package/dist/client/instantPreview/liveFields.d.ts +19 -0
  85. package/dist/client/instantPreview/liveFields.js +185 -0
  86. package/dist/client/instantPreview/liveFields.js.map +1 -0
  87. package/dist/client/instantPreview/liveMessages.d.ts +6 -0
  88. package/dist/client/instantPreview/liveMessages.js +39 -0
  89. package/dist/client/instantPreview/liveMessages.js.map +1 -0
  90. package/dist/client/instantPreview/liveRichTextOf.d.ts +9 -0
  91. package/dist/client/instantPreview/liveRichTextOf.js +26 -0
  92. package/dist/client/instantPreview/liveRichTextOf.js.map +1 -0
  93. package/dist/client/instantPreview/pageLoad.d.ts +6 -0
  94. package/dist/client/instantPreview/pageLoad.js +11 -0
  95. package/dist/client/instantPreview/pageLoad.js.map +1 -0
  96. package/dist/client/instantPreview/unsavedRender/announcer.d.ts +3 -0
  97. package/dist/client/instantPreview/unsavedRender/announcer.js +25 -0
  98. package/dist/client/instantPreview/unsavedRender/announcer.js.map +1 -0
  99. package/dist/client/instantPreview/unsavedRender/baseValues.d.ts +12 -0
  100. package/dist/client/instantPreview/unsavedRender/baseValues.js +130 -0
  101. package/dist/client/instantPreview/unsavedRender/baseValues.js.map +1 -0
  102. package/dist/client/instantPreview/unsavedRender/liveRichText.d.ts +29 -0
  103. package/dist/client/instantPreview/unsavedRender/liveRichText.js +117 -0
  104. package/dist/client/instantPreview/unsavedRender/liveRichText.js.map +1 -0
  105. package/dist/client/instantPreview/unsavedRender/optimisticValue.d.ts +6 -0
  106. package/dist/client/instantPreview/unsavedRender/optimisticValue.js +20 -0
  107. package/dist/client/instantPreview/unsavedRender/optimisticValue.js.map +1 -0
  108. package/dist/client/instantPreview/unsavedRender/renderSources.d.ts +26 -0
  109. package/dist/client/instantPreview/unsavedRender/renderSources.js +77 -0
  110. package/dist/client/instantPreview/unsavedRender/renderSources.js.map +1 -0
  111. package/dist/client/instantPreview/unsavedRender/savedShapes.d.ts +6 -0
  112. package/dist/client/instantPreview/unsavedRender/savedShapes.js +20 -0
  113. package/dist/client/instantPreview/unsavedRender/savedShapes.js.map +1 -0
  114. package/dist/client/instantPreview/unsavedRender/unsavedRender.d.ts +45 -0
  115. package/dist/client/instantPreview/unsavedRender/unsavedRender.js +257 -0
  116. package/dist/client/instantPreview/unsavedRender/unsavedRender.js.map +1 -0
  117. package/dist/client/instantPreview/unsavedRender/valueSource.d.ts +17 -0
  118. package/dist/client/instantPreview/unsavedRender/valueSource.js +38 -0
  119. package/dist/client/instantPreview/unsavedRender/valueSource.js.map +1 -0
  120. package/dist/client/overlay/constants.d.ts +3 -4
  121. package/dist/client/overlay/constants.js +5 -19
  122. package/dist/client/overlay/constants.js.map +1 -1
  123. package/dist/client/overlay/editBadge.d.ts +2 -8
  124. package/dist/client/overlay/editBadge.js +0 -8
  125. package/dist/client/overlay/editBadge.js.map +1 -1
  126. package/dist/client/overlay/editTargets.d.ts +3 -0
  127. package/dist/client/overlay/editTargets.js +98 -0
  128. package/dist/client/overlay/editTargets.js.map +1 -0
  129. package/dist/client/overlay/fieldTracker.d.ts +22 -0
  130. package/dist/client/overlay/fieldTracker.js +292 -0
  131. package/dist/client/overlay/fieldTracker.js.map +1 -0
  132. package/dist/client/overlay/hoverController.d.ts +0 -5
  133. package/dist/client/overlay/hoverController.js +3 -19
  134. package/dist/client/overlay/hoverController.js.map +1 -1
  135. package/dist/client/overlay/markerCleaner.d.ts +5 -0
  136. package/dist/client/overlay/markerCleaner.js +94 -0
  137. package/dist/client/overlay/markerCleaner.js.map +1 -0
  138. package/dist/client/overlay/markerExtractor.d.ts +4 -3
  139. package/dist/client/overlay/markerExtractor.js +13 -20
  140. package/dist/client/overlay/markerExtractor.js.map +1 -1
  141. package/dist/client/overlay/mutationPipeline.d.ts +5 -2
  142. package/dist/client/overlay/mutationPipeline.js +57 -35
  143. package/dist/client/overlay/mutationPipeline.js.map +1 -1
  144. package/dist/client/overlay/pageNodes.d.ts +3 -0
  145. package/dist/client/overlay/pageNodes.js +34 -0
  146. package/dist/client/overlay/pageNodes.js.map +1 -0
  147. package/dist/client/overlay/targetRegistry.d.ts +5 -11
  148. package/dist/client/overlay/targetRegistry.js +14 -7
  149. package/dist/client/overlay/targetRegistry.js.map +1 -1
  150. package/dist/client/overlay/targetSelector.js +0 -9
  151. package/dist/client/overlay/targetSelector.js.map +1 -1
  152. package/dist/client/overlayClickHandler.d.ts +1 -1
  153. package/dist/client/overlayClickHandler.js +9 -14
  154. package/dist/client/overlayClickHandler.js.map +1 -1
  155. package/dist/client/overlayScope.d.ts +14 -0
  156. package/dist/client/overlayScope.js +23 -0
  157. package/dist/client/overlayScope.js.map +1 -0
  158. package/dist/client/previewGrant.d.ts +5 -0
  159. package/dist/client/previewGrant.js +34 -0
  160. package/dist/client/previewGrant.js.map +1 -0
  161. package/dist/client/react/LiveRichText.d.ts +17 -0
  162. package/dist/client/react/LiveRichText.js +32 -0
  163. package/dist/client/react/LiveRichText.js.map +1 -0
  164. package/dist/client/react/UnsavedRenderBoundary.d.ts +19 -0
  165. package/dist/client/react/UnsavedRenderBoundary.js +28 -0
  166. package/dist/client/react/UnsavedRenderBoundary.js.map +1 -0
  167. package/dist/client/react/VisualEditingOverlay.js +60 -0
  168. package/dist/client/react/VisualEditingOverlay.js.map +1 -0
  169. package/dist/client/react/VisualEditingProvider.d.ts +21 -0
  170. package/dist/client/react/VisualEditingProvider.js +83 -0
  171. package/dist/client/react/VisualEditingProvider.js.map +1 -0
  172. package/dist/client/react/VisualEditingToggle.d.ts +1 -0
  173. package/dist/client/react/VisualEditingToggle.js +32 -0
  174. package/dist/client/react/VisualEditingToggle.js.map +1 -0
  175. package/dist/client/react/overlayContext.d.ts +2 -0
  176. package/dist/client/react/overlayContext.js +4 -0
  177. package/dist/client/react/overlayContext.js.map +1 -0
  178. package/dist/client/react/useIsomorphicLayoutEffect.d.ts +2 -0
  179. package/dist/client/react/useIsomorphicLayoutEffect.js +4 -0
  180. package/dist/client/react/useIsomorphicLayoutEffect.js.map +1 -0
  181. package/dist/client/react/useUnsavedRender.d.ts +16 -0
  182. package/dist/client/react/useUnsavedRender.js +89 -0
  183. package/dist/client/react/useUnsavedRender.js.map +1 -0
  184. package/dist/client/saveEvents.d.ts +3 -0
  185. package/dist/client/saveEvents.js +27 -0
  186. package/dist/client/saveEvents.js.map +1 -0
  187. package/dist/client/session.d.ts +40 -0
  188. package/dist/client/session.js +100 -0
  189. package/dist/client/session.js.map +1 -0
  190. package/dist/client/sessionOverlay.d.ts +9 -0
  191. package/dist/client/sessionOverlay.js +74 -0
  192. package/dist/client/sessionOverlay.js.map +1 -0
  193. package/dist/client/toggle.d.ts +7 -0
  194. package/dist/client/toggle.js +158 -0
  195. package/dist/client/toggle.js.map +1 -0
  196. package/dist/client/visualEditingMode.d.ts +3 -0
  197. package/dist/client/visualEditingMode.js +8 -0
  198. package/dist/client/visualEditingMode.js.map +1 -0
  199. package/dist/client/withVisualEditingPath.d.ts +5 -1
  200. package/dist/client/withVisualEditingPath.js +19 -13
  201. package/dist/client/withVisualEditingPath.js.map +1 -1
  202. package/dist/dom/index.d.ts +6 -0
  203. package/dist/dom/index.js +7 -0
  204. package/dist/dom/index.js.map +1 -0
  205. package/dist/dom/liveRichTextElements.d.ts +8 -0
  206. package/dist/dom/liveRichTextElements.js +69 -0
  207. package/dist/dom/liveRichTextElements.js.map +1 -0
  208. package/dist/dom/mountVisualEditing.d.ts +16 -0
  209. package/dist/dom/mountVisualEditing.js +52 -0
  210. package/dist/dom/mountVisualEditing.js.map +1 -0
  211. package/dist/excludeValues.js +2 -14
  212. package/dist/excludeValues.js.map +1 -1
  213. package/dist/index.d.ts +10 -1
  214. package/dist/index.js +49 -30
  215. package/dist/index.js.map +1 -1
  216. package/dist/readUnsavedRichText.d.ts +27 -0
  217. package/dist/readUnsavedRichText.js +94 -0
  218. package/dist/readUnsavedRichText.js.map +1 -0
  219. package/dist/server/endpoints.d.ts +16 -0
  220. package/dist/server/endpoints.js +136 -0
  221. package/dist/server/endpoints.js.map +1 -0
  222. package/dist/server/hooks/readHooks.d.ts +14 -0
  223. package/dist/server/hooks/readHooks.js +67 -0
  224. package/dist/server/hooks/readHooks.js.map +1 -0
  225. package/dist/{internal → server/hooks}/stripStegaHook.js +11 -12
  226. package/dist/server/hooks/stripStegaHook.js.map +1 -0
  227. package/dist/server/localeCodesKeyingValues.d.ts +4 -0
  228. package/dist/server/localeCodesKeyingValues.js +15 -0
  229. package/dist/server/localeCodesKeyingValues.js.map +1 -0
  230. package/dist/server/markRead.d.ts +12 -0
  231. package/dist/server/markRead.js +220 -0
  232. package/dist/server/markRead.js.map +1 -0
  233. package/dist/server/markedReads.d.ts +28 -0
  234. package/dist/server/markedReads.js +60 -0
  235. package/dist/server/markedReads.js.map +1 -0
  236. package/dist/server/previewGrant.d.ts +9 -0
  237. package/dist/server/previewGrant.js +31 -0
  238. package/dist/server/previewGrant.js.map +1 -0
  239. package/dist/server/schemaCache.d.ts +29 -0
  240. package/dist/server/schemaCache.js +35 -0
  241. package/dist/server/schemaCache.js.map +1 -0
  242. package/dist/server/unsavedRichText/hooks.d.ts +4 -0
  243. package/dist/server/unsavedRichText/hooks.js +57 -0
  244. package/dist/server/unsavedRichText/hooks.js.map +1 -0
  245. package/dist/server/unsavedRichText/jsonBody.d.ts +1 -0
  246. package/dist/server/unsavedRichText/jsonBody.js +47 -0
  247. package/dist/server/unsavedRichText/jsonBody.js.map +1 -0
  248. package/dist/server/unsavedRichText/latestReads.d.ts +17 -0
  249. package/dist/server/unsavedRichText/latestReads.js +70 -0
  250. package/dist/server/unsavedRichText/latestReads.js.map +1 -0
  251. package/dist/server/unsavedRichText/placeUnsavedState.d.ts +8 -0
  252. package/dist/server/unsavedRichText/placeUnsavedState.js +12 -0
  253. package/dist/server/unsavedRichText/placeUnsavedState.js.map +1 -0
  254. package/dist/server/unsavedRichText/postedEditorState.d.ts +2 -0
  255. package/dist/server/unsavedRichText/postedEditorState.js +17 -0
  256. package/dist/server/unsavedRichText/postedEditorState.js.map +1 -0
  257. package/dist/server/unsavedRichText/postedRequest.d.ts +37 -0
  258. package/dist/server/unsavedRichText/postedRequest.js +106 -0
  259. package/dist/server/unsavedRichText/postedRequest.js.map +1 -0
  260. package/dist/server/unsavedRichText/readAsUser.d.ts +11 -0
  261. package/dist/server/unsavedRichText/readAsUser.js +91 -0
  262. package/dist/server/unsavedRichText/readAsUser.js.map +1 -0
  263. package/dist/server/unsavedRichText/readContext.d.ts +16 -0
  264. package/dist/server/unsavedRichText/readContext.js +14 -0
  265. package/dist/server/unsavedRichText/readContext.js.map +1 -0
  266. package/dist/server/unsavedRichText/savedReferences.d.ts +5 -0
  267. package/dist/server/unsavedRichText/savedReferences.js +61 -0
  268. package/dist/server/unsavedRichText/savedReferences.js.map +1 -0
  269. package/dist/server/withDocumentControls.d.ts +10 -0
  270. package/dist/server/withDocumentControls.js +51 -0
  271. package/dist/server/withDocumentControls.js.map +1 -0
  272. package/dist/{client → shared}/buildAdminEditUrl.d.ts +3 -2
  273. package/dist/shared/buildAdminEditUrl.js +14 -0
  274. package/dist/shared/buildAdminEditUrl.js.map +1 -0
  275. package/dist/shared/editableSchema/editableSchema.d.ts +26 -0
  276. package/dist/shared/editableSchema/editableSchema.js +165 -0
  277. package/dist/shared/editableSchema/editableSchema.js.map +1 -0
  278. package/dist/shared/editableSchema/schemaOfFields.d.ts +16 -0
  279. package/dist/shared/editableSchema/schemaOfFields.js +106 -0
  280. package/dist/shared/editableSchema/schemaOfFields.js.map +1 -0
  281. package/dist/shared/fieldKey.d.ts +23 -0
  282. package/dist/shared/fieldKey.js +44 -0
  283. package/dist/shared/fieldKey.js.map +1 -0
  284. package/dist/shared/messageSource.d.ts +1 -0
  285. package/dist/shared/messageSource.js +3 -0
  286. package/dist/shared/messageSource.js.map +1 -0
  287. package/dist/shared/packageName.d.ts +1 -0
  288. package/dist/shared/packageName.js +3 -0
  289. package/dist/shared/packageName.js.map +1 -0
  290. package/dist/shared/plainObject.d.ts +2 -0
  291. package/dist/shared/plainObject.js +3 -0
  292. package/dist/shared/plainObject.js.map +1 -0
  293. package/dist/shared/protocol.d.ts +98 -0
  294. package/dist/shared/protocol.js +32 -0
  295. package/dist/shared/protocol.js.map +1 -0
  296. package/dist/shared/richText/blockNodes.d.ts +3 -0
  297. package/dist/shared/richText/blockNodes.js +35 -0
  298. package/dist/shared/richText/blockNodes.js.map +1 -0
  299. package/dist/shared/richText/editorNodes.d.ts +6 -0
  300. package/dist/shared/richText/editorNodes.js +25 -0
  301. package/dist/shared/richText/editorNodes.js.map +1 -0
  302. package/dist/shared/richText/editorStateTree.d.ts +2 -0
  303. package/dist/shared/richText/editorStateTree.js +34 -0
  304. package/dist/shared/richText/editorStateTree.js.map +1 -0
  305. package/dist/shared/richText/markTextLeaves.d.ts +1 -0
  306. package/dist/shared/richText/markTextLeaves.js +16 -0
  307. package/dist/shared/richText/markTextLeaves.js.map +1 -0
  308. package/dist/shared/richText/nodeKey.d.ts +14 -0
  309. package/dist/shared/richText/nodeKey.js +31 -0
  310. package/dist/shared/richText/nodeKey.js.map +1 -0
  311. package/dist/shared/richText/nodeTypes.d.ts +5 -0
  312. package/dist/shared/richText/nodeTypes.js +20 -0
  313. package/dist/shared/richText/nodeTypes.js.map +1 -0
  314. package/dist/shared/richText/references.d.ts +16 -0
  315. package/dist/shared/richText/references.js +85 -0
  316. package/dist/shared/richText/references.js.map +1 -0
  317. package/dist/shared/richText/relatedIds.d.ts +2 -0
  318. package/dist/shared/richText/relatedIds.js +30 -0
  319. package/dist/shared/richText/relatedIds.js.map +1 -0
  320. package/dist/shared/richText/savedNodeFields.d.ts +3 -0
  321. package/dist/shared/richText/savedNodeFields.js +47 -0
  322. package/dist/shared/richText/savedNodeFields.js.map +1 -0
  323. package/dist/shared/richText/shapeOf.d.ts +1 -0
  324. package/dist/shared/richText/shapeOf.js +24 -0
  325. package/dist/shared/richText/shapeOf.js.map +1 -0
  326. package/dist/shared/richText/textLeaves.d.ts +14 -0
  327. package/dist/shared/richText/textLeaves.js +32 -0
  328. package/dist/shared/richText/textLeaves.js.map +1 -0
  329. package/dist/shared/rowWithId.d.ts +2 -0
  330. package/dist/shared/rowWithId.js +7 -0
  331. package/dist/shared/rowWithId.js.map +1 -0
  332. package/dist/shared/shared.d.ts +35 -0
  333. package/dist/shared/shared.js +83 -0
  334. package/dist/shared/shared.js.map +1 -0
  335. package/dist/shared/stegaText.d.ts +3 -0
  336. package/dist/shared/stegaText.js +8 -0
  337. package/dist/shared/stegaText.js.map +1 -0
  338. package/dist/shared/veDocument.d.ts +15 -0
  339. package/dist/shared/veDocument.js +31 -0
  340. package/dist/shared/veDocument.js.map +1 -0
  341. package/dist/stripMarkers.d.ts +1 -0
  342. package/dist/stripMarkers.js +19 -0
  343. package/dist/stripMarkers.js.map +1 -0
  344. package/package.json +31 -10
  345. package/dist/client/VisualEditingOverlay.js +0 -30
  346. package/dist/client/VisualEditingOverlay.js.map +0 -1
  347. package/dist/client/VisualEditingProvider.d.ts +0 -23
  348. package/dist/client/VisualEditingProvider.js +0 -68
  349. package/dist/client/VisualEditingProvider.js.map +0 -1
  350. package/dist/client/VisualEditingToggle.d.ts +0 -1
  351. package/dist/client/VisualEditingToggle.js +0 -163
  352. package/dist/client/VisualEditingToggle.js.map +0 -1
  353. package/dist/client/buildAdminEditUrl.js +0 -9
  354. package/dist/client/buildAdminEditUrl.js.map +0 -1
  355. package/dist/client/overlay/createOverlay.d.ts +0 -11
  356. package/dist/client/overlay/createOverlay.js +0 -99
  357. package/dist/client/overlay/createOverlay.js.map +0 -1
  358. package/dist/client/overlay/stegaBookkeeper.d.ts +0 -11
  359. package/dist/client/overlay/stegaBookkeeper.js +0 -36
  360. package/dist/client/overlay/stegaBookkeeper.js.map +0 -1
  361. package/dist/client/overlay/stegaScanner.d.ts +0 -11
  362. package/dist/client/overlay/stegaScanner.js +0 -54
  363. package/dist/client/overlay/stegaScanner.js.map +0 -1
  364. package/dist/client/useVisualEditingOverlay.d.ts +0 -4
  365. package/dist/client/useVisualEditingOverlay.js +0 -21
  366. package/dist/client/useVisualEditingOverlay.js.map +0 -1
  367. package/dist/constants.d.ts +0 -16
  368. package/dist/constants.js +0 -15
  369. package/dist/constants.js.map +0 -1
  370. package/dist/internal/afterOperationHook.d.ts +0 -12
  371. package/dist/internal/afterOperationHook.js +0 -28
  372. package/dist/internal/afterOperationHook.js.map +0 -1
  373. package/dist/internal/afterReadHook.d.ts +0 -3
  374. package/dist/internal/afterReadHook.js +0 -16
  375. package/dist/internal/afterReadHook.js.map +0 -1
  376. package/dist/internal/beforeOperationHook.d.ts +0 -4
  377. package/dist/internal/beforeOperationHook.js +0 -16
  378. package/dist/internal/beforeOperationHook.js.map +0 -1
  379. package/dist/internal/buildFieldSchema.d.ts +0 -3
  380. package/dist/internal/buildFieldSchema.js +0 -67
  381. package/dist/internal/buildFieldSchema.js.map +0 -1
  382. package/dist/internal/encodeStega.d.ts +0 -7
  383. package/dist/internal/encodeStega.js +0 -171
  384. package/dist/internal/encodeStega.js.map +0 -1
  385. package/dist/internal/enrichWithPathMeta.d.ts +0 -4
  386. package/dist/internal/enrichWithPathMeta.js +0 -76
  387. package/dist/internal/enrichWithPathMeta.js.map +0 -1
  388. package/dist/internal/filterEditableFields.d.ts +0 -2
  389. package/dist/internal/filterEditableFields.js +0 -88
  390. package/dist/internal/filterEditableFields.js.map +0 -1
  391. package/dist/internal/gate.d.ts +0 -3
  392. package/dist/internal/gate.js +0 -16
  393. package/dist/internal/gate.js.map +0 -1
  394. package/dist/internal/globalAfterReadHook.d.ts +0 -12
  395. package/dist/internal/globalAfterReadHook.js +0 -19
  396. package/dist/internal/globalAfterReadHook.js.map +0 -1
  397. package/dist/internal/markTerminalUploads.d.ts +0 -13
  398. package/dist/internal/markTerminalUploads.js +0 -79
  399. package/dist/internal/markTerminalUploads.js.map +0 -1
  400. package/dist/internal/schemaCache.d.ts +0 -10
  401. package/dist/internal/schemaCache.js +0 -29
  402. package/dist/internal/schemaCache.js.map +0 -1
  403. package/dist/internal/shared.d.ts +0 -32
  404. package/dist/internal/shared.js +0 -55
  405. package/dist/internal/shared.js.map +0 -1
  406. package/dist/internal/stripStegaHook.js.map +0 -1
  407. /package/dist/client/{VisualEditingOverlay.d.ts → react/VisualEditingOverlay.d.ts} +0 -0
  408. /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,35 @@ 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.
11
+ Peer dependencies, all optional: `payload ^3.79`, `@payloadcms/ui ^3.79`, `react` and `react-dom` `^18.2.0 || ^19.0.0`. What you need depends on where you use the package:
12
12
 
13
- ## Compatibility
13
+ - The Payload app (the plugin and its admin components) needs `payload`, `@payloadcms/ui` and React 19, which Payload 3 requires anyway.
14
+ - A React frontend that imports `./client` needs `react` and `react-dom` 18.2 or newer.
15
+ - A site that imports only `./dom` needs none of them.
14
16
 
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`.
17
+ 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
18
 
17
19
  ## Setup
18
20
 
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.
21
+ 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 outside the admin: reads made with the **Local API**, and REST or GraphQL reads that send the `x-visual-editing` header with the session of a signed-in user, see [Pages without React](#pages-without-react). The steps below use the Local API and 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
22
 
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`
23
+ ### 1. Register the plugin
24
24
 
25
25
  ```ts
26
+ // payload.config.ts
26
27
  import { buildConfig } from 'payload'
27
28
  import { visualEditingPlugin } from '@focus-reactive/payload-plugin-visual-editing'
28
29
 
29
30
  export default buildConfig({
30
31
  // ...
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
- ],
32
+ plugins: [visualEditingPlugin()],
41
33
  })
42
34
  ```
43
35
 
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.
36
+ See [Options](#options) for what you can pass.
45
37
 
46
38
  ### 2. Enable drafts on editable collections
47
39
 
48
- The plugin only enriches **draft** reads, so each collection you want to edit visually needs Payload drafts turned on:
49
-
50
40
  ```ts
51
41
  export const Pages: CollectionConfig = {
52
42
  slug: 'pages',
@@ -55,9 +45,7 @@ export const Pages: CollectionConfig = {
55
45
  }
56
46
  ```
57
47
 
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):
48
+ ### 3. Add draft-mode routes
61
49
 
62
50
  ```ts
63
51
  // app/(frontend)/next/preview/route.ts
@@ -66,7 +54,6 @@ import { redirect } from 'next/navigation'
66
54
 
67
55
  export async function GET(req: Request) {
68
56
  const path = new URL(req.url).searchParams.get('path')
69
- // same-origin relative paths only — block open redirects
70
57
  if (!path || !path.startsWith('/') || path.startsWith('//')) {
71
58
  return new Response('Invalid path', { status: 400 })
72
59
  }
@@ -89,8 +76,6 @@ export async function GET(req: Request) {
89
76
 
90
77
  ### 4. Point Live Preview at the preview route
91
78
 
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
79
  ```ts
95
80
  export const Pages: CollectionConfig = {
96
81
  slug: 'pages',
@@ -107,9 +92,9 @@ export const Pages: CollectionConfig = {
107
92
  }
108
93
  ```
109
94
 
110
- ### 5. Fetch drafts in the frontend page
95
+ 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
96
 
112
- Read the document with `draft` tied to draft mode — stega is only embedded on draft reads:
97
+ ### 5. Read drafts in the frontend page
113
98
 
114
99
  ```tsx
115
100
  // app/(frontend)/[slug]/page.tsx
@@ -125,19 +110,17 @@ export default async function Page({ params }: { params: Promise<{ slug: string
125
110
  const { docs } = await payload.find({
126
111
  collection: 'pages',
127
112
  draft,
128
- depth: 1, // ≥ 1 so uploads/relationships populate (see "Editable richText and upload fields")
113
+ depth: 1,
129
114
  where: { slug: { equals: slug } },
130
115
  })
131
116
  // render docs[0]
132
117
  }
133
118
  ```
134
119
 
135
- With `enrichment: 'explicit'`, also pass `context: { visualEditing: draft }` — see [Enrichment modes](#enrichment-modes).
120
+ 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
121
 
137
122
  ### 6. Wrap the frontend layout
138
123
 
139
- Mount the provider (gated on draft mode), the toggle, and the overlay:
140
-
141
124
  ```tsx
142
125
  // app/(frontend)/layout.tsx
143
126
  import { VisualEditing } from '@focus-reactive/payload-plugin-visual-editing/client'
@@ -159,81 +142,521 @@ export default async function Layout({ children }: { children: React.ReactNode }
159
142
  }
160
143
  ```
161
144
 
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.
145
+ - `VisualEditing.Toggle` is the floating Off / Hover / Always control. It starts on **Off**: a page shows no outlines until the editor picks **Hover** or **Always**. The chosen mode is kept in `localStorage` under the key `visual-editing`, per origin of the page.
146
+ - `VisualEditing.Overlay` scans its children for markers. Content outside it is not touched.
165
147
 
166
- ### 7. Mark richText and upload fields
148
+ ### 7. Mark rich text, uploads and relationships
167
149
 
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).
150
+ 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
151
 
170
152
  ### 8. Regenerate the admin import map
171
153
 
172
- The bridge is registered as an admin component, so refresh Payload's import map (re-run after config changes):
173
-
174
154
  ```bash
175
155
  bunx payload generate:importmap
176
156
  ```
177
157
 
178
158
  ### Using it
179
159
 
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. A plain click anywhere on a highlighted element opens its field too; a modifier-click or a text selection keeps the page's normal behavior. To leave draft mode when viewing the frontend directly, hit `/next/exit-preview`.
160
+ 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
161
 
182
- ## Editable richText and upload fields
162
+ To leave draft mode in a normal browser tab, open `/next/exit-preview`.
183
163
 
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:
164
+ On a draft page where the overlay does not run (the toggle is **Off** and the page passes `instantPreview={false}`, or `framedOnly` outside the Live Preview), the markers are still removed from the text, every attribute, the title and the meta tags of `<head>`, also from content rendered later. There are no outlines and no instant preview there.
185
165
 
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.
166
+ ## What gets a marker
188
167
 
189
- For both, spread `withVisualEditingPath(value)` onto the element you want to receive the Edit badge.
168
+ - Fields of type `text`, `textarea` and `email`, at any depth: in groups, tabs, rows, collapsibles, array rows and blocks (declared inline or through `blockReferences`).
169
+ - 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.
170
+ - Not: empty values, and values that match `excludeValues` (by default URLs, slugs like `hello-world`, `#fragments` and ISO dates). A range of numbers such as `8-10` and a text that starts with a hash, such as `#1 in the ranking`, are marked.
171
+ - Not: fields named `slug`, `folder`, `_status`, `apiKey` or anything in `excludeFieldNames`.
172
+ - 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.
173
+ - Not: `text` fields with `hasMany`, numbers, selects, dates and other non-text fields.
174
+ - With `instantPreview` only: every text node of a Lexical rich text field, see [Markers in rich text](#markers-in-rich-text).
190
175
 
191
- ```tsx
192
- import { withVisualEditingPath } from '@focus-reactive/payload-plugin-visual-editing/client'
193
- ```
176
+ 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.
194
177
 
195
- ### RichText
178
+ If you render a marked value into an attribute, the overlay removes the marker from it: `alt`, `aria-label`, an `href`, a `style`, an `id`, a `data-*` attribute. It also cleans `document.title`. An image whose `alt` carries the marker of a field becomes the edit target of that field, usually the `alt` of the media document, unless the image already names its field with `withVisualEditingPath`. An element whose whole text is one marked field, such as a heading, gets the `data-ve-*` attributes of that field while the overlay runs, so it stays the edit target when a script of your site splits its text into words or characters after the overlay found it. The overlay cleans the page in the browser, so a value the template transforms before the browser sees it (a slug, a hash, a number it parses) keeps the invisible characters inside the transform: clean it first with `stripMarkers` or keep the field away with `excludeFieldNames`.
179
+
180
+ ## Rich text, uploads and relationships
181
+
182
+ 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
183
 
197
184
  ```tsx
185
+ import { withVisualEditingPath } from '@focus-reactive/payload-plugin-visual-editing/client'
198
186
  import { RichText } from '@payloadcms/richtext-lexical/react'
199
187
 
200
188
  <div {...withVisualEditingPath(page.content)}>
201
189
  <RichText data={page.content} />
202
190
  </div>
191
+
192
+ <img src={page.image.url} alt={page.image.alt} {...withVisualEditingPath(page.image)} />
193
+
194
+ <article {...withVisualEditingPath(page.author)}>
195
+ <h3>{page.author.name}</h3>
196
+ </article>
197
+ ```
198
+
199
+ 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.
200
+
201
+ | Field | Where the `_meta` is |
202
+ |---|---|
203
+ | rich text | `page.content` |
204
+ | upload or relationship | `page.image`, the populated document |
205
+ | `hasMany` | every populated document: `page.gallery[0]`, `page.gallery[1]`. Each addresses the field `gallery` |
206
+ | several `relationTo` | `page.image` (the `{ relationTo, value }` object) and `page.image.value` |
207
+
208
+ 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.
209
+
210
+ 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.
211
+
212
+ ## Instant preview
213
+
214
+ 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.
215
+
216
+ Turn it on in the plugin and regenerate the import map:
217
+
218
+ ```ts
219
+ // payload.config.ts
220
+ visualEditingPlugin({ instantPreview: true })
203
221
  ```
204
222
 
205
- ### Upload — single relationTo
223
+ The page half is on by default: `VisualEditing.Provider` and `mountVisualEditing` listen for the admin, and the admin sends nothing unless the plugin option is on. Pass `instantPreview={false}` (`instantPreview: false` without React) to a page that should not listen; with the toggle on **Off** the overlay then does not run at all and the page only loses its markers.
224
+
225
+ ### Requirements
226
+
227
+ - Live Preview is configured for the collection or global: `admin.livePreview` on it, or its slug in the root `admin.livePreview.collections` / `globals`.
228
+ - The frontend refreshes itself after a save, for example with `RefreshRouteOnSave` from `@payloadcms/live-preview-react`, see below.
229
+ - The admin posts to the origin of the Live Preview URL. The preview posts to `adminOrigin` on `VisualEditing.Provider`, its own origin by default.
230
+ - 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.
231
+ - 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, and an overlay of 1.2.0 or earlier cannot read the shorter markers this version writes and leaves every marker in the text.
232
+ - 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.
233
+
234
+ A refresh after every save, with Payload's own component:
235
+
236
+ ```bash
237
+ bun add @payloadcms/live-preview-react
238
+ ```
206
239
 
207
240
  ```tsx
208
- <img
209
- src={page.image.url}
210
- alt={page.image.alt}
211
- {...withVisualEditingPath(page.image)}
212
- />
241
+ // components/RefreshOnSave.tsx
242
+ 'use client'
243
+
244
+ import { RefreshRouteOnSave } from '@payloadcms/live-preview-react'
245
+ import { useRouter } from 'next/navigation'
246
+
247
+ export const RefreshOnSave = () => {
248
+ const router = useRouter()
249
+ const adminOrigin = typeof window === 'undefined' ? '' : window.location.origin
250
+ return <RefreshRouteOnSave refresh={() => router.refresh()} serverURL={adminOrigin} />
251
+ }
213
252
  ```
214
253
 
215
- ### Upload — polymorphic (`relationTo: ['media', 'videos']`)
254
+ ```tsx
255
+ // app/(frontend)/layout.tsx
256
+ {isEnabled && <RefreshOnSave />}
257
+ ```
258
+
259
+ `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.
260
+
261
+ ### What updates instantly
262
+
263
+ - `text`, `textarea` and `email` fields that have a marker on the page, the block name included.
264
+ - Text typed, deleted or replaced inside existing text of a Lexical rich text field: in paragraphs, headings, list items, quotes, links and formatted text.
265
+ - 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.
266
+ - Only where the page renders the stored value unchanged.
267
+ - In an element whose whole text is one field after a script of your site split that text into words or characters, while the element still shows the value the field had. The overlay writes the new value as plain text into the element, so the split and its animation are gone from the preview until the page reloads.
268
+ - In every toggle position, also **Off**. The toggle controls outlines, badges and click-to-edit only.
269
+
270
+ ### What waits for the save
271
+
272
+ - Every other field type: numbers, uploads, relationships, selects, checkboxes, dates, `code`, `json`, `text` with `hasMany`.
273
+ - 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.
274
+ - 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.
275
+ - 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.
276
+ - Text in the fields of a block inside rich text, Slate rich text, and a rich text field whose name contains `#`.
277
+ - 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.
278
+ - 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.
279
+ - 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.
280
+ - Localized fields, and all rich text, on a page that reads the document with `locale: 'all'`.
281
+
282
+ ### What is sent to the preview
283
+
284
+ 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:
285
+
286
+ 1. The field belongs to the document that is open in the admin form.
287
+ 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.
288
+ 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.
289
+ 4. The collection has no `auth`. Fields of auth collections are marked for click-to-edit but never sent.
290
+
291
+ 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`.
292
+
293
+ 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.
216
294
 
217
- Spread on `value`, not the wrapper:
295
+ 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. A page that renders rich text in the browser, with `renderValue` on `LiveRichText` or `renderRichTextValue` without React, also renders the posted state itself, with data Payload already gave that page, see [Rendering on the page with `renderValue`](#rendering-on-the-page-with-rendervalue) and [Rendered on the page first](#rendered-on-the-page-first).
296
+
297
+ 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.
298
+
299
+ `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.
300
+
301
+ 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`.
302
+
303
+ ### Unsaved rich text structure
304
+
305
+ 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.
306
+
307
+ Three pieces, all in your app. The component that renders rich text:
218
308
 
219
309
  ```tsx
220
- <img
221
- src={page.image.value.url}
222
- alt={page.image.value.alt}
223
- {...withVisualEditingPath(page.image.value)}
224
- />
310
+ // components/RichText/Body.tsx
311
+ import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
312
+
313
+ import { withVisualEditingPath } from '@focus-reactive/payload-plugin-visual-editing/client'
314
+ import { RichText } from '@payloadcms/richtext-lexical/react'
315
+
316
+ export const RichTextBody = ({ content }: { content: SerializedEditorState }) => (
317
+ <div {...withVisualEditingPath(content)}>
318
+ <RichText data={content} />
319
+ </div>
320
+ )
225
321
  ```
226
322
 
227
- Clicking the Edit badge on an upload opens the media document's admin page (not a field on the host doc).
323
+ A Server Action that renders the unsaved state with that same component:
324
+
325
+ ```tsx
326
+ // components/RichText/renderUnsavedRichText.tsx
327
+ 'use server'
328
+
329
+ import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
330
+
331
+ import { readUnsavedRichText } from '@focus-reactive/payload-plugin-visual-editing'
332
+ import config from '@payload-config'
333
+ import { draftMode, headers } from 'next/headers'
334
+ import { getPayload } from 'payload'
335
+
336
+ import { RichTextBody } from './Body'
337
+
338
+ export async function renderUnsavedRichText(request: unknown) {
339
+ const { isEnabled } = await draftMode()
340
+ if (!isEnabled) return null
341
+
342
+ const content = await readUnsavedRichText<SerializedEditorState>({
343
+ headers: await headers(),
344
+ payload: await getPayload({ config }),
345
+ request,
346
+ })
347
+ return content && <RichTextBody content={content} />
348
+ }
349
+ ```
350
+
351
+ And the component your pages use:
352
+
353
+ ```tsx
354
+ // components/RichText/index.tsx
355
+ import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
356
+
357
+ import { LiveRichText, liveRichTextOf } from '@focus-reactive/payload-plugin-visual-editing/client'
358
+
359
+ import { RichTextBody } from './Body'
360
+ import { renderUnsavedRichText } from './renderUnsavedRichText'
361
+
362
+ export const RichText = ({ content }: { content: SerializedEditorState }) => {
363
+ const body = <RichTextBody content={content} />
364
+ const liveRichText = liveRichTextOf(content)
365
+ if (!liveRichText) return body
366
+
367
+ return (
368
+ <LiveRichText {...liveRichText} action={renderUnsavedRichText}>
369
+ {body}
370
+ </LiveRichText>
371
+ )
372
+ }
373
+ ```
374
+
375
+ - `liveRichTextOf(content)` returns the identity of the field, the structure of the saved value, its `_meta` and whether it holds blocks, uploads, relationships or links to documents, about 300 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.
376
+ - 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.
377
+ - 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.
378
+ - `LiveRichText` renders no element of its own. Outside draft mode or with `instantPreview` off it only renders its children.
379
+ - Put it inside `VisualEditing.Overlay`. The overlay passes its `locale` on, and `LiveRichText` ignores the admin while it edits another locale.
380
+
381
+ `LiveRichText` makes one call at a time and only the latest state waits. It starts a call 200 ms after the first new structure, so the structures of one edit (Enter, then the first character of the new paragraph) make one call. 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.
382
+
383
+ **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.
384
+
385
+ **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.
386
+
387
+ `readUnsavedRichText` is the only safe way to turn the posted state into something to render on the server. Hand it the argument of the action untouched. It guarantees:
388
+
389
+ - **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 and uploads and the extra fields of links come from the saved document by node id, and related documents are reduced to their ids. The target of a link (`doc`, `linkType`, `newTab`, `url`) and the document a relationship or upload node refers to come from the posted state, and Payload populates them with the access of the user. Called from your Server Action, `readUnsavedRichText` therefore resolves a reference the editor has just added; the endpoint does not, see [How the page is allowed to read the unsaved value](#how-the-page-is-allowed-to-read-the-unsaved-value).
390
+ - **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.
391
+ - **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`.
392
+
393
+ 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.
394
+
395
+ | `readUnsavedRichText` argument | Purpose |
396
+ |---|---|
397
+ | `payload` | The Payload instance. |
398
+ | `request` | The argument `LiveRichText` passed to the action, or the `Request` a route handler received. Untrusted input: hand it over as it is. |
399
+ | `headers` | The headers of the request, with the argument of an action. The user is read from them. A `Request` brings its own. |
400
+ | `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. |
401
+ | `maxStateLength` | Longest accepted editor state, in characters of JSON. |
402
+ | `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. |
403
+ | `readWholeDocument` | `true` reads every field of the document, as 1.2.0 did. By default only the top-level field that holds the rich text is read, see [Upgrading from 1.2.0](#upgrading-from-120). |
404
+
405
+ 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. The read selects only the top-level field that holds the rich text (`layout` for a rich text in a block of `layout`), so a hook that reads other fields of the document sees them missing; pass `readWholeDocument: true` for such a hook.
406
+
407
+ 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 top-level field that holds it once. The draft mode check stays in your action because it is specific to Next.js; `readUnsavedRichText` does not depend on Next.
408
+
409
+ #### Rendering on the page with `renderValue`
228
410
 
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.
411
+ With a Server Action alone a structural edit shows one round trip after the admin posts it. When your rich text renderer can run as a Client Component, pass it as `renderValue` and the page shows the structure as it arrives: it builds the value Payload would answer from the posted editor state and data Payload already gave the page, with the same markers and `_meta`, and renders it with your function. A function cannot cross from a Server Component to a Client Component, so `renderValue` is set in a client module of your site:
412
+
413
+ ```tsx
414
+ // components/RichText/LiveBody.tsx
415
+ 'use client'
416
+
417
+ import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
418
+ import type { ReactNode } from 'react'
419
+
420
+ import {
421
+ LiveRichText,
422
+ type LiveRichTextIdentity,
423
+ } from '@focus-reactive/payload-plugin-visual-editing/client'
424
+
425
+ import { RichTextBody } from './Body'
426
+ import { renderUnsavedRichText } from './renderUnsavedRichText'
427
+
428
+ export const LiveBody = (props: LiveRichTextIdentity & { children: ReactNode }) => (
429
+ <LiveRichText
430
+ {...props}
431
+ action={renderUnsavedRichText}
432
+ renderValue={(value: SerializedEditorState) => <RichTextBody content={value} />}
433
+ />
434
+ )
435
+ ```
436
+
437
+ ```tsx
438
+ // components/RichText/index.tsx
439
+ import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
440
+
441
+ import { liveRichTextOf } from '@focus-reactive/payload-plugin-visual-editing/client'
442
+
443
+ import { RichTextBody } from './Body'
444
+ import { LiveBody } from './LiveBody'
445
+
446
+ export const RichText = ({ content }: { content: SerializedEditorState }) => {
447
+ const body = <RichTextBody content={content} />
448
+ const liveRichText = liveRichTextOf(content)
449
+ return liveRichText ? <LiveBody {...liveRichText}>{body}</LiveBody> : body
450
+ }
451
+ ```
452
+
453
+ Where the check with the server goes depends on `payloadApi` of `VisualEditing.Provider`:
454
+
455
+ | Setup | On the page | Check with the server |
456
+ |---|---|---|
457
+ | `action` | nothing | 200 ms after the first new structure, as above |
458
+ | `action`, `renderValue` | at once | the action, 350 ms after the last structure; its result replaces the render on the page |
459
+ | `action`, `renderValue`, `payloadApi` | at once | the `unsaved-rich-text` endpoint, 350 ms after the last structure, rendered with `renderValue` |
460
+
461
+ ```tsx
462
+ <VisualEditing.Provider available={isEnabled} payloadApi="https://cms.example.com/api">
463
+ ```
464
+
465
+ A provider that is given `adminOrigin` finds the API at `<adminOrigin>/api` on its own.
466
+
467
+ - **With `payloadApi`** the page asks the endpoint with the preview grant the admin posts, as a page without React does, see [How the page is allowed to read the unsaved value](#how-the-page-is-allowed-to-read-the-unsaved-value). The answer goes through the same `renderValue`, so React updates the elements in place and nothing changes on screen when Payload agrees. The call is a `fetch`: it can be cancelled and does not hold `router.refresh()` back. While the page holds no grant, the action is called.
468
+ - **With the action alone** its result replaces the render on the page after the pause. It renders on the server, so React mounts its elements anew: the page looks the same, but an `iframe` in a block loads again. An action that returns `null` leaves the render on the page.
469
+ - **A field with blocks, uploads, relationships or links to documents** needs its saved value for the fields of saved blocks and the documents Payload populated. With `payloadApi` the page asks the endpoint for the saved value of that field once the editor types in it or changes its structure, and adds every answer Payload gives; when the saved value arrives, the structure the editor holds renders on the page. Without `payloadApi`, such a field waits for the action. A save forgets every saved value; the page asks again when a structure with blocks, uploads, relationships or links to documents needs it. A structure without them never needs one. A newly inserted upload or relationship appears with the answer of the server, a new link to a document links to its id until then, and a new block shows only its id and type.
470
+ - **The same renderer on the client and on the server.** `renderValue` must render the same markup for the same value as the component your page and your action render with, best the very same component. Markup that differs swaps once the server answers.
471
+ - **`renderValue` runs in the browser** with a value that did not pass through your Payload hooks. When it throws, or the elements it returns throw while rendering, that structure shows the saved render and waits for the server.
472
+ - An identity printed by `liveRichTextOf` of 1.2.0, without `meta` and `hasReferences`, waits for the server.
473
+ - **After a save that renders the page again**, the children you pass are the saved render. Until they change, for example in a popup preview that does not refresh, `LiveRichText` takes the render it showed for the structure the editor saved as the saved render.
474
+
475
+ ### Markers in rich text
476
+
477
+ With `instantPreview` on, a draft read puts a marker of roughly 50 to 60 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.
478
+
479
+ 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.
480
+
481
+ ```ts
482
+ import { stripMarkers } from '@focus-reactive/payload-plugin-visual-editing'
483
+
484
+ const minutes = readingTime(stripMarkers(post.content))
485
+ const excerpt = stripMarkers(post.excerpt)
486
+ ```
487
+
488
+ `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.
489
+
490
+ ### Opting out
491
+
492
+ 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.
493
+
494
+ ```tsx
495
+ <h1 data-ve-live="off">{title.toLowerCase()}</h1>
496
+ ```
497
+
498
+ ### Limitations
499
+
500
+ - 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.
501
+ - 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.
502
+ - 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.
503
+ - Rich text that is not wrapped in `LiveRichText`:
504
+ - 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.
505
+ - 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.
506
+ - Rich text in `LiveRichText`:
507
+ - With `action`, the setup needs the App Router and a Server Action. The Pages Router has none: pass `render` with a transport of your own, and with `renderValue` and `adminOrigin` (or `payloadApi`) the page renders a structure itself and checks it through the `unsaved-rich-text` endpoint. A frontend without React uses `./dom`, see [Pages without React](#pages-without-react).
508
+ - While a Server Action call is out, `router.refresh()` waits for it, see [Unsaved rich text structure](#unsaved-rich-text-structure).
509
+ - A Server Action is called with the cookies of the preview page. A preview on another origin than the admin has no Payload session there; the answer of the action is `null`. Such a page passes `renderValue` and `adminOrigin` (or `payloadApi`): the endpoint is asked with the preview grant, which needs no session, see [How the page is allowed to read the unsaved value](#how-the-page-is-allowed-to-read-the-unsaved-value). Without them the structure appears with the save.
510
+ - Without `renderValue`, 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.
511
+ - 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.
512
+ - 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.
513
+ - An editor state longer than `maxStateLength` is not rendered before the save.
514
+ - A field the page renders twice makes two calls per structural edit, one per place.
515
+ - 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.
516
+ - 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.
517
+ - 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.
518
+ - The popup keeps unsaved text on screen after you leave the document without saving. It shows the saved content again when it reloads.
519
+ - 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.
520
+
521
+ ## Pages without React
522
+
523
+ `./dom` runs the same overlay, mode toggle and instant preview on a page that has no React: a static site generator, server templates, Vue, Svelte. It does not import React. The server half and the admin are the same as above.
524
+
525
+ ### 1. Read drafts over HTTP with the header
526
+
527
+ A page that reads Payload through REST or GraphQL asks for markers with the `x-visual-editing` header on a draft read (`draft=true`). Only the presence of the header counts, its value does not. The read is marked only for a signed-in user, so send the session of a Payload user with it.
528
+
529
+ ```ts
530
+ const response = await fetch(`${CMS_URL}/api/pages?where[slug][equals]=home&draft=true`, {
531
+ headers: { Cookie: session, 'x-visual-editing': '1' },
532
+ })
533
+ ```
534
+
535
+ A published read, a read without the header and an anonymous read get no markers. Leave the header out of production builds.
536
+
537
+ A build or a preview function has no browser session, so it signs in as a user of its own, best a service user that may read drafts and nothing else. Any way Payload authenticates a request works:
538
+
539
+ - Log in once with `POST /api/users/login` (`{ email, password }`) and send the `token` of the answer as `Authorization: JWT <token>` or `Authorization: Bearer <token>`, or as the `payload-token` cookie.
540
+ - With `auth.useAPIKey` on the users collection, send `Authorization: users API-Key <key>`.
541
+
542
+ `enrichment: 'explicit'` does not turn these reads off: it is about Local API reads, and the header is already an explicit request.
543
+
544
+ ### 2. Mount it on the page
545
+
546
+ Load this only in the preview, after the page has rendered:
547
+
548
+ ```ts
549
+ import { mountVisualEditing } from '@focus-reactive/payload-plugin-visual-editing/dom'
550
+
551
+ mountVisualEditing({
552
+ adminOrigin: 'https://cms.example.com',
553
+ framedOnly: true,
554
+ locale: 'en',
555
+ onSave: () => location.reload(),
556
+ })
557
+ ```
558
+
559
+ | Option | Default | Purpose |
560
+ |---|---|---|
561
+ | `root` | `document.body` | Element the overlay scans for markers. |
562
+ | `available` | `true` | `false` leaves the page alone, for a page read without drafts. |
563
+ | `adminOrigin` | the page's origin | Origin of the admin window, with its scheme: `https://cms.example.com`. Required when the admin runs on another origin. A value that is no `http` or `https` URL, such as `cms.example.com`, is ignored: the page then talks to its own origin and asks no `payloadApi`. |
564
+ | `framedOnly` | `false` | Only run inside the Live Preview: its iframe or the window it opens. Elsewhere it only removes the markers from `root` and `<head>`. |
565
+ | `instantPreview` | `true` | Text typed in the admin appears on the page, once the plugin option is on. `false` keeps the page from listening. |
566
+ | `locale` | none | Locale of the page, see [Requirements](#requirements). |
567
+ | `toggle` | `true` | Shows the Off / Hover / Always toggle. |
568
+ | `onSave` | none | Called after the admin saves the document, autosave included. |
569
+ | `payloadApi` | `<adminOrigin>/api` when `adminOrigin` is set | URL of the Payload REST API, where the page asks the `unsaved-rich-text` endpoint for unsaved rich text. Set it when `routes.api` of your Payload config is not `/api` or the API is served from another origin than the admin; an empty string keeps the page from asking. |
570
+ | `renderRichTextValue`, `renderRichText` | none | Unsaved rich text structure, see below. |
571
+ | `optimistic` | `true` | With `renderRichTextValue`, render a new structure on the page before the server answers, see [Rendered on the page first](#rendered-on-the-page-first). `false` waits for the server. |
572
+ | `adminBasePath`, `buildAdminEditUrl` | as for `VisualEditing.Provider` | |
573
+
574
+ It returns `{ destroy }`.
575
+
576
+ What to pass depends on what the page should do:
577
+
578
+ | Goal | Plugin | `mountVisualEditing` and templates |
579
+ |---|---|---|
580
+ | Click-to-edit | nothing | `adminOrigin`, when the admin runs on another origin |
581
+ | Text shows while it is typed | `instantPreview: true` | `adminOrigin`; `onSave`, or a reload of your own after a save |
582
+ | Paragraphs, lists and formatting show before the save | `instantPreview: true` | also `richTextAttributes(value)` on the wrapper of the rich text and `renderRichTextValue`, see [Unsaved rich text on a page without React](#unsaved-rich-text-on-a-page-without-react) |
583
+
584
+ The toggle starts on **Off**, as on a React page: the mode is kept in `localStorage` under `visual-editing`, per origin, so an editor picks **Hover** or **Always** once on each site.
585
+
586
+ Nothing reloads the page after a save unless you say so. `onSave` is called each time the editor saves the document, autosave included, and never when the page loads; `() => location.reload()` is the usual value. Without `onSave` and without a reload of your own, the page keeps the content it loaded with: typed text stays on screen through instant preview, and everything that waits for the save never appears. A site that already reloads its preview after a save should leave `onSave` out, or it reloads twice.
587
+
588
+ `onSave` follows `ve:document-saved`, a message the plugin's admin posts after Payload reports a save. The message names the saved document (`collectionSlug`, `kind`, `docId`) and the locale of the admin; `onSave` is called for every one of them, also for a document saved in a drawer. Do not use Payload's own `payload-document-event` for this: Payload also sends it once right after the page reports that it is ready, without a save, and a page that reloads on it reloads once for nothing.
589
+
590
+ ### 3. Mark rich text, uploads and relationships
591
+
592
+ `withVisualEditingPath(value)` returns the attributes as an object. Print them on the element in your template. For a rich text field that should update its structure before the save, print `richTextAttributes(value)` instead: it adds `data-ve-live-rich-text`, the identity and shape of the saved value. Both functions run in Node, at build time.
593
+
594
+ A marked text carries invisible characters. Where a template turns text into an `id`, an anchor, a CSS selector or a value it compares, clean it first with `stripMarkers(value)`, also exported from `./dom`: `{{ service.title | stripMarkers | slugify }}`.
595
+
596
+ ```njk
597
+ <div {% for name, value in richTextAttributes(page.content) %}{{ name }}="{{ value }}" {% endfor %}>
598
+ {{ page.content | richTextHtml | safe }}
599
+ </div>
600
+ ```
601
+
602
+ The example relies on Nunjucks escaping what it prints (`autoescape`, on by default and in Eleventy): the value of `data-ve-live-rich-text` is JSON and must reach the page with its quotes escaped. With autoescape off, or in a template language that does not escape, print the value through its escape filter, here `{{ value | escape }}`.
603
+
604
+ ### Unsaved rich text on a page without React
605
+
606
+ Text typed inside existing text of a rich text field updates through the markers, as on a React page. A new paragraph, a list or a bold word needs your renderer. `./dom` replaces the content of the element that carries `data-ve-live-rich-text` with the HTML of the unsaved value, and puts the saved HTML back when the editor returns to the saved structure. After a save without a reload, the HTML it shows for the structure the editor saved becomes the saved HTML, so the page shows what was saved when the editor returns to it and renders the structure it loaded with as unsaved. Choose where that HTML is made:
607
+
608
+ | | Where the HTML is made | Plugin | `mountVisualEditing` |
609
+ |---|---|---|---|
610
+ | In Payload | `renderHtml` in the plugin config | `instantPreview: true, renderHtml` | `adminOrigin` (or `payloadApi`) |
611
+ | On the site | your function, from the value Payload reads | `instantPreview: true` | `adminOrigin` (or `payloadApi`), `renderRichTextValue` |
612
+ | Anywhere | your own call | as you need | `renderRichText` |
613
+
614
+ ```ts
615
+ visualEditingPlugin({
616
+ instantPreview: true,
617
+ renderHtml: ({ value }) => toSiteHtml(value),
618
+ })
619
+
620
+ mountVisualEditing({ adminOrigin: 'https://cms.example.com' })
621
+ ```
622
+
623
+ `renderHtml` gets the value with the markers of a draft read, the field, the locale and the request. Render it with the same converter the site uses: the HTML replaces the saved HTML in place, and markup that differs flickers when the saved render comes back. There is no default converter for that reason.
624
+
625
+ `renderRichTextValue(value, signal)` gets the same value on the page and returns HTML, or a promise of it. `renderRichText(request, signal)` gets the request itself; hand it to `readUnsavedRichText` on your own server.
626
+
627
+ The HTML of `renderHtml`, `renderRichTextValue` and `renderRichText` is written into the element with `innerHTML`, as it is. The value holds what an editor typed and has not passed the validation of a save, so the renderer must escape every text it prints and check every URL it writes into an `href` or `src` (allow `http:`, `https:`, `mailto:` and relative addresses, refuse `javascript:`), as the renderer of the built site must. `convertLexicalToHTML` of Payload 3.90 escapes text and sanitizes the URL of a link; a converter of your own for a link, an upload or a block has to do both.
628
+
629
+ `./dom` finds the elements that carry `data-ve-live-rich-text` when `mountVisualEditing` runs. An element added later, by a client-side navigation or a script, is not live: call `destroy()` and `mountVisualEditing` again after the page has replaced its content. Text typed into existing text needs no new mount, the overlay follows the page.
630
+
631
+ #### Rendered on the page first
632
+
633
+ With `renderRichTextValue`, the page does not wait for Payload. When the admin posts a new structure, the page builds the value Payload would answer from the posted editor state and data Payload already gave this page, with the same markers and `_meta`, renders it with `renderRichTextValue` and shows it at once. Payload is asked once the editor pauses, 350 ms after the last structure, and its answer replaces the HTML only when it renders differently. Enter followed by the first letter of a new paragraph renders twice on the page and asks Payload once.
634
+
635
+ - **A field of paragraphs, headings, lists and links to URLs** needs nothing else: no request until the pause, and no `payloadApi` to render on the page.
636
+ - **A field with blocks, uploads, relationships or links to documents** needs the saved value of the field, the base, for the fields of saved blocks, uploads and links and for the documents Payload populated. The page asks the `unsaved-rich-text` endpoint for it, without a state, once the editor types in that field or changes its structure, and adds every answer Payload gives for a structure to it. Until the base arrives, a structure of that field goes through Payload as without this option; when it arrives, the structure renders on the page. Without `payloadApi` there is no base, and such a field waits for `renderRichText`. A base that did not arrive is asked for again. A save forgets every base; the page asks again when a structure with blocks, uploads, relationships or links to documents needs it. A structure without them renders on the page without a base, also after a save.
637
+ - **What only Payload knows appears with its answer.** A newly inserted upload or relationship is left out until then, a new link to a document links to its id, and a new block shows only its id and type, as it does in Payload's answer before the save.
638
+ - **`renderRichTextValue` runs in the browser**, so the converter ships in the bundle of the preview page. `convertLexicalToHTML` from `@payloadcms/richtext-lexical/html` bundles for the browser as it is: `renderRichTextValue: (data) => convertLexicalToHTML({ data })`. It gets a value that did not pass through your Payload hooks. It must render the same markup for the same value as the build of the site does, or the page swaps the HTML once Payload answers. When it throws for a structure, that structure goes through Payload. It may return a promise; the HTML is shown when it resolves.
639
+ - **Pass `optimistic: false`** to wait for Payload for every structure, as 1.2.0 did. A page whose `data-ve-live-rich-text` was printed by `richTextAttributes` of 1.2.0 has no `_meta` in it and waits for Payload too; build it again.
640
+
641
+ `renderHtml` in Payload and your own `renderRichText` cannot render on the page. They start a call 200 ms after the first new structure, as `LiveRichText` does, and gain from the read of one field described in [Upgrading from 1.2.0](#upgrading-from-120).
642
+
643
+ With both `renderRichTextValue` and `renderRichText`, the page renders a structure itself and checks it as `LiveRichText` does with `renderValue` and an action: through the `unsaved-rich-text` endpoint while it holds a grant, rendered with `renderRichTextValue`, and through `renderRichText` otherwise. Pass `payloadApi: ''` to check through `renderRichText` alone.
644
+
645
+ #### How the page is allowed to read the unsaved value
646
+
647
+ The admin and the page often run on different origins, so the page cannot send the admin's session cookie. With `instantPreview` on, the plugin adds two endpoints:
648
+
649
+ - `POST /api/visual-editing/preview-grant`. The admin asks it, with the editor's session, for a grant of the document open in the form. The grant names the user and the document, expires after ten minutes and is signed with a key derived from the Payload secret. The admin posts it to the preview window, only to the origin of the Live Preview URL: once to every page that loads there or asks for it, and again when it has renewed the grant, which it checks every four minutes while the form is open.
650
+ - `POST /api/visual-editing/unsaved-rich-text`. The page posts the grant and the request as `text/plain`, which needs no CORS preflight. The endpoint reads the posted state as `readUnsavedRichText` does, with the access of the user in the grant and only for the document in the grant, and answers the origin of the request. A request without `state` gets the saved value of the field, read the same way. In both answers a relationship, upload or internal link node is populated only when the saved value of the same field refers to the same document (the same `relationTo` and id), and never when it refers to an auth collection or a collection whose slug starts with `payload-`; every other reference stays an id. A reference the editor adds therefore shows on the page after the save. `renderHtml` gets a request whose `user` is the user of the grant. It waits up to eight seconds for the read, longer than the three seconds `readUnsavedRichText` allows by default, because no router queue waits behind a `fetch`. It writes nothing.
651
+
652
+ A grant is a bearer token: a script on the preview page can read it, as it can read every value the admin posts there. For ten minutes it lets the holder read the rich text fields of one document, saved or with a posted structure, with the access of the user who opened it, together with the documents the saved rich text of that field already refers to, populated as that user may read them. It reads no other field of the document and no document the posted state names on its own. The blocks of a posted state get their fields from the saved document, so what they populate is what the saved document refers to.
230
653
 
231
654
  ## Enrichment modes
232
655
 
233
- The `enrichment` option decides which reads get stega.
656
+ `enrichment` decides which reads get markers.
234
657
 
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.
658
+ - **`'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.
659
+ - **`'explicit'`**: only reads that pass `context: { visualEditing: true }`.
237
660
 
238
661
  ```ts
239
662
  const { isEnabled: draft } = await draftMode()
@@ -246,44 +669,125 @@ await payload.find({
246
669
  })
247
670
  ```
248
671
 
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.
250
-
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.
252
-
253
- ## How it works
254
-
255
- ### Server pipeline
672
+ In both modes `context.visualEditing` wins when it is set: `true` marks the read, `false` leaves it clean. `true` marks any read it is passed to, also a published one, so pass the draft flag as above and never a constant `true`.
256
673
 
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).
674
+ `enrichment` is about Local API reads. A REST or GraphQL draft read that sends the `x-visual-editing` header with a signed-in user is marked in both modes.
262
675
 
263
- The schema cache (per slug, memoized) resolves relationship targets lazily so you don't pay for unused collections.
264
-
265
- ### Client overlay
266
-
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.
676
+ 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.
268
677
 
269
678
  ## Options
270
679
 
271
680
  | Option | Type | Default | Purpose |
272
681
  |---|---|---|---|
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). |
278
-
279
- The `VisualEditing.Provider` (client) also accepts `framedOnly` (restrict the overlay to the CMS preview iframe) and `adminBasePath` (must match the server option).
682
+ | `skipCollections` | `string[]` | `[]` | Collections the plugin does not mark. Payload's internal collections are always skipped. |
683
+ | `skipGlobals` | `string[]` | `[]` | Globals the plugin does not mark. |
684
+ | `excludeFieldNames` | `string[]` | `[]` | Field names that are never marked and never sent to the preview, in addition to `_status`, `folder`, `slug` and `apiKey`. |
685
+ | `excludeValues` | `((value: string) => boolean)[]` | `defaultExcludeValues` | Values that are not marked. Replaces the defaults (`isUrl`, `isSlug`, `isHash`, `isIsoDate`, all exported). |
686
+ | `adminBasePath` | `string` | `/admin` | Admin base path. Reads from below it are not marked; the bridge uses it to recognise the open document. A slash at its end is ignored. |
687
+ | `enrichment` | `'auto' \| 'explicit'` | `'auto'` | See [Enrichment modes](#enrichment-modes). |
688
+ | `instantPreview` | `boolean` | `false` | See [Instant preview](#instant-preview). |
689
+ | `renderHtml` | `({ value, field, locale, req }) => string \| Promise<string>` | none | Renders unsaved rich text to HTML for a page without React, see [Pages without React](#unsaved-rich-text-on-a-page-without-react). |
690
+ | `readWholeDocument` | `boolean` | `false` | The `unsaved-rich-text` endpoint reads every field of the document instead of the top-level field that holds the rich text. For `afterRead` hooks that need other fields, see [Upgrading from 1.2.0](#upgrading-from-120). |
691
+
692
+ `LiveRichText` props:
693
+
694
+ | Prop | Purpose |
695
+ |---|---|
696
+ | `field`, `shape`, `meta`, `hasReferences` | From `liveRichTextOf(value)`: spread its whole result. `field` and `shape` identify the saved value; `meta` and `hasReferences` are what a render on the page with `renderValue` needs, and without them the field waits for the server. |
697
+ | `action` | A Server Action that renders the unsaved state. It is called with the request only. |
698
+ | `render` | In place of `action`: `(request, signal) => Promise<ReactNode>`, a call you make yourself. |
699
+ | `renderValue` | `(value) => ReactNode`, your rich text renderer as a Client Component. Renders a structure on the page as it arrives, see [Rendering on the page with `renderValue`](#rendering-on-the-page-with-rendervalue). |
700
+ | `children` | The saved render. |
701
+
702
+ `VisualEditing.Provider` props:
703
+
704
+ | Prop | Default | Purpose |
705
+ |---|---|---|
706
+ | `available` | `false` | Turns the overlay on. Pass the draft mode flag. |
707
+ | `framedOnly` | `false` | Only run inside the Live Preview: its iframe or the window it opens. Elsewhere a draft page only loses its markers. |
708
+ | `adminBasePath` | `/admin` | Must match the plugin option. |
709
+ | `adminOrigin` | the page's origin | Origin of the admin window, with its scheme: `https://cms.example.com`. A value that is no `http` or `https` URL is ignored: the page then talks to its own origin and asks no `payloadApi`. |
710
+ | `instantPreview` | `true` | See [Instant preview](#instant-preview). `false` keeps the page from listening to the admin. |
711
+ | `buildAdminEditUrl` | built in | Builds the link used when the page was not opened from the admin. A link without an origin opens on `adminOrigin`. |
712
+ | `payloadApi` | `<adminOrigin>/api` when `adminOrigin` is set | URL of the Payload REST API, such as `https://cms.example.com/api`. With `renderValue` on `LiveRichText`, unsaved rich text is checked through the `unsaved-rich-text` endpoint instead of the action. |
713
+
714
+ ## Reads with every locale
715
+
716
+ 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.
717
+
718
+ 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.
719
+
720
+ ## Upgrading from 1.2.0
721
+
722
+ Regenerate the import map. The plugin adds `PreviewPageBridge` to every collection and global with Live Preview, and `OpenFormAnnouncer` to every collection and global it marks, both also with `instantPreview` off. Without `OpenFormAnnouncer` in the import map a link with `?veFocus` waits 15 seconds before it focuses the field.
723
+
724
+ - **A click on a page served from another origin than the admin opens the field.** The admin used to accept clicks only from its own origin. It now also accepts them from the Live Preview window, on the origin of its URL.
725
+ - **The page no longer posts a click to any origin.** Without `adminOrigin` it posts to its own origin, as instant preview already did.
726
+ - **Draft reads over REST and GraphQL can be marked.** Only with the `x-visual-editing` header and a signed-in user, see [Pages without React](#pages-without-react). Reads that do not send the header are unchanged.
727
+ - **With `instantPreview` on, the plugin adds two endpoints** under `/api/visual-editing/`, see [How the page is allowed to read the unsaved value](#how-the-page-is-allowed-to-read-the-unsaved-value). A grant issued before a deploy that changes how it is signed is refused once; the admin asks for a new one when the page asks again or within four minutes.
728
+ - **A draft page without the overlay loses its markers.** With the toggle on **Off** and instant preview off, or with `framedOnly` in a normal tab, the page used to keep every marker, and a script that splits text into characters rendered them as empty boxes. `VisualEditing.Overlay` and `mountVisualEditing` now remove them from the text, every attribute, the title and `<head>`, and put them back when they unmount. A script that reads marked text from the page after that sees clean text.
729
+ - **The meta tags of `<head>` lose their markers while the overlay runs**, like the title already did.
730
+ - **A structural rich text edit makes one render call, not one per structure.** `LiveRichText` and the rich text of `mountVisualEditing` wait 200 ms after a new structure before they start a call. Enter followed by typing used to start two calls in a row and showed the new text only after both.
731
+ - **A page without React renders a structural edit itself.** With `renderRichTextValue`, `mountVisualEditing` shows the new structure as the admin posts it and asks Payload 350 ms after the last one, see [Rendered on the page first](#rendered-on-the-page-first). Your `renderRichTextValue` now also runs on every structure, in the browser. A page that also passes `renderRichText` is checked through the `unsaved-rich-text` endpoint while it holds a grant, and through `renderRichText` otherwise. Print `richTextAttributes` again: its attribute now carries the `_meta` of the value and whether it holds references. Pass `optimistic: false` to keep the old behaviour.
732
+ - **An unsaved rich text read reads one field, not the whole document.** `readUnsavedRichText` and the `unsaved-rich-text` endpoint pass `select` with the top-level field that holds the rich text, so Payload no longer reads and populates every other field of the document for each structural edit. Collection and field `afterRead` hooks of your project see only that field during the read. A hook that needs another field (a slug, a sibling value) should pass `readWholeDocument: true` to `readUnsavedRichText` and set the plugin option `readWholeDocument: true` for the endpoint.
733
+ - **`LiveRichText` can render a structural edit on the page.** Pass your renderer as `renderValue` from a client module, and `payloadApi` to `VisualEditing.Provider` to check it through the endpoint instead of the action, see [Rendering on the page with `renderValue`](#rendering-on-the-page-with-rendervalue). Without `renderValue` nothing changes. `liveRichTextOf` now also returns the `_meta` of the value and whether it holds references; spread its whole result into `LiveRichText`.
734
+ - **An element whose whole text is one marked field gets that field's `data-ve-*` attributes while the overlay runs.** A heading that a script of your site splits into words after the overlay found it stays an edit target and keeps its instant text; the overlay then writes the new value as plain text into it, which resets the split until the page reloads. The attributes are removed when the overlay unmounts. A CSS selector of your site on `[data-ve-path]` now also matches these elements.
735
+ - **Markers are about half as long.** A marker used to spell out the names of its properties and state the path of a row twice, about 1.6 KB of UTF-8 for a field in a row; it now holds the same identity as a short list. Upgrade the server and the frontend together: the overlay of this version reads both forms, an overlay of 1.2.0 does not read the new one and leaves it in the text. Code of your own that decodes a marker with `vercelStegaDecode` gets the list; `stripMarkers` and `vercelStegaClean` work as before. A block name the page never shows still costs a marker in every block: add `blockName` to `excludeFieldNames` to leave it out.
736
+ - **The page half of instant preview is on by default.** `instantPreview` of `VisualEditing.Provider` and `mountVisualEditing` used to be `false`. The admin still sends nothing unless the plugin option is on, so a site without the plugin option sees one difference: with the toggle on **Off** the overlay runs instead of the marker cleaner, which costs a few milliseconds more on a page with some hundred marked texts. Pass `instantPreview={false}` to keep the old behaviour.
737
+ - **`payloadApi` is `<adminOrigin>/api` when `adminOrigin` is set.** A page that names its admin origin and prints `richTextAttributes` or passes `renderValue` now asks the `unsaved-rich-text` endpoint without being given `payloadApi`. Pass `payloadApi` when your API is elsewhere, or an empty string to keep the page from asking.
738
+ - **The mode toggle lives in a shadow root.** Its element is `[data-ve-toggle]` on `<body>`, and its buttons and styles are inside its shadow root, so styles of the site no longer reach them and the toggle no longer inherits fonts or resets. `[data-ve-toggle-root]`, `[data-ve-toggle-btn]` and the `<style id="ve-toggle-styles">` element are gone: a selector or a test of your own that used them finds nothing. Reach a button through `document.querySelector('[data-ve-toggle]').shadowRoot`; the buttons are `button[data-mode]` with `role="radio"`.
739
+ - **`isSlug` and `isHash` exclude less, so more values are marked.** `isSlug` now needs a letter: `8-10` and `10-20-30` are marked, `top-10` and `a-1` still are not. `isHash` now needs a value without white space: `#1 in the ranking` is marked, `#demo` and `#` still are not. A project that passes its own `excludeValues` with these two gets the new behaviour; write your own predicate to keep the old one.
740
+ - **All peers are optional, and `react` and `react-dom` accept `^18.2.0` again.** The Payload app still needs `payload`, `@payloadcms/ui` and React 19. A site that installs the package only for `./dom` gets none of them, and a site that keeps React 18 for something else can install it.
741
+
742
+ ## Upgrading from 1.1.1
743
+
744
+ No config change is needed. Regenerate the import map when you turn `instantPreview` on: it adds `InstantPreviewBroadcaster` and `OpenFormAnnouncer`.
745
+
746
+ 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.
747
+
748
+ Globals:
749
+
750
+ - **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.
751
+ - **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`.
752
+ - **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.
753
+ - **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.
754
+
755
+ Markers:
756
+
757
+ - **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.
758
+ - **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.
759
+ - **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.
760
+ - **`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 `{}`.
761
+ - **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.
762
+ - **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.
763
+ - **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.
764
+ - **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.
765
+ - **`blockName`.** Still marked, except for a block with `admin.disableBlockName`. A click now focuses the name input in the block header.
766
+ - **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`.
767
+ - **Otherwise unchanged while `instantPreview` is off.** With the option on:
768
+ - 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`.
769
+ - 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`.
770
+ - 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.
771
+
772
+ - 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.
773
+ - 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.
774
+
775
+ Overlay:
776
+
777
+ - **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.
778
+ - **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. It is now added with `instantPreview` off as well, because a link with `?veFocus` waits for it.
280
779
 
281
780
  ## Caveats
282
781
 
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).
782
+ - **Click-to-edit works across origins only from the Live Preview.** The admin accepts a click from its own origin, and from the Live Preview iframe or the window it opens, on the origin of the Live Preview URL; pass `adminOrigin` to the page. A page on another origin that has no admin window behind it, such as one opened from a bookmark, opens the field in a new admin tab; a click posted from any other window on another origin is ignored.
783
+ - **`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.
784
+ - **`slug` is never marked.** Zero-width characters in a slug end up in URLs.
785
+ - **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.
786
+ - **Do not transform marked text on the server and write it back**, see [Enrichment modes](#enrichment-modes).
787
+
788
+ ## Contributing
789
+
790
+ See [`CLAUDE.md`](./CLAUDE.md) for where things are, the rules that are easy to break and how to test.
287
791
 
288
792
  ## License
289
793