payload-live-preview 1.8.0 → 2.0.0-beta.0

package/README.md

@@ -18,7 +18,7 @@ Under the hood it's framework-agnostic — the same runtime drives SvelteKit, Nu
 
 |                               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Single source of truth**    | One TypeScript runtime compiled to a self-contained IIFE (~64 KB raw, ~20 KB gzipped) at build time — no parallel inline/class implementations to drift.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **Single source of truth**    | One TypeScript runtime compiled to a self-contained IIFE (~64 KB raw, ~21 KB gzipped) at build time — no parallel inline/class implementations to drift.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | **Payload 3.x native**        | Optional REST data merging (`serverURL`) re-fetches populated documents exactly like the official client, so relationship and upload fields render as content, not as bare IDs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | **Complete Lexical renderer** | 16 node types incl. `upload`, `relationship`, `block`, `autolink`, `tab`, indent, RTL — plus automatic rich-text detection, so `data-payload-field` alone is enough.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | **Intent-gated delivery**     | Server adapters can limit runtime delivery to requests carrying preview-intent signals (`?preview=true`, `Sec-Fetch-Dest: iframe`, admin referer). Those client-controlled signals are an optimisation, never authorization.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
@@ -36,9 +36,26 @@ Under the hood it's framework-agnostic — the same runtime drives SvelteKit, Nu
 | Relationship / upload population               | ✅ (admin merges client-side) | ✅ with `serverURL` (REST merge)                                      |
 | Schema-driven field typing (`fieldSchemaJSON`) | ✅                            | — (3.x removed it; DOM heuristics + Lexical auto-detection take over) |
 
-Astro **4 – 7** is the supported peer range; the current real-app browser fixture exercises Astro 7, not every supported Astro major. Node ≥ 20.19. Protocol compatibility is covered by captured-message integration tests plus a weekly `@payloadcms/live-preview` latest/canary drift check.
+<!-- compat-matrix:start -->
 
