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

package/dist/index.d.ts

@@ -1,67 +1,22 @@
-/**
- * Single source of truth for the library version.
- *
- * Both the npm package surface (`src/index.ts`, `src/core-entry.ts`)
- * and the inline runtime (`src/core/runtime.ts`, which gets bundled by
- * esbuild and embedded into `runtime.generated.ts`) read the version
- * from here so they never drift.
- *
- * Imports `package.json` directly — tsc, tsup, and esbuild all inline
- * the value at build time when `resolveJsonModule` is enabled.
- *
- * @module @/version
- */
+/** The package version, read from package.json so the entries and the inline runtime cannot drift. */
 declare const VERSION: string;
 
-/**
- * Connection state + heartbeat.
- *
- * Tracks whether the runtime is currently receiving updates from a
- * trusted origin and fires a callback when the heartbeat times out.
- *
- * The heartbeat is reset on every valid message and considered dead
- * after `timeoutMs` of silence. The host typically responds by
- * re-sending the `ready` handshake to attempt reconnection.
- *
- * @module @core/state
- */
+/** Connection status and the heartbeat that decides a disconnect. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected';
 
 /**
- * The shape of a live-preview inspection snapshot.
- *
- * This module is types only. The snapshot is assembled by
- * `LivePreviewRuntime.inspect()` as a plain object literal, because the inline
- * runtime pays for every byte of indirection and the assembly needs access to
- * internal state the runtime does not otherwise expose.
- *
- * A snapshot is a read of what the runtime already holds. It discloses nothing
- * that is not already observable on the page: the trusted origins are inside
- * the injected script, the field names are `data-payload-field` attributes in
- * the DOM, and the counters are derived from those. It is therefore available
- * in production rather than gated to development builds — a preview that
- * misbehaves only on the deployed site is exactly the case where the
- * information is worth having, and a development-only gate would withhold it
- * there.
- *
- * Nothing here is transmitted anywhere. Reading a snapshot performs no I/O.
- *
- * @module @core/inspection/types
+ * Shape of the `inspect()` snapshot. It only re-reads what the page already
+ * shows — origins from the injected script, field names from the DOM,
+ * counters derived from both — so it stays available in production, where a
+ * misbehaving preview is exactly the case worth diagnosing. Reading one
+ * performs no I/O and transmits nothing.
  */
 
 /** Origin trust as the runtime currently sees it. */
 interface InspectionOrigins {
-    /**
-     * Origins the runtime is willing to accept messages from, as configured.
-     * An empty list means no explicit allow-list was given, which is the
-     * condition under which referrer and localhost heuristics decide instead.
-     */
+    /** Configured origins; empty means the referrer and localhost heuristics decide instead. */
     readonly trusted: readonly string[];
-    /**
-     * The origin the runtime locked onto after its first accepted update, or
-     * `undefined` while still unlocked. Once locked, every other origin is
-     * refused for the rest of the session.
-     */
+    /** The origin locked onto by the first accepted update; every other is then refused. */
     readonly locked: string | undefined;
 }
 /** Protocol versions and the capabilities they enable. */
