payload-live-preview 2.0.6 → 2.1.0

package/dist/index.d.cts

@@ -2,280 +2,6 @@
 /** @internal */
 declare const VERSION: string;
 
-/** Connection status and the heartbeat that decides a disconnect. */
-type ConnectionStatus = 'disconnected' | 'connecting' | 'connected';
-
-/**
- * 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 {
-    /** Configured origins; empty means the referrer and localhost heuristics decide instead. */
-    readonly trusted: readonly string[];
-    /** 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. */
-interface InspectionProtocol {
-    /** This library's protocol version. */
-    readonly ours: number;
-    /** The remote party's version, or `undefined` if it never announced one. */
-    readonly theirs: number | undefined;
-    /** `min(ours, theirs ?? 1)` — what both sides actually share. */
-    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 {
-    /** Updates accepted since the runtime started. */
-    readonly accepted: number;
-    /**
-     * Updates that were still in flight when a newer one arrived and were
-     * therefore abandoned. A number that tracks `accepted` closely means the
-     * editor is out-typing the pipeline, which is normal; it is only a problem
-     * 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;
-}
-/** What the DOM offers the runtime to write into. */
-interface InspectionBindings {
-    /** Elements carrying a binding. */
-    readonly elements: number;
-    /** Distinct field names across those elements. */
-    readonly fields: number;
-    /** Those field names, sorted. */
-    readonly fieldNames: readonly string[];
-    /**
-     * 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[];
-    /**
-     * Field names that arrived but matched no binding — a markup problem.
-     * A name in neither this list nor `fieldNames` was never sent. Cumulative.
-     */
-    readonly orphanFields: readonly string[];
-    /** Whether `scopeBindingsByOwner` is active. */
-    readonly ownerScoped: boolean;
-    /** Distinct document owners currently on the page, sorted. */
-    readonly owners: readonly string[];
-    /**
-     * Bindings the runtime found by value on the connection's first message
-     * (`autoBind: 'unique'`, ADR 0014), sorted by field, each with the value it
-     * matched on and the attribute it matched in — `undefined` for a text match.
-     * These are the elements that change without a `data-payload-field` in the
-     * template; every one of them carries `data-payload-guessed` in the DOM.
-     */
-    readonly guessed: readonly {
-        readonly field: string;
-        readonly matched: string;
-        readonly attribute: string | undefined;
-    }[];
-    /** `autoBind` as configured, and what the one search cost; `searchMs` is `undefined` until it ran. */
-    readonly autoBind: {
-        readonly mode: 'off' | 'unique';
-        readonly searchMs: number | undefined;
-    };
-}
-/** Scheduler work in progress. */
-interface InspectionScheduler {
-    /** Writes buffered for the next flush. */
-    readonly pending: number;
-    /** 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;
-    /** Whether the binding count is above that threshold right now. */
-    readonly visibilityGateActive: boolean;
-    /** Stats of the most recent flush, or `undefined` if none has run. */
-    readonly lastFlush: {
-        readonly applied: number;
-        /** 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; plain values only, with no references into runtime internals. */
-interface LivePreviewInspection {
-    /** Package version that produced this snapshot. */
-    readonly version: string;
-    /** Whether the runtime is started, and whether it has been destroyed. */
-    readonly started: boolean;
-    /** Connection status as reported to the `connect`/`disconnect` events. */
-    readonly status: ConnectionStatus;
-    readonly origins: InspectionOrigins;
-    readonly protocol: InspectionProtocol;
-    readonly revisions: InspectionRevisions;
-    readonly bindings: InspectionBindings;
-    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, were paced, or were stopped by the loop guard. */
-    readonly route: InspectionRoute;
-    /** Patches the runtime knew could not match the server's render, and what became of them. */
-    readonly fidelity: InspectionFidelity;
-    /**
-     * Whether the page declared a framework that hydrates it, and how far the
-     * wait for its first commit — React's, or Vue's mount — got (ADR 0015).
-     * `waiting` is why a preview on a Next or Nuxt page is not connected yet;
-     * `timed-out` is LP0607.
-     */
-    readonly hydration: {
-        readonly mode: 'off' | 'react' | 'vue';
-        readonly state: 'idle' | 'waiting' | 'committed' | 'timed-out';
-    };
-}
-/**
- * The fidelity verdicts as `inspect()` reports them (LP0411). A positive
- * `unfaithful` beside `escalated: 0` is a page that keeps a degraded patch —
- * because `mode` says so, or because `canEscalate` is false: neither
- * `fragments.handler` nor `route.handler` is there to escalate to, which the
- * runtime also says once as LP0808 when `mode` is `'escalate'`.
- */
-interface InspectionFidelity {
-    /** `onUnfaithfulPatch` as resolved from both of its names. */
-    readonly mode: 'ignore' | 'warn' | 'escalate';
-    /** Whether a fragment or route strategy exists for `'escalate'` to hand a patch to. */
-    readonly canEscalate: boolean;
-    /** Bindings reported unfaithful since start — once per element, like LP0411, and under every mode. */
-    readonly unfaithful: number;
-    /** Of those, how many were handed to the fragment or route strategy. */
-    readonly escalated: number;
-    /** The field names behind `unfaithful`, sorted. Cumulative. */
-    readonly fields: readonly string[];
-}
-/** The route strategy as `inspect()` reports it. */
-interface InspectionRoute {
-    readonly handler: boolean;
-    readonly refreshes: number;
-    /** Refreshes that broke: the request, the answer, or the morph. */
-    readonly failed: number;
-    /**
-     * Refreshes the strategy's own minimum interval held back (LP0805). Each is
-     * run once the window closes unless a newer revision takes its place, so this
-     * counts pacing and not loss — and it is deliberately not `failed`.
-     */
-    readonly refused: 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'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: the most recent relationship-document event (a drawer save), or `null`. */
-    readonly externallyUpdatedRelationship?: PayloadDocumentEventDetail | null;
-    /** Library extension: the token `validateToken` checks. Stock Payload never sends one. */
-    readonly previewToken?: string;
-    /** Library extension: the highest protocol version the sender supports; absent means v1. */
-    readonly protocolVersion?: number;
-}
-/** Payload's `DocumentEvent` shape (admin `providers/DocumentEvents`). */
-interface PayloadDocumentEventDetail {
-    readonly entitySlug: string;
-    readonly operation?: 'create' | 'update';
-    readonly id?: string | number;
-    readonly updatedAt?: string;
-    readonly [extra: string]: unknown;
-}
-/** A validated update as events expose it. */
-interface PayloadLivePreviewData {
-    readonly fields: Record<string, unknown>;
-    readonly schema?: readonly PayloadFieldSchema[];
-    readonly globalSlug?: string;
-    readonly collectionSlug?: string;
-    readonly locale?: string;
-}
-/** The subset of Payload's field schema the runtime reads; extra properties are kept opaquely. */
-interface PayloadFieldSchema {
-    readonly name: string;
-    readonly type: PayloadFieldType;
-    readonly label?: string;
-    readonly required?: boolean;
-    readonly localized?: boolean;
-    readonly fields?: readonly PayloadFieldSchema[];
-    readonly blocks?: readonly PayloadBlockSchema[];
-    readonly relationTo?: string | readonly string[];
-    readonly hasMany?: boolean;
-    readonly admin?: {
-        readonly condition?: PayloadFieldCondition;
-    };
-    readonly [extra: string]: unknown;
-}
-interface PayloadBlockSchema {
-    readonly slug: string;
-    readonly fields: readonly PayloadFieldSchema[];
-    readonly [extra: string]: unknown;
-}
-/** 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';
-/** `admin.condition` is a function in source and cannot cross `postMessage`; modelled, not consumed. */
-type PayloadFieldCondition = (data: unknown, siblingData: unknown) => boolean;
-
 /**
  * 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
@@ -355,13 +81,13 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly StartupFailed: "LP0605";
     /** Sending the ready handshake failed. */
     readonly ReadyFailed: "LP0606";
-    /** The page declared hydration, but no React commit or Vue mount came within the cap; the runtime started without waiting. */
+    /** The page declared hydration, but no React commit, Vue mount or SvelteKit mount came within the cap; the runtime started without waiting. */
     readonly HydrationWaitTimedOut: "LP0607";
     /** The audit found no runtime in a response that carried preview intent. */
     readonly AuditRuntimeMissing: "LP0701";
     /** The preview response declares no `frame-ancestors`. */
     readonly AuditNoFrameAncestors: "LP0702";
-    /** `X-Frame-Options` forbids framing, which no CSP can undo; `SAMEORIGIN` forbids it from another origin only. */
+    /** `X-Frame-Options` forbids framing on a response that declares no `frame-ancestors`; `SAMEORIGIN` forbids it from another origin only. */
     readonly AuditFrameOptionsBlocks: "LP0703";
     /** Binding attributes are served to anonymous visitors. */
     readonly AuditBindingsExposed: "LP0704";
@@ -389,6 +115,10 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly UnboundChangeRefresh: "LP0807";
     /** `onUnfaithfulPatch: 'escalate'` found no route or fragment strategy to hand an unfaithful patch to; the page keeps it. */
     readonly EscalationUnavailable: "LP0808";
+    /** A fragment inserted an Astro island the page cannot start: it never loaded the island element or that client directive. */
+    readonly IslandStartUnavailable: "LP0809";
+    /** The host's route refresh returned no promise, so the revision was re-applied before the host committed. */
+    readonly RouteRefreshUnconfirmed: "LP0810";
     /** 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. */
@@ -397,6 +127,69 @@ declare const DIAGNOSTIC_CODES: Readonly<{
 /** A diagnostic code, as it appears in log output and on the `error` event. */
 type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[keyof typeof DIAGNOSTIC_CODES];
 
+/**
+ * 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: the most recent relationship-document event (a drawer save), or `null`. */
+    readonly externallyUpdatedRelationship?: PayloadDocumentEventDetail | null;
+    /** Library extension: the token `validateToken` checks. Stock Payload never sends one. */
+    readonly previewToken?: string;
+    /** Library extension: the highest protocol version the sender supports; absent means v1. */
+    readonly protocolVersion?: number;
+}
+/** Payload's `DocumentEvent` shape (admin `providers/DocumentEvents`). */
+interface PayloadDocumentEventDetail {
+    readonly entitySlug: string;
+    readonly operation?: 'create' | 'update';
+    readonly id?: string | number;
+    readonly updatedAt?: string;
+    readonly [extra: string]: unknown;
+}
+/** A validated update as events expose it. */
+interface PayloadLivePreviewData {
+    readonly fields: Record<string, unknown>;
+    readonly schema?: readonly PayloadFieldSchema[];
+    readonly globalSlug?: string;
+    readonly collectionSlug?: string;
+    readonly locale?: string;
+}
+/** The subset of Payload's field schema the runtime reads; extra properties are kept opaquely. */
+interface PayloadFieldSchema {
+    readonly name: string;
+    readonly type: PayloadFieldType;
+    readonly label?: string;
+    readonly required?: boolean;
+    readonly localized?: boolean;
+    readonly fields?: readonly PayloadFieldSchema[];
+    readonly blocks?: readonly PayloadBlockSchema[];
+    readonly relationTo?: string | readonly string[];
+    readonly hasMany?: boolean;
+    readonly admin?: {
+        readonly condition?: PayloadFieldCondition;
+    };
+    readonly [extra: string]: unknown;
+}
+interface PayloadBlockSchema {
+    readonly slug: string;
+    readonly fields: readonly PayloadFieldSchema[];
+    readonly [extra: string]: unknown;
+}
+/** 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';
+/** `admin.condition` is a function in source and cannot cross `postMessage`; modelled, not consumed. */
+type PayloadFieldCondition = (data: unknown, siblingData: unknown) => boolean;
+
 /**
  * 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
@@ -420,9 +213,9 @@ interface FragmentContext {
     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). */
+    /** Morph server-rendered HTML into a boundary; no-op after supersession (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. */
+    /** Patch the boundary's owned bindings from this revision; no-op after supersession. */
     readonly patch: (boundary: Element) => void;
     /** Debug log through the runtime's logger, with the diagnostic code. */
     readonly log: (code: DiagnosticCode, detail: string) => void;
@@ -447,8 +240,13 @@ interface FragmentStrategy {
 interface RouteContext {
     readonly revision: number;
     readonly receivedAt: number;
-    /** Aborted when a newer revision arrives or the runtime stops. */
+    /** Aborted when a newer revision asks for a refresh of its own, a navigation commits, or the runtime stops. */
     readonly signal: AbortSignal;
+    /**
+     * Whether the refresh may still land. A newer revision that asks for no
+     * refresh of its own does not end it: the route is the server's, so the
+     * refresh lands for that revision, which the runtime then re-applies.
+     */
     readonly isCurrent: () => boolean;
     readonly log: (code: DiagnosticCode, detail: string) => void;
     /**
@@ -461,18 +259,30 @@ interface RouteContext {
     readonly retryAfter?: (delayMs: number) => void;
 }
 /**
- * What one refresh did. `refused` is the strategy's own brake and not a
- * failure — it is counted separately, because a number that mixes a planned
- * pause with a broken request cannot be read.
+ * What one refresh did. `refreshed` asserts that the strategy rendered the
+ * current unsaved revision. `partial` completed a render whose data source was
+ * not proven current; the runtime still reapplies every binding it can reach.
+ * `refused` is the strategy's own brake and not a failure.
  */
-type RouteOutcome = 'refreshed' | 'failed' | 'refused' | 'superseded';
+type RouteOutcome = 'refreshed' | 'partial' | 'failed' | 'refused' | 'superseded';
+/** What the runtime tells a route planner about the update it plans for. */
+interface RoutePlanContext {
+    /**
+     * Whether an element belongs to the update: always `true` without
+     * `scopeBindingsByOwner`, otherwise only inside the document the update
+     * names. A marker outside it asks for nothing.
+     */
+    readonly inScope: (element: Element) => boolean;
+}
 /**
  * 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.
+ * refresh the runtime rescans and re-applies the revision, so reachable
+ * unsaved bindings land on the fresh markup. The runtime always passes
+ * `context`; a planner written before it existed still works, but plans for
+ * markers of every document.
  */
 interface RouteStrategy {
-    readonly plan: (root: ParentNode, changedFields: ReadonlySet<string>) => boolean;
+    readonly plan: (root: ParentNode, changedFields: ReadonlySet<string>, context?: RoutePlanContext) => boolean;
     readonly refresh: (context: RouteContext) => Promise<RouteOutcome>;
 }
 interface StrategyHandlers {
@@ -542,6 +352,12 @@ interface LivePreviewEventMap {
         readonly revision: number;
         readonly receivedAt: number;
     };
+    /**
+     * A revision left `pending`: it is current, partial (with the shortfalls
+     * that kept it from being current), unconfirmed by an island, or superseded.
+     * Fires again when an unconfirmed revision is confirmed (ADR 0023).
+     */
+    readonly revisionDisplay: RevisionDisplay;
     /** A `payload-document-event` message arrived (document save). */
     readonly documentSave: {
         readonly timestamp: number;
@@ -630,6 +446,12 @@ interface SanitizeOptions {
      * never add a binding.
      */
     readonly templateMode?: boolean;
+    /**
+     * The DOM to parse with, for this call: an SSR document such as linkedom's
+     * or jsdom's. Wins over `setSanitizerDocument()` and over the global
+     * `document`, and two callers with two documents never share one.
+     */
+    readonly document?: SanitizerDocument;
 }
 /**
  * The default for calls without an explicit `policy`, per package entry. A
@@ -643,10 +465,19 @@ interface SanitizerDocument {
         readonly content: ParentNode;
     };
 }
-/** Supply a `Document` for SSR, e.g. linkedom's `parseHTML(...).document`; `null` clears it, for every entry. */
+/**
+ * Supply a `Document` for SSR, e.g. linkedom's `parseHTML(...).document`;
+ * `null` clears it, for every entry. The fallback for a call that names no
+ * document of its own.
+ *
+ * @deprecated Since 2.1 a call names its document: `sanitizeHtml(html, { document })`,
+ * `lexicalToHtml(content, { document })`. The process-wide slot stays until 3.0
+ * (ADR 0007 ledger).
+ */
 declare function setSanitizerDocument(doc: SanitizerDocument | null): void;
 /**
- * Sanitize `html`; malformed input is recovered by the parser first.
+ * Sanitize `html`; malformed input is recovered by the parser first. The
+ * result is a fixed point: sanitising it again changes nothing.
  *
  * @throws {SanitizerEnvironmentError} when no DOM is available.
  */
@@ -712,41 +543,381 @@ interface CachedElement {
      * binding the runtime found by value rather than one the template declared.
      * Absent for a declared binding.
      */
-    readonly guessed?: string;
+    readonly guessed?: string;
+}
+/** 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>;
+    /** Active locale, or `undefined` when none is established. */
+    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;
+    /**
+     * The Payload server the runtime reads populated documents from (`serverURL`),
+     * absent without one. A renderer that writes a URL out of a media document
+     * resolves a path against it, as Payload's admin does; the built-in `upload`
+     * and `image` renderers do.
+     */
+    readonly serverURL?: string;
+    /**
+     * This instance's sanitizer policy, for every HTML write the renderer makes.
+     * Absent, the process default set by `setSanitizerPolicy()` applies.
+     */
+    readonly sanitizerPolicy?: SanitizerPolicyMode;
+    /**
+     * Say that this write cannot reproduce what the server drew, so
+     * `onUnfaithfulPatch` can have a strategy render the region instead of
+     * leaving a degraded patch on the page. The built-in rich-text renderer
+     * calls it for a Lexical block whose markup it had to drop; a project
+     * renderer may call it for any value it can only approximate. `reason`
+     * completes the sentence 'field "x" …' in LP0411.
+     */
+    readonly reportUnfaithful?: (target: CachedElement, reason: string) => void;
+}
+/**
+ * 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: RendererKey;
+    render(target: CachedElement, value: unknown, context: RenderContext): void;
+}
+
+/**
+ * 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. @internal */
+declare const LIBRARY_PROTOCOL_VERSION = 4;
+/** How a capability becomes active. @internal */
+type CapabilitySource = 'version' | 'observed';
+/** @internal */
+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. @internal */
+declare const PROTOCOL_CAPABILITIES: readonly ProtocolCapability[];
+interface ProtocolNegotiation {
+    /** This library's protocol version. */
+    readonly ours: number;
+    /** 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;
+    /** 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>;
+}
+/** Deterministic; the runtime re-runs it whenever either input changes. */
+declare function negotiateProtocol(theirs: number | undefined, observed?: Iterable<ProtocolCapability>): ProtocolNegotiation;
+/** @internal */
+declare function hasCapability(negotiation: ProtocolNegotiation, capability: ProtocolCapability): boolean;
+
+/** Connection status and the heartbeat that decides a disconnect. */
+type ConnectionStatus = 'disconnected' | 'connecting' | 'connected';
+
+/**
+ * How completely the page shows one revision (ADR 0023). The session counters
+ * say what happened over a session; this says, for the revision in flight,
+ * whether work is outstanding and which step fell short, so a host does not
+ * have to attribute route outcomes and fragment fallbacks itself.
+ */
+
+/** Where a revision stands: work left, shown, shown with shortfalls, awaiting an island, or replaced (ADR 0023). */
+type RevisionDisplayState = 'pending' | 'current' | 'partial' | 'unconfirmed' | 'superseded';
+/** One step that kept a settled revision from being current. */
+type RevisionShortfall = {
+    readonly kind: 'fragment';
+    readonly id: string;
+    readonly key: string | undefined;
+    readonly code: DiagnosticCode;
+} | {
+    readonly kind: 'route-saved';
+} | {
+    readonly kind: 'route-failed';
+    readonly outcome: RouteOutcome;
+} | {
+    readonly kind: 'unfaithful' | 'unbound';
+    readonly field: string;
+} | {
+    readonly kind: 'write';
+    readonly field: string;
+    readonly code: DiagnosticCode;
+} | {
+    readonly kind: 'merge';
+};
+/** How completely the page shows one accepted revision (ADR 0023). */
+interface RevisionDisplay {
+    /** The message revision this record is about. */
+    readonly revision: number;
+    /** `pending` while work is left; the other states once it settled. */
+    readonly state: RevisionDisplayState;
+    /** What kept a settled revision from being current; empty unless `state` is `partial`. */
+    readonly shortfalls: readonly RevisionShortfall[];
+    /** Writes the visibility gate holds until their element is seen; they count as landed. */
+    readonly deferred: number;
+    /** Islands the revision was handed to that have not called `displayed()`. */
+    readonly awaitingIslands: number;
+}
+
+/**
+ * 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 {
+    /** Configured origins; empty means the referrer and localhost heuristics decide instead. */
+    readonly trusted: readonly string[];
+    /** 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. */
+interface InspectionProtocol {
+    /** This library's protocol version. */
+    readonly ours: number;
+    /** The remote party's version, or `undefined` if it never announced one. */
+    readonly theirs: number | undefined;
+    /** `min(ours, theirs ?? 1)` — what both sides actually share. */
+    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 {
+    /** Updates accepted since the runtime started. */
+    readonly accepted: number;
+    /**
+     * Updates that were still in flight when a newer one arrived and were
+     * therefore abandoned. A number that tracks `accepted` closely means the
+     * editor is out-typing the pipeline, which is normal; it is only a problem
+     * 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;
+    /**
+     * How completely the page shows the latest accepted revision (ADR 0023):
+     * `pending`, `current`, `partial` with its shortfalls, or `unconfirmed` while
+     * an island it was handed has not called `displayed()`. `undefined` before
+     * the first message.
+     */
+    readonly display: RevisionDisplay | undefined;
 }
-/** 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>;
-    /** Active locale, or `undefined` when none is established. */
-    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;
+/** What the DOM offers the runtime to write into. */
+interface InspectionBindings {
+    /** Elements carrying a binding. */
+    readonly elements: number;
+    /** Distinct field names across those elements. */
+    readonly fields: number;
+    /** Those field names, sorted. */
+    readonly fieldNames: readonly string[];
     /**
-     * This instance's sanitizer policy, for every HTML write the renderer makes.
-     * Absent, the process default set by `setSanitizerPolicy()` applies.
+     * 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 sanitizerPolicy?: SanitizerPolicyMode;
+    readonly absentFields: readonly string[];
     /**
-     * Say that this write cannot reproduce what the server drew, so
-     * `onUnfaithfulPatch` can have a strategy render the region instead of
-     * leaving a degraded patch on the page. The built-in rich-text renderer
-     * calls it for a Lexical block whose markup it had to drop; a project
-     * renderer may call it for any value it can only approximate. `reason`
-     * completes the sentence 'field "x" …' in LP0411.
+     * Scalar fields (and one group level) that arrived but matched no binding.
+     * Arrays, relationships, rich text, `null` and the fields Payload sends with
+     * every update are never listed. Cumulative.
      */
-    readonly reportUnfaithful?: (target: CachedElement, reason: string) => void;
+    readonly orphanFields: readonly string[];
+    /** Whether `scopeBindingsByOwner` is active. */
+    readonly ownerScoped: boolean;
+    /** Distinct document owners currently on the page, sorted. */
+    readonly owners: readonly string[];
+    /**
+     * Bindings the runtime found by value on the connection's first message
+     * (`autoBind: 'unique'`, ADR 0014), sorted by field, each with the value it
+     * matched on and the attribute it matched in — `undefined` for a text match.
+     * These are the elements that change without a `data-payload-field` in the
+     * template; every one of them carries `data-payload-guessed` in the DOM.
+     */
+    readonly guessed: readonly {
+        readonly field: string;
+        readonly matched: string;
+        readonly attribute: string | undefined;
+    }[];
+    /** `autoBind` as configured, and what the one search cost; `searchMs` is `undefined` until it ran. */
+    readonly autoBind: {
+        readonly mode: 'off' | 'unique';
+        readonly searchMs: number | undefined;
+    };
+}
+/** Scheduler work in progress. */
+interface InspectionScheduler {
+    /** Writes buffered for the next flush. */
+    readonly pending: number;
+    /** 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;
+    /** Whether the binding count is above that threshold right now. */
+    readonly visibilityGateActive: boolean;
+    /** Stats of the most recent flush, or `undefined` if none has run. */
+    readonly lastFlush: {
+        readonly applied: number;
+        /** 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; plain values only, with no references into runtime internals. */
+interface LivePreviewInspection {
+    /** Package version that produced this snapshot. */
+    readonly version: string;
+    /** Whether the runtime is started, and whether it has been destroyed. */
+    readonly started: boolean;
+    /** Connection status as reported to the `connect`/`disconnect` events. */
+    readonly status: ConnectionStatus;
+    readonly origins: InspectionOrigins;
+    readonly protocol: InspectionProtocol;
+    readonly revisions: InspectionRevisions;
+    readonly bindings: InspectionBindings;
+    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, were paced, or were stopped by the loop guard. */
+    readonly route: InspectionRoute;
+    /** Patches the runtime knew could not match the server's render, and what became of them. */
+    readonly fidelity: InspectionFidelity;
+    /**
+     * Whether the page declared a framework that hydrates it, and how far the
+     * wait for its first commit — React's, Vue's mount, or SvelteKit's root
+     * mounting — got (ADR 0015). `waiting` is why a preview on a Next, Nuxt or
+     * SvelteKit page is not connected yet; `timed-out` is LP0607.
+     */
+    readonly hydration: {
+        readonly mode: 'off' | 'react' | 'vue' | 'sveltekit';
+        readonly state: 'idle' | 'waiting' | 'committed' | 'timed-out';
+    };
 }
 /**
- * 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.
+ * The fidelity verdicts as `inspect()` reports them (LP0411). A positive
+ * `unfaithful` beside `escalated: 0` is a page that keeps a degraded patch —
+ * because `mode` says so, or because `canEscalate` is false: neither
+ * `fragments.handler` nor `route.handler` is there to escalate to, which the
+ * runtime also says once as LP0808 when `mode` is `'escalate'`.
  */
-interface FieldRenderer {
-    readonly name: RendererKey;
-    render(target: CachedElement, value: unknown, context: RenderContext): void;
+interface InspectionFidelity {
+    /** `onUnfaithfulPatch` as resolved from both of its names. */
+    readonly mode: 'ignore' | 'warn' | 'escalate';
+    /** Whether a fragment or route strategy exists for `'escalate'` to hand a patch to. */
+    readonly canEscalate: boolean;
+    /** Bindings reported unfaithful since start — once per element, like LP0411, and under every mode. */
+    readonly unfaithful: number;
+    /** Of those, how many were handed to the fragment or route strategy. */
+    readonly escalated: number;
+    /** The field names behind `unfaithful`, sorted. Cumulative. */
+    readonly fields: readonly string[];
+}
+/** The route strategy as `inspect()` reports it. */
+interface InspectionRoute {
+    readonly handler: boolean;
+    readonly refreshes: number;
+    /** Successful refreshes whose server render was not proven to contain the current unsaved revision. */
+    readonly partial: number;
+    /** Refreshes that broke: the request, the answer, or the morph. */
+    readonly failed: number;
+    /**
+     * Refreshes the strategy's own minimum interval held back (LP0805). Each is
+     * run once the window closes unless a newer revision takes its place, so this
+     * counts pacing and not loss — and it is deliberately not `failed`.
+     */
+    readonly refused: 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;
+    };
 }
 
 /**
@@ -861,6 +1032,13 @@ interface LivePreviewClientConfig {
      * and listed in `inspect().bindings.guessed`. Default `'off'`.
      */
     readonly autoBind?: 'off' | 'unique';
+    /**
+     * How a group counts as covered (ADR 0022). `'descendant'` (default): one
+     * bound path inside it covers all of it. `'declared'`: each changed path
+     * inside such a group needs its own binding or a `data-payload-covers`
+     * declaration; an uncovered one is an unbound change.
+     */
+    readonly subfieldCoverage?: 'descendant' | 'declared';
     /** 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. */
@@ -926,7 +1104,10 @@ declare class LivePreviewClient {
     use(plugin: LivePreviewPlugin): Promise<void>;
     /** Unregister a plugin and release everything its registration owned. Still allowed from a destroy hook during teardown. */
     unuse(name: string): Promise<void>;
+    /** Re-scan bindings after replacing markup without crossing a navigation boundary. */
     refreshCache(): void;
+    /** Re-scan bindings and locally replay the last accepted document after a router commit. */
+    refreshAfterNavigation(): void;
     get events(): EventEmitter;
     /** Names of the registered plugins. */
     get plugins(): readonly string[];
@@ -972,7 +1153,10 @@ declare function createPreviewFocusReporter(resolveTarget: () => FocusReportTarg
 interface NavigationLifecycleTarget {
     suspend(): boolean;
     resume(): boolean;
+    /** Re-scan bindings after replacing markup without crossing a navigation boundary. */
     refreshCache(): void;
+    /** Re-scan and replay the last accepted document after a committed router navigation. */
+    refreshAfterNavigation?(): void;
 }
 interface NavigationLifecycleOptions {
     /** Where `pagehide`/`pageshow` fire; they exist only on the window. Defaults to `window`. */
@@ -980,8 +1164,9 @@ interface NavigationLifecycleOptions {
     /** Event target for soft-navigation events. Defaults to `document`. */
     readonly documentTarget?: EventTarget;
     /**
-     * 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.
+     * Events after which the DOM was replaced and the current editor state must
+     * be replayed, e.g. `astro:page-load`. Empty by default: only the host knows
+     * which its router fires.
      */
     readonly softNavigationEvents?: readonly string[];
 }
@@ -1011,6 +1196,9 @@ declare function bindNavigationLifecycle(target: NavigationLifecycleTarget, opti
  * A host's own route refresh. It must settle once the fresh markup is
  * committed: the runtime re-applies the revision on top of it, and doing that
  * against the markup being replaced would write into nodes about to be dropped.
+ * A function that returns nothing is taken as already committed; the route
+ * strategy says once that it could not wait (LP0810), and 3.0 requires the
+ * promise (ADR 0028).
  */
 type RouteRefresh = () => void | Promise<void>;
 /**
@@ -1105,21 +1293,40 @@ interface InlineScriptConfig {
      * throws `Hydration failed` and regenerates the tree, and the write is gone.
      * Under `'vue'` it holds the write until Vue has mounted the app around them
      * — otherwise Vue's hydration repairs the write back to the server's value,
-     * quietly. The Next.js and Nuxt adapters set it on every script they emit; a
-     * page built by hand with `generateInlineScript()` may. Omitted: the runtime
-     * starts on `DOMContentLoaded`, as on a static page.
+     * quietly. Under `'sveltekit'` it holds the write until SvelteKit's root has
+     * mounted, on a page SvelteKit's client runs on — otherwise Svelte's
+     * hydration sets its own text back over it, as quietly. The Next.js, Nuxt
+     * and SvelteKit adapters set it on every script they emit; a page built by
+     * hand with `generateInlineScript()` may. Omitted: the runtime starts on
+     * `DOMContentLoaded`, as on a static page.
      */
-    readonly hydration?: 'react' | 'vue';
+    readonly hydration?: 'react' | 'vue' | 'sveltekit';
     /**
      * Which defaults the omitted options fall back to, resolved by the generator
      * rather than the runtime, whose own fallbacks are the 2.0 rows: `'v1'`
      * writes its four runtime rows into their slots (an explicit option still
      * wins) and relaxes the `mergeDepth` check. The resolved value always
-     * travels, in the last slot, so a reader of the served page knows what an
+     * travels in slot 24, so a reader of the served page knows what an
      * empty slot means instead of guessing it — `pll doctor --v2` reads it. The
-     * runtime does not: every row the profile decides is already in its slot.
+     * runtime does not use that value: every row the profile decides is already
+     * in its slot. Slot 24 stays fixed as later options are appended.
      */
     readonly defaults?: DefaultsProfile;
+    /**
+     * Document events fired after a client router committed new markup. Each
+     * rebuilds the binding cache and locally reapplies the last accepted state.
+     * Adapter integrations set this from their framework lifecycle. It is a
+     * low-level generator fact, not a `PreviewAdapterOptions` field. Empty by
+     * default.
+     */
+    readonly softNavigationEvents?: readonly string[];
+    /**
+     * How a group counts as covered (ADR 0022). `'descendant'`, the 2.x default:
+     * one bound path inside it covers all of it. `'declared'`: each changed path
+     * inside such a group needs its own binding or a `data-payload-covers`
+     * declaration; an uncovered one is an unbound change.
+     */
+    readonly subfieldCoverage?: 'descendant' | 'declared';
     /**
      * A runtime artifact to embed instead of the full one — today only
      * `LEAN_RUNTIME` from `payload-live-preview/lean`, which leaves out the
@@ -1249,6 +1456,25 @@ declare function mergeCspHeader(existing: string, additions: Readonly<Record<str
  */
 declare const AUTHORIZED_PREVIEW_BRAND_KEY = "payload-live-preview.authorized-preview-context";
 type PreviewAuthorizationStrategyName = 'payload-session' | 'signed-token' | 'verifier';
+/** One server-authorized Payload document, not a query selected by the browser. */
+type AuthorizedPreviewDocument = {
+    readonly kind: 'collection';
+    readonly slug: string;
+    readonly id: string | number;
+} | {
+    readonly kind: 'global';
+    readonly slug: string;
+};
+/** Opt-in data capability, enforced by the fragment endpoint and `definePreview`. */
+interface AuthorizedPreviewPayloadScope {
+    /** Payload base URL, distinct from the preview site's audience. */
+    readonly serverURL: string;
+    /** REST prefix, default `/api`. */
+    readonly apiRoute?: string;
+    readonly document: AuthorizedPreviewDocument;
+    /** Maximum requested population depth, not a field-level ACL. */
+    readonly maxDepth: number;
+}
 /** 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. */
@@ -1256,6 +1482,8 @@ interface AuthorizedPreviewScope {
     /** The request pathname the credential is valid for. */
     readonly path?: string;
     readonly locale?: string;
+    /** Requires a finite context expiry. Unscoped contexts keep their existing behavior. */
+    readonly payload?: AuthorizedPreviewPayloadScope;
 }
 /** The verdict of a successful `authorizePreviewRequest()`: frozen, branded, produced only there. Carry it, do not rebuild it. */
 interface AuthorizedPreviewContext {
@@ -1298,11 +1526,15 @@ interface PreviewAuthorizationRequest {
     readonly headers: {
         get(name: string): string | null;
     };
+    /** Request lifetime, when supplied by the caller. Session fetches follow it. */
+    readonly signal?: AbortSignal;
 }
 
 /**
  * The `payload-session` strategy: forward exactly one named cookie to
  * `GET <serverURL>/api/<usersSlug>/me` and authorize when a user comes back.
+ * A cookie-only request preserves working Payload 2 sessions. When `/me`
+ * reports no user, one retry adds an `Origin` for Payload 3's CSRF check.
  */
 
 /** A `fetch`-compatible function, injectable for tests. */
@@ -1322,6 +1554,12 @@ interface PayloadSessionStrategy {
     readonly usersSlug?: string;
     /** Cookie name; Payload's default is `payload-token`. */
     readonly cookieName?: string;
+    /**
+     * Send this listed origin with the cookie from the first request. Without
+     * it, try the existing cookie-only request, then the origin of `serverURL`
+     * once when `/me` reports a null user. Draft reads keep the accepted headers.
+     */
+    readonly origin?: 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 `missing-credential`. Default 4096. */
@@ -1371,7 +1609,7 @@ interface PreviewTokenReplayStore {
     consume(id: string, expiresAt: number): Promise<boolean> | boolean;
 }
 /**
- * @deprecated The 1.x store shape, removed in 3.0. Its two calls cannot be one
+ * @deprecated The store shape of the 2.0 beta, removed in 3.0. Its two calls cannot be one
  * step, so two requests with the same token that arrive together both pass
  * `isUsed` before either reaches `markUsed`. Implement
  * {@link PreviewTokenReplayStore.consume} instead.
@@ -1535,6 +1773,19 @@ interface LexicalRoot {
 interface LexicalRenderOptions {
     /** Pass the result through `sanitizeHtml()` (default `true`). */
     readonly sanitize?: boolean;
+    /**
+     * The DOM the sanitizer parses with, for this call: an SSR document such as
+     * linkedom's or jsdom's. Without it the document `setSanitizerDocument()`
+     * supplied is used, then the global one; with neither the result is
+     * unsanitised and warns once.
+     */
+    readonly document?: SanitizerDocument;
+    /**
+     * Throw instead of returning unsanitised HTML when no document is available:
+     * the `SanitizerEnvironmentError` `sanitizeHtml()` throws (ADR 0025). Off in
+     * 2.x, where the call warns once and returns the markup; the default in 3.0.
+     */
+    readonly requireDocument?: boolean;
     /**
      * Called for every `block` or `inlineBlock` the registry has no renderer
      * for, with the block's slug as Payload sent it and the class its empty
@@ -1546,7 +1797,7 @@ interface LexicalRenderOptions {
 }
 /** @internal */
 declare function isLexicalContent(value: unknown): value is LexicalRoot;
-/** Render a Lexical document to HTML; without `setSanitizerDocument()` the result is unsanitised and warns once. */
+/** Render a Lexical document to HTML; without a document the result is unsanitised and warns once, or throws under `requireDocument`. */
 declare function lexicalToHtml(content: LexicalRoot, options?: LexicalRenderOptions): string;
 /** Plain text of a document, paragraphs separated by `\n`. */
 declare function lexicalToPlainText(content: LexicalRoot): string;
@@ -1570,7 +1821,7 @@ declare function registerBlockRenderer(blockType: string, renderer: BlockRendere
 
 declare const highlightPlugin: LivePreviewPlugin;
 
-/** `debug` plugin: logs every lifecycle event through the plugin context. */
+/** `debug` plugin: logs init, connect, disconnect, cacheRefresh, beforeUpdate, afterUpdate and error through the plugin context. */
 
 declare const debugPlugin: LivePreviewPlugin;
 
@@ -1714,74 +1965,6 @@ interface PayloadRelationship<TSlug extends string = string> {
 /** One renderer map per client; the stateful text and structural renderers are created fresh each call. @internal */
 declare function buildBuiltinRenderers(): Readonly<Record<string, FieldRenderer>>;
 
-/**
- * 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. @internal */
-declare const LIBRARY_PROTOCOL_VERSION = 4;
-/** How a capability becomes active. @internal */
-type CapabilitySource = 'version' | 'observed';
-/** @internal */
-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. @internal */
-declare const PROTOCOL_CAPABILITIES: readonly ProtocolCapability[];
-interface ProtocolNegotiation {
-    /** This library's protocol version. */
-    readonly ours: number;
-    /** 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;
-    /** 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>;
-}
-/** Deterministic; the runtime re-runs it whenever either input changes. */
-declare function negotiateProtocol(theirs: number | undefined, observed?: Iterable<ProtocolCapability>): ProtocolNegotiation;
-/** @internal */
-declare function hasCapability(negotiation: ProtocolNegotiation, capability: ProtocolCapability): boolean;
-
 /**
  * What each capability tells the runtime, for `inspect()` and consumer
  * diagnostics. Kept out of the runtime module so the inline bundle ships the
@@ -1808,9 +1991,10 @@ interface ProtocolProfile {
     /** 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.
+     * Legacy transport label, retained for 2.x compatibility. `admin` identifies
+     * Payload 2's schema-based path; observed messages can contain raw relation IDs,
+     * which the shared merger populates with collection GETs. `server` identifies
+     * the Payload 3 merge path. This label alone does not describe population state.
      */
     readonly populatesRelationships: 'admin' | 'server';
     /** Whether the peer reports document saves and relationship edits. */
@@ -1858,7 +2042,7 @@ interface BindOptions {
     readonly attribute?: string;
     /** Explicit field type, bypassing schema detection. */
     readonly type?: string;
-    /** Mark the binding as Lexical rich text; needed only when the initial render is empty. */
+    /** Mark the binding as Lexical rich text; needed for an element that can hold uploads or relationships, or when the initial render is empty. */
     readonly richtext?: boolean;
     /** Render the value as sanitised HTML rather than text. */
     readonly html?: boolean;
@@ -1920,6 +2104,12 @@ interface PreviewBindings {
      * The registry behind `id` is the endpoint's (docs/hybrid.md).
      */
     boundary: (id: string, options?: FragmentBoundaryOptions) => FragmentBoundaryAttributes | SuppressedBinding;
+    /**
+     * Field paths the page accounts for without binding them, and everything
+     * below them (`data-payload-covers`, ADR 0022), or nothing while
+     * unauthorized.
+     */
+    covers: (...paths: readonly string[]) => Readonly<Record<'data-payload-covers', string>> | SuppressedBinding;
 }
 /** Request-scoped `bind`, `bindByPath` and `owner`, all suppressed unless `authorization` is a real context. */
 declare function createPreviewBindings(options: PreviewBindingsOptions): PreviewBindings;
@@ -1949,7 +2139,8 @@ declare function previewBindingsFromLocals(locals: unknown, options?: {
  * Instead every flush that carried a change dispatches `payload-live-preview:update`
  * on each island root with the update in `detail`, whether or not a binding
  * outside the islands was written. `data-payload-island="patch"` opts back in.
- * @internal
+ * Server HTML reaches an Astro island only through Astro's own props handoff
+ * (ADR 0021). @internal
  */
 declare const ISLAND_EVENT = "payload-live-preview:update";
 interface IslandUpdateDetail {
@@ -1957,8 +2148,15 @@ interface IslandUpdateDetail {
     readonly revision: number;
     readonly receivedAt: number;
     readonly locale: string | undefined;
+    /**
+     * Call once the island has rendered this revision, for instance from an
+     * effect after its framework committed. Until every island handed the
+     * revision has called it, `inspect().revisions.display` says `unconfirmed`
+     * (ADR 0023). Repeated, late or superseded calls do nothing.
+     */
+    readonly displayed: () => void;
 }
 /** Whether `element` (or an ancestor) is an island that did not opt into patching. @internal */
 declare function isInsideIsland(element: Element): boolean;
 
-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 FragmentBoundaryAttributes, type FragmentBoundaryOptions, type FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InlineScriptConfig, type InspectionBindings, type InspectionFidelity, 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 PreviewBindingsOptions, type PreviewFocusMessage, type PreviewRequestLike, type PreviewRequestOptions, type PreviewTokenClaims, type PreviewTokenReplayChecks, type PreviewTokenReplayStore, type PreviewTokenTransport, type PreviewVerifierClaims, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RichTextRenderer, type RouteContext, type RouteOutcome, type RouteRefresh, type RouteStrategy, type RuntimeArtifact, 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, isPreviewRequest, isSafeUrl, issuePreviewToken, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, previewBindingsFromLocals, registerBlockRenderer, registerBuiltinRenderer, registerRouteRefresh, reportPreviewFocus, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, setSanitizerPolicy, setTrustedTypesPolicy, trustedHtml, wrapWithScriptTag };
+export { AUTHORIZED_PREVIEW_BRAND_KEY, type AnalyticsSnapshot, type AuthorizedPreviewContext, type AuthorizedPreviewDocument, type AuthorizedPreviewPayloadScope, 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 FragmentBoundaryAttributes, type FragmentBoundaryOptions, type FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InlineScriptConfig, type InspectionBindings, type InspectionFidelity, 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 PreviewBindingsOptions, type PreviewFocusMessage, type PreviewRequestLike, type PreviewRequestOptions, type PreviewTokenClaims, type PreviewTokenReplayChecks, type PreviewTokenReplayStore, type PreviewTokenTransport, type PreviewVerifierClaims, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RevisionDisplay, type RevisionDisplayState, type RevisionShortfall, type RichTextRenderer, type RouteContext, type RouteOutcome, type RoutePlanContext, type RouteRefresh, type RouteStrategy, type RuntimeArtifact, 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, isPreviewRequest, isSafeUrl, issuePreviewToken, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, previewBindingsFromLocals, registerBlockRenderer, registerBuiltinRenderer, registerRouteRefresh, reportPreviewFocus, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, setSanitizerPolicy, setTrustedTypesPolicy, trustedHtml, wrapWithScriptTag };