-**When to use the official packages instead:** for a client-rendered React or Vue app, [`@payloadcms/live-preview-react`](https://payloadcms.com/docs/live-preview/client) / `-vue` re-render your real component tree and are maintained in lockstep with Payload — that is the better tool there. This package exists for everything the official hooks cannot cover: Astro, static/SSR pages, SvelteKit/Nuxt server-rendered markup, plain HTML — anywhere there is no client framework to re-render the page.
+| Framework | Supported             | Tested in CI on every push (version, browsers)                                    |
+| --------- | --------------------- | --------------------------------------------------------------------------------- |
+| Astro     | >=4.0.0 <8.0.0        | 7.2.1 (chromium, firefox, webkit); 6.x (chromium); 5.x (chromium); 4.x (chromium) |
+| Next.js   | App Router, 15 and 16 | 16.3.0 (chromium, firefox, webkit)                                                |
+| SvelteKit | 2.x                   | 2.70.2 (chromium, firefox, webkit)                                                |
+| Nuxt      | 3.x                   | 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`.
+
+- Payload 2.x: captured-message integration tests and fieldSchemaJSON typing.
+- Payload 3.85.0: wire corpus captured from a real admin, replayed in tests/integration/wire-corpus.test.ts.
+- Payload 3.88.0: real admin E2E (examples/payload-backend) on every push, plus a wire corpus captured from it.
+- Payload latest: weekly protocol watch executes @payloadcms/live-preview@latest against the corpus.
+- Payload 4.0 pre-releases: weekly protocol watch against @payloadcms/live-preview@canary, early warning only.
+
+<!-- compat-matrix:end -->
+
+**When to use the official packages instead:** for a client-rendered React or Vue app, [`@payloadcms/live-preview-react`](https://payloadcms.com/docs/live-preview/client) / `-vue` re-render your real component tree and are maintained in lockstep with Payload — that is the better tool there. This package exists for everything the official hooks cannot cover: Astro, static/SSR pages, SvelteKit/Nuxt server-rendered markup, plain HTML — anywhere there is no client framework to re-render the page. The longer comparison — what is shared, what is not, and running both on one page — is in [docs/interop.md](docs/interop.md).
 
 ## Install
 
@@ -46,6 +63,25 @@ Astro **4 – 7** is the supported peer range; the current real-app browser fixt
 npm install payload-live-preview
 ```
 
+### Package entries
+
+The root import carries everything. The focused entries below ship the same
+code as smaller, self-contained bundles — each with ESM and CommonJS builds,
+its own type declarations, size budget and API report:
+
+| Entry                                                | Contents                                                                                          |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `payload-live-preview`                               | Everything: client, inline script generator, renderers, plugins, adapters' shared helpers.        |
+| `payload-live-preview/core`                          | The client and runtime without the built-in plugin constructors, generator or adapters.           |
+| `payload-live-preview/client`                        | `LivePreviewClient` and `initLivePreview()` alone.                                                |
+| `payload-live-preview/structural`                    | The structural array renderer, the keyed morph (ADR 0008) and the `data-payload-depends` helpers. |
+| `payload-live-preview/lexical`                       | `lexicalToHtml()`, `lexicalToPlainText()`, node and block renderer registries.                    |
+| `payload-live-preview/plugins`                       | `PluginManager`, plugin types and the built-in plugins.                                           |
+| `payload-live-preview/fragment`                      | `createFragmentStrategy()`: the browser half of server-rendered fragment boundaries (ADR 0011).   |
+| `payload-live-preview/server`                        | `definePreview()` and `authorizePreviewRequest()` for server code.                                |
+| `payload-live-preview/{astro,nextjs,sveltekit,nuxt}` | One framework adapter each.                                                                       |
+| `payload-live-preview/codegen`                       | Type generation from a Payload config.                                                            |
+
 ## Configure Payload
 
 Enable live preview in `payload.config.ts` — the `url` callback maps the edited document to the frontend URL shown in the preview iframe. `buildLivePreviewUrl` replaces the usual lookup-table boilerplate:
@@ -78,6 +114,69 @@ export default buildConfig({
 });
 ```
 
+### Authorized preview URLs: a token per page, for a few minutes
+
+The URL above says `?preview=true`, which is intent, not proof. To let the
+frontend verify the iframe request without a session cookie crossing
+origins, mint a short-lived token on the Payload side and verify it in the
+adapter with the `signed-token` strategy. The token is bound to the site,
+the path, the locale and ten minutes; a leaked one is worth that much.
+
+```ts
+// payload.config.ts
+import { buildLivePreviewUrl } from 'payload-live-preview/payload';
+import { issuePreviewToken } from 'payload-live-preview';
+
+const toPreviewUrl = buildLivePreviewUrl({
+  baseUrl: process.env.FRONTEND_URL!,
+  collections: { posts: ({ data }) => `/blog/${String(data.slug ?? '')}` },
+  globals: { homepage: '/' },
+  fallback: '/',
+});
+
+export default buildConfig({
+  admin: {
+    livePreview: {
+      url: async (args) => {
+        const url = new URL(toPreviewUrl(args));
+        const locale = typeof args.locale === 'string' ? args.locale : args.locale?.code;
+        url.searchParams.set(
+          'previewToken',
+          await issuePreviewToken(
+            {
+              audience: url.origin,
+              path: url.pathname,
+              ...(locale ? { locale } : {}),
+              ttlMs: 10 * 60_000,
+            },
+            { secret: process.env.PREVIEW_TOKEN_SECRET! }, // ≥ 32 bytes, shared with the frontend
+          ),
+        );
+        return url.toString();
+      },
+      // …breakpoints, collections, globals as above
+    },
+  },
+});
+```
+
+```ts
+// frontend middleware — the matching side
+authorizePreview: (request) =>
+  authorizePreviewRequest(request, {
+    type: 'signed-token',
+    secret: import.meta.env.PREVIEW_TOKEN_SECRET,
+    audience: import.meta.env.SITE_ORIGIN,
+    locale: (request) => new URL(request.url).pathname.split('/')[1],
+  }),
+```
+
+Keep the query parameter out of access-log formats and error-reporter URLs,
+set `Referrer-Policy: no-referrer` on preview responses, and hand the
+adapter a replay store if a replay inside the ten minutes matters to you —
+[ADR 0006](docs/architecture/0006-authorized-preview-context.md) lists the
+channels and what each binding closes.
+
 The helper appends `?preview=true` automatically so the adapters detect preview intent. That query parameter is client-controlled and does not authorize draft access or response changes. A hand-written `url: ({ data, locale, collectionConfig, globalConfig }) => string` callback works exactly the same — see the [official docs](https://payloadcms.com/docs/live-preview/overview) for the full contract.
 
 **Documents without a preview target.** Not every document has a reachable
@@ -117,6 +216,8 @@ export default defineConfig({
       allowedOrigins: [import.meta.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN],
       // Payload 3.x: populate relationship/upload fields via REST merge
       serverURL: import.meta.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN,
+      // Required alongside serverURL: the population depth, 0 for none.
+      mergeDepth: 1,
     }),
   ],
 });
@@ -166,12 +267,14 @@ The trade is one extra request the first time an editor opens a preview.
 Under a strict CSP, the asset itself is unremarkable: a same-origin script with an `integrity` attribute, needing no `'unsafe-inline'`. The bootstrap does need covering, though — a static build has no request, so there is no per-request nonce to attach and Astro emits it as a plain inline `<script>`. Its content is deterministic for a given package version and configuration, so the practical answer is a `'sha256-…'` source expression rather than `'unsafe-inline'`. `mode: 'middleware'` is the option that can carry a real nonce, because there a request exists to derive one from.
 
 For SSR projects (`output: 'server'`), request-time injection can limit the bytes to requests carrying preview intent:
+continue
 
 ```ts
 livePreview({
   mode: 'middleware',
   allowedOrigins: [import.meta.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN],
   serverURL: import.meta.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN,
+  mergeDepth: 1,
 }),
 ```
 
@@ -181,34 +284,24 @@ If draft data or response changes are privileged, use one application-owned serv
 
 ```ts
 // src/middleware.ts
-import { createLivePreviewMiddleware, isPreviewRequest } from 'payload-live-preview/astro';
-import { verifyAppPreviewSession } from './lib/server/preview-auth'; // your server code
+import { createLivePreviewMiddleware } from 'payload-live-preview/astro';
+import { authorizePreviewRequest } from 'payload-live-preview';
 
-const previewMiddleware = createLivePreviewMiddleware({
+export const onRequest = createLivePreviewMiddleware({
   allowedOrigins: [import.meta.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN],
+  strict: true,
+  // Runs only on requests with preview intent. A refusal leaves the response
+  // exactly as rendered: no runtime, no CSP change, no nonce in Astro.locals.
+  authorizePreview: (request) =>
+    authorizePreviewRequest(request, {
+      type: 'payload-session',
+      serverURL: import.meta.env.PAYLOAD_URL,
+    }),
 });
-
-export const onRequest = async (context, next) => {
-  const hasPreviewIntent = isPreviewRequest(context.request, {
-    adminOrigins: [import.meta.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN],
-  });
-  const authorization = hasPreviewIntent ? await verifyAppPreviewSession(context.request) : null;
-
-  if (authorization === null) return next();
-
-  // Reuse this request-scoped decision in the page's draft fetch.
-  context.locals.previewAuthorization = authorization;
-  const response = await previewMiddleware(context, next);
-  const headers = new Headers(response.headers);
-  headers.set('cache-control', 'private, no-store');
-  return new Response(response.body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
-  });
-};
 ```
 
+The same verdict gates the page: read `Astro.locals.livePreviewNonce` for your own scripts, and pass the context to `fetchPreviewDocument({ authorization })` and `createPreviewBindings({ authorization })` so draft selection and `data-payload-*` emission follow it. Three strategies exist — `payload-session`, `signed-token` (issued by `issuePreviewToken()` on the Payload side, bound to site, path, locale and a few minutes) and `verifier` (your own function). [ADR 0006](docs/architecture/0006-authorized-preview-context.md) is the threat model.
+
 ### Next.js (App Router)
 
 > **Client-rendered React app?** Use the official [`@payloadcms/live-preview-react`](https://payloadcms.com/docs/live-preview/client) (`useLivePreview`) instead — it re-renders your real component tree, so conditional sections and custom components update with full fidelity, and it ships in lockstep with Payload. This package's DOM patching targets **server-rendered/static markup**; a hydrating React tree can revert its patches on re-render. For React Server Components, Payload's `RefreshRouteOnSave` is the save-triggered equivalent.
@@ -222,6 +315,7 @@ import { generateInlineScript } from 'payload-live-preview';
 const previewScript = generateInlineScript({
   allowedOrigins: [process.env.PAYLOAD_ADMIN_ORIGIN!],
   serverURL: process.env.PAYLOAD_ADMIN_ORIGIN!,
+  mergeDepth: 1,
 });
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
@@ -240,10 +334,18 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 // middleware.ts — frame-ancestors on requests carrying preview intent
 import { NextResponse, type NextRequest } from 'next/server';
 import { createLivePreviewMiddleware } from 'payload-live-preview/nextjs';
+import { authorizePreviewRequest } from 'payload-live-preview';
 
 const livePreview = createLivePreviewMiddleware({
   allowedOrigins: [process.env.PAYLOAD_ADMIN_ORIGIN!],
   autoInject: false,
+  // Required under the 2.0 defaults: `strict` is on, and without this hook the
+  // adapter refuses rather than gating a response on client-controlled intent.
+  authorizePreview: (request) =>
+    authorizePreviewRequest(request, {
+      type: 'payload-session',
+      serverURL: process.env.PAYLOAD_ADMIN_ORIGIN!,
+    }),
 });
 
 export async function middleware(request: NextRequest) {
@@ -257,25 +359,45 @@ A static build cannot make a request-time authorization decision, so the inline
 
 ```ts
 // src/hooks.server.ts
+import { env } from '$env/dynamic/private';
 import { livePreviewHandle } from 'payload-live-preview/sveltekit';
+import { authorizePreviewRequest } from 'payload-live-preview';
+const adminOrigin = env.PAYLOAD_ADMIN_ORIGIN ?? '';
 export const handle = livePreviewHandle({
-  allowedOrigins: [process.env.PAYLOAD_ADMIN_ORIGIN!],
-  serverURL: process.env.PAYLOAD_ADMIN_ORIGIN!,
+  allowedOrigins: [adminOrigin],
+  serverURL: adminOrigin,
+  mergeDepth: 1,
+  // Required under the 2.0 defaults; without it the handle refuses and every
+  // route, not only the preview, fails.
+  authorizePreview: (request) =>
+    authorizePreviewRequest(request, { type: 'payload-session', serverURL: adminOrigin }),
 });
 ```
 
+`$env/dynamic/private` rather than `process.env`: a SvelteKit project carries no
+Node globals in its types unless it adds `@types/node`, so the `process.env`
+form does not type-check in a fresh one.
+
 This shorthand performs intent-gated delivery, not authentication. For protected preview responses, wrap it and invoke it only after an application-owned server verifier succeeds; reuse that authorization for draft data and cache policy.
 
-### Nuxt 3
+### Nuxt
 
 ```ts
 // server/plugins/live-preview.ts
 import { livePreviewNitroPlugin } from 'payload-live-preview/nuxt';
+import { authorizePreviewRequest } from 'payload-live-preview';
 
 export default defineNitroPlugin(
   livePreviewNitroPlugin({
     allowedOrigins: [process.env.NUXT_PUBLIC_PAYLOAD_ADMIN_ORIGIN!],
     serverURL: process.env.NUXT_PUBLIC_PAYLOAD_ADMIN_ORIGIN!,
+    mergeDepth: 1,
+    // Required under the 2.0 defaults; without it the plugin refuses.
+    authorizePreview: (request) =>
+      authorizePreviewRequest(request, {
+        type: 'payload-session',
+        serverURL: process.env.NUXT_PUBLIC_PAYLOAD_ADMIN_ORIGIN!,
+      }),
   }),
 );
 ```
@@ -291,6 +413,7 @@ import { generateInlineScript, wrapWithScriptTag } from 'payload-live-preview';
 const script = generateInlineScript({
   allowedOrigins: ['https://admin.example.com'],
   serverURL: 'https://admin.example.com',
+  mergeDepth: 1,
 });
 // Inject via `<script>${script}</script>` — or wrapWithScriptTag(script, { nonce }).
 ```
@@ -308,48 +431,88 @@ Requirements: the preview page must be able to reach the Payload API with the ed
 Live preview patches the DOM **after** the page has loaded — the initial server render is your job. If you use Payload drafts, fetch draft content only after authorizing the preview request; otherwise editors see stale published content until their first keystroke. `fetchPreviewDocument` / `fetchPreviewGlobal` build the REST query but deliberately do not authenticate it. Their 1.x `draft` default remains `true` for compatibility, so set it explicitly from your verified decision:
 
 ```ts
-// Astro example — in your page/loader code. The middleware example
-// above stored this application-owned, request-scoped authorization.
-import { fetchPreviewDocument } from 'payload-live-preview';
+// src/lib/preview.ts — server-only
+import { definePreview } from 'payload-live-preview/server';
 
-const authorization = Astro.locals.previewAuthorization ?? null;
-const page = await fetchPreviewDocument<Page>({
+export const preview = definePreview({
   serverURL: import.meta.env.PAYLOAD_URL,
+  depth: 1, // one number for the initial read and the runtime merge
+});
+```
+
+```astro
+---
+import { preview } from '../lib/preview';
+
+const result = await preview.fetchDocument<Page>({
   collection: 'pages',
   where: { slug: { equals: Astro.params.slug } },
-  draft: authorization !== null, // published for unauthorised/normal traffic
-  depth: 1, // keep equal to mergeDepth!
-  ...(authorization === null ? {} : { headers: authorization.payloadHeaders }),
+  authorization: Astro.locals.livePreviewAuthorization ?? null, // draft only with a verified context
+  signal: Astro.request.signal,
 });
+if (!result.ok) return new Response(null, { status: 503 }); // or log result.reason
+const page = result.data;
+---
 ```
 
-`isPreviewRequest()` is intentionally retained as the 1.x compatibility name, but it detects intent only. Query parameters, iframe navigation, and referrers are not credentials. Do not attach a long-lived API key or service token based on its boolean result; the verifier should forward only the minimum request-scoped session material or validate a short-lived, scoped signature.
+Spread `preview.runtimeOptions` (`serverURL`, `apiRoute`, `mergeDepth`) into the adapter so the runtime merges at the depth the page was read with. The root-entry `fetchPreviewDocument()` / `fetchPreviewGlobal()` keep their 1.x behaviour (draft by default, `null` on failure) and are deprecated.
+
+`hasPreviewIntent()` (and its deprecated alias `isPreviewRequest()`) detects intent only. Query parameters, iframe navigation, and referrers are not credentials. Do not attach a long-lived API key or service token based on its boolean result; the verifier should forward only the minimum request-scoped session material or validate a short-lived, scoped signature.
 
 ## Data-attribute reference
 
-| Attribute                      | Purpose                                                                                       | Example                                            |
-| ------------------------------ | --------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| `data-payload-field`           | Bind element to a Payload field path                                                          | `data-payload-field="hero.title"`                  |
-| `data-payload-type`            | Force a specific renderer                                                                     | `data-payload-type="image"`                        |
-| `data-payload-attribute`       | Write the value into an attribute instead of content (unsafe attributes and URLs are refused) | `data-payload-attribute="datetime"`                |
-| `data-payload-href`            | Read `href` from a sibling field                                                              | `data-payload-href="ctaUrl"`                       |
-| `data-payload-src`             | Read `src` from a sibling field                                                               | `data-payload-src="hero.url"`                      |
-| `data-payload-alt`             | Read `alt` from a sibling field                                                               | `data-payload-alt="hero.alt"`                      |
-| `data-payload-richtext`        | Force Lexical rendering (usually auto-detected)                                               | `data-payload-richtext`                            |
-| `data-payload-html`            | Render value as sanitised HTML                                                                | `data-payload-html`                                |
-| `data-payload-array`           | Treat value as an array                                                                       | `data-payload-array`                               |
-| `data-payload-array-template`  | HTML template per array item                                                                  | `data-payload-array-template="<li>{{title}}</li>"` |
-| `data-payload-array-separator` | Separator for primitive arrays                                                                | `data-payload-array-separator=" · "`               |
-| `data-payload-structural`      | Use diff-based structural updates                                                             | `data-payload-structural`                          |
-| `data-payload-locale`          | Override locale for this element                                                              | `data-payload-locale="de-AT"`                      |
-| `data-payload-owner`           | Document this subtree belongs to (see below)                                                  | `data-payload-owner="global:homepage"`             |
+| Attribute                      | Purpose                                                                                                                                                                                                                                     | Example                                            |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `data-payload-field`           | Bind element to a Payload field path                                                                                                                                                                                                        | `data-payload-field="hero.title"`                  |
+| `data-payload-type`            | Force a specific renderer                                                                                                                                                                                                                   | `data-payload-type="image"`                        |
+| `data-payload-attribute`       | Write the value into an attribute instead of content (unsafe attributes and URLs are refused)                                                                                                                                               | `data-payload-attribute="datetime"`                |
+| `data-payload-href`            | Read `href` from a sibling field                                                                                                                                                                                                            | `data-payload-href="ctaUrl"`                       |
+| `data-payload-src`             | Read `src` from a sibling field                                                                                                                                                                                                             | `data-payload-src="hero.url"`                      |
+| `data-payload-alt`             | Read `alt` from a sibling field                                                                                                                                                                                                             | `data-payload-alt="hero.alt"`                      |
+| `data-payload-richtext`        | Force Lexical rendering (usually auto-detected)                                                                                                                                                                                             | `data-payload-richtext`                            |
+| `data-payload-html`            | Render value as sanitised HTML                                                                                                                                                                                                              | `data-payload-html`                                |
+| `data-payload-array`           | Treat value as an array                                                                                                                                                                                                                     | `data-payload-array`                               |
+| `data-payload-array-template`  | HTML template per array item                                                                                                                                                                                                                | `data-payload-array-template="<li>{{title}}</li>"` |
+| `data-payload-array-separator` | Separator for primitive arrays                                                                                                                                                                                                              | `data-payload-array-separator=" · "`               |
+| `data-payload-structural`      | Use diff-based structural updates                                                                                                                                                                                                           | `data-payload-structural`                          |
+| `data-payload-locale`          | Override locale for this element                                                                                                                                                                                                            | `data-payload-locale="de-AT"`                      |
+| `data-payload-owner`           | Document this subtree belongs to (see below)                                                                                                                                                                                                | `data-payload-owner="global:homepage"`             |
+| `data-payload-depends`         | Fields whose change re-applies this binding under `skipUnchanged`, e.g. `data-payload-depends="price currency"`                                                                                                                             | `data-payload-depends="price"`                     |
+| `data-payload-strategy`        | Delivery strategy: `patch` (default), `fragment` (server-rendered boundary) or `route` (whole-route refresh); anything else is left alone with `LP0407`. Without it: inside a fragment boundary → fragment, in `<head>` → route, else patch | `data-payload-strategy="route"`                    |
+| `data-payload-fragment`        | A server-rendered boundary; the value is a registry id the endpoint may render ([docs/hybrid.md](docs/hybrid.md))                                                                                                                           | `data-payload-fragment="hero"`                     |
+| `data-payload-fragment-key`    | Distinguishes several boundaries of one id on a page                                                                                                                                                                                        | `data-payload-fragment-key="a"`                    |
+| `data-payload-boundary`        | A stable anchor for a possibly-empty field: hidden while empty, shown when filled (`PreviewBoundary.astro` renders it)                                                                                                                      | `data-payload-boundary hidden`                     |
+| `data-payload-island`          | A hydrated framework root: never patched or morphed into (see docs/renderers.md, islands)                                                                                                                                                   | `data-payload-island`                              |
+| `data-payload-owned`           | A subtree the site scripts itself: the morph retains it whole                                                                                                                                                                               | `data-payload-owned`                               |
+
+The `{{field}}` mustache in `data-payload-array-template` is read by this
+package, not by your framework — but Svelte reads `{...}` and Vue reads
+`{{ ... }}` as their own interpolation, so writing the template inline in a
+`.svelte` or `.vue` file is a compile error or a silently empty value. Bind it
+as a string instead:
+
+```svelte
+<script lang="ts">
+  const template = '<li><a data-payload-href="url">{{title}}</a></li>';
+</script>
+<ul data-payload-field="posts" data-payload-array-template={template}></ul>
+```
+
+```vue
+<script setup lang="ts">
+const template = '<li><a data-payload-href="url">{{title}}</a></li>';
+</script>
+<template>
+  <ul data-payload-field="posts" :data-payload-array-template="template"></ul>
+</template>
+```
 
 Binding metadata is live: changing any of these attributes (including inferred
 type markers and an input's native `type`) rebuilds the affected cache snapshot
 after the mutation debounce. Locale-specific bindings resolve their own suffixed
 field value, and stale work prepared for a previous element locale is discarded.
 
-**Empty-field gotcha:** the runtime can only patch elements that exist. If your template renders a binding only when the field is non-empty, editing a previously-empty field has nowhere to land. Render the anchor unconditionally:
+**Empty-field gotcha:** the runtime can only patch elements that exist. `PreviewBoundary.astro` (`payload-live-preview/astro/PreviewBoundary.astro`) renders a hidden anchor for an empty field and the runtime unhides it when the editor fills the field. If your template renders a binding only when the field is non-empty, editing a previously-empty field has nowhere to land. Render the anchor unconditionally:
 
 ```astro
 <div data-payload-field="subtitle">{subtitle ?? ''}</div>
@@ -453,7 +616,7 @@ marker of your own that has nothing to do with preview state.
 
 `text` · `textarea` · `richText` · `html` · `email` · `number` · `checkbox` · `date` · `select` · `radio` · `relationship` · `upload` · `image` · `url` · `array` · `blocks` · `structural-array`
 
-Custom renderers register via the plugin system:
+Custom renderers register via the plugin system (see [docs/renderers.md](docs/renderers.md) for what a renderer receives, namespaced custom keys such as `acme:money`, the `resolveRenderer` and `renderRichText` client options, and the plugin ownership contract):
 
 ```ts
 import { LivePreviewClient } from 'payload-live-preview';
@@ -475,6 +638,22 @@ await client.use({
 });
 ```
 
+## Hybrid preview: fragments
+
+Patching edits what the page already renders. 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 in with focus and visitor state intact. The runtime posts
+the fields to a same-origin endpoint you build with `createFragmentEndpoint()`
+(Astro; registry of components, the same authorization strategies as the
+page, no code or paths cross the wire), and patches the boundary's own
+bindings if the server cannot render. Opt in per boundary; a page without
+`fragments` carries no fragment client. [docs/hybrid.md](docs/hybrid.md) has
+the markup, the endpoint, the deployment requirements and the abuse model
+(ADR 0011). A binding in `<head>` or one marked `data-payload-strategy="route"`
+refreshes the whole route once per revision instead, with scroll and focus
+kept and the unsaved state re-applied on the fresh markup.
+
 ## Typed bindings and codegen
 
 Generate interfaces straight from your Payload config:
@@ -510,7 +689,9 @@ client.events.on('beforeUpdate', (e) => {
 client.events.on('documentSave', () => location.reload());
 ```
 
-Events: `init` · `connect` · `disconnect` · `beforeUpdate` · `afterUpdate` · `elementUpdate` · `documentSave` · `cacheRefresh` · `error` · `destroy`.
+Events: `init` · `connect` · `disconnect` · `beforeUpdate` · `afterUpdate` · `elementUpdate` · `documentSave` · `relationshipUpdate` · `cacheRefresh` · `error` · `destroy`. `relationshipUpdate` fires when an update carries `externallyUpdatedRelationship` (a related document edited in an admin drawer); that update re-renders every bound field even under `skipUnchanged`, because populated values may have changed while the form values did not.
+
+Since 1.1.0 `beforeUpdate`, `afterUpdate` and `elementUpdate` also carry `receivedAt` (when the runtime accepted the message, Unix ms) and `source` (`'patch'` for an admin postMessage; fragment strategies will name themselves here), next to `revision`.
 
 Plugin resources are registration-scoped. `client.unuse(name)` revokes that registration's event listeners, transforms, renderer layers, and `registerCleanup()` callbacks without touching another plugin or the built-in renderer; registering it again starts with a fresh scope. Resources remain staged until `init()` succeeds, and a failed `init()` rolls them back without exposing a partial registration. Renderers form a per-type stack (last active registration wins, removal reveals the previous layer). Synchronous transforms see the merged field value and run in registration order while each revision-bound binding entry is prepared, immediately before that entry is scheduled. The transformed value is fixed in the entry and later passes through the normal attribute or renderer dispatch. A thrown error or Promise/thenable result emits a lifecycle `error` and stores the original merged value as fallback, which still passes through the normal security checks.
 
@@ -540,15 +721,18 @@ Options accepted by `generateInlineScript`, every adapter, and `LivePreviewClien
 Additional runtime options accepted by `generateInlineScript` and `LivePreviewClient`
 (not by the adapter option objects):
 
-| Option                     | Default   | Meaning                                                                                                                                                                                               |
-| -------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `enableA11y`               | `true`    | Shared `aria-live` region announcing connections, applied updates, and heartbeat-timeout disconnects while mounted; destroy releases it synchronously without promising a final audible announcement. |
-| `disableVisibilityGate`    | `false`   | Apply updates to off-screen elements immediately.                                                                                                                                                     |
-| `visibilityGateThreshold`  | `50`      | Cache size above which off-screen updates are queued.                                                                                                                                                 |
-| `scopeBindingsByOwner`     | `false`   | Restrict each update to bindings owned by the document it names (`data-payload-owner`). Unowned bindings stop updating.                                                                               |
-| `intersectionRootMargin`   | `'200px'` | Pre-render margin for the visibility gate.                                                                                                                                                            |
-| `disableReferrerDetection` | `false`   | Opt out of `document.referrer` origin auto-detection.                                                                                                                                                 |
-| `disableLocalhostMatching` | `false`   | Opt out of dev-mode localhost origin matching.                                                                                                                                                        |
+| Option                     | Default    | Meaning                                                                                                                                                                                                                           |
+| -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enableA11y`               | `true`     | Shared `aria-live` region announcing connections, applied updates, and heartbeat-timeout disconnects while mounted; destroy releases it synchronously without promising a final audible announcement.                             |
+| `disableVisibilityGate`    | `false`    | Apply updates to off-screen elements immediately.                                                                                                                                                                                 |
+| `visibilityGateThreshold`  | `50`       | Cache size above which off-screen updates are queued.                                                                                                                                                                             |
+| `scopeBindingsByOwner`     | `false`    | Restrict each update to bindings owned by the document it names (`data-payload-owner`). Unowned bindings stop updating.                                                                                                           |
+| `skipUnchanged`            | `false`    | Skip a binding whose value is identical to the one it last applied, so a keystroke re-renders only what changed. Renderers and `elementUpdate` then stop seeing repeats; `inspect().revisions.skippedUnchanged` counts the skips. |
+| `sanitizerPolicy`          | `'compat'` | `'strict'` (the 2.0 default, set by `defaults: 'v2'`) strips `id`, `name` and `data-payload-*` from rich-text/HTML writes and passes other `data-*` only by list — see docs/security.md §3.                                       |
+| `dependencies`             | `{}`       | Fields whose change re-applies other bindings even when their own value did not change: `{ price: ['priceLabel'] }`. Used only with `skipUnchanged`.                                                                              |
+| `intersectionRootMargin`   | `'200px'`  | Pre-render margin for the visibility gate.                                                                                                                                                                                        |
+| `disableReferrerDetection` | `false`    | Opt out of `document.referrer` origin auto-detection.                                                                                                                                                                             |
+| `disableLocalhostMatching` | `false`    | Opt out of dev-mode localhost origin matching.                                                                                                                                                                                    |
 
 `LivePreviewClient` additionally accepts the programmatic-only `mergeFetch`,
 `a11yLocale`, `root`, `autoStart`, and `validateToken` options. `validateToken` is a
@@ -565,7 +749,16 @@ does not suppress CSP handling. Astro additionally accepts `mode` (`'inline'` /
 per-request `nonce`; `generateInlineScript()` itself returns a script body, so pass
 the nonce to `wrapWithScriptTag()` when embedding it manually.
 
-Bundle-size note: `import … from 'payload-live-preview/core'` is a lighter entry without the built-in plugin constructors, inline generator/runtime source, or framework adapters. It still includes the built-in field renderers used by `LivePreviewClient`, including Lexical rendering. Hot-path timings live in [docs/benchmarks.md](docs/benchmarks.md).
+Bundle-size note: the root barrel tree-shakes, and that is measured rather
+than declared — `npm run test:treeshake` bundles one-symbol consumers with
+Vite against the built package and holds each to a budget. Importing
+`escapeHtml` from the root ships 220 B gzip, `lexicalToHtml` 4.3 KB,
+`initLivePreview` 30.5 KB (the client with its built-in renderers, Lexical
+included), `generateInlineScript` 24.8 KB (the inline runtime source and
+nothing of the client). The focused entries under [Package entries](#package-entries)
+give a bundler less to look through and a reader a smaller surface; the
+bytes are the same. Hot-path timings and the tree-shaking table live in
+[docs/benchmarks.md](docs/benchmarks.md).
 
 The four real-app browser fixtures in `examples/` cover Astro 7, Next.js 16, SvelteKit 2, and Nuxt 3 in Chromium, Firefox, and WebKit. The Astro 4–7 peer range is broader than the single Astro-major browser fixture.
 
@@ -573,7 +766,7 @@ The four real-app browser fixtures in `examples/` cover Astro 7, Next.js 16, Sve
 
 1. **Full running-Payload E2E** (`tests/real-payload/`, `npm run test:e2e:real-payload`) boots an **actual Payload 3.x admin** — `examples/payload-backend`, a self-contained SQLite Payload + Next.js server, seeded and auto-logged-in — opens its **real** Live Preview panel, types into real form fields, and asserts the cross-origin Astro preview iframe (our injected runtime) patches the DOM. No mock, no fixture, no stub: `real admin → real form → real postMessage → real iframe → runtime → DOM`, driven by Payload's own admin code.
 2. **Browser E2E** (`tests/e2e/`) drives a real browser + real iframe across Chromium, Firefox and WebKit: `postMessage → runtime → DOM`. Its `/admin` page _emulates_ the Payload admin, so it can exercise edge cases (XSS, origin spoofing, every field type) faster than booting a full server.
-3. **Real-message contract test** (`tests/integration/real-payload-protocol.test.ts`) feeds a message **captured verbatim from a running Payload 3.85 admin** through the real `MessageBus` + runtime — the envelope quirks included: `collectionSlug` absent on a global, `externallyUpdatedRelationship: null`, `_status`/`id` alongside real fields.
+3. **Wire corpus** (`tests/fixtures/wire-corpus/`, one file per Payload version, recorded from a real admin by `tests/real-payload/record-wire-corpus.spec.ts` with `PLP_RECORD_CORPUS=1`) is replayed through the real runtime by `tests/integration/wire-corpus.test.ts`: every capture must validate, render, and demonstrate exactly the capabilities the runtime then reports. The protocol watch also checks that the official client still recognises every captured message. The original **real-message contract test** (`tests/integration/real-payload-protocol.test.ts`) feeds a message **captured verbatim from a running Payload 3.85 admin** through the real `MessageBus` + runtime — the envelope quirks included: `collectionSlug` absent on a global, `externallyUpdatedRelationship: null`, `_status`/`id` alongside real fields.
 4. **Weekly protocol-watch** (`.github/workflows/protocol-watch.yml`) **executes** the real `@payloadcms/live-preview@latest` **and `@canary`** (Payload 4.0 pre-releases) and asserts their actual behaviour — the `ready` handshake, event discriminators, and `mergeData` REST request — still matches our runtime's invariants.
 
 Together these span the whole spectrum: tier 1 proves the real thing works end to end, tier 2 exhausts edge cases quickly, tier 3 pins the exact wire shape Payload emits, and tier 4 catches drift the moment Payload ships it.
@@ -613,14 +806,19 @@ console.log(client.inspect());
 
 The snapshot answers the questions that are otherwise guesswork:
 
-| Reading                                                    | What it tells you                                                                                                                                                                    |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `bindings.orphanFields`                                    | Field names that arrived but matched no element. A name here is a markup problem; a name in neither this nor `bindings.fieldNames` was never sent.                                   |
-| `scheduler.deferred` with `scheduler.visibilityGateActive` | Updates the visibility gate is holding until the element scrolls into view. On a page nobody scrolls, that is "never" — the symptom is a preview that stops updating below the fold. |
-| `revisions.superseded`                                     | Updates abandoned because a newer one arrived. Tracking `accepted` closely is normal for fast typing; it only matters when the _last_ update is among them.                          |
-| `origins.locked`                                           | The origin the runtime locked onto after its first accepted update. Every other origin is refused from then on.                                                                      |
-| `bindings.ownerScoped` with `bindings.owners`              | Whether owner scoping is on, and which documents the page declares. Under scoping, an unowned binding receives nothing.                                                              |
-| `protocol.negotiated`                                      | The version both sides share, which caps the capabilities in `protocol.capabilities`.                                                                                                |
+| Reading                                                    | What it tells you                                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bindings.orphanFields`                                    | Field names that arrived but matched no element. A name here is a markup problem; a name in neither this nor `bindings.fieldNames` was never sent.                                                                                                                                                        |
+| `scheduler.deferred` with `scheduler.visibilityGateActive` | Updates the visibility gate is holding until the element scrolls into view. On a page nobody scrolls, that is "never" — the symptom is a preview that stops updating below the fold.                                                                                                                      |
+| `revisions.superseded`                                     | Updates abandoned because a newer one arrived. Tracking `accepted` closely is normal for fast typing; it only matters when the _last_ update is among them.                                                                                                                                               |
+| `revisions.completed`                                      | Updates whose flush ran — their writes reached the DOM, or there was nothing to write. `accepted − superseded − completed` is in flight or cancelled.                                                                                                                                                     |
+| `origins.locked`                                           | The origin the runtime locked onto after its first accepted update. Every other origin is refused from then on.                                                                                                                                                                                           |
+| `bindings.ownerScoped` with `bindings.owners`              | Whether owner scoping is on, and which documents the page declares. Under scoping, an unowned binding receives nothing.                                                                                                                                                                                   |
+| `protocol.negotiated`                                      | The version both sides share, which caps the capabilities in `protocol.capabilities`.                                                                                                                                                                                                                     |
+| `protocol.observed`                                        | Capabilities seen on the wire rather than granted by version — the stock admin announces no version, so this is how its abilities become known (`locale`, `schema-json`, `document-events`, `relationship-events`, `preview-token`). Each capability declares a fallback; see `CAPABILITY_DOCUMENTATION`. |
+| `protocol.profile`                                         | What the observed capabilities imply: `payload-2` (a schema on the wire; the admin populates relationships itself, so no REST merge), `payload-3` (document or relationship events seen), or `unknown` (treated like 3.x for merging).                                                                    |
+| `fragments`                                                | Server-rendered boundaries: `handler` (a fragment client is configured), `inFlight`, `rendered`, `failed`, `superseded`.                                                                                                                                                                                  |
+| `route`                                                    | Route refreshes: `handler`, `refreshes`, `failed`, `loopStopped` (second requests for one revision, refused with `LP0805`).                                                                                                                                                                               |
 
 This is deliberately not gated to development builds. A snapshot discloses
 nothing that is not already on the page — the trusted origins are inside the
@@ -670,23 +868,33 @@ Every message the runtime reports carries a stable code. Prose gets reworded; a
 code does not — so a log filter, an alert rule, or a bug report that names
 `LP0301` still means the same thing after the sentence around it changes.
 
-| Code     | Meaning                                              | What to do                                                                                             |
-| -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `LP0101` | No trusted origin configured in production           | Set `PAYLOAD_ADMIN_ORIGIN` or pass `allowedOrigins`. Nothing is accepted until you do.                 |
-| `LP0102` | Origin trust rests on `document.referrer`            | Any framing site is trusted. Set `allowedOrigins` and a `frame-ancestors` CSP.                         |
-| `LP0201` | An update named a field with no binding on the page  | Render the binding anchor unconditionally so edits to an initially-empty field have somewhere to land. |
-| `LP0202` | Owner scoping is on and the update names no document | The message carries neither a global slug nor a collection slug plus id.                               |
-| `LP0301` | The visibility gate held offscreen writes back       | Raise `visibilityGateThreshold`, or accept that below-the-fold updates wait for a scroll.              |
-| `LP0401` | A value was refused as an unsafe attribute write     | The attribute or the value is not safe to write; see the security model.                               |
-| `LP0402` | A text element has structured children               | Move `data-payload-field` to the value element, or add `data-payload-text`.                            |
-| `LP0403` | A structural container has no array template         | Add `data-payload-array-template`.                                                                     |
-| `LP0501` | A message was rejected before the update pipeline    | Reason is one of origin, shape, type, token. Visible with `debug: true`.                               |
-| `LP0502` | A preview token was rejected                         | Also reported when your `validateToken` throws — a throwing validator fails closed.                    |
-| `LP0601` | A consumer event handler threw                       | Your `on(...)` handler; the runtime continued.                                                         |
-| `LP0602` | A consumer transform threw                           | The original value was kept.                                                                           |
-| `LP0603` | A renderer threw while writing                       | That one write was abandoned.                                                                          |
-| `LP0605` | Runtime startup failed                               |                                                                                                        |
-| `LP0606` | Sending the ready handshake failed                   |                                                                                                        |
+| Code     | Meaning                                                  | What to do                                                                                               |
+| -------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `LP0101` | No trusted origin configured in production               | Set `PAYLOAD_ADMIN_ORIGIN` or pass `allowedOrigins`. Nothing is accepted until you do.                   |
+| `LP0102` | Origin trust rests on `document.referrer`                | Any framing site is trusted. Set `allowedOrigins` and a `frame-ancestors` CSP.                           |
+| `LP0201` | An update named a field with no binding on the page      | Render the binding anchor unconditionally so edits to an initially-empty field have somewhere to land.   |
+| `LP0202` | Owner scoping is on and the update names no document     | The message carries neither a global slug nor a collection slug plus id.                                 |
+| `LP0301` | The visibility gate held offscreen writes back           | Raise `visibilityGateThreshold`, or accept that below-the-fold updates wait for a scroll.                |
+| `LP0401` | A value was refused as an unsafe attribute write         | The attribute or the value is not safe to write; see the security model.                                 |
+| `LP0402` | A text element has structured children                   | Move `data-payload-field` to the value element, or add `data-payload-text`.                              |
+| `LP0403` | A structural container has no array template             | Add `data-payload-array-template`.                                                                       |
+| `LP0404` | A structural item has no `id`                            | Give items a stable `id`; without one they pair by position and an insert re-renders every row after it. |
+| `LP0405` | Two structural items share a key                         | Make `id` unique per item; later duplicates pair by position.                                            |
+| `LP0406` | Every structural key changed at once                     | The source generates keys per message; the morph cannot retain nodes across such updates.                |
+| `LP0407` | A binding asks for a strategy this release does not have | Only `patch` and `fragment` exist; the element is left unchanged.                                        |
+| `LP0801` | A fragment request failed                                | Network, timeout or a 5xx from the endpoint; the boundary was patched from the same revision instead.    |
+| `LP0802` | A fragment response was invalid                          | Wrong content type, shape, size or boundary; patched instead.                                            |
+| `LP0803` | The fragment endpoint refused the preview                | 401/403 — the page's authorization did not hold for the endpoint; patched instead.                       |
+| `LP0804` | A late fragment response was discarded                   | It belonged to a superseded revision; nothing was applied.                                               |
+| `LP0805` | A route refresh loop was stopped                         | The same revision asked for a second refresh; the guard refused it.                                      |
+| `LP0806` | A fragment boundary has no fragment client               | Configure `fragments` (the endpoint) to render it on the server; until then it is patched.               |
+| `LP0501` | A message was rejected before the update pipeline        | Reason is one of origin, shape, type, token. Visible with `debug: true`.                                 |
+| `LP0502` | A preview token was rejected                             | Also reported when your `validateToken` throws — a throwing validator fails closed.                      |
+| `LP0601` | A consumer event handler threw                           | Your `on(...)` handler; the runtime continued.                                                           |
+| `LP0602` | A consumer transform threw                               | The original value was kept.                                                                             |
+| `LP0603` | A renderer threw while writing                           | That one write was abandoned.                                                                            |
+| `LP0605` | Runtime startup failed                                   |                                                                                                          |
+| `LP0606` | Sending the ready handshake failed                       |                                                                                                          |
 
 Codes on the `error` event can be branched on directly: