payload-live-preview 2.2.1 → 2.3.0

package/README.md

@@ -37,7 +37,7 @@ One runtime serves every framework. The Astro, Next.js, SvelteKit and Nuxt adapt
 | 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.
+**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)). 3.0 also needs Node 22 or newer and drops no framework major (entries 28 and 29). 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:
 
@@ -50,16 +50,18 @@ What differs between Payload 2, 3 and 4:
 
 <!-- compat-matrix:start -->
 
-| Framework | Supported                                                                    | Tested in CI on every push (version, browsers)                                    |
-| --------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| 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)                                               |
+| Framework | Supported                                                                         | Tested in CI on every push (version, browsers)                                    |
+| --------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| 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 and 3.x                                                                       | 3.1.1 (chromium, firefox, webkit); 2.70.3 (chromium, firefox, webkit)             |
+| Nuxt      | 4.x; 3.x (end of life since 31 July 2026: kept working, not officially supported) | 4.6.3 (chromium, firefox, webkit); 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.
+Of the 58 feature rows of `quality/compat-matrix.json`, 55 passed in the CI run the last Version PR recorded (commit `c9ffe5d`, 2026-11-01, `quality/compat-results.json`); the other 3 have no recorded result.
+
+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 3 → 8, SvelteKit 2 → 5/6/7/8, Nuxt 4 → 8, Nuxt 3 → 7), measured 2026-10-31. `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.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`.
 
@@ -76,11 +78,9 @@ The framework hooks and fragment renderers run twice on every push: at the floor
 
 <!-- compat-matrix:end -->
 
-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.
-
-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.
+SvelteKit 3 and Nuxt 4 are supported. The `sveltekit3` job runs the SvelteKit example migrated to SvelteKit 3.1.1 with `npx sv migrate sveltekit-3`, and the `nuxt4` job runs the Nuxt example in Nuxt 4.6.3's `app/` layout. Both run on the development server against the mock admin in Chromium, Firefox and WebKit, and `real-payload-surfaces` drives both from the real admin in the same three engines. The production jobs still build the SvelteKit 2 and Nuxt 3 examples. The SvelteKit example needed the migration's changes ([docs/sveltekit.md](docs/sveltekit.md)); the package needed no change for either.
 
-**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).
+**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 a hook given a `document` merges only that document's updates; without one it 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
 
@@ -125,8 +125,10 @@ the mappings. Existing breakpoints stay when the option is omitted; supplying
 it replaces the list. A competing root URL or a URL on a selected entity that
 already exists when this transform runs is a configuration error. Make this
 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).
+effective execution order (Payload 3 and 4 sort by the `order` option), or
+compose both routing policies explicitly. A resolver or the `fallback` may be
+`null` for a document without a preview on Payload 3 and 4. The complete merge
+and conflict rules are in [docs/payload.md](docs/payload.md).
 
 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
@@ -137,10 +139,11 @@ Firefox and WebKit.
 
 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.
+what that run covered and what it left out. Its `order` option and `null`
+resolvers were measured once against 4.0.0-beta.6, also outside CI
+([ADR 0017](docs/architecture/0017-structural-payload-config-plugin.md)).
 
-Use the lower-level callback when another plugin owns the surrounding config or
-when a document may have no preview route:
+Use the lower-level callback when another plugin owns the surrounding config:
 
 ```ts
 import { buildLivePreviewUrl } from 'payload-live-preview/payload';
@@ -171,7 +174,7 @@ export default buildConfig({
 });
 ```
 
-The helper appends `?preview=true`, one of the query parameters (`preview`, `draft`, `livePreview`) the adapters read as preview intent. The parameter is client-controlled: it selects delivery and never authorizes draft access. A hand-written `url: ({ data, locale, collectionConfig, globalConfig }) => string` callback works the same way; the [official docs](https://payloadcms.com/docs/live-preview/overview) have the full contract. The helper's nullable overload lets a resolver return `null` for a document without a route, and `fallback: null` declines every unmapped one; Payload 3 then shows no iframe. Payload 2.32.3's published callback result is string-only, so use the non-null overload and a string fallback there. The config plugin deliberately stays inside that common contract.
+The helper appends `?preview=true`, one of the query parameters (`preview`, `draft`, `livePreview`) the adapters read as preview intent. The parameter is client-controlled: it selects delivery and never authorizes draft access. A hand-written `url: ({ data, locale, collectionConfig, globalConfig }) => string` callback works the same way; the [official docs](https://payloadcms.com/docs/live-preview/overview) have the full contract. The helper's nullable overload lets a resolver return `null` for a document without a route, and `fallback: null` declines every unmapped one; Payload 3 then shows no iframe. Payload 2.32.3's published callback result is string-only, so use the non-null overload and a string fallback there, and keep the config plugin's resolvers to strings.
 
 The config plugin accepts no signing secret or token option. Where no session
 cookie crosses origins, the manual `signed-token` URL callback is a Payload 3

package/dist/adapters/astro/PreviewBoundary.astro

@@ -24,6 +24,9 @@
  * `data-payload-strategy="patch"` is written explicitly: the wrapper is a
  * patch target; markup a server renders instead lives in a
  * `data-payload-fragment` boundary (docs/hybrid.md).
+ *
+ * Where `authorizePreview` decides, a response it did not authorize keeps the
+ * wrapper and carries no `data-payload-*`, as the gated helpers do (ADR 0006).
  */
 
 interface Props {
@@ -50,14 +53,24 @@ function isEmpty(candidate: unknown): boolean {
 
 const Tag = as;
 const empty = isEmpty(value);
+const locals = Astro.locals as {
+  livePreviewRequiresAuthorization?: boolean;
+  livePreviewAuthorization?: unknown;
+};
+const binding =
+  locals.livePreviewRequiresAuthorization === true && locals.livePreviewAuthorization === undefined
+    ? {}
+    : {
+        'data-payload-field': field,
+        'data-payload-type': type,
+        'data-payload-boundary': '',
+        'data-payload-strategy': 'patch',
+      };
 ---
 
 <Tag
   {...rest}
-  data-payload-field={field}
-  data-payload-type={type}
-  data-payload-boundary=""
-  data-payload-strategy="patch"
+  {...binding}
   hidden={empty ? true : undefined}
 >
   <slot />

package/dist/adapters/astro/RichText.astro

@@ -70,6 +70,17 @@ const {
   requireDocument,
 } = Astro.props;
 const Tag = tag;
+const locals = Astro.locals as {
+  livePreviewRequiresAuthorization?: boolean;
+  livePreviewAuthorization?: unknown;
+};
+// Where `authorizePreview` decides, a response it did not authorize carries no binding (ADR 0006).
+const bound =
+  field !== undefined &&
+  !(
+    locals.livePreviewRequiresAuthorization === true &&
+    locals.livePreviewAuthorization === undefined
+  );
 const html = isLexicalContent(value)
   ? lexicalToHtml(value, {
       ...(sanitizerDocument === undefined ? {} : { document: sanitizerDocument }),
@@ -80,7 +91,7 @@ const html = isLexicalContent(value)
 
 <Tag
   class={className}
-  data-payload-field={field}
-  data-payload-richtext={field !== undefined ? '' : undefined}
+  data-payload-field={bound ? field : undefined}
+  data-payload-richtext={bound ? '' : undefined}
   set:html={html}
 />

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

@@ -1,10 +1,10 @@
-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';
+import { L as LivePreviewAstroOptions } from '../../middleware-Dnt6u4nF.js';
+export { a as LivePreviewMiddleware, c as createLivePreviewMiddleware } from '../../middleware-Dnt6u4nF.js';
+import { h as hasPreviewIntent } from '../../options-DTzhFVJ4.js';
+export { P as PreviewAdapterOptions, a as PreviewRequestLike, b as PreviewRequestOptions, c as PreviewSignal } from '../../options-DTzhFVJ4.js';
+import { F as FragmentEndpointOptions$1, a as FragmentRegistry$1, b as FragmentRegistryEntry$1, c as FragmentRenderer$1 } from '../../fragment-endpoint-CQE_7MKi.js';
+export { d as FragmentRenderInput } from '../../fragment-endpoint-CQE_7MKi.js';
+export { A as AUTHORIZATION_LOCALS_KEY, a as AUTHORIZATION_OUTCOME_LOCALS_KEY, L as LivePreviewLocals, N as NONCE_LOCALS_KEY } from '../../locals-CyzDKfKU.js';
 
 /**
  * The Astro integration for `astro.config.mjs`: `livePreview({ ... })`.