@@ -74,6 +29,10 @@ interface InspectionProtocol {
     readonly negotiated: number;
     /** Capability flags enabled at the negotiated version. */
     readonly capabilities: readonly string[];
+    /** The subset of `capabilities` seen on the wire rather than granted by version. */
+    readonly observed: readonly string[];
+    /** The Payload profile the observed capabilities imply: `unknown`, `payload-2` or `payload-3`. */
+    readonly profile: string;
 }
 /** Revision accounting for the update pipeline. */
 interface InspectionRevisions {
@@ -86,6 +45,19 @@ interface InspectionRevisions {
      * when the last update is among the abandoned ones.
      */
     readonly superseded: number;
+    /**
+     * Updates whose scheduled writes reached the DOM. What is neither
+     * superseded nor completed is in flight or was cancelled; a `superseded`
+     * that tracks `accepted` while `completed` stays low is the editor
+     * out-typing the pipeline.
+     */
+    readonly completed: number;
+    /**
+     * Bindings not scheduled because their value was identical to the one last
+     * applied. Cumulative since start; always `0` unless `skipUnchanged` is on.
+     * A large number beside a small `accepted` is the optimisation working.
+     */
+    readonly skippedUnchanged: number;
     /** Revision currently in flight, or `undefined` when the pipeline is idle. */
     readonly active: number | undefined;
 }
@@ -98,22 +70,14 @@ interface InspectionBindings {
     /** Those field names, sorted. */
     readonly fieldNames: readonly string[];
     /**
-     * Field names that arrived in an update but matched no binding, as far as
-     * the runtime has observed. This is the list to read when a field refuses
-     * to update: a name here is a markup problem, a name absent from here and
-     * from `fieldNames` was never sent.
+     * Bound fields some update carried no value for, so the binding kept its old
+     * text — why a binding can stay stale while its siblings update. Cumulative.
      */
+    readonly absentFields: readonly string[];
     /**
-     * Bound fields that some update since start carried no value for, so the
-     * binding kept whatever text it already had. Cumulative, like
-     * `orphanFields`, and the exact opposite of it: a binding with no value
-     * rather than a value with no binding.
-     *
-     * This is why a binding can stay stale while its siblings update. Without
-     * it the two cases are indistinguishable from the DOM, since neither
-     * leaves a trace.
+     * Field names that arrived but matched no binding — a markup problem.
+     * A name in neither this list nor `fieldNames` was never sent. Cumulative.
      */
-    readonly absentFields: readonly string[];
     readonly orphanFields: readonly string[];
     /** Whether `scopeBindingsByOwner` is active. */
     readonly ownerScoped: boolean;
@@ -124,11 +88,7 @@ interface InspectionBindings {
 interface InspectionScheduler {
     /** Writes buffered for the next flush. */
     readonly pending: number;
-    /**
-     * Writes held back because their element is offscreen and the binding count
-     * is above `visibilityGateThreshold`. These are applied when the element
-     * scrolls into view — never, on a page nobody scrolls.
-     */
+    /** Writes held back offscreen above `visibilityGateThreshold`; applied when scrolled into view. */
     readonly deferred: number;
     /** The binding count above which the visibility gate starts deferring. */
     readonly visibilityGateThreshold: number;
@@ -137,23 +97,13 @@ interface InspectionScheduler {
     /** Stats of the most recent flush, or `undefined` if none has run. */
     readonly lastFlush: {
         readonly applied: number;
-        /**
-         * Field names the flush applied, in application order.
-         *
-         * `applied` is a count, and a count cannot separate "this binding was
-         * written" from "this binding was never scheduled" — a stale binding
-         * next to a non-zero count is consistent with both. The names can.
-         */
+        /** Which fields the flush wrote; a count alone cannot say a binding was skipped. */
         readonly appliedFields: readonly string[];
         readonly deferred: number;
         readonly durationMs: number;
     } | undefined;
 }
-/**
- * A point-in-time read of runtime state, for diagnosing a preview that is not
- * behaving. Every field is a plain value; the snapshot holds no references
- * into runtime internals and does not change after it is returned.
- */
+/** A point-in-time read; plain values only, with no references into runtime internals. */
 interface LivePreviewInspection {
     /** Package version that produced this snapshot. */
     readonly version: string;
@@ -168,65 +118,67 @@ interface LivePreviewInspection {
     readonly scheduler: InspectionScheduler;
     /** Field types with a registered renderer, sorted. */
     readonly renderers: readonly string[];
+    /** Registered plugins and their live registrations; empty on a bare runtime. */
+    readonly plugins: readonly PluginInspection[];
+    /** Server-rendered fragment boundaries: whether a handler exists and what happened to renders. */
+    readonly fragments: InspectionFragments;
+    /** Route refreshes: whether a strategy exists, how many ran, failed, or were stopped by the loop guard. */
+    readonly route: InspectionRoute;
+}
+/** The route strategy as `inspect()` reports it. */
+interface InspectionRoute {
+    readonly handler: boolean;
+    readonly refreshes: number;
+    readonly failed: number;
+    /** Second refresh requests for one revision, refused with LP0805. */
+    readonly loopStopped: number;
+}
+/** The fragment strategy as `inspect()` reports it. */
+interface InspectionFragments {
+    /** Whether a fragment handler is configured; without one, boundaries are patched. */
+    readonly handler: boolean;
+    readonly inFlight: number;
+    readonly rendered: number;
+    readonly failed: number;
+    readonly superseded: number;
+}
+/** One plugin as `inspect().plugins` reports it. */
+interface PluginInspection {
+    readonly name: string;
+    readonly version: string | undefined;
+    /** `initializing` while `init` runs, `active` afterwards, `tearing-down` while `destroy` runs. */
+    readonly state: 'initializing' | 'active' | 'tearing-down';
+    /** Live registrations owned by the plugin's scope, by kind. */
+    readonly registrations: {
+        readonly transforms: number;
+        readonly renderers: number;
+        readonly subscriptions: number;
+        readonly cleanups: number;
+    };
 }
 
 /**
- * Payload Live Preview message protocol.
- *
- * Mirrors the messages emitted by Payload CMS through
- * `window.postMessage`, verified against the shipped admin code
- * (`@payloadcms/ui` → `elements/LivePreview/Window`):
- *
- *   - Payload **3.x** sends `{ type, collectionSlug, globalSlug, data,
- *     locale, externallyUpdatedRelationship }` on every form edit —
- *     `data` holds **raw form values** (relationships as bare IDs) and
- *     there is **no** `fieldSchemaJSON`.
- *   - Payload **2.x** additionally sent `fieldSchemaJSON` with the
- *     first update (client-side merge era).
- *   - `previewToken` and `protocolVersion` are extensions of THIS
- *     library for custom admin senders; stock Payload never sends
- *     them and ignores them in our `ready` handshake.
- *
- * @module @/types/payload-protocol
- */
-/**
- * A `payload-live-preview` data update.
- *
- * `data` is the serialized document state. `fieldSchemaJSON`, when
- * present (Payload 2.x or custom senders), allows the schema-driven
- * engine to resolve field types without any DOM annotations.
+ * Payload's live-preview `postMessage` protocol as the shipped admin sends it:
+ * raw form values on every edit, no schema. `previewToken` and
+ * `protocolVersion` are extensions of this library for custom senders.
  */
 interface PayloadLivePreviewMessage {
     readonly type: 'payload-live-preview';
     readonly data?: Record<string, unknown>;
+    /** Sent by Payload 2.x and custom senders only. */
     readonly fieldSchemaJSON?: readonly PayloadFieldSchema[];
     readonly globalSlug?: string;
     readonly collectionSlug?: string;
     readonly locale?: string;
     readonly ready?: boolean;
-    /**
-     * Payload 3.x: most recent relationship-document event (create/update
-     * in a drawer), or `null`. The official client ignores it too — it is
-     * modeled here for completeness and consumer event access.
-     */
+    /** Payload 3.x: the most recent relationship-document event (a drawer save), or `null`. */
     readonly externallyUpdatedRelationship?: PayloadDocumentEventDetail | null;
-    /**
-     * Optional preview JWT. ⚠️ Library extension — stock Payload never
-     * sends one. When `RuntimeOptions.validateToken` is set, the runtime
-     * requires every data update to carry a token that passes the
-     * validator; messages without a valid token are dropped.
-     */
+    /** Library extension: the token `validateToken` checks. Stock Payload never sends one. */
     readonly previewToken?: string;
-    /**
-     * Highest protocol version the sender supports. ⚠️ Library extension
-     * for custom senders — stock Payload sends no version. When absent,
-     * the receiver assumes v1.
-     */
+    /** Library extension: the highest protocol version the sender supports; absent means v1. */
     readonly protocolVersion?: number;
 }
-/**
- * Payload's `DocumentEvent` shape (admin `providers/DocumentEvents`).
- */
+/** Payload's `DocumentEvent` shape (admin `providers/DocumentEvents`). */
 interface PayloadDocumentEventDetail {
     readonly entitySlug: string;
     readonly operation?: 'create' | 'update';
@@ -234,9 +186,7 @@ interface PayloadDocumentEventDetail {
     readonly updatedAt?: string;
     readonly [extra: string]: unknown;
 }
-/**
- * Parsed, validated message payload exposed to consumers via events.
- */
+/** A validated update as events expose it. */
 interface PayloadLivePreviewData {
     readonly fields: Record<string, unknown>;
     readonly schema?: readonly PayloadFieldSchema[];
@@ -244,13 +194,7 @@ interface PayloadLivePreviewData {
     readonly collectionSlug?: string;
     readonly locale?: string;
 }
-/**
- * The subset of Payload's field-schema description we rely on.
- *
- * Payload emits the entire field configuration tree but we only need
- * the discriminator `type` and the nesting via `fields`/`blocks`.
- * Extra properties are preserved opaquely.
- */
+/** The subset of Payload's field schema the runtime reads; extra properties are kept opaquely. */
 interface PayloadFieldSchema {
     readonly name: string;
     readonly type: PayloadFieldType;
@@ -271,54 +215,19 @@ interface PayloadBlockSchema {
     readonly fields: readonly PayloadFieldSchema[];
     readonly [extra: string]: unknown;
 }
-/**
- * The Payload core field types this library recognises (20 as of
- * Payload 3.x). `tabs` is treated as a structural container; `group`
- * flattens nested fields.
- */
+/** Payload's core field types. `tabs` is a structural container; `group` flattens. */
 type PayloadFieldType = 'text' | 'textarea' | 'richText' | 'email' | 'number' | 'checkbox' | 'date' | 'select' | 'radio' | 'array' | 'blocks' | 'group' | 'tabs' | 'row' | 'collapsible' | 'relationship' | 'upload' | 'point' | 'json' | 'code' | 'ui';
-/**
- * Payload's `admin.condition` is a function in source, but it cannot
- * be transferred over postMessage. The schema arrives with this slot
- * either absent or, in future Payload versions, replaced by a
- * serialized expression. We model the slot but do not consume it yet.
- */
+/** `admin.condition` is a function in source and cannot cross `postMessage`; modelled, not consumed. */
 type PayloadFieldCondition = (data: unknown, siblingData: unknown) => boolean;
 
 /**
- * Stable identifiers for everything the runtime reports.
- *
- * Prose gets reworded; a code does not. A consumer filtering logs, an alert
- * rule, or a bug report referring to `LP0301` keeps meaning the same thing
- * after the sentence around it is rewritten, and a code is greppable in a way
- * that a sentence fragment is not.
- *
- * Codes are grouped by the question they answer:
- *
- * - `LP01xx` — configuration and origin trust: the runtime is running, but it
- *   was set up in a way that will bite.
- * - `LP02xx` — bindings and markup: an update had nowhere to land.
- * - `LP03xx` — updates and scheduling: the update landed somewhere other than
- *   the DOM, or not yet.
- * - `LP04xx` — rendering: a value reached an element and was refused.
- * - `LP05xx` — protocol and messages: something arrived that was not accepted.
- * - `LP06xx` — consumer callbacks: code the consumer supplied threw.
- * - `LP07xx` — audit findings from `pll doctor`, which reports on a served
- *   response rather than on a running runtime.
+ * Every diagnostic code the runtime and tools emit, so a consumer can branch
+ * on `e.code` instead of matching message text. A code is never reused for a
+ * different meaning; a retired one stays reserved.
  *
- * A code is part of the public contract. Codes are never reused for a
- * different meaning and never renumbered; a retired code stays retired.
- * `LP0604` is unassigned: a throwing token validator is deliberately treated
- * as a rejection and reported as `LP0502`, so there is nothing distinct to
- * report yet. The number stays reserved rather than being handed to something
- * else.
- *
- * The runtime writes these as string literals at each reporting site rather
- * than reading them from this record, so the inline build pays for the six
- * characters it prints and nothing more. This record exists so consumers can
- * refer to a code by name instead of copying a literal.
- *
- * @module @core/diagnostic-codes
+ * Browser-side reporting sites write the literal (`code: 'LP0603'`) rather than
+ * reading it from this record: the frozen table would then ship in the inline
+ * runtime for the sake of six characters. Server-side tools may import it.
  */
 /**
  * Every diagnostic code the runtime can report, by name.
@@ -334,6 +243,8 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly NoTrustedOrigin: "LP0101";
     /** Origin trust rests on `document.referrer`, so any framing site is trusted. */
     readonly ReferrerOnlyTrust: "LP0102";
+    /** A plugin declares a runtime range this runtime does not satisfy; it was refused. */
+    readonly PluginIncompatible: "LP0103";
     /** An update named a field with no binding anchor on the page. */
     readonly OrphanField: "LP0201";
     /** Owner scoping is on and the update names no document it could belong to. */
@@ -346,6 +257,14 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly TextTargetHasChildren: "LP0402";
     /** A structural container has no array template, so the update was skipped. */
     readonly MissingArrayTemplate: "LP0403";
+    /** A structural item has no `id`; it pairs positionally, so an insert re-renders every row after it. */
+    readonly StructuralItemUnkeyed: "LP0404";
+    /** Two structural items share a key; later ones pair positionally. */
+    readonly StructuralDuplicateKey: "LP0405";
+    /** Every structural key changed while the length did not; the source generates keys per message. */
+    readonly StructuralUnstableKeys: "LP0406";
+    /** A binding asks for a delivery strategy this release does not have; it is left unchanged. */
+    readonly UnsupportedStrategy: "LP0407";
     /** A message was rejected before it reached the update pipeline. */
     readonly MessageRejected: "LP0501";
     /** A preview token was rejected. */
@@ -376,251 +295,245 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly AuditNoBindings: "LP0707";
     /** The URL did not return an HTML page, so nothing else can be judged. */
     readonly AuditNotAPage: "LP0708";
+    /** A fragment request failed (network, timeout, server error); the boundary was patched instead. */
+    readonly FragmentRequestFailed: "LP0801";
+    /** The fragment response had the wrong content type or shape; the boundary was patched instead. */
+    readonly FragmentResponseInvalid: "LP0802";
+    /** The fragment endpoint refused the preview (not authorized); the boundary was patched instead. */
+    readonly FragmentUnauthorized: "LP0803";
+    /** A fragment response arrived for a revision that was already superseded and was discarded. */
+    readonly FragmentSuperseded: "LP0804";
+    /** A route refresh was requested again for the same revision; the loop guard stopped it. */
+    readonly RouteRefreshLoop: "LP0805";
+    /** A boundary asks for the fragment strategy but no fragment handler is configured; it is patched. */
+    readonly FragmentStrategyUnavailable: "LP0806";
+    /** A readiness row is not yet at its 2.0 value; `pll doctor --v2` reports it. */
+    readonly V2ReadinessGap: "LP0709";
+    /** The preview runtime is served to anonymous visitors, not only inside the admin frame. */
+    readonly RuntimeOnPublicPage: "LP0710";
 }>;
 /** A diagnostic code, as it appears in log output and on the `error` event. */
 type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[keyof typeof DIAGNOSTIC_CODES];
 
 /**
- * Public event payload shapes for the live preview lifecycle.
- *
- * The map keys form the union of valid event names. Adding a new event
- * is a two-line change: add the entry here and dispatch from the
- * relevant module. Consumers get autocompletion and exhaustive checks
- * for free because the `EventEmitter` is generic over this map.
- *
- * @module @events/types
+ * How a bound region is brought up to date: the runtime patches it, a server
+ * renders a `data-payload-fragment` boundary from the unsaved form state, or
+ * the whole route refreshes. Core carries only the seam — which boundaries a
+ * strategy owns and what it may do — so a patch-only page pays for nothing
+ * more; the orchestration lives in `payload-live-preview/fragment`.
  */
 
+/** What produced an update: the runtime's DOM patching, a server-rendered fragment, or a route refresh. */
+type UpdateSource = 'patch' | 'fragment' | 'route';
+/** One revision, as a strategy sees it, with the runtime capabilities it may use. */
+interface FragmentContext {
+    readonly root: ParentNode;
+    readonly revision: number;
+    readonly receivedAt: number;
+    readonly fields: Readonly<Record<string, unknown>>;
+    readonly locale: string | undefined;
+    readonly collectionSlug: string | undefined;
+    readonly globalSlug: string | undefined;
+    /** Aborted when a newer revision arrives or the runtime stops. */
+    readonly signal: AbortSignal;
+    /** Whether this revision is still the current one. */
+    readonly isCurrent: () => boolean;
+    /** Morph server-rendered HTML into a boundary (Trusted Types and the keyed morph apply). */
+    readonly morph: (boundary: Element, html: string) => void;
+    /** Patch the boundary's own bindings from this revision — the deterministic fallback. */
+    readonly patch: (boundary: Element) => void;
+    /** Debug log through the runtime's logger, with the diagnostic code. */
+    readonly log: (code: DiagnosticCode, detail: string) => void;
+    /** Report a boundary rendered. */
+    readonly rendered: (boundary: Element, id: string, key: string | undefined) => void;
+    /** Report a boundary failed and patched instead; emits the `error` and `fragmentRender` events. */
+    readonly failed: (boundary: Element, id: string, key: string | undefined, code: DiagnosticCode, reason: string) => void;
+}
+interface FragmentReport {
+    readonly rendered: number;
+    readonly failed: number;
+    readonly superseded: number;
+}
+/** A fragment strategy: which boundaries it owns for a revision, and how it renders them. */
+interface FragmentStrategy {
+    /** The boundaries this update re-renders; their inner bindings are left to the strategy. */
+    readonly plan: (root: ParentNode, changedFields: ReadonlySet<string>) => readonly Element[];
+    /** Render the planned boundaries; resolves once every one settled. */
+    readonly render: (context: FragmentContext, boundaries: readonly Element[]) => Promise<FragmentReport>;
+}
+/** One revision, as the route strategy sees it. */
+interface RouteContext {
+    readonly revision: number;
+    readonly receivedAt: number;
+    /** Aborted when a newer revision arrives or the runtime stops. */
+    readonly signal: AbortSignal;
+    readonly isCurrent: () => boolean;
+    readonly log: (code: DiagnosticCode, detail: string) => void;
+}
+/**
+ * Whether a revision needs the whole route re-rendered, and how. After a
+ * refresh the runtime rescans and re-applies the revision, so the unsaved
+ * state lands on the fresh markup.
+ */
+interface RouteStrategy {
+    readonly plan: (root: ParentNode, changedFields: ReadonlySet<string>) => boolean;
+    readonly refresh: (context: RouteContext) => Promise<'refreshed' | 'failed' | 'superseded'>;
+}
+interface StrategyHandlers {
+    readonly fragment?: FragmentStrategy;
+    readonly route?: RouteStrategy;
+}
+
+/** Public event payloads. The map keys are the valid event names; `EventEmitter` is generic over it. */
+
 interface LivePreviewEventMap {
-    /**
-     * Fired once per startup attempt after observers, cache, and message listening
-     * are active. A later startup failure may roll that attempt back; retrying then
-     * emits a new `init` event.
-     */
+    /** Once per startup attempt, after observers, cache and message listening are active. A rolled-back attempt emits it again on retry. */
     readonly init: {
         readonly timestamp: number;
     };
-    /** Fired for the first accepted data-bearing update from a trusted origin. */
+    /** The first accepted data-bearing update from a trusted origin. */
     readonly connect: {
         readonly origin: string;
         readonly timestamp: number;
     };
-    /**
-     * Fired when the heartbeat times out or the runtime is destroyed. The
-     * `'unload'` reason remains in the public union for 1.x producer compatibility;
-     * the built-in runtime does not currently emit it.
-     */
+    /** The heartbeat timed out, the runtime was destroyed, or the page was suspended for navigation (`'unload'`). */
     readonly disconnect: {
         readonly reason: 'timeout' | 'destroy' | 'unload';
         readonly timestamp: number;
     };
-    /**
-     * Fired before the DOM is mutated for an incoming update.
-     *
-     * Handlers may call `cancel()` before their synchronous or asynchronous
-     * work settles to skip exactly this revision.
-     */
+    /** Before the DOM is mutated for an update; `cancel()` skips exactly this revision. */
     readonly beforeUpdate: {
         readonly data: PayloadLivePreviewData;
-        /** Runtime-populated ordering metadata; optional for 1.x producer compatibility. */
         readonly revision?: number;
+        /** When the runtime accepted the message, Unix milliseconds. */
+        readonly receivedAt?: number;
+        /** The strategy that produced the update. */
+        readonly source?: UpdateSource;
         readonly cancel: () => void;
     };
-    /**
-     * Fired after each actual, current DOM application batch. Visibility replay
-     * may produce another event for the same revision; cancelled, obsolete, and
-     * deferred-only batches produce none.
-     */
+    /** After each applied, still-current batch. Visibility replay may emit another for the same revision; cancelled, obsolete and deferred-only batches emit none. */
     readonly afterUpdate: {
         readonly data: PayloadLivePreviewData;
         readonly updatedCount: number;
         readonly durationMs: number;
-        /** Runtime-populated ordering metadata; optional for 1.x producer compatibility. */
         readonly revision?: number;
+        readonly receivedAt?: number;
+        readonly source?: UpdateSource;
     };
-    /** Fired for each successful, still-current element write. */
+    /** Each successful, still-current element write. */
     readonly elementUpdate: {
         readonly element: Element;
         readonly fieldName: string;
         readonly previousValue: unknown;
         readonly nextValue: unknown;
-        /** Runtime-populated ordering metadata; optional for 1.x producer compatibility. */
         readonly revision?: number;
+        readonly receivedAt?: number;
+        readonly source?: UpdateSource;
     };
-    /** Fired whenever the element cache is rebuilt (initial scan or MutationObserver-triggered). */
+    /** The element cache was rebuilt (initial scan or mutation). */
     readonly cacheRefresh: {
         readonly elementCount: number;
         readonly fieldCount: number;
         readonly durationMs: number;
     };
-    /** Fired when a `payload-document-event` message arrives (document save). */
+    /** Once per fragment boundary and revision: rendered by the server, or failed (with the LP08xx code) and patched instead. */
+    readonly fragmentRender: {
+        readonly element: Element;
+        readonly id: string;
+        readonly key: string | undefined;
+        readonly status: 'rendered' | 'failed';
+        readonly code?: DiagnosticCode;
+        readonly revision: number;
+        readonly receivedAt: number;
+    };
+    /** A `payload-document-event` message arrived (document save). */
     readonly documentSave: {
         readonly timestamp: number;
     };
-    /**
-     * Fired on errors that the runtime caught but cannot fully recover from.
-     *
-     * The `context` string identifies where the error originated. `code` says
-     * the same thing in a form that survives rewording — branch on `code`, read
-     * `context` when you want the human-readable origin.
-     */
+    /** A data update carried `externallyUpdatedRelationship`: a related document changed in an admin drawer, so the update re-renders unconditionally. */
+    readonly relationshipUpdate: {
+        readonly detail: PayloadDocumentEventDetail;
+        readonly timestamp: number;
+    };
+    /** An error the runtime caught but cannot fully recover from. Branch on `code`; `context` is the human-readable origin. */
     readonly error: {
         readonly error: Error;
         readonly context: string;
         readonly code: DiagnosticCode;
     };
-    /**
-     * Fired during destroy after browser observers and the message listener are
-     * removed. Event/plugin listeners remain available for this notification and
-     * are released by the owning client afterwards.
-     */
+    /** During destroy, after observers and the message listener are removed; listeners are released by the owning client afterwards. */
     readonly destroy: {
         readonly timestamp: number;
     };
 }
-/**
- * Handler signature: receives the payload and may return a Promise.
- *
- * Promise-returning handlers are awaited in registration order — this
- * is important for `beforeUpdate.cancel()` semantics.
- */
+/** Handlers may return a promise; they are awaited in registration order, which `beforeUpdate.cancel()` relies on. */
 type EventHandler<TPayload> = (payload: TPayload) => void | Promise<void>;
-/** Subscription removal function returned by `on()`/`once()`. */
 type Unsubscribe = () => void;
 
 /**
- * Per-instance, type-safe event emitter.
- *
- * Replaces the legacy module-level singleton. Each `LivePreviewClient`
- * instantiates its own emitter so that calling `destroy()` on one
- * instance cannot clobber listeners attached to another.
- *
- * Design notes:
- *
- *   - Generic over an event map type. The default `LivePreviewEventMap`
- *     captures every event this library emits, but the implementation
- *     is reusable for any map.
- *   - Handlers may be `async`. They are awaited sequentially in
- *     registration order. This is intentional: `beforeUpdate.cancel()`
- *     and similar synchronization rely on stable ordering.
- *   - Errors thrown by one handler are logged via `console.error` and
- *     do not prevent later handlers from running.
- *   - `once()` semantics: registered into a separate map; the entire
- *     snapshot for an event is claimed immediately before its dispatch,
- *     and remains consumed even if individual handlers throw.
- *
- * @module @events/emitter
+ * Per-instance typed emitter: handlers run sequentially in registration order,
+ * may be async, and a throwing one is logged and isolated. See ADR 0002.
  */
 
 declare class EventEmitter<TMap extends object = LivePreviewEventMap> {
     #private;
-    /**
-     * Subscribe `handler` to `event`. Returns an unsubscribe function;
-     * call it to remove the handler. The handler is invoked for every
-     * subsequent emit until unsubscribed.
-     */
     on<E extends keyof TMap>(event: E, handler: EventHandler<TMap[E]>): Unsubscribe;
-    /**
-     * Subscribe `handler` for a single emit. After the first dispatch,
-     * the handler is removed automatically.
-     */
     once<E extends keyof TMap>(event: E, handler: EventHandler<TMap[E]>): Unsubscribe;
-    /**
-     * Remove `handler` from `event`. Works for both `on`- and
-     * `once`-registered handlers. No-op when the handler isn't registered.
-     */
     off<E extends keyof TMap>(event: E, handler: EventHandler<TMap[E]>): void;
-    /**
-     * Dispatch `payload` to every handler registered for `event`.
-     *
-     * Handlers run sequentially in registration order — regular ones
-     * first, then `once` handlers. Async handlers are awaited. Synchronous
-     * exceptions are caught, logged, and isolated to the offending handler.
-     */
+    /** Dispatch to every handler: regular ones first, then `once` handlers. */
     emit<E extends keyof TMap>(event: E, payload: TMap[E]): Promise<void>;
     /**
-     * Lifecycle-only guarded dispatch. The predicate is checked before and after
-     * every handler so an async boundary cannot let an obsolete transaction run
-     * later callbacks. `emit()` intentionally keeps its established behaviour.
-     *
-     * Once-handlers are claimed only when dispatch reaches the once phase. Once
-     * claimed, the whole snapshot remains consumed even if the predicate changes
-     * while one of its handlers is awaiting, matching normal once semantics.
-     *
+     * Dispatch while `shouldContinue()` holds — checked around every handler, so
+     * an obsolete transaction cannot resume across an await.
      * @internal
-     * @returns `true` when the complete handler sequence ran while eligible.
      */
     emitWhile<E extends keyof TMap>(event: E, payload: TMap[E], shouldContinue: () => boolean): Promise<boolean>;
-    /**
-     * Number of handlers currently registered for `event`.
-     * Sum of `on` and `once` registrations.
-     */
+    /** Registered handlers for `event`, `on` and `once` together. */
     listenerCount(event: keyof TMap): number;
-    /**
-     * Remove every handler. Pass an event name to limit the removal to
-     * one event; omit it to clear every event on this emitter.
-     *
-     * Crucially this only affects the current instance — there is no
-     * shared global state.
-     */
+    /** Remove every handler, or only those of `event`. */
     removeAllListeners(event?: keyof TMap): void;
-    /**
-     * Snapshot of all event names that currently have at least one
-     * registered handler. Useful for debugging.
-     */
+    /** Event names with at least one handler. */
     eventNames(): (keyof TMap)[];
 }
 
-/**
- * Core type definitions shared across all runtime primitives.
- *
- * @module @core/types
- */
+/** Types shared by the runtime primitives. */
 
-/**
- * Field types recognized by the live preview renderer.
- *
- * Extends Payload's field set with `html` and `url` which are not
- * Payload field types per se but useful DOM-binding categories.
- */
+/** Payload's field set plus the DOM-binding categories `html`, `url`, `image` and `structural-array`. */
 type FieldType = PayloadFieldType | 'html' | 'url' | 'image' | 'structural-array';
+/** A namespaced project renderer key, so a typo of a built-in type can never become one. */
+type CustomRendererKey = `${string}:${string}`;
+/** What a renderer may be registered under and an element may ask for. */
+type RendererKey = FieldType | CustomRendererKey;
 /**
- * A DOM element that has been registered as a live preview binding.
- *
- * Stored in the element cache indexed by `fieldName`. Multiple cached
- * entries can share a field name when the same field is rendered in
- * several places (e.g., a title shown in both the header and the
- * page body).
+ * A project rich-text renderer, shared by SSR and preview. Its output goes
+ * through the sanitizer; call the same `sanitizeHtml()` server-side for byte equality.
  */
+type RichTextRenderer = (value: unknown, context: {
+    readonly fieldName: string;
+    readonly element: Element;
+    readonly locale: string | undefined;
+}) => string;
+/** One registered binding. Several may share a field name when it renders in several places. */
 interface CachedElement {
     /** The bound DOM element. */
     readonly element: Element;
     /** Payload field path, e.g., `title` or `hero.subtitle`. */
     readonly fieldName: string;
-    /**
-     * Resolved field type, used to dispatch to the right renderer.
-     *
-     * The cache resolves this from DOM attributes (`data-payload-type`,
-     * tag-based heuristics) at build time. When `explicitFieldType` is
-     * `false` the lifecycle is allowed to override this with the type
-     * learned from the schema once `fieldSchemaJSON` arrives.
-     */
-    readonly fieldType: FieldType;
-    /**
-     * `true` when the field type was set by an explicit
-     * `data-payload-type` attribute (consumer trumps schema), `false`
-     * when it was inferred via tag-based heuristics (schema may
-     * override later). Optional so synthetic bindings (tests / programmatic
-     * `cache.add()` callers) need not supply it; the cache always
-     * populates it for DOM-derived bindings.
-     */
+    /** Resolved from attributes and tag heuristics; the schema may override it unless explicit. */
+    readonly fieldType: RendererKey;
+    /** Whether `data-payload-type` set the type, in which case the schema must not override it. */
     readonly explicitFieldType?: boolean;
-    /**
-     * Optional target attribute: the value is written to this attribute
-     * instead of the element's content (from `data-payload-attribute`,
-     * or `bind(field, { attribute })`). Writes are policed — event
-     * handlers, `style`, and unsafe URLs are refused.
-     */
+    /** Fields this binding depends on (`data-payload-depends`); a change in any re-applies it under `skipUnchanged`. */
+    readonly dependsOn?: readonly string[];
+    /** Raw `data-payload-strategy` value. */
+    readonly strategy?: string;
+    /** How the runtime brings this binding up to date; `'unknown'` for an unrecognised strategy. Resolved by the cache. */
+    readonly strategyKind?: UpdateSource | 'unknown';
+    /** Nearest enclosing `data-payload-fragment` boundary. Resolved by the cache. */
+    readonly fragmentBoundary?: Element;
+    /** `data-payload-boundary`: an anchor that hides itself while its field is empty. */
+    readonly boundary?: boolean;
+    /** Write the value into this attribute instead of the content; policed writes. */
     readonly targetAttribute?: string;
     /** Optional sibling-field path bound to the element's `href` attribute. */
     readonly hrefField?: string;
@@ -634,21 +547,10 @@ interface CachedElement {
     readonly arraySeparator?: string;
     /** Optional locale code locked onto this element (overrides the global locale). */
     readonly locale?: string;
-    /**
-     * Optional document this binding belongs to, resolved from the nearest
-     * `data-payload-owner` ancestor (the element itself included).
-     *
-     * Only consulted while owner scoping is enabled. Without it a field name is
-     * the sole identity, so every document rendered on the page competes for the
-     * same name.
-     */
+    /** The document this binding belongs to, from the nearest `data-payload-owner`. */
     readonly owner?: string;
 }
-/**
- * Context passed to every field renderer. Provides access to the
- * entire field tree so renderers can resolve sibling fields (e.g.,
- * an `<a>` that pulls `href` from a different field).
- */
+/** What a renderer is given; `allFields` lets it resolve a sibling field. */
 interface RenderContext {
     /** Full field map for the current update — used for sibling lookups. */
     readonly allFields: Record<string, unknown>;
@@ -656,315 +558,221 @@ interface RenderContext {
     readonly locale: string | undefined;
     /** Optional schema descriptor for the field, when available. */
     readonly schema: PayloadFieldSchema | undefined;
+    /** The project's rich-text renderer, when the client was configured with one. */
+    readonly renderRichText?: RichTextRenderer;
 }
 /**
- * Contract that every field renderer implements.
- *
- * Renderers are pure DOM-write functions: they receive the cached
- * binding plus the new value and apply it to the element. They must
- * not throw — failures should be silenced and logged so that one bad
- * field cannot stop an entire update. The public renderer result remains
- * `void` for 1.x compatibility. Built-in renderers may use an internal exact
- * `false` sentinel when they deliberately perform no DOM write; callers must
- * not rely on that implementation detail.
+ * A renderer writes one value into its element. It must not throw: one bad
+ * field may not stop an update. The result stays `void` — the internal
+ * no-write sentinel is not part of the contract.
  */
 interface FieldRenderer {
-    readonly name: FieldType;
+    readonly name: RendererKey;
     render(target: CachedElement, value: unknown, context: RenderContext): void;
 }
 
 /**
- * Plugin system types.
- *
- * Each plugin participates in the live-preview lifecycle through a
- * scoped, per-instance context. Plugins can register custom field
- * renderers, transform incoming values, and subscribe to events —
- * the same primitives the built-in renderers use.
- *
- * The system is intentionally minimal. Anything that can be expressed
- * with an event subscription belongs in `events`, not `plugins`.
- *
- * @module @plugins/types
+ * Plugin compatibility claims. The range grammar is the subset a plugin
+ * author writes (`*`, `1.2.3`, `^`, `~`, `>=`, `>`, `<`, `<=`, space-joined
+ * conjunctions, `||` alternatives); prerelease tags are ignored.
  */
+interface PluginCompatibility {
+    /** A semver range the runtime's `VERSION` must satisfy, e.g. `>=2.0.0`. */
+    readonly runtime?: string;
+    /** The highest postMessage protocol version the plugin understands. */
+    readonly protocol?: number;
+}
+
+/** Plugin contract: a scoped, per-instance context for renderers, transforms and events. */
 
 /** Idempotent handle that releases one plugin-owned resource. */
 type PluginDisposer = () => void;
-/**
- * Event subscriptions scoped to one plugin registration.
- *
- * This remains nominally compatible with the pre-1.0.4 `EventEmitter` context
- * type. Its methods are registration-scoped: even bulk removal affects only
- * this plugin's subscriptions, never a consumer's or another plugin's
- * listeners.
- */
-interface PluginEvents extends EventEmitter {
+/** The client's event surface scoped to one registration: bulk removal and introspection see only this plugin's listeners. */
+interface PluginEvents {
     readonly on: <E extends keyof LivePreviewEventMap>(event: E, handler: EventHandler<LivePreviewEventMap[E]>) => Unsubscribe;
     readonly once: <E extends keyof LivePreviewEventMap>(event: E, handler: EventHandler<LivePreviewEventMap[E]>) => Unsubscribe;
     readonly off: <E extends keyof LivePreviewEventMap>(event: E, handler: EventHandler<LivePreviewEventMap[E]>) => void;
     /** Emit through the owning client's event channel. */
     readonly emit: <E extends keyof LivePreviewEventMap>(event: E, payload: LivePreviewEventMap[E]) => Promise<void>;
-    /**
-     * Guarded emit through the owning client channel. Dispatch stops when the
-     * caller predicate becomes false or this plugin registration is removed.
-     */
+    /** Guarded emit; dispatch stops when the predicate turns false or this registration is removed. */
     readonly emitWhile: <E extends keyof LivePreviewEventMap>(event: E, payload: LivePreviewEventMap[E], shouldContinue: () => boolean) => Promise<boolean>;
-    /** Number of listeners owned by this plugin registration. */
     readonly listenerCount: (event: keyof LivePreviewEventMap) => number;
-    /** Remove only listeners owned by this plugin registration. */
     readonly removeAllListeners: (event?: keyof LivePreviewEventMap) => void;
-    /** Event names for which this plugin registration owns listeners. */
     readonly eventNames: () => (keyof LivePreviewEventMap)[];
 }
 /**
- * Synchronous function that transforms a merged field value while a revision's
- * per-binding scheduler entry is prepared. Transforms run in registration
- * order and each receives the preceding transform's result. The final value is
- * frozen into that entry before later renderer or attribute dispatch;
- * `allFields` remains the merged, untransformed update snapshot.
- *
- * Returning a different shape than the input is allowed, but returning a
- * Promise or other thenable is a contract error. If a transform throws or
- * returns a thenable, the chain stops, the runtime emits an `error` event, and
- * dispatch falls back to the original merged value. That fallback still passes
- * through the normal renderer and attribute security controls.
+ * Synchronous value transform run in registration order; returning a thenable
+ * is a contract error (`LP0602`) that dispatches the untransformed value.
  */
 type FieldTransform = (value: unknown, context: {
     readonly fieldName: string;
     readonly element: Element;
     readonly allFields: Record<string, unknown>;
 }) => unknown;
-/**
- * Per-instance plugin context. Replaces the legacy singleton context.
- *
- * Plugins receive a context that is bound to the parent
- * `LivePreviewClient`. They can:
- *
- *   - subscribe via `events.on/once`,
- *   - register field renderers,
- *   - register value transforms,
- *   - read the client's (frozen) configuration,
- *   - log through the client's debug channel.
- */
 interface PluginContext {
     readonly events: PluginEvents;
-    /** Register a renderer owned by this plugin registration. */
+    /** Register a renderer layer owned by this registration. */
     readonly registerFieldRenderer: (renderer: FieldRenderer) => void;
-    /** Register an ordered transform owned by this plugin registration. */
+    /** Register an ordered transform owned by this registration. */
     readonly registerTransform: (fieldName: string, transform: FieldTransform) => void;
-    /**
-     * Register any additional synchronous cleanup owned by this registration.
-     * The manager invokes it during rollback, `unuse()`, or client destruction.
-     * Optional so pre-1.0.4 structural context mocks remain assignable.
-     */
+    /** Register a synchronous cleanup run on rollback, `unuse()` and client destruction. */
     readonly registerCleanup?: (cleanup: PluginDisposer) => void;
     readonly getConfig: () => Readonly<Record<string, unknown>>;
     readonly log: (...args: unknown[]) => void;
 }
-/**
- * Plugin definition. `init` runs once per registration; `destroy`
- * runs when the plugin is unregistered or the client is destroyed.
- *
- * Both hooks may return a promise; the manager awaits them.
- */
+/** `init` runs once per registration, `destroy` on removal; both may return a promise. */
 interface LivePreviewPlugin {
     readonly name: string;
     readonly version?: string;
+    /** Checked at registration; a plugin this runtime does not fit is refused (`LP0103`). */
+    readonly compat?: PluginCompatibility;
     readonly init: (context: PluginContext) => void | Promise<void>;
     readonly destroy?: () => void | Promise<void>;
 }
 
 /**
- * `LivePreviewClient` configuration shape.
- *
- * @module @client/config
+ * The two defaults profiles, row by row. 2.0 ships `v2`; `defaults: 'v1'` opts
+ * back into the 1.x table for a staged migration. Each row belongs to exactly
+ * one side — the adapter's request decision or the browser runtime — and a
+ * test asserts the profile assigns every readiness row that has an option, so
+ * a row added later cannot be forgotten. See ADR 0007.
+ */
+/** `'v2'` is the 2.0 default; `'v1'` is the 1.x table. */
+type DefaultsProfile = 'v1' | 'v2';
+/** How the runtime decides which windows may post updates. */
+type EventSourcePolicy = 'any' | 'parent-or-opener';
+
+/**
+ * `LivePreviewClient` configuration. Defaults are the 2.0 rows; `defaults: 'v1'`
+ * restores the 1.x values named per option (ADR 0007).
  */
+
 interface LivePreviewClientConfig {
-    /** Explicit additional trusted origins. */
+    /** Explicit trusted admin origins. */
     readonly allowedOrigins?: readonly string[];
-    /**
-     * Payload server origin, e.g. `https://cms.example.com`. When set,
-     * every incoming update is re-fetched through the Payload REST API
-     * so relationship/upload fields render populated instead of as bare
-     * IDs (same strategy as the official client). Recommended for
-     * Payload 3.x.
-     */
+    /** Payload origin; every update is then re-fetched through the REST API so relations arrive populated. Requires `mergeDepth`. */
     readonly serverURL?: string;
-    /** REST API route prefix used with `serverURL`. Defaults to `/api`. */
+    /** REST route prefix used with `serverURL`. Default `/api`. */
     readonly apiRoute?: string;
-    /** Population depth used with `serverURL`. Defaults to `1`. */
+    /** Population depth used with `serverURL`. Required with it; `defaults: 'v1'` falls back to `1`. */
     readonly mergeDepth?: number;
-    /**
-     * Custom fetch implementation for the `serverURL` merge request —
-     * the equivalent of the official client's `requestHandler`. Use it
-     * to attach auth headers or route through your own proxy. Only
-     * available on the programmatic client (functions cannot be
-     * serialised into the inline script).
-     */
+    /** Custom fetch for the `serverURL` merge request: attach auth headers or route through a proxy. */
     readonly mergeFetch?: typeof fetch;
-    /** Enable verbose console debug output. Defaults to dev-mode detection. */
+    /** Verbose console output. Defaults to dev-mode detection. */
     readonly debug?: boolean;
-    /** Debounce window for incoming updates. Defaults to 50 ms. */
+    /** Debounce window for incoming updates. Default 50 ms. */
     readonly debounceMs?: number;
-    /**
-     * Heartbeat timeout in ms. Defaults to `0` (disabled) because the
-     * Payload admin sends messages only on form edits — there is no
-     * protocol keepalive, so an idle timeout would produce false
-     * disconnects.
-     */
+    /** Heartbeat timeout in ms; `0` disables it (default), because the admin posts only on edits. */
     readonly heartbeatMs?: number;
-    /** IntersectionObserver rootMargin. Defaults to `200px`. */
+    /** IntersectionObserver `rootMargin`. Default `200px`. */
     readonly intersectionRootMargin?: string;
-    /**
-     * Restrict each update to the bindings owned by the document it describes.
-     *
-     * Ownership is declared in markup with `data-payload-owner`, resolved from
-     * the nearest ancestor: `global:<slug>`, `collection:<slug>`, or
-     * `collection:<slug>:<id>`. Payload already sends the edited document's
-     * identity, so nothing else needs configuring.
-     *
-     * Defaults to `false`, which keeps the 1.x behaviour of matching on the
-     * field name alone. Enable it when one page previews more than one document
-     * and a field name is therefore no longer a unique identity. While enabled,
-     * a binding without an owner is never updated.
-     */
+    /** Update only bindings under a matching `data-payload-owner`; an unowned binding is then never updated. Default `false`. */
     readonly scopeBindingsByOwner?: boolean;
-    /** Bypass the visibility gate (apply every update). Defaults to `false`. */
+    /** Skip a binding whose value did not change. Default `true`; `defaults: 'v1'` sets `false`. */
+    readonly skipUnchanged?: boolean;
+    /** Scroll the preview to the field being edited when its value changes. Default `false`. */
+    readonly revealEditedField?: boolean;
+    /** Fields whose change re-applies other bindings regardless of their own value: `{ price: ['priceLabel'] }`. Used with `skipUnchanged`. */
+    readonly dependencies?: Readonly<Record<string, readonly string[]>>;
+    /** Strategy handlers beyond patching; `createFragmentStrategy()` from `payload-live-preview/fragment` builds one. */
+    readonly strategies?: StrategyHandlers;
+    /** Apply every update regardless of visibility. Default `false`. */
     readonly disableVisibilityGate?: boolean;
-    /** Cache-size threshold above which off-screen updates are queued for replay. Defaults to 50. */
+    /** Cache size above which off-screen updates wait for intersection. Default `50`. */
     readonly visibilityGateThreshold?: number;
-    /**
-     * Mount an `aria-live` region for connections, applied updates, and mounted
-     * heartbeat-timeout disconnects. Destroy releases it synchronously. Default `true`.
-     */
+    /** Mount an `aria-live` region for connections, applied updates and heartbeat disconnects. Default `true`. */
     readonly enableA11y?: boolean;
-    /** Locale used to pick A11y announcement strings. Defaults to detected locale. */
+    /** Locale of the announcement strings. Defaults to the detected locale. */
     readonly a11yLocale?: string;
-    /** Document root, defaults to `document`. */
+    /** Document root. Default `document`. */
     readonly root?: Document | Element;
-    /** Disable `document.referrer` detection. */
+    /** Renderer resolution ahead of the registry; return `undefined` to fall through. */
+    readonly resolveRenderer?: (fieldType: RendererKey, target: CachedElement) => FieldRenderer | undefined;
+    /** The project's rich-text renderer, shared with SSR. Its output is sanitized. */
+    readonly renderRichText?: RichTextRenderer;
+    /** Ignore `document.referrer` as an origin source. Default `true`; `defaults: 'v1'` sets `false`. */
     readonly disableReferrerDetection?: boolean;
-    /** Disable the localhost dev-mode pattern matcher. */
+    /** Disable the dev-mode localhost matcher. Default `false`. */
     readonly disableLocalhostMatching?: boolean;
-    /** Auto-start the runtime in the constructor. Defaults to `true`. */
+    /** Which windows may post updates. Default `'parent-or-opener'`; `defaults: 'v1'` sets `'any'`. */
+    readonly eventSourcePolicy?: EventSourcePolicy;
+    /** Sanitizer policy for rich text and HTML writes. Default `'strict'`; `defaults: 'v1'` sets `'compat'`. */
+    readonly sanitizerPolicy?: 'compat' | 'strict';
+    /** `'v2'` (default) is the 2.0 table; `'v1'` restores every 1.x row at once. Explicit options win. */
+    readonly defaults?: DefaultsProfile;
+    /** Start the runtime in the constructor. Default `true`. */
     readonly autoStart?: boolean;
-    /**
-     * Optional preview-token validator. When set, every data update
-     * must carry a `previewToken` field that this function approves.
-     *
-     * ⚠️ `previewToken` is an extension of THIS library, not part of the
-     * stock Payload postMessage protocol — the Payload admin never sends
-     * one. Only enable this when a custom admin component adds the token
-     * to outgoing messages; against an unmodified Payload admin it would
-     * drop every update.
-     */
+    /** Preview-token validator; every update must then carry a `previewToken` it approves. Stock Payload sends none. */
     readonly validateToken?: (token: string | undefined, origin: string) => boolean | Promise<boolean>;
 }
 
 /**
- * Public, high-level `LivePreviewClient`.
- *
- * The client wraps a `LivePreviewRuntime` with:
- *
- *   - Per-instance event emitter (no singleton).
- *   - Per-instance plugin manager.
- *   - Custom-renderer registration.
- *   - Field-name transforms frozen into revision-bound scheduler entries before
- *     their later attribute or renderer dispatch.
- *
- * Consumers who want full programmatic control instantiate
- * `LivePreviewClient` directly. Consumers who just want a working
- * inline preview should use `generateInlineScript()` instead.
- *
- * @module @client
+ * `LivePreviewClient`: a `LivePreviewRuntime` with its own emitter, plugin
+ * manager and renderer registry. A page that only needs a working preview uses
+ * `generateInlineScript()` instead.
  */
 
 declare class LivePreviewClient {
     #private;
-    constructor(config?: LivePreviewClientConfig);
+    constructor(rawConfig?: LivePreviewClientConfig);
     /**
-     * Start the runtime. Returns `true` when this client is eligible and runtime
-     * startup is active or scheduled for DOM readiness. Repeated calls on an
-     * active client also return `true`; `false` means the client was destroyed or
-     * the page is outside a preview context. A deferred startup can still fail,
-     * roll back, and be retried by a later call.
+     * Start the runtime: `true` while eligible and started or scheduled for DOM
+     * readiness, `false` once destroyed or outside a preview context.
      */
     start(): boolean;
     /**
-     * Release the message ingress while keeping this client usable.
-     *
-     * For the document lifecycle, not for teardown: a back/forward-cache restore
-     * does not re-run module scripts, so a client that stays attached across
-     * `pagehide` returns bound to a frozen page and silently stops updating.
-     * Plugins, renderers and transforms survive; `resume()` brings the same
-     * client back. Returns `false` when there was nothing running to suspend.
+     * Release the message ingress, keeping plugins and renderers, for `pagehide`:
+     * a bfcache restore re-runs no script, so an attached client would return
+     * bound to a frozen page. `false` when nothing was running.
      */
     suspend(): boolean;
-    /**
-     * Reacquire after `suspend()`.
-     *
-     * Deliberately the same path as `start()`: a restored document needs the
-     * cache rebuilt, the observers rebound and the handshake rebroadcast, which
-     * is exactly what starting does. Returns `false` for a destroyed client or
-     * one that was never started.
-     */
+    /** Reacquire after `suspend()`: the same path as `start()`, because a restored document needs the same rebuild. */
     resume(): boolean;
-    /**
-     * Stop the runtime and tear down every plugin. Idempotent.
-     */
+    /** Stop the runtime and tear down every plugin. Idempotent; concurrent callers share one promise. */
     destroy(): Promise<void>;
-    /**
-     * Register a plugin.
-     */
     use(plugin: LivePreviewPlugin): Promise<void>;
-    /** Unregister a plugin and release all resources owned by that registration. */
+    /** Unregister a plugin and release everything its registration owned. Still allowed from a destroy hook during teardown. */
     unuse(name: string): Promise<void>;
-    /** Rebuild the element cache manually. */
     refreshCache(): void;
-    /** Read-only access to the event emitter for `on`/`once`/`off`. */
     get events(): EventEmitter;
-    /** Names of currently registered plugins. */
+    /** Names of the registered plugins. */
     get plugins(): readonly string[];
-    /** Current connection status. */
     get status(): 'disconnected' | 'connecting' | 'connected';
-    /** Number of valid updates received so far. */
     /**
-     * Point-in-time read of runtime state, for diagnosing a preview that is not
-     * updating. Performs no I/O and transmits nothing.
-     *
-     * Read `bindings.orphanFields` when a field refuses to update, and
-     * `scheduler.deferred` together with `scheduler.visibilityGateActive` when
-     * updates stop below the fold.
+     * Point-in-time read of runtime state, no I/O: `bindings.orphanFields` when a
+     * field refuses to update, `scheduler.deferred` when updates stop below the fold.
      */
     inspect(): LivePreviewInspection;
+    /** Number of accepted updates so far. */
     get updateCount(): number;
     /** `true` once `destroy()` has been called. */
     get destroyed(): boolean;
 }
+/** A started client, or `null` when the page is not a preview context. */
+declare function initLivePreview(config?: LivePreviewClientConfig): LivePreviewClient | null;
+
 /**
- * Convenience factory: instantiate the client, returning `null` when
- * the page is not currently a preview context (top-level navigation).
- * Useful for SSR-style integrations that import this from any context.
+ * Admin-side reporter for "reveal the edited section": it names the field the
+ * editor's cursor is in so the preview scrolls there without a keystroke.
  */
-declare function initLivePreview(config?: LivePreviewClientConfig): LivePreviewClient | null;
+/** The preview window (usually `iframe.contentWindow`) messages are posted to. */
+interface FocusReportTarget {
+    postMessage: (message: unknown, targetOrigin: string) => void;
+}
+interface PreviewFocusMessage {
+    readonly type: 'payload-live-preview-focus';
+    readonly field: string;
+}
+/** Post one focus report. `targetOrigin` must be the preview's exact origin, never `'*'`. */
+declare function reportPreviewFocus(target: FocusReportTarget, field: string, targetOrigin: string): void;
+/** A reporter bound to a preview window and origin; `resolveTarget` runs per report, so a re-created iframe is addressed freshly. */
+declare function createPreviewFocusReporter(resolveTarget: () => FocusReportTarget | null | undefined, targetOrigin: string): (field: string) => void;
 
 /**
- * Document-lifecycle owner for the live-preview client.
- *
- * The runtime learns about messages, not about navigation. Two browser
- * behaviours make that gap visible, and both are silent:
- *
- *   - A **back/forward-cache restore** does not re-run module scripts. A client
- *     that stays attached across `pagehide` comes back bound to a document the
- *     browser froze and thawed, and simply stops updating.
- *   - A **soft navigation** replaces page content without a new document. The
- *     bindings the cache holds are gone, and nothing tells the runtime.
- *
- * This binds both to `suspend()`/`resume()`/`refreshCache()` in one place, so a
- * consumer that uses no framework adapter can own the lifecycle with one call
- * instead of re-deriving it — which is what every integration has had to do so
- * far.
- *
- * @module @core/navigation-lifecycle
+ * Binds the document lifecycle the runtime cannot see: a back/forward-cache
+ * restore re-runs no scripts, so a client that stayed attached comes back
+ * bound to a frozen document and quietly stops updating; a soft navigation
+ * replaces the content the binding cache describes. Both are silent failures.
  */
 /** The part of the client this owner drives. */
 interface NavigationLifecycleTarget {
@@ -973,30 +781,17 @@ interface NavigationLifecycleTarget {
     refreshCache(): void;
 }
 interface NavigationLifecycleOptions {
-    /**
-     * Event target for `pagehide`/`pageshow`. Defaults to `window`.
-     *
-     * These fire on the window, not the document, and only there — binding them
-     * anywhere else silently never fires.
-     */
+    /** Where `pagehide`/`pageshow` fire; they exist only on the window. Defaults to `window`. */
     readonly windowTarget?: EventTarget;
-    /**
-     * Event target for soft-navigation events. Defaults to `document`.
-     */
+    /** Event target for soft-navigation events. Defaults to `document`. */
     readonly documentTarget?: EventTarget;
     /**
-     * Soft-navigation events after which the DOM has been replaced and the
-     * binding cache has to be rebuilt — for example `astro:page-load`.
-     *
-     * Empty by default: the package cannot know which framework is present, and
-     * guessing would either miss the event or rebuild on an unrelated one.
+     * Events after which the DOM was replaced and the cache must be rebuilt, e.g.
+     * `astro:page-load`. Empty by default: only the host knows which its router fires.
      */
     readonly softNavigationEvents?: readonly string[];
 }
-/**
- * Bind the document lifecycle. Returns an unbind function; calling it twice is
- * harmless.
- */
+/** Returns an unbind function; calling it twice is harmless. */
 declare function bindNavigationLifecycle(target: NavigationLifecycleTarget, options?: NavigationLifecycleOptions): () => void;
 
 interface RuntimeBuildInfo {
@@ -1005,536 +800,417 @@ interface RuntimeBuildInfo {
 }
 
 /**
- * Inline script generator.
- *
- * Wraps the build-time-generated runtime IIFE with consumer-provided
- * configuration. Returns a JavaScript string suitable for embedding
- * via `<script>` in any framework.
- *
- * The runtime body is identical to the one used by the high-level
- * client because both originate from `src/core/runtime.ts`. There is
- * no parallel implementation to drift out of sync.
- *
- * @module @inline/generator
+ * The inline script's configuration and its positional wire order: the
+ * generator writes the tuple, `src/core/runtime.ts` destructures it, and
+ * `INLINE_CONFIG_KEYS` is where they agree. Append only, never reorder.
  */
 
 interface InlineScriptConfig {
-    /** Additional trusted origins to merge with auto-detected ones. */
+    /** Trusted admin origins, merged with the detected ones. */
     readonly allowedOrigins?: readonly string[];
-    /**
-     * Payload server origin, e.g. `https://cms.example.com`. When set,
-     * every incoming update is re-fetched through the Payload REST API
-     * (`X-Payload-HTTP-Method-Override: GET`, same strategy as the
-     * official client) so relationship and upload fields render
-     * populated instead of as bare IDs. Strongly recommended for
-     * Payload 3.x. Requires the preview page to be able to reach the
-     * API with credentials (same-site cookies or CORS `credentials`).
-     */
+    /** Payload origin; every update is then re-fetched through the REST API with credentials. Requires `mergeDepth`. */
     readonly serverURL?: string;
-    /** REST API route prefix used with `serverURL`. Defaults to `/api`. */
+    /** REST route prefix used with `serverURL`. Default `/api`. */
     readonly apiRoute?: string;
-    /** Population depth used with `serverURL`. Defaults to `1`. */
+    /** Population depth used with `serverURL`. Required with `serverURL` unless `defaults: 'v1'`. */
     readonly mergeDepth?: number;
-    /** Enable verbose console logging. Defaults to `false`. */
+    /** Verbose console logging. Default `false`. */
     readonly debug?: boolean;
-    /** Debounce window for incoming updates in ms. Defaults to `50`. */
+    /** Debounce window for incoming updates in ms. Default `50`. */
     readonly debounceMs?: number;
-    /** Enable screen-reader live region. Defaults to `true`. */
+    /** Mount the screen-reader live region. Default `true`. */
     readonly enableA11y?: boolean;
-    /**
-     * Heartbeat timeout in ms. Defaults to `0` (disabled). The Payload
-     * admin only posts messages on form edits — there is no protocol
-     * keepalive — so an idle-based timeout would fire spurious
-     * disconnects while the editor pauses. Enable only if your admin
-     * setup sends periodic messages.
-     */
+    /** Heartbeat timeout in ms; `0` disables it (default), because the admin posts only on edits. */
     readonly heartbeatMs?: number;
-    /**
-     * Bypass the visibility-gate optimisation and apply every update
-     * regardless of viewport position. Default `false` — the gate kicks
-     * in when the cache exceeds `visibilityGateThreshold` entries.
-     */
+    /** Apply every update regardless of viewport position. Default `false`. */
     readonly disableVisibilityGate?: boolean;
-    /**
-     * Cache-size threshold above which the visibility gate activates.
-     * Default `50`. Off-screen elements above this threshold are queued
-     * for replay on intersection instead of being updated immediately.
-     */
+    /** Cache size above which off-screen updates wait for intersection. Default `50`. */
     readonly visibilityGateThreshold?: number;
-    /**
-     * `rootMargin` passed to the `IntersectionObserver` watching the
-     * cached elements. Default `'200px'`. Increase to pre-render
-     * further off-screen content; decrease for tighter visibility.
-     */
+    /** `rootMargin` of the IntersectionObserver. Default `'200px'`. */
     readonly intersectionRootMargin?: string;
-    /**
-     * Opt out of `document.referrer`-based origin auto-detection.
-     * Useful when the page is loaded under `Referrer-Policy: no-referrer`
-     * and you want predictable behaviour. Default `false`.
-     */
+    /** Ignore `document.referrer` as an origin source. Default `true`; `defaults: 'v1'` sets `false`. */
     readonly disableReferrerDetection?: boolean;
-    /**
-     * Opt out of the dev-mode localhost-pattern matcher (any port on
-     * `localhost` / `127.0.0.1`). Useful when running locally against
-     * a production-like origin list. Default `false`.
-     */
+    /** Disable the dev-mode localhost matcher (any port on `localhost`/`127.0.0.1`). Default `false`. */
     readonly disableLocalhostMatching?: boolean;
-    /**
-     * Restrict each update to the bindings owned by the document it describes,
-     * declared in markup with `data-payload-owner` and resolved from the nearest
-     * ancestor. Default `false`, which keeps matching on the field name alone.
-     *
-     * Enable it when one page previews more than one document. While enabled a
-     * binding without an owner is never updated.
-     */
+    /** Update only bindings under a matching `data-payload-owner`. Default `false`. */
     readonly scopeBindingsByOwner?: boolean;
-    /**
-     * Retained for 1.x source compatibility, but has no effect here:
-     * `generateInlineScript()` returns a script body and creates no tag.
-     * Pass the nonce separately to `wrapWithScriptTag(body, { nonce })`.
-     *
-     * @deprecated Use the second argument of `wrapWithScriptTag()`.
-     */
-    readonly nonce?: string;
+    /** Skip bindings whose value did not change. Default `true`; `defaults: 'v1'` sets `false`. */
+    readonly skipUnchanged?: boolean;
+    /** Scroll the preview to the field being edited. Default `false`. */
+    readonly revealEditedField?: boolean;
+    /** Which windows may post updates. Default `'parent-or-opener'`; `defaults: 'v1'` sets `'any'`. */
+    readonly eventSourcePolicy?: 'any' | 'parent-or-opener';
+    /** Sanitizer policy for rich text and HTML writes. Default `'strict'`; `defaults: 'v1'` sets `'compat'`. */
+    readonly sanitizerPolicy?: 'compat' | 'strict';
+    /** Same-origin path of a fragment endpoint; the script then carries the fragment client ahead of the runtime (ADR 0011). */
+    readonly fragmentEndpoint?: string;
+    /** Which defaults the omitted options fall back to. Not serialized: `'v1'` only relaxes the generator's `mergeDepth` check. */
+    readonly defaults?: DefaultsProfile;
 }
+
 /**
- * Build an inline script body. The result is a self-contained IIFE
- * with the build-time runtime, prefixed by a configuration block.
- *
- * The string does NOT include the `<script>` tags — use
- * `wrapWithScriptTag()` when you need them.
+ * Wraps the build-time runtime IIFE with the consumer's configuration; a page
+ * with a fragment endpoint gets the fragment prelude ahead of it.
  */
+
+/** The inline script body without `<script>` tags; see `wrapWithScriptTag()`. */
 declare function generateInlineScript(config?: InlineScriptConfig): string;
-/**
- * Wrap an inline script body in a `<script>` tag. When a nonce is
- * provided it is added as the `nonce` attribute so CSP policies that
- * require `'nonce-...'` accept the script.
- */
+/** Wrap a script body in `<script>`, with the CSP nonce attribute when given. */
 declare function wrapWithScriptTag(body: string, options?: {
     nonce?: string;
 }): string;
-/**
- * Snapshot of the build-time information for diagnostics.
- */
 declare function runtimeBuildInfo(): RuntimeBuildInfo;
 
-/**
- * HTML-escape primitives.
- *
- * Implementations follow the OWASP XSS Prevention Cheat Sheet: each
- * special character is replaced with its decimal or hex entity. The
- * functions are isomorphic — they have no dependency on the DOM and
- * can run in any JavaScript environment (browser, Node, Deno, Bun).
- *
- * @module @security/escape
- */
-/**
- * Escape every HTML-significant character in `text` so the result is
- * safe to interpolate into any HTML context (element body or attribute).
- *
- * - Coerces non-strings via `String(value)`; pass `null`/`undefined`
- *   intentionally — they become `"null"`/`"undefined"`.
- * - Cannot fail; returns `""` for the empty input.
- */
+/** HTML and CSS escaping primitives (OWASP XSS Prevention Cheat Sheet). DOM-free. */
+/** Escape `text` for an element body or a *quoted* attribute value; strings only, and unquoted attributes are not covered. */
 declare function escapeHtml(text: string): string;
-/**
- * Escape characters that would break out of a double-quoted HTML
- * attribute value. Stricter than `escapeHtml` for body content but
- * preserves URL characters (`/`, `=`, etc.) that are common in
- * `href` and `src` values.
- *
- * Only call this for values that have already been validated as safe
- * URLs or trusted strings; it does NOT block dangerous protocols.
- */
+/** Escape a value for a *quoted* HTML attribute, leaving URL characters intact; it validates no scheme, so run `isSafeUrl()` on `href`/`src` first. */
 declare function escapeHtmlAttribute(value: string): string;
 
 /**
- * URL safety validation.
- *
- * Single source of truth for URL-protocol decisions used by both the
- * inline runtime and the high-level client. The previous version of
- * this library had two implementations that subtly disagreed; this
- * module replaces both.
- *
- * Policy:
- *   - Allow only the protocols in `SAFE_PROTOCOLS`.
- *   - Reject every other protocol explicitly, including `javascript:`,
- *     `data:`, `vbscript:`, `file:`, `blob:`, and any custom scheme.
- *   - Empty strings are NOT considered safe (this is a tightening from
- *     the legacy behaviour and avoids producing `<a href="">` markup).
- *
- * @module @security/url-validator
- */
-/**
- * Returns `true` only when `url` is one of the explicitly allowed forms:
- *
- *   - Absolute URL with `http:`, `https:`, `mailto:`, or `tel:` protocol
- *   - Protocol-relative URL (`//example.com/...`)
- *   - Same-origin absolute path (`/foo`)
- *   - Hash or query fragment (`#section`, `?q=1`)
- *   - Plain relative path (`foo/bar`, `./foo`, `../foo`)
+ * URL safety: the one scheme allow-list the runtime, the client and the
+ * sanitizer share. Empty strings are not safe (`<a href="">` is never emitted).
  */
+/** `true` only for absolute `http`/`https`/`mailto`/`tel` URLs, protocol-relative URLs, paths, `#`/`?` fragments and relative paths. */
 declare function isSafeUrl(url: unknown): boolean;
-/**
- * Returns `true` when the URL points to an external HTTP(S) origin.
- * Protocol-relative URLs (`//example.com/...`) count as external —
- * they resolve to another origin and need the same `noopener`
- * hardening as absolute ones.
- *
- * Used by renderers to decide whether to add `target="_blank"` and the
- * `noopener noreferrer` rel attributes to anchors. Inputs that fail
- * `isSafeUrl()` always return `false`.
- */
+/** Whether a safe URL points at another HTTP(S) origin, protocol-relative forms included, and so needs `noopener` hardening. */
 declare function isExternalHttpUrl(url: string): boolean;
 
+/**
+ * `'strict'` (default) strips `id`, `name` and `data-payload-*` and passes
+ * other `data-*` only via `allowedDataAttributes`; `'compat'` keeps them.
+ */
+type SanitizerPolicyMode = 'compat' | 'strict';
 interface SanitizeOptions {
-    /** Extra tags to allow beyond the built-in list. Lower-case, untrimmed. */
+    /** Overrides the module default set by `setSanitizerPolicy()`. */
+    readonly policy?: SanitizerPolicyMode;
+    /** `data-*` attributes (full names) that pass under `'strict'`; `data-payload-*` never does. */
+    readonly allowedDataAttributes?: readonly string[];
+    /**
+     * Keep `input`, `button`, `textarea`, `select`, `option` and `label` — only
+     * for markup the page author wrote, never for CMS content. `form`,
+     * handlers, `style` and unsafe URLs stay dropped.
+     */
+    readonly allowFormControls?: boolean;
+    /** Extra tags to allow. Lower-case, untrimmed. */
     readonly additionalAllowedTags?: readonly string[];
-    /** Extra per-tag attributes to allow. Tag and attribute names must be lower-case. */
+    /**
+     * Extra per-tag attributes, lower-case. Cannot re-admit handlers, `style`,
+     * or — under `'strict'` — `id`, `name` and `data-payload-*`.
+     */
     readonly additionalAllowedAttributes?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * The input is a page-author item template, so `'strict'` keeps the
+     * applier's reconciliation attributes (`TEMPLATE_ATTRIBUTES`) and nothing
+     * else — every other `data-payload-*` is still stripped, so a template can
+     * never add a binding.
+     */
+    readonly templateMode?: boolean;
 }
-/**
- * Minimal `Document`-shaped surface the sanitizer needs. Any DOM
- * implementation (browser, jsdom, linkedom, happy-dom, parse5 + a
- * thin adapter) that produces `<template>`-style elements works.
- */
+/** Set the policy for calls without an explicit `policy`. The runtime sets it from `sanitizerPolicy`. */
+declare function setSanitizerPolicy(mode: SanitizerPolicyMode): void;
+/** The `Document` surface the sanitizer needs; jsdom, linkedom and happy-dom all provide it. */
 interface SanitizerDocument {
     createElement: (tagName: string) => {
         innerHTML: string;
         readonly content: ParentNode;
     };
 }
+/** Supply a `Document` for SSR, e.g. linkedom's `parseHTML(...).document`; `null` clears it. */
+declare function setSanitizerDocument(doc: SanitizerDocument | null): void;
 /**
- * Inject a `Document` implementation for the sanitizer to use when
- * `globalThis.document` is unavailable.
- *
- * Server-side renderers (Node, Bun, Deno without DOM globals) can wire
- * this up once at startup with any of the popular pure-JS DOM
- * libraries:
- *
- *   ```ts
- *   // linkedom — recommended (smallest, fastest)
- *   import { parseHTML } from 'linkedom';
- *   import { setSanitizerDocument } from 'payload-live-preview';
- *   const { document } = parseHTML('<!doctype html><html><body></body></html>');
- *   setSanitizerDocument(document);
- *   ```
- *
- *   ```ts
- *   // jsdom — heavier, but already in many SSR pipelines
- *   import { JSDOM } from 'jsdom';
- *   setSanitizerDocument(new JSDOM().window.document);
- *   ```
- *
- * Pass `null` to clear a previous override (mostly useful for tests).
- */
-declare function setSanitizerDocument(doc: SanitizerDocument | null): void;
-/**
- * Sanitize `html` and return safe HTML.
- *
- * The function never returns `undefined`/`null`. On malformed input the
- * browser parser silently recovers and the sanitizer continues from
- * the recovered tree.
+ * Sanitize `html`; malformed input is recovered by the parser first.
  *
  * @throws {SanitizerEnvironmentError} when no DOM is available.
  */
 declare function sanitizeHtml(html: string, options?: SanitizeOptions): string;
 
 /**
- * Content-Security-Policy helpers.
- *
- * Two responsibilities:
- *
- *   1. Generate cryptographic nonces so consumers can opt into a strict
- *      `script-src 'nonce-...'` policy and avoid `'unsafe-inline'`.
- *   2. Build the `frame-ancestors` directive value, restricting which
- *      origins may embed the preview page in an iframe.
- *
- * Both functions are isomorphic — they work in browsers, Node, and
- * edge runtimes that expose Web Crypto via `globalThis.crypto`.
- *
- * @module @security/csp
- */
-/**
- * Minimal Web-Crypto surface area we actually call. The full `Crypto`
- * type drags in browser-only declarations that don't typecheck cleanly
- * against Node's `webcrypto` shape — this narrower interface accepts
- * both without an unsafe cast.
+ * Content-Security-Policy helpers: nonce generation, directive builders and
+ * the header merge every adapter uses. Isomorphic; needs only Web Crypto.
  */
+/** The one Web Crypto method this module calls; accepts Node's `webcrypto` without a cast. */
 interface WebCryptoLike {
     getRandomValues: <T extends ArrayBufferView | null>(array: T) => T;
 }
-/**
- * Inject a Web Crypto implementation to use when `globalThis.crypto`
- * is unavailable.
- *
- * Node.js exposed `globalThis.crypto` globally starting with v19. On
- * Node 18 (still LTS at time of writing) consumers can flip the
- * `--experimental-global-webcrypto` flag *or* call this function once
- * at startup:
- *
- *   ```ts
- *   import { webcrypto } from 'node:crypto';
- *   import { setCspCrypto } from 'payload-live-preview';
- *   setCspCrypto(webcrypto as { getRandomValues: typeof webcrypto.getRandomValues });
- *   ```
- *
- * Browser bundles never need to call this — `globalThis.crypto` is
- * always present there, and the override only matters when the global
- * is missing.
- *
- * Pass `null` to clear a previous override (mostly useful for tests).
- */
+/** Supply a Web Crypto implementation for runtimes without `globalThis.crypto`; `null` clears it. */
 declare function setCspCrypto(crypto: WebCryptoLike | null): void;
-/**
- * Generate a base64url-encoded cryptographic nonce.
- *
- * Uses `crypto.getRandomValues` everywhere — falls back to throwing
- * if no Web Crypto implementation is available, because a predictable
- * nonce would silently defeat the entire CSP.
- *
- * @param bytes Number of random bytes (defaults to 16 → 128-bit entropy).
- */
+/** A base64url nonce of `bytes` random bytes (default 16); throws without Web Crypto, since a predictable nonce silently defeats the CSP. */
 declare function generateCspNonce(bytes?: number): string;
 interface FrameAncestorsOptions {
     readonly self?: boolean;
     readonly origins?: readonly string[];
     readonly allowNone?: boolean;
 }
-/**
- * Build the value for `frame-ancestors` in a `Content-Security-Policy`
- * header.
- *
- * Returns `'none'` if `allowNone: true` and no other sources are
- * provided. Otherwise concatenates `'self'` (if requested) with the
- * given origins, deduplicating and trimming entries.
- *
- * @example
- *   `frame-ancestors ${buildFrameAncestors({ self: true, origins: [adminUrl] })}`
- */
+/** The `frame-ancestors` value: `'self'` and the origins, deduplicated; `'none'` when empty. */
 declare function buildFrameAncestors(options?: FrameAncestorsOptions): string;
 /**
- * Build a `script-src` value that permits a single nonce plus optional
- * extra sources.
- *
- * `'strict-dynamic'` is **opt-in**: under CSP 3 it makes browsers
- * ignore `'self'` and every host source in the directive, so any
- * parser-inserted script without a nonce (framework hydration scripts,
- * consumer `<script>` tags) would be blocked. Only enable it when every
- * script on the page carries the nonce.
+ * A `script-src` value permitting one nonce plus optional extra sources.
+ * `'strict-dynamic'` is opt-in: it makes CSP 3 browsers ignore `'self'` and
+ * host sources, so every script on the page must then carry the nonce.
  */
 declare function buildScriptSrcWithNonce(nonce: string, options?: {
     readonly self?: boolean;
     readonly extra?: readonly string[];
     readonly strictDynamic?: boolean;
 }): string;
-/**
- * How a directive is merged into an existing CSP header value.
- *
- *   - `union` (default) — the new sources are added to the existing
- *     directive's sources (deduplicated). An existing `'none'` is
- *     dropped when real sources are added, since `'none'` may not be
- *     combined with other sources.
- *   - `replace` — the new value overwrites the existing directive.
- */
+/** `union` (default) adds sources to an existing directive; `replace` overwrites it. */
 interface CspDirectiveMerge {
     readonly value: string;
     readonly mode?: 'union' | 'replace';
 }
 /**
- * Merge directives into an existing `Content-Security-Policy` header
- * value without clobbering what a consumer (or another middleware)
- * already configured. Directives not mentioned in `additions` pass
- * through untouched; new directives are appended. Existing policy parsing
- * follows CSP3's ASCII-whitespace and first-duplicate-wins rules.
- *
- * This is the single CSP-merge implementation shared by every adapter.
+ * Merge directives into an existing `Content-Security-Policy` header value.
+ * Commas separate policies (that is how `Headers.get()` joins repeated
+ * headers); each is merged, because a browser enforces every policy and
+ * widening only the last would leave the others blocking.
  */
 declare function mergeCspHeader(existing: string, additions: Readonly<Record<string, string | CspDirectiveMerge>>): string;
 
 /**
- * Server-side preview-intent detection.
- *
- * The live-preview runtime only ever activates inside the Payload
- * admin's iframe, but the *server* still has to decide whether a
- * request expresses preview intent before doing optional preview
- * work. Adapters use this predicate as a delivery optimisation, and
- * consumers with hand-rolled middleware can import it directly.
- *
- * IMPORTANT: every signal inspected here is controlled or triggerable
- * by the client. A positive result is never proof of identity,
- * authentication, or permission to read drafts. Before forwarding
- * credentials, fetching draft data, bypassing caches, changing CSP,
- * or injecting the runtime, verify the request with an application-
- * owned server session or a short-lived signed authorization. Use the
- * same verified decision for all of those effects.
- *
- * Preview intent is present when any of these hold:
- *
- *   1. A preview query parameter is present (`?preview=true`,
- *      `?draft=true`, `?livePreview=true` — configurable).
- *   2. `Sec-Fetch-Dest: iframe` — the document is being loaded as an
- *      iframe, which is exactly how the Payload admin embeds it.
- *      (Sent by all evergreen browsers; absence never *excludes* a
- *      request, presence includes it.)
- *   3. The `Referer` points at one of the given admin origins.
- *
- * @module @adapters/shared/preview-request
- */
-/** The individual signals the predicate can consider. */
-type PreviewSignal = 'query' | 'fetch-dest' | 'referer';
-interface PreviewRequestOptions {
-    /**
-     * Which signals count as preview intent. Default: all three.
-     * Restricting this to `['query']` reduces accidental activation, but
-     * an explicit `?preview=true` is still client-controlled and must not
-     * authorize response changes or privileged data access by itself.
-     */
-    readonly signals?: readonly PreviewSignal[];
-    /**
-     * Query parameters (with values `true` or `1`) that signal preview
-     * intent. Default: `['preview', 'draft', 'livePreview']`.
-     */
-    readonly queryParams?: readonly string[];
-    /**
-     * Treat `Sec-Fetch-Dest: iframe` as a preview-intent signal. Default `true`.
-     * Legacy alias for excluding `'fetch-dest'` from `signals`.
-     */
-    readonly checkFetchDest?: boolean;
-    /**
-     * Admin origins whose `Referer` signals preview intent, e.g.
-     * `['https://cms.example.com']`. Referer matching is not HTTP-request
-     * authentication.
-     */
-    readonly adminOrigins?: readonly string[];
+ * The authorized preview context's shape and brand, in the leaf `types` domain
+ * so producer and consumers recognise the same context. See ADR 0006.
+ */
+/**
+ * The brand key, in the type and on the object.
+ *
+ * This was a `unique symbol` until 2026-08-30. A `unique symbol` is nominal per
+ * *declaration*, and the published entries each carry their own declaration
+ * file — so `AuthorizedPreviewContext` from the root barrel was a different
+ * type from the one in `./server` or in an adapter, and the documented flow
+ * (authorize once, hand the context to the adapter hook and to the draft read)
+ * did not type-check in any combination a consumer can write.
+ *
+ * That is the same trap the runtime brand below already avoids by using
+ * `Symbol.for` rather than `Symbol()`; the lesson simply had not reached the
+ * type. A shared string literal is identical in every bundle for the same
+ * reason a registry symbol is.
+ *
+ * It is not what makes a context trustworthy. `isAuthorizedPreviewContext`
+ * decides that, on the registry symbol and on `Object.isFrozen`, and every
+ * consumption point calls it — the adapter policy, the draft read and the
+ * binding emitter. Writing this key by hand buys nothing.
+ */
+declare const AUTHORIZED_PREVIEW_BRAND_KEY = "payload-live-preview.authorized-preview-context";
+type PreviewAuthorizationStrategyName = 'payload-session' | 'signed-token' | 'verifier';
+/** What a context is bound to; every field is optional because every strategy binds differently. */
+interface AuthorizedPreviewScope {
+    /** The site origin the credential was issued for. */
+    readonly audience?: string;
+    /** The request pathname the credential is valid for. */
+    readonly path?: string;
+    readonly locale?: string;
 }
+/** The verdict of a successful `authorizePreviewRequest()`: frozen, branded, produced only there. Carry it, do not rebuild it. */
+interface AuthorizedPreviewContext {
+    readonly [AUTHORIZED_PREVIEW_BRAND_KEY]: true;
+    readonly strategy: PreviewAuthorizationStrategyName;
+    /** The user id, token subject, or whatever the verifier named. */
+    readonly subject: string | undefined;
+    /** Unix milliseconds. */
+    readonly authorizedAt: number;
+    /** Unix milliseconds, or `undefined` when the strategy does not know. */
+    readonly expiresAt: number | undefined;
+    readonly scope: AuthorizedPreviewScope;
+    /** The minimal request material a draft read forwards to Payload — one verified cookie, never the whole `Cookie` header. */
+    readonly payloadHeaders: Readonly<Record<string, string>>;
+}
+/** Whether `value` was produced by `authorizePreviewRequest()`; a copy or JSON round trip is not. */
+declare function isAuthorizedPreviewContext(value: unknown): value is AuthorizedPreviewContext;
+
 /**
- * The minimal request surface the predicate needs. The standard
- * `Request` satisfies it structurally, and server frameworks without
- * fetch-style requests (e.g. Nitro/H3) can supply a tiny shim.
+ * The verdict shape every authorization strategy produces, and the one error
+ * class that is allowed to escape it. Kept apart from the strategies so the
+ * adapters can import the error without pulling in HMAC or session code.
  */
-interface PreviewRequestLike {
+
+/** Why a request was refused. `'authorized'` is the one non-refusal. */
+type PreviewAuthorizationOutcome = 'authorized' | 'missing-credential' | 'invalid' | 'expired' | 'wrong-audience' | 'wrong-path' | 'wrong-locale' | 'wrong-purpose' | 'replayed' | 'unavailable';
+/** The result of `authorizePreviewRequest()`: a verdict, never an exception. */
+type PreviewAuthorization = {
+    readonly authorized: true;
+    readonly outcome: 'authorized';
+    readonly context: AuthorizedPreviewContext;
+} | {
+    readonly authorized: false;
+    readonly outcome: Exclude<PreviewAuthorizationOutcome, 'authorized'>;
+    readonly context: null;
+};
+/** The request shape every strategy reads: a URL and a header getter. */
+interface PreviewAuthorizationRequest {
     readonly url: string;
     readonly headers: {
         get(name: string): string | null;
     };
 }
-/**
- * Detect whether `request` carries live-preview intent. See the module
- * docblock for the exact signals and the required authorization
- * boundary. This compatibility name does not imply authentication.
- */
-declare function isPreviewRequest(request: PreviewRequestLike, options?: PreviewRequestOptions): boolean;
 
 /**
- * Draft-aware document fetching for the initial preview render.
- *
- * The live-preview runtime patches the DOM *after* the page loads —
- * the initial server render is the consumer's job. With Payload
- * drafts enabled, an **authorized** preview should render the draft
- * version on first load, otherwise editors see stale published
- * content until their first keystroke.
- *
- * These helpers wrap the corresponding REST queries with `draft` and
- * `depth` options and an explicit nudge to keep `depth` in sync with
- * the runtime's `mergeDepth` — a mismatch makes populated
- * relationships degrade to IDs after the first edit.
- *
- * These helpers do not authenticate or authorize requests.
- * `isPreviewRequest()` detects client-controlled preview intent only.
- * Verify an application-owned server session or short-lived signed
- * authorization first, and use that one decision to gate `draft`, any
- * privileged headers, cache bypass, CSP changes, and runtime injection.
- * Never attach a long-lived service/API key merely because
- * `isPreviewRequest()` returned `true`.
- *
- * Isomorphic and dependency-free: works in Astro frontmatter,
- * SvelteKit `load`, Next.js server components, or any Node/edge
- * runtime with `fetch`.
- *
- * ```ts
- * // Astro frontmatter. `verifyAppPreviewSession` is application-owned,
- * // server-only code; it validates the request and returns only the
- * // minimal Payload session headers needed for this request.
- * const hasPreviewIntent = isPreviewRequest(Astro.request);
- * const authorization = hasPreviewIntent
- *   ? await verifyAppPreviewSession(Astro.request)
- *   : null;
- * const page = await fetchPreviewDocument<Page>({
- *   serverURL: import.meta.env.PAYLOAD_URL,
- *   collection: 'pages',
- *   where: { slug: { equals: Astro.params.slug } },
- *   draft: authorization !== null,
- *   ...(authorization === null ? {} : { headers: authorization.payloadHeaders }),
- * });
- * ```
- *
- * @module @preview-fetch
+ * The `payload-session` strategy: forward exactly one named cookie to
+ * `GET <serverURL>/api/<usersSlug>/me` and authorize when a user comes back.
  */
-interface PreviewFetchBaseOptions {
+
+/** A `fetch`-compatible function, injectable for tests. */
+type FetchLike = (input: string, init: {
+    readonly headers: Record<string, string>;
+    readonly signal: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+}>;
+interface PayloadSessionStrategy {
+    readonly type: 'payload-session';
     /** Payload server origin, e.g. `https://cms.example.com`. */
     readonly serverURL: string;
-    /** REST API route prefix. Defaults to `/api`. */
-    readonly apiRoute?: string;
-    /**
-     * Population depth. Defaults to `1`. ⚠️ Keep this equal to the
-     * runtime's `mergeDepth` — the live-merge re-fetches with that
-     * depth, and a mismatch makes nested relationships flip between
-     * objects and IDs mid-session.
-     */
-    readonly depth?: number;
-    /**
-     * Fetch the draft version. Defaults to `true` for 1.x compatibility.
-     * Set this from a verified authorization decision, not directly
-     * from `isPreviewRequest()`, whose result only expresses intent.
-     */
-    readonly draft?: boolean;
-    /** Locale to fetch. */
+    /** Auth collection slug; `users` unless the project renamed it. */
+    readonly usersSlug?: string;
+    /** Cookie name; Payload's default is `payload-token`. */
+    readonly cookieName?: string;
+    /** Upper bound for the `/me` round trip. Below 250 ms is raised to 250 ms; default 3000. */
+    readonly timeoutMs?: number;
+    /** Longest cookie value accepted; longer ones are refused as `invalid`. Default 4096. */
+    readonly maxCookieLength?: number;
+    readonly fetch?: FetchLike;
+    /** Clock, Unix milliseconds. Injectable for tests. */
+    readonly now?: () => number;
+}
+
+/**
+ * The `signed-token` strategy: a short-lived HMAC-SHA256 token minted by the
+ * Payload side and verified by the site. Format and bindings: ADR 0006 §3.
+ */
+
+/** The subset of Web Crypto the token strategy needs, injectable for environments that expose it elsewhere. */
+interface SubtleCryptoLike {
+    readonly subtle: {
+        importKey(format: 'raw', keyData: Uint8Array, algorithm: {
+            readonly name: 'HMAC';
+            readonly hash: 'SHA-256';
+        }, extractable: false, keyUsages: readonly ('sign' | 'verify')[]): Promise<CryptoKey>;
+        sign(algorithm: 'HMAC', key: CryptoKey, data: Uint8Array): Promise<ArrayBuffer>;
+        verify(algorithm: 'HMAC', key: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+    };
+    getRandomValues<T extends Uint8Array>(array: T): T;
+}
+/** Where a signed token is read from on the request. */
+type PreviewTokenTransport = {
+    readonly kind: 'query';
+    readonly param?: string;
+} | {
+    readonly kind: 'header';
+    readonly name?: string;
+};
+/**
+ * Optional replay store. Not shipped: a per-process memory is useless behind
+ * a load balancer, so the store is a deployment decision.
+ */
+interface PreviewTokenReplayStore {
+    isUsed(id: string): Promise<boolean> | boolean;
+    markUsed(id: string, expiresAt: number): Promise<void> | void;
+}
+interface SignedTokenStrategy {
+    readonly type: 'signed-token';
+    /** Shared secret, at least 32 bytes; shorter ones are refused on first use. */
+    readonly secret: string | Uint8Array;
+    /** The site origin tokens must name, e.g. `https://www.example.com`. */
+    readonly audience: string;
+    /** Purpose string tokens must carry. Default `live-preview`. */
+    readonly purpose?: string;
+    /** Default: query parameter `previewToken`. */
+    readonly transport?: PreviewTokenTransport;
+    /** Resolve the request's locale for the `loc` binding. Unset: tokens with `loc` are refused as `wrong-locale`. */
+    readonly locale?: (request: PreviewAuthorizationRequest) => string | undefined;
+    readonly replay?: PreviewTokenReplayStore;
+    readonly crypto?: SubtleCryptoLike;
+    readonly now?: () => number;
+}
+/** What `issuePreviewToken()` binds a token to. */
+interface PreviewTokenClaims {
+    /** The site origin the token is for. */
+    readonly audience: string;
+    /** Request pathname the token opens. Recommended; omit only for a single-page preview. */
+    readonly path?: string;
     readonly locale?: string;
-    /**
-     * Extra request headers. Supply only credentials derived from the
-     * current request's verified server-side session (or another
-     * short-lived, scoped authorization). Do not attach a long-lived
-     * service/API key based on a preview-intent signal.
-     */
-    readonly headers?: Readonly<Record<string, string>>;
-    /** Injectable fetch implementation (tests, custom agents). */
-    readonly fetchFn?: typeof fetch;
-}
-/** Payload `where` clause — kept loose on purpose (server validates). */
-type PreviewWhere = Readonly<Record<string, unknown>>;
-interface FetchPreviewDocumentOptions extends PreviewFetchBaseOptions {
-    /** Collection slug. */
-    readonly collection: string;
-    /** Fetch a single document by id. Mutually exclusive with `where`. */
-    readonly id?: string | number;
-    /**
-     * Fetch the first document matching this Payload `where` clause,
-     * e.g. `{ slug: { equals: 'about' } }`.
-     */
-    readonly where?: PreviewWhere;
+    readonly subject?: string;
+    readonly purpose?: string;
+    /** Lifetime in milliseconds. Default ten minutes; capped at one hour. */
+    readonly ttlMs?: number;
 }
-interface FetchPreviewGlobalOptions extends PreviewFetchBaseOptions {
-    /** Global slug. */
-    readonly global: string;
+interface IssuePreviewTokenOptions {
+    readonly secret: string | Uint8Array;
+    readonly crypto?: SubtleCryptoLike;
+    readonly now?: () => number;
 }
+/** Mint a preview token on the Payload side; pair with `buildLivePreviewUrl`. */
+declare function issuePreviewToken(claims: PreviewTokenClaims, options: IssuePreviewTokenOptions): Promise<string>;
+
 /**
- * Fetch a single collection document (draft-first by default for 1.x
- * compatibility; callers must authorize draft access).
- * Returns `null` when nothing matches or the request fails —
- * loaders should fall back to their regular data path or a 404.
+ * Authorized preview context: the one verdict every privileged preview
+ * decision is keyed on. Intent (`?preview=true`, an iframe destination, a
+ * referer) is client-chosen; this turns a session, a signed token or the
+ * application's own verifier into a branded context. Threat model: ADR 0006.
  */
-declare function fetchPreviewDocument<T = Record<string, unknown>>(options: FetchPreviewDocumentOptions): Promise<T | null>;
+
+/** Claims a consumer verifier returns for a request it accepts. */
+interface PreviewVerifierClaims {
+    readonly subject?: string;
+    readonly expiresAt?: number;
+    readonly scope?: AuthorizedPreviewScope;
+    readonly payloadHeaders?: Readonly<Record<string, string>>;
+}
+/** The application's own verification: claims authorize, `null` refuses, a throw is `unavailable`. */
+interface VerifierStrategy {
+    readonly type: 'verifier';
+    readonly verify: (request: PreviewAuthorizationRequest) => Promise<PreviewVerifierClaims | null> | PreviewVerifierClaims | null;
+    readonly now?: () => number;
+}
+type PreviewAuthorizationStrategy = PayloadSessionStrategy | SignedTokenStrategy | VerifierStrategy;
+/** Decide whether `request` is an authorized preview; refusals resolve to `{ authorized: false }` and only a `PreviewConfigurationError` throws. */
+declare function authorizePreviewRequest(request: PreviewAuthorizationRequest, strategy: PreviewAuthorizationStrategy): Promise<PreviewAuthorization>;
+
 /**
- * Fetch a global (draft-first by default for 1.x compatibility;
- * callers must authorize draft access). Returns `null` on failure.
+ * Trusted Types: every HTML sink routes through one policy, `payload-live-preview`,
+ * whose `createHTML` is the identity — what reaches a sink is already sanitized
+ * or escaped. Without the API, strings pass through untouched.
  */
-declare function fetchPreviewGlobal<T = Record<string, unknown>>(options: FetchPreviewGlobalOptions): Promise<T | null>;
+/** The subset of the Trusted Types API this module needs. */
+interface TrustedHtmlPolicyLike {
+    createHTML(input: string): unknown;
+}
+declare const TRUSTED_TYPES_POLICY_NAME = "payload-live-preview";
+/**
+ * Use `policy` for every sink, `null` to assign plain strings, `undefined` to
+ * return to the auto-created package policy.
+ */
+declare function setTrustedTypesPolicy(policy: TrustedHtmlPolicyLike | null | undefined): void;
+/** `html` as a `TrustedHTML` when a policy exists, else the string. Typed `string` for `innerHTML`. */
+declare function trustedHtml(html: string): string;
 
 /**
- * Generic Lexical node. Concrete renderers consume specific subtypes
- * through narrow type guards in their own modules.
+ * Server-side preview-intent detection. Every signal here is client-controlled:
+ * a positive result is a delivery hint, never proof of identity or permission.
+ * Verify with `authorizePreviewRequest()` before anything privileged.
  */
+/** `query`: `?preview=true`; `fetch-dest`: `Sec-Fetch-Dest: iframe`; `referer`: an admin-origin Referer. */
+type PreviewSignal = 'query' | 'fetch-dest' | 'referer';
+interface PreviewRequestOptions {
+    /** Which signals count. Default: all three. `['query']` is the adapters' 2.0 default. */
+    readonly signals?: readonly PreviewSignal[];
+    /** Query parameters (value `true` or `1`) that signal intent. Default `['preview', 'draft', 'livePreview']`. */
+    readonly queryParams?: readonly string[];
+    /** Admin origins whose Referer signals intent, e.g. `['https://cms.example.com']`. */
+    readonly adminOrigins?: readonly string[];
+}
+/** The request surface the predicate reads; `Request` satisfies it, Nitro/H3 events need a shim. */
+interface PreviewRequestLike {
+    readonly url: string;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+}
+/** Whether `request` carries live-preview intent. Intent, not authorization. */
+declare function hasPreviewIntent(request: PreviewRequestLike, options?: PreviewRequestOptions): boolean;
+
 interface LexicalNode {
     readonly type: string;
     readonly version?: number;
@@ -1545,9 +1221,6 @@ interface LexicalNode {
     readonly text?: string;
     readonly [extra: string]: unknown;
 }
-/**
- * Root of a Lexical document.
- */
 interface LexicalRoot {
     readonly root: {
         readonly type?: string;
@@ -1560,107 +1233,44 @@ interface LexicalRoot {
 }
 
 /**
- * Top-level Lexical → HTML renderer.
- *
- * Walks the document tree, dispatching each node to the renderer
- * registered for its `type`. Unknown nodes are handled gracefully:
- * children are rendered (so the user sees content), the wrapper is
- * skipped.
- *
- * @module @lexical/render
+ * Lexical → HTML. Each node dispatches to the renderer registered for its
+ * `type`; an unknown node renders its children so content is never lost.
  */
 
 interface LexicalRenderOptions {
-    /**
-     * When `true` (default), the resulting HTML is passed through the
-     * isomorphic `sanitizeHtml()` for defence-in-depth.
-     */
+    /** Pass the result through `sanitizeHtml()` (default `true`). */
     readonly sanitize?: boolean;
 }
-/**
- * Identify whether a value looks like a Lexical root payload.
- */
 declare function isLexicalContent(value: unknown): value is LexicalRoot;
-/**
- * Convert a Lexical root payload to an HTML string. By default the
- * result is sanitised through `sanitizeHtml`. The renderer is
- * security-first; per-node renderers already escape text and validate
- * URLs, but the final sanitiser closes any gap.
- */
+/** Render a Lexical document to HTML; without `setSanitizerDocument()` the result is unsanitised and warns once. */
 declare function lexicalToHtml(content: LexicalRoot, options?: LexicalRenderOptions): string;
-/**
- * Extract the plain text content of a Lexical document.
- *
- * Paragraphs are separated by `\n`. Used by the text/textarea renderer
- * when a rich-text value is bound to a non-rich-text element.
- */
+/** Plain text of a document, paragraphs separated by `\n`. */
 declare function lexicalToPlainText(content: LexicalRoot): string;
 
-/**
- * Block-renderer sub-registry.
- *
- * Payload's BlocksFeature emits Lexical `block` nodes with a
- * `blockType` slug. The default `block`-node renderer (in
- * `../nodes/block.ts`) only emits a generic
- * `<div data-block-type="…">` — useful as a hook, but unhelpful when
- * the consumer wants out-of-the-box rendering for common block types.
- *
- * This registry maps `blockType` → renderer. Default renderers ship
- * for the most common Payload block patterns (callout, image,
- * video, code, cta). Custom slugs override defaults via
- * `registerBlockRenderer(slug, renderer)`.
- *
- * @module @lexical/blocks/registry
- */
+/** Block-renderer registry keyed by Payload block slug; consulted by the `block` and `inlineBlock` nodes. */
 
-/**
- * Context passed to a block renderer. Includes the recursive
- * `renderChildren` function so blocks that house nested Lexical
- * content can delegate back to the main renderer.
- */
 interface BlockRenderContext {
-    /** Renders a list of Lexical children to HTML. */
+    /** Render nested Lexical content through the node registry. */
     readonly renderChildren: (children: readonly LexicalNode[]) => string;
 }
-/**
- * Renderer signature. Receives the block node *and* its already-read
- * `fields` payload (the parser pulls these out so individual block
- * renderers don't have to reach into `node['fields']` themselves).
- */
+/** Receives the block's `fields` (with `blockType`) and returns HTML. */
 type BlockRenderer = (fields: Record<string, unknown>, context: BlockRenderContext) => string;
 /** Register or replace the renderer for `blockType`. */
 declare function registerBlockRenderer(blockType: string, renderer: BlockRenderer): void;
 
 /**
- * `highlight` plugin — flashes an outline on updated elements so the
- * editor can see what changed.
- *
- * Respects `prefers-reduced-motion`. Adds at most one style tag per
- * document.
- *
- * @module @plugins/built-in/highlight
+ * `highlight` plugin: flashes an outline on updated elements. Respects
+ * `prefers-reduced-motion`; the stylesheet is shared per document across
+ * clients through a lease (ADR 0002).
  */
 
 declare const highlightPlugin: LivePreviewPlugin;
 
-/**
- * `debug` plugin — logs every lifecycle event via the plugin context.
- *
- * @module @plugins/built-in/debug
- */
+/** `debug` plugin: logs every lifecycle event through the plugin context. */
 
 declare const debugPlugin: LivePreviewPlugin;
 
-/**
- * `analytics` plugin — accumulates summary statistics about the
- * update stream. Useful for performance dashboards.
- *
- * The plugin owns its own state (no module singleton) and exposes it
- * via the `getStats` factory passed through the plugin's `init` hook
- * by closing over a local object.
- *
- * @module @plugins/built-in/analytics
- */
+/** `analytics` plugin: running totals over the update stream, read through `getStats()`. */
 
 interface AnalyticsSnapshot {
     readonly updateCount: number;
@@ -1673,281 +1283,100 @@ declare function createAnalyticsPlugin(): LivePreviewPlugin & {
 };
 
 /**
- * `documentSave` plugin — react to Payload document-save events with
- * out-of-the-box strategies. Most consumers just want one of these:
- *
- *   - `'silent'` (default) → only emit the event, do nothing else.
- *   - `'reload'`           → reload the page, **preserving the scroll
- *                            position** across the reload (the
- *                            framework-agnostic analog of Payload's
- *                            `RefreshRouteOnSave`).
- *   - `'revalidate'`       → POST to a revalidation endpoint (Astro,
- *                            Next.js convention) so SSR caches refresh
- *                            without losing client state.
- *   - `'fetch'`            → custom async handler supplied by the user.
- *
- * Each strategy is intentionally narrow so consumers can compose them
- * — e.g. revalidate, then if revalidation fails, fall back to reload.
- *
- * @module @plugins/built-in/document-save
+ * `documentSave` plugin: what to do when Payload saves the document.
+ * `'silent'` (default) emits only; `'reload'` reloads and restores the scroll
+ * position; `'revalidate'` POSTs to a revalidation endpoint; `'fetch'` runs
+ * a custom handler.
  */
 
 type DocumentSaveStrategy = 'silent' | 'reload' | 'revalidate' | 'fetch';
-/**
- * A fetch strategy handler. The optional parameter preserves calls through
- * pre-1.0.4 option objects (`options.handler?.()`), while method bivariance
- * also accepts explicitly signal-aware handlers. The built-in plugin always
- * supplies a live `AbortSignal`.
- */
+/** Handler for the `fetch` strategy; the signal aborts when the plugin is removed. */
 type DocumentSaveHandler = {
     bivarianceHack(signal?: AbortSignal): void | Promise<void>;
 }['bivarianceHack'];
 interface DocumentSavePluginOptions {
-    /** Strategy to invoke on each `documentSave` event. Default `'silent'`. */
+    /** Default `'silent'`. */
     readonly strategy?: DocumentSaveStrategy;
     /**
-     * For `'revalidate'`: endpoint to POST to. Defaults to `/api/revalidate`.
-     * The request body is `{ source: 'payload-live-preview' }` JSON.
+     * `'revalidate'` endpoint, default `/api/revalidate`; the body is
+     * `{ source: 'payload-live-preview' }`. The request is a plain `fetch` from
+     * the preview page: cookies travel with it, there is no CSRF token, and a
+     * bearer secret in `revalidateHeaders` would sit in page JavaScript. The
+     * endpoint must authorise on its own (session cookie, same-origin check).
      */
     readonly revalidateUrl?: string;
-    /**
-     * For `'revalidate'`: extra headers (e.g., `Authorization: Bearer …`).
-     * The `Content-Type: application/json` header is set automatically.
-     */
+    /** Extra request headers for `'revalidate'`; `Content-Type` is set already. */
     readonly revalidateHeaders?: Readonly<Record<string, string>>;
-    /**
-     * For `'fetch'`: async handler called on each event. The plugin
-     * awaits it; rejections are logged but don't crash the runtime. The signal
-     * aborts when the plugin is removed. Existing zero-argument handlers remain
-     * compatible because they may ignore the argument.
-     */
+    /** `'fetch'` handler; rejections are logged, never thrown. */
     readonly handler?: DocumentSaveHandler;
-    /**
-     * Optional fallback strategy when `'revalidate'` POST fails (network
-     * error or non-2xx). Set to `'reload'` to hard-refresh the page when
-     * SSR-cache invalidation can't be confirmed.
-     */
+    /** `'reload'` hard-refreshes when the revalidate request fails or returns non-2xx. */
     readonly onRevalidateFailure?: 'silent' | 'reload';
 }
-/**
- * Build the plugin. Pass it to `client.use(documentSavePlugin({ … }))`.
- */
 declare function documentSavePlugin(options?: DocumentSavePluginOptions): LivePreviewPlugin;
 
 /**
- * Environment introspection helpers.
- *
- * The detection layer needs to know whether the runtime is currently
- * running inside an iframe, in a popup, in development mode, and
- * whether environment variables are accessible. None of these checks
- * is dramatic on its own, but having a single, tested module avoids
- * the duplicated, subtly-different `typeof process` snippets that
- * accumulated in the legacy implementation.
- *
- * @module @detection/environment
- */
-/**
- * Returns `true` when the current window is inside an iframe.
- *
- * Uses a try/catch around `window.self !== window.top` because the
- * comparison throws in cross-origin iframes — and that very throw is
- * itself a definitive "yes, I am in an iframe" signal.
+ * Where the runtime is running: framed, opened, or on a developer's machine.
+ * Nothing reads bundler-injected variables; a Vite consumer passes
+ * `import.meta.env.X` explicitly (docs/astro.md).
  */
 declare function isInIframe(): boolean;
-/**
- * Returns `true` when the current window was opened via `window.open()`
- * and the opener reference is still accessible.
- */
 declare function isInPopup(): boolean;
-/**
- * Returns `true` when running in a preview-capable context: iframe or
- * popup. Anything else (top-level navigation) should skip live preview
- * initialisation entirely.
- */
+/** An iframe or a popup; top-level navigation never starts the preview. */
 declare function isInPreviewContext(): boolean;
-/**
- * Returns `true` when the runtime appears to be in development mode.
- *
- * Detection order:
- *   1. `process.env.NODE_ENV !== 'production'`
- *   2. `import.meta.env.DEV === true` (Vite / Astro / SvelteKit)
- *   3. `window.location.hostname` is `localhost`/`127.0.0.1`
- *
- * Returns `false` when none of those are available.
- */
+/** Under Node, `NODE_ENV !== 'production'`; in a browser the hostname, which is the only signal a bundle has. */
 declare function isDevMode(): boolean;
 
 /**
- * Origin detection and matching.
- *
- * Builds the set of trusted Payload admin origins and exposes a fast
- * matcher used by the message bus. Three sources, in precedence order:
- *
- *   1. Explicit origins passed via configuration. Always trusted.
- *   2. `document.referrer` — **only when no explicit origins are
- *      configured**. The browser writes the embedder's origin here
- *      when the iframe loads; using it as a fallback gives a
- *      zero-config path, but it must never widen an explicit
- *      allow-list (the referrer is whoever framed the page, which in
- *      an attack is the attacker).
- *   3. Localhost pattern (any port on `localhost` / `127.0.0.1`),
- *      enabled when development mode is detected. Replaces the
- *      legacy hand-rolled port list.
- *
- * Once the parent's origin is confirmed by an accepted data-bearing
- * update, callers can call `lockOrigin()` to drop every other candidate,
- * making subsequent matches exact. A data-less `ready` handshake does
- * not lock the detector.
- *
- * @module @detection/origin
+ * Which admin origins the runtime trusts: explicit ones always, the
+ * `document.referrer` origin only when none is configured, any localhost port
+ * in development. See docs/security.md §1.
  */
 interface OriginDetectorOptions {
-    /** Explicit additional origins to trust. Always allowed. */
+    /** Explicit origins to trust. Always allowed. */
     readonly additionalOrigins?: readonly string[];
-    /** Set to `false` to opt out of `document.referrer` detection. */
+    /** Set to `false` to ignore `document.referrer`. */
     readonly enableReferrerDetection?: boolean;
-    /** Set to `false` to opt out of localhost-pattern matching. */
+    /** Set to `false` to ignore the localhost pattern even in development. */
     readonly enableLocalhostMatching?: boolean;
-    /**
-     * Override the dev-mode detection. When `undefined`, dev mode is
-     * inferred from the runtime (see `isDevMode`).
-     */
+    /** Override dev-mode detection. */
     readonly forceDevMode?: boolean;
     /** Override `document.referrer` for tests. */
     readonly referrer?: string;
 }
-/**
- * Holds the resolved origin policy and exposes a matcher.
- *
- * The detector is stateful: it starts with the union of all candidate
- * sources, then narrows down to a single, verified origin once the
- * lifecycle calls `lockOrigin()` for its first accepted data-bearing
- * update.
- */
+/** The trusted-origin policy: the union of the candidate sources, narrowed to one by `lockOrigin()`. */
 declare class OriginDetector {
     #private;
     constructor(options?: OriginDetectorOptions);
-    /**
-     * Returns `true` when `origin` is trusted under the current policy.
-     *
-     * If an origin has been locked, only that exact value matches.
-     * Otherwise explicit origins and (in dev mode) localhost-pattern
-     * matches are accepted. The referrer-derived origin is a **fallback,
-     * not a union member**: it only counts when NO explicit origins are
-     * configured. `document.referrer` always names whoever actually
-     * framed the page — if it were unioned with the explicit list, any
-     * site embedding the page in an iframe would become a trusted
-     * postMessage sender despite the consumer having pinned the admin
-     * origin explicitly.
-     */
+    /** Whether `origin` is trusted: the locked origin alone once locked, otherwise the policy above. */
     matches(origin: string): boolean;
-    /**
-     * Narrow the trusted set to a single origin after an accepted
-     * data-bearing update. Subsequent calls to `matches()` only allow
-     * `origin`.
-     *
-     * Returns `true` if locking succeeded; `false` if the candidate is
-     * not currently considered trusted (which would defeat the purpose
-     * of locking).
-     */
+    /** Narrow trust to `origin`; refused (`false`) when it is not currently trusted. */
     lockOrigin(origin: string): boolean;
-    /**
-     * Release the origin lock so any allow-listed origin is trusted
-     * again until the next accepted data-bearing update. The lifecycle
-     * calls this on heartbeat timeout — after the trusted parent disappears,
-     * a different (still-allowed) origin should be free to reconnect.
-     *
-     * Returns the previously-locked origin, or `undefined` when nothing
-     * was locked.
-     */
+    /** Release the lock (heartbeat timeout) so another allow-listed origin may reconnect. Returns the previous lock. */
     unlockOrigin(): string | undefined;
-    /** The currently locked origin, or `undefined`. */
     get lockedOrigin(): string | undefined;
-    /**
-     * Snapshot of every origin currently allowed by the policy. Used by
-     * the message bus to broadcast `ready` messages.
-     *
-     * Localhost pattern matches are expanded into the common dev ports
-     * so the handshake can find a Payload running on its usual port.
-     */
+    /** Every origin the `ready` handshake is broadcast to; the localhost pattern expands to the common dev ports. */
     enumerate(): string[];
-    /**
-     * Reports whether `document.referrer` contributed at least one
-     * origin. Useful for surfacing a console warning when running in
-     * production without an explicit origin and the referrer is absent
-     * (because of a `Referrer-Policy: no-referrer` header).
-     */
+    /** Whether `document.referrer` contributed an origin (absent under `Referrer-Policy: no-referrer`). */
     get referrerWasAvailable(): boolean;
-    /**
-     * Indicates whether the detector is operating in a "production-without-
-     * explicit-origin" configuration. When `true`, the host should log a
-     * loud warning — silent connection failure is the worst outcome.
-     */
+    /** Framed, outside development, with no trusted origin at all: the host should warn (LP0101). */
     get isProductionUnconfigured(): boolean;
-    /**
-     * `true` when the referrer is the ONLY trust source (no explicit
-     * origins, no localhost matching). In that mode any site that frames
-     * the page becomes a trusted postMessage sender — `document.referrer`
-     * always names the actual embedder. Content is still sanitized, but
-     * the origin allow-list no longer restricts who may drive it. Hosts
-     * should surface a warning suggesting explicit `allowedOrigins` and
-     * a `frame-ancestors` policy in production.
-     */
+    /** The referrer is the only trust source, so any framing site may drive the preview (LP0102). */
     get isReferrerOnlyTrust(): boolean;
 }
 
-/**
- * Locale detection.
- *
- * The runtime needs a sensible default locale for date/number renders
- * before Payload tells us the active locale. Order of precedence:
- *
- *   1. The `lang` attribute on `<html>`.
- *   2. `navigator.language`.
- *   3. The hard-coded fallback `'en'`.
- *
- * The previous version of this library defaulted to `'de'` — a German
- * default that surprised consumers in other locales. We now use the
- * browser hint and fall back to English.
- *
- * @module @detection/locale
- */
-/**
- * Returns a BCP-47 locale string suitable for `Intl.*` constructors.
- *
- * Always returns a non-empty string. When no signal is available the
- * fallback (`'en'`) is returned.
- */
+/** The locale for `Intl` renders before Payload names one: `<html lang>`, then `navigator.language`, then `'en'`. */
 declare function detectInitialLocale(): string;
 
 /**
- * Field-renderer registry.
- *
- * Maps a `FieldType` to the function that mutates a DOM element with
- * the new value. The registry pattern decouples the lifecycle from the
- * concrete renderers, so:
- *
- *   - Tests can substitute mock renderers.
- *   - Plugins can register custom renderers via the high-level client.
- *   - New field types ship without touching `lifecycle.ts`.
- *
- * The explicit aggregator in `@field-types/index` supplies the default
- * renderers as values, so it remains tree-shaking-safe without module import
- * side effects. This registry stores only explicit consumer overrides.
- *
- * @module @field-types/registry
+ * Explicit renderer overrides, layered above the defaults each time a map is
+ * built. The registry never retains the defaults, so stateful ones can be
+ * recreated per client.
  */
 
-/**
- * Register or replace an explicit renderer override for future snapshots.
- */
+/** Register or replace an override for maps built afterwards. */
 declare function registerBuiltinRenderer(renderer: FieldRenderer): void;
 
-/**
- * Shared shapes for the field-type renderers.
- *
- * @module @field-types/types
- */
+/** Populated value shapes the field renderers read. */
 interface PayloadMedia {
     readonly id?: string | number;
     readonly url?: string;
@@ -1962,13 +1391,7 @@ interface PayloadMedia {
         readonly height?: number;
     }>>;
 }
-/**
- * Generic relationship payload. The optional `TSlug` parameter is a
- * phantom marker that codegen uses to record the target collection(s)
- * without changing the runtime shape — `PayloadRelationship<'users'>`
- * and `PayloadRelationship<'users' | 'authors'>` behave identically at
- * runtime but carry different types at compile time.
- */
+/** `TSlug` is a phantom marker codegen uses to record the target collection; the runtime shape is identical. */
 interface PayloadRelationship<TSlug extends string = string> {
     readonly id?: string | number;
     readonly title?: string;
@@ -1979,145 +1402,137 @@ interface PayloadRelationship<TSlug extends string = string> {
     readonly [extra: string]: unknown;
 }
 
-/**
- * Public barrel for built-in field renderers.
- *
- * Each renderer is imported as a named binding (not a side-effect)
- * and assembled into the registry through `buildBuiltinRenderers`.
- * The bundler keeps every reference reachable, so the registry is
- * fully populated at runtime even under `sideEffects: false`.
- *
- * @module @field-types
- */
+/** Built-in field renderers, assembled as values so `sideEffects: false` bundlers keep them all. */
 
-/**
- * Built-in renderer map. Called once per client/runtime; the
- * `structural-array` renderer gets a fresh instance with its own diff
- * state so nothing is shared between concurrent clients.
- */
+/** One renderer map per client; the stateful text and structural renderers are created fresh each call. */
 declare function buildBuiltinRenderers(): Readonly<Record<string, FieldRenderer>>;
 
 /**
- * Protocol-version negotiation.
- *
- * ⚠️ Reality check: **stock Payload does not version its live-preview
- * postMessage protocol.** The admin never sends a `protocolVersion`
- * field and ignores extra fields in our `ready` handshake. Observed
- * wire behaviour:
- *
- *   - Payload **2.x** sent `fieldSchemaJSON` with the first update
- *     (client-side merge era).
- *   - Payload **3.x** removed `fieldSchemaJSON` entirely; the official
- *     client re-fetches merged documents through the REST API instead.
- *   - No Payload version sends `previewToken` or any keepalive.
- *
- * This module therefore only matters for NON-stock admin panels — a
- * custom `window.postMessage` sender can advertise a version and this
- * library will negotiate `min(ours, theirs)` and expose capability
- * flags. Against stock Payload, `theirs` stays `undefined`, negotiation
- * collapses to v1, and nothing is gated on it: schema handling
- * activates whenever `fieldSchemaJSON` is actually present, and token
- * validation only runs when the consumer opts in.
- *
- * Version ladder (this library's own numbering, not Payload's):
- *
- *   - **v1** — data + slug + locale (matches stock Payload of any era).
- *   - **v2** — remote sends `fieldSchemaJSON` (Payload 2.x behaviour).
- *   - **v3** — remote sends `previewToken` (custom senders only).
- *   - **v4** — nested-array recursion / richer document events
- *     (custom senders only).
- *
- * @module @core/protocol-version
+ * Protocol negotiation. A capability is granted either by the version a peer
+ * announces or by observation, since the stock Payload admin announces none:
+ * what it can do is read off the messages it sends. See ADR 0010.
  */
+/** Bumped only when this library's understanding of the wire format changes. */
 declare const LIBRARY_PROTOCOL_VERSION = 4;
-/** Capability flag → minimum protocol version it requires. */
-declare const CAPABILITY_REQUIREMENTS: Readonly<Record<string, number>>;
-type ProtocolCapability = keyof typeof CAPABILITY_REQUIREMENTS;
+/** How a capability becomes active. */
+type CapabilitySource = 'version' | 'observed';
+interface CapabilityDeclaration {
+    /** Enabled once the negotiated version reaches this (for announced peers). */
+    readonly since: number;
+    /** The wire signal that grants this capability to a peer announcing no version. */
+    readonly observed?: 'schema' | 'locale' | 'preview-token' | 'document-event' | 'relationship-event';
+}
+/** What activates each capability; the prose lives in `CAPABILITY_DOCUMENTATION`. */
+declare const CAPABILITY_DECLARATIONS: {
+    readonly basic: {
+        readonly since: 1;
+    };
+    readonly 'schema-json': {
+        readonly since: 2;
+        readonly observed: "schema";
+    };
+    readonly locale: {
+        readonly since: 2;
+        readonly observed: "locale";
+    };
+    readonly 'preview-token': {
+        readonly since: 3;
+        readonly observed: "preview-token";
+    };
+    readonly 'nested-arrays': {
+        readonly since: 4;
+    };
+    readonly 'recursive-diffs': {
+        readonly since: 4;
+    };
+    readonly 'document-events': {
+        readonly since: 4;
+        readonly observed: "document-event";
+    };
+    readonly 'relationship-events': {
+        readonly since: 4;
+        readonly observed: "relationship-event";
+    };
+};
+type ProtocolCapability = keyof typeof CAPABILITY_DECLARATIONS;
+/** Every declared capability, in declaration order. */
+declare const PROTOCOL_CAPABILITIES: readonly ProtocolCapability[];
 interface ProtocolNegotiation {
     /** This library's protocol version. */
     readonly ours: number;
-    /** The remote party's version, when known. */
+    /** The remote party's version, when it announced one. */
     readonly theirs: number | undefined;
     /** `min(ours, theirs ?? 1)` — the version both sides actually share. */
     readonly negotiated: number;
-    /** Capability flags enabled at the negotiated version. */
-    readonly capabilities: ReadonlySet<string>;
+    /** Capabilities active at the negotiated version or seen on the wire. */
+    readonly capabilities: ReadonlySet<ProtocolCapability>;
+    /** The subset that was observed on the wire rather than granted by version. */
+    readonly observed: ReadonlySet<ProtocolCapability>;
 }
-/**
- * Compute the negotiated view of the protocol.
- *
- * `theirs === undefined` collapses to v1 — assume the remote party is
- * an older Payload that does not advertise a version.
- *
- * Non-finite or non-positive `theirs` values fall back to v1 as well —
- * we never trust an obviously-corrupted negotiation byte.
- */
-declare function negotiateProtocol(theirs: number | undefined): ProtocolNegotiation;
+/** Deterministic; the runtime re-runs it whenever either input changes. */
+declare function negotiateProtocol(theirs: number | undefined, observed?: Iterable<ProtocolCapability>): ProtocolNegotiation;
 declare function hasCapability(negotiation: ProtocolNegotiation, capability: ProtocolCapability): boolean;
 
 /**
- * Type-level path utilities — used by the typed binding DSL to give
- * callers compile-time autocomplete on field names.
- *
- * The same path strings the runtime reads from `data-payload-field`
- * are typed here, so a typo like `'heroTitlee'` is rejected at compile
- * time *and* the runtime side does not need to change.
- *
- * @module @dsl/paths
+ * What each capability tells the runtime, for `inspect()` and consumer
+ * diagnostics. Kept out of the runtime module so the inline bundle ships the
+ * rules and not this prose. See ADR 0010.
  */
+
+interface CapabilityDocumentation {
+    /** The runtime behaviour that depends on the capability. */
+    readonly gates: string;
+    /** What the runtime does without it. */
+    readonly fallback: string;
+}
+declare const CAPABILITY_DOCUMENTATION: Readonly<Record<ProtocolCapability, CapabilityDocumentation>>;
+
 /**
- * All string-typed top-level keys of `T`. Non-string keys (numeric
- * indices on arrays) are filtered out.
+ * What the peer does, derived from the capabilities its messages showed —
+ * the runtime never asks which Payload version it is talking to. Unknown
+ * until the admin reveals its shape. See ADR 0010.
  */
-type FieldName<T> = Extract<keyof T, string>;
+
+type ProtocolProfileName = 'unknown' | 'payload-2' | 'payload-3';
+interface ProtocolProfile {
+    readonly name: ProtocolProfileName;
+    /** Where field types come from. */
+    readonly fieldTyping: 'schema' | 'heuristic';
+    /**
+     * Who populates relationships. Payload 2.x's admin posts populated data
+     * (it merges client-side with `fieldSchemaJSON`); Payload 3.x posts raw
+     * form values and the runtime asks the REST API when `serverURL` is set.
+     */
+    readonly populatesRelationships: 'admin' | 'server';
+    /** Whether the peer reports document saves and relationship edits. */
+    readonly documentEvents: boolean;
+}
 /**
- * Dotted paths into nested object structures, capped at three levels
- * deep — sufficient for Payload's `group`/`tab`/`array` nesting
- * without ballooning the IDE's IntelliSense list past the point of
- * usefulness.
+ * `schema-json` on the wire is the Payload 2.x signature: 3.x removed
+ * `fieldSchemaJSON`. Document or relationship events are 3.x-only. Until
+ * either shows, the peer is unknown and treated like 3.x for merging — the
+ * conservative choice, because a needless REST merge costs a request while
+ * a missing one loses populated relationships.
  */
+declare function detectProtocolProfile(observed: ReadonlySet<ProtocolCapability>): ProtocolProfile;
+
+/** Type-level field paths, so a binding name is checked at compile time against the codegen schema. */
+/** String keys of `T`. */
+type FieldName<T> = Extract<keyof T, string>;
+/** Dotted paths into `T`, capped at three levels so IntelliSense stays usable. */
 type FieldPath<T, Depth extends 0 | 1 | 2 | 3 = 3> = Depth extends 0 ? never : T extends readonly (infer U)[] ? FieldPath<U, Prev<Depth>> : T extends object ? {
     [K in Extract<keyof T, string>]: K | (T[K] extends object ? `${K}.${FieldPath<T[K], Prev<Depth>>}` : never);
 }[Extract<keyof T, string>] : never;
-/** Decrement helper for depth-bounded recursion. */
 type Prev<N extends 0 | 1 | 2 | 3> = N extends 3 ? 2 : N extends 2 ? 1 : N extends 1 ? 0 : 0;
-/**
- * Resolve the value type at a dotted path. Returns `unknown` when the
- * path does not exist on `T`, so consumers can opt into stricter
- * `keyof`-based DSLs when they want absolute type safety.
- */
+/** The value type at a dotted path, or `unknown` when the path does not exist. */
 type ValueAt<T, P extends string> = P extends `${infer Head}.${infer Rest}` ? Head extends keyof T ? T[Head] extends readonly (infer U)[] ? ValueAt<U, Rest> : T[Head] extends object ? ValueAt<T[Head], Rest> : unknown : unknown : P extends keyof T ? T[P] : unknown;
 
 /**
- * Typed binding helpers — emit the `data-payload-field` attribute pair
- * that the live-preview runtime reads, with compile-time validation
- * of the field name.
- *
- * Two forms are exposed:
- *
- *   - **`bind<Schema>('heroTitle')`** — string-literal form. Lightest
- *     possible runtime (no Proxy), but a rename in the IDE does NOT
- *     follow into the string.
- *   - **`bindByPath<Schema>(s => s.heroTitle)`** — proxy form. The
- *     callback walks a Proxy that records the access path, returning
- *     the same shape as `bind` so the two are interchangeable. Slightly
- *     heavier runtime, but rename-safe and discourages typos.
- *
- * Both helpers also accept a richer return — `bind('image', 'src')` —
- * to bind an attribute other than the default `data-payload-field`,
- * matching the cache resolver's `data-payload-attribute` flow.
- *
- * @module @dsl/bind
+ * Typed helpers emitting the `data-payload-*` attributes the runtime reads.
+ * `bindByPath` records the path through a Proxy, so a rename follows.
  */
 
-/**
- * Shape returned by every binding helper — a spreadable HTML attribute
- * record. Astro / JSX / Svelte all accept this style directly:
- *
- *   ```astro
- *   <h1 {...bind<Homepage>('heroTitle')}>{data.heroTitle}</h1>
- *   ```
- */
+/** A spreadable attribute record: `<h1 {...bind<Homepage>('heroTitle')}>`. */
 interface FieldBindingAttributes {
     readonly 'data-payload-field': string;
     readonly 'data-payload-attribute'?: string;
@@ -2125,139 +1540,78 @@ interface FieldBindingAttributes {
     readonly 'data-payload-richtext'?: string;
     readonly 'data-payload-html'?: string;
     readonly 'data-payload-locale'?: string;
+    readonly 'data-payload-alt'?: string;
+    readonly 'data-payload-href'?: string;
+    readonly 'data-payload-array-template'?: string;
 }
 interface BindOptions {
-    /** Override the bound attribute (e.g., `'src'` for `<img>`). Default: textContent. */
+    /** Attribute to write instead of the text content, e.g. `'src'` for `<img>`. */
     readonly attribute?: string;
-    /** Explicit field-type override — bypasses schema detection. */
+    /** Explicit field type, bypassing schema detection. */
     readonly type?: string;
-    /**
-     * Mark the binding as Lexical rich text. Usually detected automatically;
-     * set it where the initial render is empty and there is nothing to detect.
-     */
+    /** Mark the binding as Lexical rich text; needed only when the initial render is empty. */
     readonly richtext?: boolean;
     /** Render the value as sanitised HTML rather than text. */
     readonly html?: boolean;
     /** Lock this element to one locale, overriding the message locale. */
     readonly locale?: string;
+    /** Field whose value becomes the image `alt`. */
+    readonly alt?: string;
+    /** Field whose value becomes the link `href`. */
+    readonly href?: string;
+    /** Markup per array item with `{{value}}` placeholders. */
+    readonly arrayTemplate?: string;
 }
-/**
- * String-literal binding helper.
- *
- *   ```ts
- *   import { bind } from 'payload-live-preview';
- *   import type { Homepage } from './payload-types';
- *
- *   <h1 {...bind<Homepage>('heroTitle')}>{data.heroTitle}</h1>
- *   <img {...bind<Homepage>('heroImage', { attribute: 'src' })} />
- *   ```
- *
- * The generic `T` is the schema interface emitted by `pll-codegen`.
- * `field` is constrained to `keyof T` so misspellings fail at compile
- * time. When `T` is omitted, the helper accepts any string — useful
- * for incremental adoption.
- */
+/** `bind<Homepage>('heroTitle')`; without `T` any string is accepted. */
 declare function bind<T = Record<string, unknown>>(field: FieldName<T>, options?: BindOptions): FieldBindingAttributes;
-/**
- * Proxy-path binding helper.
- *
- *   ```ts
- *   <h1 {...bindByPath<Homepage>(d => d.heroTitle)}>{data.heroTitle}</h1>
- *   ```
- *
- * The picker is invoked once with a recording Proxy; the recorded path
- * is joined with `.` and emitted as the binding name. Property access
- * on nested objects and arrays both work — `d => d.slides[0].title`
- * becomes `slides.title` (array indices are normalised away because the
- * runtime resolves bindings against schema, not against positional
- * indices).
- */
+/** `bindByPath<Homepage>(d => d.slides[0].title)` → `slides.title`; array indices are dropped because bindings resolve against the schema. */
 declare function bindByPath<T = Record<string, unknown>>(picker: (data: T) => unknown, options?: BindOptions): FieldBindingAttributes;
 
 /**
- * Authorization-gated binding emission.
- *
- * Binding attributes are not neutral markup. `data-payload-field` names a CMS
- * field, and `data-payload-owner` names a global, a collection and often a
- * document id. Emitted unconditionally they publish the shape of the content
- * model — and the identity of documents — to every anonymous visitor and
- * crawler of the page.
- *
- * The gate belongs to the application, not to this package: it is the same
- * decision that already controls draft reads and cache policy. What this
- * module provides is a place to apply that decision **once per request** so no
- * individual call site can forget it, and an emission unit that cannot be
- * partially suppressed.
- *
- * That second property matters more than it looks. A binding is not one
- * attribute: a field travels with its type, its locale, its rich-text marker
- * and its owner. Gating only the field name leaves the companions behind,
- * which discloses the taxonomy anyway and leaves the runtime looking at a
- * binding whose field is gone.
- *
- * @module @dsl/preview-bindings
+ * Binding helpers gated on one authorization verdict per request: the
+ * attributes publish the content model, so an unauthorized response carries
+ * none and a binding is suppressed whole, never in part. See ADR 0006.
  */
 
-/** Owner marker naming the document a subtree belongs to. */
 interface OwnerBindingAttributes {
     readonly 'data-payload-owner': string;
 }
-/**
- * The complete absence of binding attributes.
- *
- * Spreading this into markup contributes nothing, which is the point: an
- * unauthorized response must be byte-identical to one that never knew about
- * live preview.
- */
+/** No attributes at all: an unauthorized response is byte-identical to one that never knew about live preview. */
 type SuppressedBinding = Readonly<Record<string, never>>;
-interface PreviewBindingsOptions {
-    /**
-     * The application's own authorization verdict for this request.
-     *
-     * Never derive this from `?preview=true`, an iframe destination or a
-     * referer — those are client-controlled intent signals. Use the same
-     * verified result that decides whether drafts may be read.
-     */
-    readonly authorized: boolean;
-    /**
-     * Document this subtree belongs to, emitted as `data-payload-owner` by
-     * {@link PreviewBindings.owner}. Required only when the page previews more
-     * than one document and the runtime runs with `scopeBindingsByOwner`.
-     */
+interface PreviewBindingsCommonOptions {
+    /** Document this subtree belongs to, emitted as `data-payload-owner`; needed with `scopeBindingsByOwner`. */
     readonly owner?: string;
 }
-/** Request-scoped binding helpers that carry one authorization decision. */
+/** The verdict from `authorizePreviewRequest()`, or `null` for a public response. Only a branded context authorizes emission. */
+interface PreviewBindingsOptions extends PreviewBindingsCommonOptions {
+    readonly authorization: AuthorizedPreviewContext | null;
+}
+/** Request-scoped binding helpers carrying one authorization decision. */
 interface PreviewBindings {
-    /** The verdict these helpers were built with. */
     readonly authorized: boolean;
-    /** Typed field binding, or nothing at all while unauthorized. */
+    /** Typed field binding, or nothing while unauthorized. */
     bind: <T = Record<string, unknown>>(field: FieldName<T>, options?: BindOptions) => FieldBindingAttributes | SuppressedBinding;
-    /** Rename-safe field binding, or nothing at all while unauthorized. */
+    /** Rename-safe field binding, or nothing while unauthorized. */
     bindByPath: <T = Record<string, unknown>>(picker: (data: T) => unknown, options?: BindOptions) => FieldBindingAttributes | SuppressedBinding;
-    /**
-     * Owner marker for the element that owns this subtree, or nothing at all
-     * while unauthorized or when no owner was configured.
-     */
+    /** Owner marker for this subtree, or nothing while unauthorized or without an owner. */
     owner: () => OwnerBindingAttributes | SuppressedBinding;
 }
+/** Request-scoped `bind`, `bindByPath` and `owner`, all suppressed unless `authorization` is a real context. */
+declare function createPreviewBindings(options: PreviewBindingsOptions): PreviewBindings;
+
 /**
- * Build request-scoped binding helpers around one authorization decision.
- *
- * ```ts
- * const preview = createPreviewBindings({
- *   authorized: authorization !== null,
- *   owner: `global:${slug}`,
- * });
- * ```
- * ```astro
- * <section {...preview.owner()}>
- *   <h1 {...preview.bind<Homepage>('heroTitle')}>{data.heroTitle}</h1>
- * </section>
- * ```
- *
- * While unauthorized every helper returns an empty attribute set, so the
- * public response carries no `data-payload-*` at all.
+ * Hydrated islands own their subtree, so the runtime never patches inside one.
+ * Instead every flush dispatches `payload-live-preview:update` on each island
+ * root with the update in `detail`. `data-payload-island="patch"` opts back in.
  */
-declare function createPreviewBindings(options: PreviewBindingsOptions): PreviewBindings;
+declare const ISLAND_EVENT = "payload-live-preview:update";
+interface IslandUpdateDetail {
+    readonly fields: Readonly<Record<string, unknown>>;
+    readonly revision: number;
+    readonly receivedAt: number;
+    readonly locale: string | undefined;
+}
+/** Whether `element` (or an ancestor) is an island that did not opt into patching. */
+declare function isInsideIsland(element: Element): boolean;
 
-export { type AnalyticsSnapshot, type BindOptions, type BlockRenderContext, type BlockRenderer, type CachedElement, type ConnectionStatus, type CspDirectiveMerge, DIAGNOSTIC_CODES, type DiagnosticCode, type DocumentSaveHandler, type DocumentSavePluginOptions, type DocumentSaveStrategy, EventEmitter, type EventHandler, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldTransform, type FieldType, type FrameAncestorsOptions, type InlineScriptConfig, type InspectionBindings, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionScheduler, LIBRARY_PROTOCOL_VERSION, type LexicalNode, type LexicalRoot, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, type LivePreviewPlugin, type NavigationLifecycleOptions, type NavigationLifecycleTarget, OriginDetector, type OwnerBindingAttributes, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PayloadMedia, type PayloadRelationship, type PluginContext, type PluginDisposer, type PluginEvents, type PreviewBindings, type PreviewBindingsOptions, type PreviewFetchBaseOptions, type PreviewRequestLike, type PreviewRequestOptions, type PreviewWhere, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type SuppressedBinding, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, bindNavigationLifecycle, buildBuiltinRenderers, buildFrameAncestors, buildScriptSrcWithNonce, createAnalyticsPlugin, createPreviewBindings, debugPlugin, detectInitialLocale, documentSavePlugin, escapeHtml, escapeHtmlAttribute, fetchPreviewDocument, fetchPreviewGlobal, generateCspNonce, generateInlineScript, hasCapability, highlightPlugin, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isLexicalContent, isPreviewRequest, isSafeUrl, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, wrapWithScriptTag };
+export { AUTHORIZED_PREVIEW_BRAND_KEY, type AnalyticsSnapshot, type AuthorizedPreviewContext, type AuthorizedPreviewScope, type BindOptions, type BlockRenderContext, type BlockRenderer, CAPABILITY_DECLARATIONS, CAPABILITY_DOCUMENTATION, type CachedElement, type CapabilityDeclaration, type CapabilityDocumentation, type CapabilitySource, type ConnectionStatus, type CspDirectiveMerge, type CustomRendererKey, DIAGNOSTIC_CODES, type DefaultsProfile, type DiagnosticCode, type DocumentSaveHandler, type DocumentSavePluginOptions, type DocumentSaveStrategy, EventEmitter, type EventHandler, type EventSourcePolicy, type FetchLike, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldTransform, type FieldType, type FocusReportTarget, type FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InlineScriptConfig, type InspectionBindings, type InspectionFragments, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionRoute, type InspectionScheduler, type IslandUpdateDetail, type IssuePreviewTokenOptions, LIBRARY_PROTOCOL_VERSION, type LexicalNode, type LexicalRoot, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, type LivePreviewPlugin, type NavigationLifecycleOptions, type NavigationLifecycleTarget, OriginDetector, type OwnerBindingAttributes, PROTOCOL_CAPABILITIES, type PayloadDocumentEventDetail, type PayloadFieldCondition, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PayloadMedia, type PayloadRelationship, type PayloadSessionStrategy, type PluginCompatibility, type PluginContext, type PluginDisposer, type PluginEvents, type PluginInspection, type PreviewAuthorization, type PreviewAuthorizationOutcome, type PreviewAuthorizationRequest, type PreviewAuthorizationStrategy, type PreviewAuthorizationStrategyName, type PreviewBindings, type PreviewBindingsCommonOptions, type PreviewBindingsOptions, type PreviewFocusMessage, type PreviewRequestLike, type PreviewRequestOptions, type PreviewTokenClaims, type PreviewTokenReplayStore, type PreviewTokenTransport, type PreviewVerifierClaims, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RichTextRenderer, type RouteContext, type RouteStrategy, type SanitizerDocument, type SanitizerPolicyMode, type SignedTokenStrategy, type StrategyHandlers, type SubtleCryptoLike, type SuppressedBinding, TRUSTED_TYPES_POLICY_NAME, type TrustedHtmlPolicyLike, type Unsubscribe, type UpdateSource, VERSION, type ValueAt, type VerifierStrategy, authorizePreviewRequest, bind, bindByPath, bindNavigationLifecycle, buildBuiltinRenderers, buildFrameAncestors, buildScriptSrcWithNonce, createAnalyticsPlugin, createPreviewBindings, createPreviewFocusReporter, debugPlugin, detectInitialLocale, detectProtocolProfile, documentSavePlugin, escapeHtml, escapeHtmlAttribute, generateCspNonce, generateInlineScript, hasCapability, hasPreviewIntent, highlightPlugin, initLivePreview, isAuthorizedPreviewContext, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isInsideIsland, isLexicalContent, isSafeUrl, issuePreviewToken, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, registerBlockRenderer, registerBuiltinRenderer, reportPreviewFocus, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, setSanitizerPolicy, setTrustedTypesPolicy, trustedHtml, wrapWithScriptTag };