payload-live-preview 2.1.2 → 2.2.1

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/relative23/payload-live-preview/actions/workflows/ci.yml/badge.svg)](https://github.com/relative23/payload-live-preview/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node >= 20.19](https://img.shields.io/badge/node-%3E%3D20.19-brightgreen)](package.json)
-[![Payload 2.x / 3.x](https://img.shields.io/badge/Payload-2.x%20%2F%203.x-black)](https://payloadcms.com)
+[![Payload 2.x / 3.x / 4.x beta](https://img.shields.io/badge/Payload-2.x%20%2F%203.x%20%2F%204.x%20beta-black)](#compatibility)
 [![npm](https://img.shields.io/npm/v/payload-live-preview?color=cb3837&logo=npm)](https://www.npmjs.com/package/payload-live-preview)
 
 ![The Payload admin posts every keystroke; the runtime in the preview iframe patches the bound element in place, has your server render a fragment boundary, or refreshes the route](.github/social-preview.png)
@@ -12,17 +12,17 @@
 
 Payload publishes the framework-independent `@payloadcms/live-preview` client and the official `@payloadcms/live-preview-react` and `@payloadcms/live-preview-vue` wrappers. Those hooks feed a hydrated component tree; they do not own server markup outside that tree. This package covers that markup. Mark one boundary per server-rendered component, or individual fields on a static page, and edits reach the iframe as the editor types. Scalar patches and successful fragment renders need neither a rebuild nor a full-page reload; a route-level change uses the configured route refresh. Client-rendered apps can instead use this package's React or Vue entry. Its v2 sanitizer and request-time policy defaults are strict; static delivery has no request to authorize. The package has no direct dependencies; framework entries use optional peers.
 
-One runtime serves every framework, and every framework adapter's example app runs end to end in Chromium, Firefox and WebKit on every push to `main` and on pull requests. Astro has the most coverage: the widest version matrix (4.x to 7.x), the `RichText` and `PreviewBoundary` components, and the annotator as a Vite plugin (`pll-codegen annotate` itself also reads `.jsx`, `.tsx` and `.svelte`).
+One runtime serves every framework. The Astro, Next.js, SvelteKit and Nuxt adapters authorize a preview request, merge `frame-ancestors` into your CSP and render fragment boundaries on your server, and each adapter's example app runs end to end against a real Payload admin in Chromium, Firefox and WebKit on every push to `main` and on pull requests. Where the adapters differ, the difference comes from the framework: [Frameworks](#frameworks) lists it.
 
-**New here? Start with the [Astro guide](docs/astro.md), or pick your framework in the [documentation index](docs/README.md).**
+**New here?** Configure Payload, then add your framework's adapter under [Quick start](#quick-start). The [documentation index](docs/README.md) has the reading path.
 
 ## Highlights
 
-- **One runtime, every frontend.** One TypeScript runtime compiled to a self-contained inline script of about 44 KB gzip — 36 KB with the lean artifact, 47 to 49 KB once the route or fragment prelude is appended ([docs/options.md](docs/options.md)). The adapters for Astro, Next.js, SvelteKit and Nuxt deliver it; where they decide per request they also authorize the request, merge `frame-ancestors` into your CSP and mark the changed response `private, no-store`. They provide the fragment endpoint and, outside Astro, the route that serves the runtime asset.
+- **One runtime, every frontend.** One TypeScript runtime compiled to a self-contained inline script of about 46 KB gzip — 37 KB with the lean artifact, 48 to 50 KB once the route or fragment prelude is appended ([docs/options.md](docs/options.md)). The adapters for Astro, Next.js, SvelteKit and Nuxt deliver it; where they decide per request they also authorize the request, merge `frame-ancestors` into your CSP and mark the changed response `private, no-store`. They provide the fragment endpoint and, outside Astro, the route that serves the runtime asset.
 - **Patch, fragment, route.** A binding is patched in place; a `data-payload-fragment` boundary is rendered again by your server from the unsaved form state; a patch that fell short, or a change nothing binds, goes to the fragment render or a route refresh when the page has one ([below](#patch-fragment-route)).
 - **Delivery.** Inline, or a bootstrap that fetches the content-hashed, SRI-verified runtime only inside a preview (`delivery: 'asset'`; Astro's static equivalent is `mode: 'loader'`). Where something decides per request — Astro's middleware, `await LivePreviewScript(…)` in Next.js, the SvelteKit handle, the Nuxt Nitro plugin — a public visitor receives no script at all ([docs/deployment.md](docs/deployment.md#what-a-public-visitor-pays)).
 - **Payload 3.x native.** `serverURL` re-fetches the populated document, like the official client, so relationship and upload fields render as content rather than as IDs — but only when an edit needs one: in the DOM runtime, typing into a text field costs no request, and a burst on a relationship costs two requests, at its start and its end, rather than one per keystroke.
-- **Lexical renderer.** 20 node types including `upload`, `relationship`, `block`, `autolink`, tabs, indent and RTL, with rich-text detection from the value shape (an element that can hold uploads or relationships needs `data-payload-richtext`). An unknown node renders only its children; a block with no registered renderer becomes an empty placeholder, and the live write keeps the markup your server rendered in its place when the two trees line up. The prebuilt inline runtime cannot register block renderers.
+- **Lexical renderer.** 20 node types including `upload`, `relationship`, `block`, `autolink`, tabs, indent and RTL, with rich-text detection from the value shape, which also decides when Payload is asked to fill in uploads and relationships. An unknown node renders only its children; a block with no registered renderer becomes an empty placeholder, and the live write keeps the markup your server rendered in its place when the two trees line up. The prebuilt inline runtime cannot register block renderers.
 - **Hooks for client-rendered apps.** `useLivePreviewDocument()` from `payload-live-preview/react` or `/vue` hands the merged document to your component tree ([docs/react.md](docs/react.md), [docs/vue.md](docs/vue.md)).
 - **Tooling.** `pll doctor <url>` requests a page as a visitor and as the admin's iframe and reports the difference; `pll migrate` rewrites 1.x APIs to their 2.0 names; `pll-codegen` generates types from the Payload config, and `pll-codegen annotate` finds the bindings a template can take unambiguously.
 - **Authorization before anything privileged.** Where an adapter decides per request with `authorizePreview`, draft reads, runtime injection, CSP changes and binding attributes follow one verified decision, and the client-controlled intent signals unlock nothing. The setups that decide less are named under [Security model](#security-model).
@@ -31,35 +31,46 @@ One runtime serves every framework, and every framework adapter's example app ru
 
 ## Compatibility
 
-|                                                | Payload 2.x                                                                                                                                              | Payload 3.x                                                           |
-| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| Scalar field updates                           | ✅                                                                                                                                                       | ✅                                                                    |
-| Rich text (Lexical)                            | ✅                                                                                                                                                       | ✅                                                                    |
-| Relationship / upload population               | Collection GETs from the accepted schema with `serverURL` and matching depth (relationships measured against a real 2.32.3 admin, uploads by unit tests) | ✅ with `serverURL` (REST merge)                                      |
-| Schema-driven field typing (`fieldSchemaJSON`) | ✅                                                                                                                                                       | — (3.x removed it; DOM heuristics + Lexical auto-detection take over) |
+| Payload | Status                                     | Checked by                                                                                                                                                                                       |
+| ------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 2.x     | supported in 2.x; ends with 3.0            | the 2.32.3 wire corpus replayed in CI; real-admin release checks of the DOM runtime and the React and Vue hooks ([docs/testing.md](docs/testing.md#local-release-checks))                        |
+| 3.x     | supported                                  | the real admin on every push (3.92.1, three engines); the 3.85, 3.88 and 3.89 wire corpora replayed in CI                                                                                        |
+| 4.x     | pre-release, the direction of this package | the 4.0.0-beta.4 wire corpus replayed in CI; the real-admin suite against `payload@beta` every day, as an early warning; a 2.2 release candidate on a site running 4.0.0-beta.4 with Astro 7.4.2 |
+
+**Payload 4** is where this package is headed. Its pre-releases are followed as they appear, and support becomes official with the stable 4.0 release; until then the daily run against `payload@beta` warns early and does not gate a release. The Payload 4 pre-release captured so far passes the same protocol checks as the 3.x corpora. As of 4.0.0-beta.4, Payload 4 needs Node 24.22.1 or later, and its admin Next.js 16.4 or a later 16.x release. Payload 2.x support ends with the next major release of this package: 3.0 supports Payload 3.x and 4.x, and every 2.x release keeps supporting Payload 2 ([ADR 0007 ledger, entry 25](docs/architecture/0007-v2-defaults-and-renames-ledger.md#ledger), [Preparing for 3.0](docs/migration.md#preparing-for-30)). Payload 3.x stays supported. The manifest declares `payload` as an optional peer, `^2.0.0 || ^3.0.0 || ^4.0.0-0`: npm never installs it, and a project that has Payload outside that range gets npm's `ERESOLVE` error.
+
+What differs between Payload 2, 3 and 4:
+
+|                                                | Payload 2.x                                                                                                                                              | Payload 3.x                                                           | Payload 4.x (measured on 4.0.0-beta.4)                                  |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Scalar field updates                           | ✅                                                                                                                                                       | ✅                                                                    | ✅                                                                      |
+| Rich text (Lexical)                            | ✅                                                                                                                                                       | ✅                                                                    | ✅ through a fragment render; the client-side renderer not measured yet |
+| Relationship / upload population               | Collection GETs from the accepted schema with `serverURL` and matching depth (relationships measured against a real 2.32.3 admin, uploads by unit tests) | ✅ with `serverURL` (REST merge)                                      | not measured yet                                                        |
+| Schema-driven field typing (`fieldSchemaJSON`) | ✅                                                                                                                                                       | — (3.x removed it; DOM heuristics + Lexical auto-detection take over) | — (as in 3.x)                                                           |
 
 <!-- compat-matrix:start -->
 
 | Framework | Supported                                                                    | Tested in CI on every push (version, browsers)                                    |
 | --------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| Astro     | >=4.0.0 <8.0.0                                                               | 7.3.2 (chromium, firefox, webkit); 6.x (chromium); 5.x (chromium); 4.x (chromium) |
-| Next.js   | App Router, 15.5 and 16                                                      | 16.4.2 (chromium, firefox, webkit); 15.x (chromium)                               |
-| SvelteKit | 2.x                                                                          | 2.70.2 (chromium, firefox, webkit)                                                |
+| Astro     | >=4.0.0 <8.0.0                                                               | 7.4.2 (chromium, firefox, webkit); 6.x (chromium); 5.x (chromium); 4.x (chromium) |
+| Next.js   | App Router, 15.5 and 16                                                      | 16.4.3 (chromium, firefox, webkit); 15.x (chromium)                               |
+| SvelteKit | 2.x                                                                          | 2.70.3 (chromium, firefox, webkit)                                                |
 | Nuxt      | 3.x (end of life since 31 July 2026: kept working, not officially supported) | 3.21.11 (chromium, firefox, webkit)                                               |
 
 Node >=20.19.0; the unit and integration suites run on Node 20, 22, 24, 26. Every version in the table is what the fixture lockfile or the matrix job installs, checked by `npm run compat:check`.
 
 Vite 5 through 8: that is what the supported framework majors install (Astro 7 → 8, Astro 6 → 7, Astro 5 → 6, Astro 4 → 5, SvelteKit 2 → 5/6/7/8, Nuxt 3 → 7), measured 2026-09-06. `npm run compat:check` keeps the devDependency and the fixture lockfiles inside that span; `npm run compat:refresh` re-reads it from the registry.
 
-The framework hooks and fragment renderers run twice on every push: at the floor of each peer range, as unit tests in jsdom that the `hook-matrix` job runs after installing the floors over the lockfile (React 18.0.0, Vue 3.3.0, Svelte 5.0.0), and at what the lockfile installs (React 19.2.8, Vue 3.5.42, Svelte 5.56.9), in the unit tests and the browser suites; the SvelteKit renderer is measured against a component compiled by `svelte/compiler` and rendered by the real `svelte/server`.
+The framework hooks and fragment renderers run twice on every push: at the floor of each peer range, as unit tests in jsdom that the `hook-matrix` job runs after installing the floors over the lockfile (React 18.0.0, Vue 3.3.0, Svelte 5.0.0), and at what the lockfile installs (React 19.3.1, Vue 3.5.44, Svelte 5.57.3), in the unit tests and the browser suites; the SvelteKit renderer is measured against a component compiled by `svelte/compiler` and rendered by the real `svelte/server`.
 
 - Payload 2.32.3: wire corpus captured from a real admin and replayed in tests/integration/wire-corpus.test.ts, plus fieldSchemaJSON typing in tests/integration/schema-driven.test.ts; local release checks also exercise the real admin in DOM, React and Vue previews, each in frontend-only and serverURL modes (24 browser cases per variant), and run the React hook and the Vue composable through three lifecycle journeys (9 browser cases per variant) and seven guard journeys (21 browser cases per variant) in development builds; the legacy dependency graph retains upstream audit findings.
 - Payload 3.85.0: wire corpus captured from a real admin, replayed in tests/integration/wire-corpus.test.ts.
 - Payload 3.88.0: wire corpus captured from a real admin, replayed in tests/integration/wire-corpus.test.ts.
 - Payload 3.89.0: wire corpus captured from a real admin, replayed in tests/integration/wire-corpus.test.ts.
-- Payload 3.92.0: real admin E2E fixture (examples/payload-backend), run by CI on every push.
-- Payload 4.0.0-canary.33: wire corpus captured from a real Payload 4 admin in a one-off upgrade round, replayed in tests/integration/wire-corpus.test.ts; the fixture itself stays on 3.x.
-- Payload 4.0.0-beta.4 (pre-release): measured once on 2026-10-24, outside CI, in a consumer project that runs 2.1.0 from npm (Next 16, Node 24, Postgres 18, the real admin driven by headless Chromium). The config plugin type-checks against Payload's declarations and passes its config sanitizing. For six collection documents in two locales, the admin's preview frame loads the URL a hand-written callback produced, apart from the order of the query parameters, with the same breakpoint menu and no page errors, and the locale reaches the path resolvers. Against an admin with a `csrf` list, the `payload-session` strategy authorizes once its `origin` option is set. That run did not cover globals, the create screen, drafts and autosave, other plugins that write a Live Preview URL, or replacing existing breakpoints. Since 2026-10-25 the nightly protocol watch installs payload@beta into the admin fixture as a soft-fail early warning.
+- Payload 3.92.1: real admin E2E fixture (examples/payload-backend), run by CI on every push.
+- Payload 4.0.0-beta.4: wire corpus captured on 2026-10-26 from a real Payload 4 admin (examples/payload-backend with payload@4.0.0-beta.4 installed over it, Node 24.22.1), replayed in tests/integration/wire-corpus.test.ts; the fixture itself stays on 3.x.
+- Payload 4.0.0-beta.4 (pre-release): measured once on 2026-10-24, outside CI, in a consumer project that runs 2.1.0 from npm (Next 16, Node 24, Postgres 18, the real admin driven by headless Chromium). The config plugin type-checks against Payload's declarations and passes its config sanitizing. For six collection documents in two locales, the admin's preview frame loads the URL a hand-written callback produced, apart from the order of the query parameters, with the same breakpoint menu and no page errors, and the locale reaches the path resolvers. Against an admin with a `csrf` list, the `payload-session` strategy authorizes once its `origin` option is set. That run did not cover globals, the create screen, drafts and autosave, other plugins that write a Live Preview URL, or replacing existing breakpoints. Since 2026-10-25 the daily protocol watch installs payload@beta into the admin fixture as a soft-fail early warning.
+- Payload 4.0.0-beta.4 with Astro 7.4.2 (pre-release): measured on 2026-10-26, outside CI, with a 2.2 release candidate on a consumer site (the real admin driven by headless Chromium). Typing into a title and a text line patched the preview, typing into a rich-text field updated it through 7 fragment renders that answered 200, the frame never reloaded, and all 31 live-preview messages had the shape of the recorded capture. Relationship and upload population were not part of the run.
 - Payload latest: daily protocol watch executes @payloadcms/live-preview@latest against the corpus.
 - Payload 4.0 pre-releases: daily protocol watch against @payloadcms/live-preview@beta and the real admin against payload@beta, early warning only.
 
@@ -67,25 +78,9 @@ The framework hooks and fragment renderers run twice on every push: at the floor
 
 Nuxt 4 has no row because no CI job installs it. A copy of the Nuxt example in Nuxt 4.5.2's `app/` layout passed the production suite against the mock admin on 2026-10-02 (54 of 54 cases), and a Nuxt 4.5.2 site installed from the 2.1.0 release candidate built and served its pages on 2026-10-18; neither was a real-admin run.
 
-**A client-rendered app takes a hook.** `useLivePreviewDocument()` from `payload-live-preview/react` or `payload-live-preview/vue` returns the merged document and re-renders your tree. Payload 3 updates use the method-override merge request; Payload 2 scalar updates settle locally and raw relationships use schema-based collection GETs. A newer update aborts any request in flight; an HTTP error is refused instead of becoming the document; each hook has a session of its own, so two previews on one page keep their own documents ([docs/react.md](docs/react.md), [docs/vue.md](docs/vue.md)). The official [`@payloadcms/live-preview-react`](https://payloadcms.com/docs/live-preview/client) / `-vue` hooks ship in lockstep with Payload and remain the safe default if that matters more to you; running either alongside the DOM runtime on one page: [docs/interop.md](docs/interop.md).
-
-### Local 2.1.0 release checks
-
-The following checks passed on 2026-10-23 on the package archive that was published as 2.1.0; the npm tarball differs from it only in the build timestamp. These are local results, separate from the CI jobs listed above. Browser counts include Chromium, Firefox and WebKit on Linux. `examples/payload-version-lanes` runs the Payload 2.32.3 rows, with `--probe=population`, `--probe=lifecycle` or `--probe=guards` for React and Vue.
-
-| Version        | Checked population                                                                                                                                                                                                  | Passed cases                  |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| Payload 2.32.3 | DOM, React and Vue, each with frontend-only and serverURL modes                                                                                                                                                     | 24 per variant, six variants  |
-| Payload 2.32.3 | React and Vue hook lifecycle, frontend-only and serverURL                                                                                                                                                           | 9 per variant, four variants  |
-| Payload 2.32.3 | React and Vue hook guards, frontend-only and serverURL                                                                                                                                                              | 21 per variant, four variants |
-| Node 20.19.0   | Peer-free consumer of the archive: every export without a peer under ESM and CommonJS, CLI help, inline script, signed tokens, `payload-session` and the fragment endpoint with its body, deadline and depth limits | 11 runtime cases              |
-| Next.js 16.4.2 | Webpack production preview and fragment rendering                                                                                                                                                                   | 54 browser cases              |
-| Astro 4.0.0    | Base adapter with loader and inline delivery, static output and scoped updates, two control builds                                                                                                                  | 36 browser cases              |
-| Astro 4.16.19  | Native React islands, CSP and navigation ownership                                                                                                                                                                  | 12 browser cases              |
+SvelteKit 3 has no row either: no CI job installs it. A copy of the SvelteKit example, moved to SvelteKit 3.1.0 with `npx sv migrate sveltekit-3`, built with adapter-node 6 and passed the 32 SvelteKit cases of the browser suite against the mock admin in Chromium, Firefox and WebKit on 2026-10-26; it was not a real-admin run. The example needed the migration's changes ([docs/sveltekit.md](docs/sveltekit.md)); the package needed none.
 
-The Node row runs the official 20.19.0 binary with no framework or optional peer installed; its fragment endpoint uses a custom renderer and its session check a local `/me` stub, not a real Payload admin, and it covers no framework build, development server or browser. The Next checks use a controlled preview cookie and fragment tokens; they do not use a real Payload admin. The Payload 2 graph still has upstream audit findings, including a critical finding in the 2026-10-05 audit. Its passing preview cases establish compatibility, not a clean dependency graph. Payload 3 lifecycle and Payload 4 canary checks are not included in this table. The Payload 2 lifecycle and guards rows run development builds on Linux engines. The lifecycle row covers an owner replaced while a read is held, a document change by navigation and a reload of the preview frame. The guards row covers a late successful response of a replaced owner, messages from a foreign window and a foreign origin, a receiver switch in a running session and a sign-out in the middle of one; neither row covers a token that expires by time or a production build.
-
-The two Astro rows can be repeated from the repository. The `astro-floor-base` and `astro-floor-islands` jobs run their specs on every push in Chromium ([Astro peer floors](docs/testing.md#astro-peer-floors)); the counts above are all three engines, with loader and inline delivery at five cases each and two control builds per engine for Astro 4.0.0.
+**A client-rendered app takes a hook.** `useLivePreviewDocument()` from `payload-live-preview/react` or `payload-live-preview/vue` returns the merged document and re-renders your tree. Payload 3 updates use the method-override merge request; Payload 2 scalar updates settle locally and raw relationships use schema-based collection GETs. A newer update aborts any request in flight; an HTTP error is refused instead of becoming the document; each hook keeps its own state, requests and errors, and every hook on the page follows the document the admin sends, whichever one it started from ([docs/react.md](docs/react.md), [docs/vue.md](docs/vue.md)). The official [`@payloadcms/live-preview-react`](https://payloadcms.com/docs/live-preview/client) / `-vue` hooks ship in lockstep with Payload and remain the safe default if that matters more to you; running either alongside the DOM runtime on one page: [docs/interop.md](docs/interop.md).
 
 ## Install
 
@@ -107,7 +102,8 @@ import { livePreview } from 'payload-live-preview/plugin';
 export default buildConfig({
   plugins: [
     livePreview({
-      baseUrl: process.env.FRONTEND_URL ?? 'http://localhost:4321',
+      // Your site's origin. In development: Astro 4321, Next.js and Nuxt 3000, SvelteKit 5173.
+      baseUrl: process.env.FRONTEND_URL ?? 'http://localhost:3000',
       collections: {
         posts: ({ data }) => `/blog/${String(data['slug'] ?? '')}`,
         services: ({ data, locale }) => `/${locale ?? 'en'}/services/${String(data['slug'] ?? '')}`,
@@ -132,16 +128,16 @@ transform run after any plugin that may write a Live Preview URL in Payload's
 effective execution order, or compose both routing policies explicitly. The
 complete merge and conflict rules are in [docs/payload.md](docs/payload.md).
 
-In the Payload 3.92.0 admin, a collection document gets its native Live
+In the Payload 3.92.1 admin, a collection document gets its native Live
 Preview after its first save. The create screen has no preview toggle and no
 frame, for a function-valued URL and for a fixed string alike. The frame that
 appears after the save loads the URL the plugin's function builds from the saved
 document. `tests/real-payload/surface-create.spec.ts` checks this in Chromium,
 Firefox and WebKit.
 
-Payload 4 is still a pre-release. The plugin was measured once against
-4.0.0-beta.4, outside CI; the [compatibility list](#compatibility) says what
-that run covered and what it left out.
+Payload 4 is still a pre-release ([Compatibility](#compatibility)). The plugin
+was measured once against 4.0.0-beta.4, outside CI; the compatibility list says
+what that run covered and what it left out.
 
 Use the lower-level callback when another plugin owns the surrounding config or
 when a document may have no preview route:
@@ -153,7 +149,7 @@ export default buildConfig({
   admin: {
     livePreview: {
       url: buildLivePreviewUrl({
-        baseUrl: process.env.FRONTEND_URL ?? 'http://localhost:4321',
+        baseUrl: process.env.FRONTEND_URL ?? 'http://localhost:3000',
         collections: {
           posts: ({ data }) => `/blog/${String(data['slug'] ?? '')}`,
           services: ({ data, locale }) =>
@@ -186,6 +182,10 @@ strategies, and the initial draft read.
 
 ## Quick start
 
+Install the package, give the Payload admin your site's URLs ([Configure Payload](#configure-payload)), add your framework's adapter, then mark what should update. Each framework guide goes from there to a working preview and names its runnable example.
+
+The snippets read the admin origin the browser sees from `PUBLIC_PAYLOAD_ADMIN_ORIGIN` and, where they authorize, Payload's own origin from `PAYLOAD_URL`; the Next.js layout also needs the site's own origin as `SITE_ORIGIN`. The `payload-session` strategy accepts an editor signed in to that admin ([docs/authorization.md](docs/authorization.md)).
+
 ### Astro
 
 ```js
@@ -207,40 +207,167 @@ export default defineConfig({
 });
 ```
 
-Then mark what should update. On a server-rendered page that is one attribute per component — the region is rendered again from the unsaved form state, so everything in it stays correct, conditional sections and derived values included:
+The default `inline` mode writes the runtime into every page at build time, where it starts only inside the admin's preview frame. `mode: 'middleware'` decides per request with an `authorizePreview` module, as the adapters below do: [docs/astro.md](docs/astro.md).
+
+### Next.js (App Router)
+
+```tsx
+// app/layout.tsx
+import type { ReactNode } from 'react';
+import { headers } from 'next/headers';
+import { LivePreviewScript } from 'payload-live-preview/nextjs';
+import { authorizePreviewRequest } from 'payload-live-preview/server';
+
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  // Awaited, not rendered as <LivePreviewScript />: docs/nextjs.md says why.
+  const livePreview = await LivePreviewScript({
+    request: new Request(process.env.SITE_ORIGIN!, { headers: await headers() }),
+    // A layout cannot see the query string, so the verdict is the gate.
+    inject: 'always',
+    allowedOrigins: [process.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN!],
+    serverURL: process.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN!,
+    mergeDepth: 1,
+    authorizePreview: (request) =>
+      authorizePreviewRequest(request, {
+        type: 'payload-session',
+        serverURL: process.env.PAYLOAD_URL!,
+      }),
+  });
+  return (
+    <html lang="en">
+      <head>{livePreview}</head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
 
-```astro
+Awaited in the layout, the server component returns nothing for a request that is not an authorized preview. The adapter middleware merges `frame-ancestors` and marks the preview response `private, no-store`: [docs/nextjs.md](docs/nextjs.md).
+
+### SvelteKit
+
+```ts
+// src/hooks.server.ts
+import { env } from '$env/dynamic/private';
+import { env as publicEnv } from '$env/dynamic/public';
+import { livePreviewHandle } from 'payload-live-preview/sveltekit';
+import { authorizePreviewRequest } from 'payload-live-preview/server';
+
+const adminOrigin = publicEnv.PUBLIC_PAYLOAD_ADMIN_ORIGIN ?? '';
+
+export const handle = livePreviewHandle({
+  allowedOrigins: [adminOrigin],
+  // Payload 3.x: re-fetch the populated document; mergeDepth is required with serverURL.
+  serverURL: adminOrigin,
+  mergeDepth: 1,
+  // Required under the strict default: without the hook the handle refuses to
+  // start, and every route fails, not only the preview.
+  authorizePreview: (request) =>
+    authorizePreviewRequest(request, { type: 'payload-session', serverURL: env.PAYLOAD_URL ?? '' }),
+});
+```
+
+The handle authorizes the request, injects the runtime into the `<head>` of an authorized preview response and merges the CSP: [docs/sveltekit.md](docs/sveltekit.md).
+
+### Nuxt
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['payload-live-preview/nuxt-module'],
+  livePreview: {
+    authorizePreviewModule: './server/utils/live-preview-auth',
+    allowedOrigins: [process.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN!],
+    serverURL: process.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN!,
+    mergeDepth: 1,
+  },
+});
+```
+
+```ts
+// server/utils/live-preview-auth.ts
+import { authorizePreviewRequest, type PreviewRequestLike } from 'payload-live-preview/server';
+
+export default (request: PreviewRequestLike) =>
+  authorizePreviewRequest(request, {
+    type: 'payload-session',
+    serverURL: process.env.PAYLOAD_URL!,
+  });
+```
+
+The module registers a Nitro plugin and a server handler, and takes the authorization hook by module reference: [docs/nuxt.md](docs/nuxt.md).
+
+### Plain HTML
+
+```ts
+// build.ts — runs at build time, never in the browser
+import { generateInlineScript, wrapWithScriptTag } from 'payload-live-preview';
+
+const script = generateInlineScript({
+  allowedOrigins: [process.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN!],
+  // Payload 3.x: re-fetch the populated document; mergeDepth is required with serverURL.
+  serverURL: process.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN!,
+  mergeDepth: 1,
+});
+
+const tag = wrapWithScriptTag(script); // `<script>…</script>`; pass { nonce } for a CSP nonce
+const html = `<!doctype html><html lang="en"><head><meta charset="utf-8">${tag}</head><body>…</body></html>`;
+```
+
+The tag goes into `<head>`; the script stays inert outside the admin's preview frame: [docs/html.md](docs/html.md).
+
+### Mark what should update
+
+The attributes are plain HTML, written the same way in `.astro`, JSX, Svelte and Vue templates. On a server-rendered page that is one attribute per component — the region is rendered again from the unsaved form state, so everything in it stays correct, conditional sections and derived values included:
+
+```html
 <section data-payload-fragment="hero" data-payload-depends="title,subtitle,body">
-  <Hero {...page} />
+  <!-- the hero component, rendered by your server -->
 </section>
 ```
 
-The attribute needs a renderer behind it: a route exporting `createFragmentEndpoint()` with `authorizePreview` or `authorize`, served at request time (an SSR adapter, `prerender = false` on that route), and its path in the options above as `fragments: { endpoint: '/payload/fragment' }` ([docs/hybrid.md](docs/hybrid.md)). Without `fragments` the bindings inside the boundary are patched instead (`LP0806`), and a boundary with none inside does not update.
+The attribute needs a renderer behind it: a route exporting `createFragmentEndpoint()` from your adapter's entry, with `authorizePreview` or `authorize`, served at request time, and its path in the adapter options as `fragments: { endpoint: '/payload/fragment' }` ([docs/hybrid.md](docs/hybrid.md)). Without `fragments` the bindings inside the boundary are patched instead (`LP0806`), and a boundary with none inside does not update.
 
-On a static build there is no server to render it, so the fields are bound individually — and inside a boundary too. A direct patch retains the target element. A component render or fragment morph can retain it as well when type, key and position stay compatible, but may replace it when they do not:
+Without a server to render it — on a static build, for one — the fields are bound individually, and inside a boundary too. A direct patch retains the target element. A component render or fragment morph can retain it as well when type, key and position stay compatible, but may replace it when they do not:
 
-```astro
-<h1 data-payload-field="title">{title}</h1>
+```html
+<h1 data-payload-field="title">…</h1>
 <div data-payload-field="body">…server-rendered rich text…</div>
-<img data-payload-field="hero" alt={alt} src={url} />
+<img data-payload-field="hero" alt="…" src="…" />
 ```
 
-Which to reach for, and what each costs: [docs/bindings.md](docs/bindings.md#how-much-markup-this-actually-needs). `pll-codegen annotate` adds the unambiguous bindings and names each one it refuses, with the reason; without `--write` it only reports, and exits with `3` when it found work.
+Which to reach for, and what each costs: [docs/bindings.md](docs/bindings.md#how-much-markup-this-actually-needs). `pll-codegen annotate` adds the unambiguous bindings and names each one it refuses, with the reason; without `--write` it only reports, and exits with `3` when it found work and with `2` when the config yields no collection or global.
 
-That is it: the inline script detects the admin's iframe and starts patching. Rich text is written from the value shape, but a rich-text element that can hold uploads or relationships needs `data-payload-richtext`: only then does the runtime ask Payload to fill those nodes in ([docs/renderers.md](docs/renderers.md#media-urls)). Payload 2.x and 3.x can post raw form values, so relationship and upload fields arrive as IDs until `serverURL` with `mergeDepth` re-fetches the populated document ([docs/options.md](docs/options.md)). Injection modes, request-time middleware, authorization and the initial draft read: [docs/astro.md](docs/astro.md).
+That is it: the runtime detects the admin's iframe and starts patching. Rich text is written from the value shape, and a value that holds an upload or a relationship has the runtime ask Payload to fill it in ([docs/renderers.md](docs/renderers.md#media-urls)). The admin posts raw form values, so relationship and upload fields arrive as IDs until `serverURL` with `mergeDepth` re-fetches the populated document ([docs/options.md](docs/options.md)). Authorization and the initial draft read: your framework's guide and [docs/authorization.md](docs/authorization.md).
 
-### Other frameworks
+## Frameworks
 
-- **Next.js (App Router)** — `await LivePreviewScript(…)` in `app/layout.tsx`, the adapter middleware for headers: [docs/nextjs.md](docs/nextjs.md).
-- **SvelteKit** — `livePreviewHandle()` in `hooks.server.ts`: [docs/sveltekit.md](docs/sveltekit.md).
-- **Nuxt** — a Nitro plugin plus a server handler: [docs/nuxt.md](docs/nuxt.md).
-- **Plain HTML** — `generateInlineScript()` at build time: [docs/html.md](docs/html.md).
+|                                                          | Astro                                           | Next.js                                                          | SvelteKit                                               | Nuxt                                                    |
+| -------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
+| Decides per request: authorizes, injects, merges the CSP | `mode: 'middleware'`                            | `await LivePreviewScript(…)` and `createLivePreviewMiddleware()` | `livePreviewHandle()`                                   | `payload-live-preview/nuxt-module`                      |
+| The runtime as a hashed, cached asset                    | `mode: 'loader'`                                | `delivery: 'asset'` and `createRuntimeAssetRoute()`              | `delivery: 'asset'` and `createRuntimeAssetRoute()`     | `delivery: 'asset'` and `createRuntimeAssetRoute()`     |
+| Renders a fragment boundary with                         | Astro's container API                           | `react-dom/server`                                               | `svelte/server`                                         | `vue/server-renderer`                                   |
+| First write waits for hydration                          | islands keep their own subtree                  | yes                                                              | yes                                                     | yes                                                     |
+| Rich text and empty fields on the server                 | the `RichText` and `PreviewBoundary` components | `lexicalToHtml()` and a `data-payload-boundary` element          | `lexicalToHtml()` and a `data-payload-boundary` element | `lexicalToHtml()` and a `data-payload-boundary` element |
+| `pll-codegen annotate` reads                             | `.astro`, also as a Vite plugin                 | `.jsx`, `.tsx`                                                   | `.svelte`                                               | not `.vue` files                                        |
 
-Whatever the framework, the admin also needs your frontend's URLs: the config plugin under [Configure Payload](#configure-payload) supplies them.
+Astro also writes the runtime into a static build (`inline`, `loader`). Its `RichText` and `PreviewBoundary` components write the same markup the other frameworks write by hand with `lexicalToHtml()` and a `data-payload-boundary` element ([docs/bindings.md](docs/bindings.md)). The test depth differs: CI installs Astro 4 to 7 and Next.js 15.5 and 16, SvelteKit 2 and Nuxt 3. Nuxt 3 reached its end of life on 31 July 2026, and no job installs Nuxt 4 yet.
 
 ## Patch, fragment, route
 
-A binding is patched in place by default. A `data-payload-fragment` boundary is rendered by your server from the unsaved form state instead — conditional sections, derived values, custom blocks, the component's own logic — and morphed into the page. Compatible retained nodes keep their focus and live properties; a node that changes kind, loses its pairing or crosses an ownership boundary is replaced and loses that state. The runtime posts the fields to the same-origin endpoint named in `fragments: { endpoint }`, built with `createFragmentEndpoint()`, which every adapter entry exports — Astro renders through its container API, Next.js through `react-dom/server`, SvelteKit through `svelte/server`, Nuxt through `vue/server-renderer` — and patches the boundary's own bindings when the server cannot render. With `routeStrategy: true` or `fragments` set, a binding in `<head>`, or one marked `data-payload-strategy="route"`, refreshes the whole route once per revision. The route morph follows the same retention rule and restores focus after a retained keyed move; it does not promise state for replaced nodes. Without either strategy the binding is patched like any other. The route is matched by top-level field name, so a dotted binding such as `meta.title` refreshes it only with `data-payload-depends="meta"`. Markup, endpoint, deployment requirements and the abuse model: [docs/hybrid.md](docs/hybrid.md).
+Who renders what, and from which data:
+
+| What updates            | Who renders it                                                        | From                                                                             | What it cannot do                                                                                                                              |
+| ----------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| A bound element (patch) | the runtime, in the preview frame                                     | the unsaved values; with `serverURL`, Payload fills in relationships and uploads | create a section the template leaves out, or run a component's logic                                                                           |
+| A boundary, Astro       | your server, through Astro's container API                            | the unsaved values                                                               | —                                                                                                                                              |
+| A boundary, Next.js     | your server, `renderToString()` from `react-dom/server`               | the unsaved values                                                               | await its own data: one synchronous component, with no App Router context around it (no layout, no provider)                                   |
+| A boundary, SvelteKit   | your server, `render()` from `svelte/server`                          | the unsaved values                                                               | write the head: only its `body` is delivered                                                                                                   |
+| A boundary, Nuxt        | your server, a Vue SSR app of its own per render                      | the unsaved values                                                               | call Nuxt's app composables (`useHead()`, `useNuxtApp()`)                                                                                      |
+| The route               | your server, an ordinary GET of the page, or the router's own refresh | the saved document                                                               | show unsaved values outside the bindings: the result is `partial`, and the runtime writes the unsaved values back into the bindings it reaches |
+| A hook's tree           | React or Vue, in the browser                                          | the merged document from `useLivePreviewDocument()`                              | —                                                                                                                                              |
+
+A binding is patched in place by default. A `data-payload-fragment` boundary is rendered by your server from the unsaved form state instead — conditional sections, derived values, custom blocks, the component's own logic — and morphed into the page. Compatible retained nodes keep their focus and live properties; a node that changes kind, loses its pairing or crosses an ownership boundary is replaced and loses that state. The runtime posts the fields to the same-origin endpoint named in `fragments: { endpoint }`, built with `createFragmentEndpoint()`, which every adapter entry exports, and patches the boundary's own bindings when the server cannot render. With `routeStrategy: true` or `fragments` set, a binding in `<head>`, or one marked `data-payload-strategy="route"`, refreshes the whole route once per revision. The route morph follows the same retention rule and restores focus after a retained keyed move; it does not promise state for replaced nodes. Without either strategy the binding is patched like any other. The route is matched by top-level field name, so a dotted binding such as `meta.title` refreshes it only with `data-payload-depends="meta"`. Markup, endpoint, deployment requirements and the abuse model: [docs/hybrid.md](docs/hybrid.md).
 
 Custom elements are protected from fragment, route and structural morphs by
 default. Add the opt-in attribute `data-payload-morph` to a custom element in
@@ -266,8 +393,10 @@ and nested protected descendants remain protected. Ordinary elements are unchang
 The morph makes the host's attributes and light DOM match the server's markup,
 so what a component added to its own host or built inside it is removed or
 replaced on the next update (the state attributes `open`, `value`, `checked` and
-`selected` are left alone unless the template names them). Keep markup a
-component owns in its shadow root, or mark it `data-payload-owned`. Components
+`selected` are left alone unless the template names them). That includes
+`popover`, `popovertarget` or `hidden` set by an enhancement script; render
+them on the server in the preview instead. Keep markup a component owns in its
+shadow root, or mark it `data-payload-owned`. Components
 must react to child changes, refresh cached references, preserve UI state, and
 clean up listeners or observers. `connectedCallback` does not rerun for child
 updates; DOM moves can still reconnect a retained host. Consumers may emit the
@@ -306,7 +435,7 @@ Full details in [docs/security.md](docs/security.md). Report vulnerabilities per
 - **The preview iframe refuses to load.** The host sets `X-Frame-Options` or a restrictive `frame-ancestors`. The adapters merge `frame-ancestors` on authorized preview responses, and browsers frame by that directive alone; an `X-Frame-Options: DENY` from a proxy still blocks a preview response that has none, so it must go there.
 - **The adapter refuses the configuration.** The strict default needs `authorizePreview`, a non-empty `allowedOrigins` (`https:` in production) and no referer trust; the deprecated `defaults: 'v1'` stages a migration one row at a time, and `pll migrate` writes out the rows it stands for.
 
-`inspect()` readings, `pll doctor` and every diagnostic code: [docs/troubleshooting.md](docs/troubleshooting.md). `pll doctor` sends its preview request with `?preview=true`; a preview behind `authorizePreview` is audited with an editor's credential. A signed token goes in the URL as `?previewToken=…`, which the visitor request drops; `--header "x-preview-token: …"` works only where the token strategy sets `transport: { kind: 'header' }`; a Payload session is `--header "Cookie: payload-token=…"`.
+`inspect()` readings, `pll doctor` and every diagnostic code: [docs/troubleshooting.md](docs/troubleshooting.md). `pll doctor` sends its preview request with `?preview=true`; a preview behind `authorizePreview` is audited with an editor's credential. A signed token goes in the URL as `?previewToken=$PREVIEW_TOKEN`, which the visitor request drops; `--header "x-preview-token: $PREVIEW_TOKEN"` works only where the token strategy sets `transport: { kind: 'header' }`; a Payload session is `--header "Cookie: payload-token=$PAYLOAD_TOKEN"`. Keep the credential in an environment variable and run `node_modules/.bin/pll`, not `npx pll`, which prints the whole command line.
 
 ## Documentation
 

package/dist/adapters/astro/index.d.ts

@@ -1,10 +1,10 @@
-import { L as LivePreviewAstroOptions } from '../../middleware-BGobLN9P.js';
-export { a as LivePreviewMiddleware, c as createLivePreviewMiddleware } from '../../middleware-BGobLN9P.js';
-import { h as hasPreviewIntent } from '../../options-Cm8fC7dj.js';
-export { P as PreviewAdapterOptions, a as PreviewRequestLike, b as PreviewRequestOptions, c as PreviewSignal } from '../../options-Cm8fC7dj.js';
-import { F as FragmentEndpointOptions$1, a as FragmentRegistry$1, b as FragmentRegistryEntry$1, c as FragmentRenderer$1 } from '../../fragment-endpoint-B2qcRw5T.js';
-export { d as FragmentRenderInput } from '../../fragment-endpoint-B2qcRw5T.js';
-export { A as AUTHORIZATION_LOCALS_KEY, a as AUTHORIZATION_OUTCOME_LOCALS_KEY, L as LivePreviewLocals, N as NONCE_LOCALS_KEY } from '../../locals-B1mF3aTb.js';
+import { L as LivePreviewAstroOptions } from '../../middleware-CI-UTf6R.js';
+export { a as LivePreviewMiddleware, c as createLivePreviewMiddleware } from '../../middleware-CI-UTf6R.js';
+import { h as hasPreviewIntent } from '../../options-CnYybG51.js';
+export { P as PreviewAdapterOptions, a as PreviewRequestLike, b as PreviewRequestOptions, c as PreviewSignal } from '../../options-CnYybG51.js';
+import { F as FragmentEndpointOptions$1, a as FragmentRegistry$1, b as FragmentRegistryEntry$1, c as FragmentRenderer$1 } from '../../fragment-endpoint-DGGLIijM.js';
+export { d as FragmentRenderInput } from '../../fragment-endpoint-DGGLIijM.js';
+export { A as AUTHORIZATION_LOCALS_KEY, a as AUTHORIZATION_OUTCOME_LOCALS_KEY, L as LivePreviewLocals, N as NONCE_LOCALS_KEY } from '../../locals-zz2gi9dj.js';
 
 /**
  * The Astro integration for `astro.config.mjs`: `livePreview({ ... })`.