payload-live-preview 2.0.6 → 2.1.1

package/dist/client.d.ts

@@ -1,256 +1,3 @@
-/** 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 `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
@@ -330,13 +77,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";
@@ -364,6 +111,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. */
@@ -372,6 +123,48 @@ 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 `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
@@ -395,9 +188,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;
@@ -422,8 +215,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;
     /**
@@ -436,18 +234,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 {
@@ -517,6 +327,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;
@@ -653,6 +469,13 @@ interface RenderContext {
     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.
@@ -678,6 +501,271 @@ interface FieldRenderer {
     render(target: CachedElement, value: unknown, context: RenderContext): void;
 }
 
+/** 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 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[];
+    /**
+     * 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 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';
+    };
+}
+/**
+ * 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;
+    /** 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;
+    };
+}
+
 /**
  * Plugin compatibility claims. The range grammar is the subset a plugin
  * author writes (`*`, `1.2.3`, `^`, `~`, `>=`, `>`, `<`, `<=`, space-joined
@@ -790,6 +878,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. */
@@ -855,7 +950,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[];
@@ -914,6 +1012,9 @@ declare function createPreviewFocusReporter(resolveTarget: () => FocusReportTarg
  * 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>;
 /**
@@ -924,4 +1025,4 @@ type RouteRefresh = () => void | Promise<void>;
  */
 declare function registerRouteRefresh(refresh: RouteRefresh): () => void;
 
-export { type CachedElement, type ConnectionStatus, type CustomRendererKey, DIAGNOSTIC_CODES, type DefaultsProfile, type DiagnosticCode, EventEmitter, type EventHandler, type EventSourcePolicy, type FieldRenderer, type FieldTransform, type FieldType, type FocusReportTarget, type FragmentContext, type FragmentReport, type FragmentStrategy, type InspectionBindings, type InspectionFidelity, type InspectionFragments, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionRoute, type InspectionScheduler, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, type LivePreviewPlugin, type PayloadBlockSchema, type PayloadDocumentEventDetail, type PayloadFieldCondition, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PluginCompatibility, type PluginContext, type PluginDisposer, type PluginEvents, type PluginInspection, type PreviewFocusMessage, type RenderContext, type RendererKey, type RichTextRenderer, type RouteContext, type RouteOutcome, type RouteRefresh, type RouteStrategy, type SanitizerPolicyMode, type StrategyHandlers, type Unsubscribe, type UpdateSource, createPreviewFocusReporter, initLivePreview, registerRouteRefresh, reportPreviewFocus };
+export { type CachedElement, type ConnectionStatus, type CustomRendererKey, DIAGNOSTIC_CODES, type DefaultsProfile, type DiagnosticCode, EventEmitter, type EventHandler, type EventSourcePolicy, type FieldRenderer, type FieldTransform, type FieldType, type FocusReportTarget, type FragmentContext, type FragmentReport, type FragmentStrategy, type InspectionBindings, type InspectionFidelity, type InspectionFragments, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionRoute, type InspectionScheduler, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, type LivePreviewPlugin, type PayloadBlockSchema, type PayloadDocumentEventDetail, type PayloadFieldCondition, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PluginCompatibility, type PluginContext, type PluginDisposer, type PluginEvents, type PluginInspection, type PreviewFocusMessage, type RenderContext, type RendererKey, type RevisionDisplay, type RevisionDisplayState, type RevisionShortfall, type RichTextRenderer, type RouteContext, type RouteOutcome, type RoutePlanContext, type RouteRefresh, type RouteStrategy, type SanitizerPolicyMode, type StrategyHandlers, type Unsubscribe, type UpdateSource, createPreviewFocusReporter, initLivePreview, registerRouteRefresh, reportPreviewFocus };