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

package/dist/client.d.cts

@@ -80,6 +80,23 @@ interface InspectionBindings {
     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 {
@@ -119,14 +136,49 @@ interface LivePreviewInspection {
     readonly plugins: readonly PluginInspection[];
     /** Server-rendered fragment boundaries: whether a handler exists and what happened to renders. */
     readonly fragments: InspectionFragments;
-    /** Route refreshes: whether a strategy exists, how many ran, failed, or were stopped by the loop guard. */
+    /** 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 neither `fragments.handler` nor
+ * `route.handler` is there to escalate to.
+ */
+interface InspectionFidelity {
+    /** `onUnfaithfulPatch` as resolved from both of its names. */
+    readonly mode: 'ignore' | 'warn' | 'escalate';
+    /** 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;
 }
@@ -203,7 +255,9 @@ type PayloadFieldCondition = (data: unknown, siblingData: unknown) => boolean;
  *
  * Browser-side reporting sites write the literal (`code: 'LP0603'`) rather than
  * reading it from this record: the frozen table would then ship in the inline
- * runtime for the sake of six characters. Server-side tools may import it.
+ * runtime for the sake of six characters — it did, 1 287 B in every page, for
+ * the one read Z6 left in the strategy runner, and `diagnostic-codes.test.ts`
+ * now holds the artifact free of it. Server-side tools may import it.
  */
 /**
  * Every diagnostic code the runtime can report, by name.
@@ -221,6 +275,8 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly ReferrerOnlyTrust: "LP0102";
     /** A plugin declares a runtime range this runtime does not satisfy; it was refused. */
     readonly PluginIncompatible: "LP0103";
+    /** The page carries the lean runtime and needs a feature that profile leaves out. */
+    readonly ProfileFeatureOmitted: "LP0104";
     /** An update named a field with no binding anchor on the page. */
     readonly OrphanField: "LP0201";
     /** Owner scoping is on and the update names no document it could belong to. */
@@ -241,10 +297,24 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly StructuralUnstableKeys: "LP0406";
     /** A binding asks for a delivery strategy this release does not have; it is left unchanged. */
     readonly UnsupportedStrategy: "LP0407";
+    /** `data-payload-format` names a format the vocabulary does not contain; the default formatting was used instead. */
+    readonly UnknownValueFormat: "LP0408";
+    /** The strict sanitizer removed an attribute the 1.x `'compat'` policy kept. */
+    readonly SanitizerDroppedAttribute: "LP0409";
+    /** A Lexical block has no renderer; the markup the server rendered for it is kept instead. */
+    readonly UnrenderedBlockKept: "LP0410";
+    /** A patch cannot reach what the server would have drawn; `onUnfaithfulPatch` decided what happens next. */
+    readonly UnfaithfulPatch: "LP0411";
+    /** The first write to a date, number or checkbox binding replaced a different reading of the same value. */
+    readonly ServerFormatReplaced: "LP0412";
+    /** A Lexical block has no renderer, and the write could not keep the markup the server rendered for it; it is gone. */
+    readonly UnrenderedBlockLost: "LP0413";
     /** A message was rejected before it reached the update pipeline. */
     readonly MessageRejected: "LP0501";
     /** A preview token was rejected. */
     readonly TokenRejected: "LP0502";
+    /** A trusted origin sent a message this protocol version does not recognise. */
+    readonly ProtocolShapeUnknown: "LP0503";
     /** A consumer event handler threw. */
     readonly HandlerThrew: "LP0601";
     /** A consumer transform threw; the original value was kept. */
@@ -255,11 +325,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. */
+    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. */
+    /** `X-Frame-Options` forbids framing, which no CSP can undo; `SAMEORIGIN` forbids it from another origin only. */
     readonly AuditFrameOptionsBlocks: "LP0703";
     /** Binding attributes are served to anonymous visitors. */
     readonly AuditBindingsExposed: "LP0704";
@@ -279,10 +351,12 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly FragmentUnauthorized: "LP0803";
     /** A fragment response arrived for a revision that was already superseded and was discarded. */
     readonly FragmentSuperseded: "LP0804";
-    /** A route refresh was requested again for the same revision; the loop guard stopped it. */
+    /** A route refresh was refused: the loop guard, or the strategy's minimum interval. */
     readonly RouteRefreshLoop: "LP0805";
     /** A boundary asks for the fragment strategy but no fragment handler is configured; it is patched. */
     readonly FragmentStrategyUnavailable: "LP0806";
+    /** A revision changed a field with no binding; `onUnfaithfulPatch` refreshed the route. */
+    readonly UnboundChangeRefresh: "LP0807";
     /** 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. */
@@ -345,7 +419,21 @@ interface RouteContext {
     readonly signal: AbortSignal;
     readonly isCurrent: () => boolean;
     readonly log: (code: DiagnosticCode, detail: string) => void;
+    /**
+     * Ask to be run again in `delayMs`, once. A strategy that refuses a refresh
+     * because it is rate-limiting itself uses this: the window is a rate limit
+     * and not a filter, so what falls inside it still has to reach the preview.
+     * The runtime runs at most one such request, and only while the revision that
+     * asked is still the current one.
+     */
+    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.
+ */
+type RouteOutcome = 'refreshed' | 'failed' | 'refused' | 'superseded';
 /**
  * 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
@@ -353,7 +441,7 @@ interface RouteContext {
  */
 interface RouteStrategy {
     readonly plan: (root: ParentNode, changedFields: ReadonlySet<string>) => boolean;
-    readonly refresh: (context: RouteContext) => Promise<'refreshed' | 'failed' | 'superseded'>;
+    readonly refresh: (context: RouteContext) => Promise<RouteOutcome>;
 }
 interface StrategyHandlers {
     readonly fragment?: FragmentStrategy;
@@ -426,7 +514,15 @@ interface LivePreviewEventMap {
     readonly documentSave: {
         readonly timestamp: number;
     };
-    /** A data update carried `externallyUpdatedRelationship`: a related document changed in an admin drawer, so the update re-renders unconditionally. */
+    /**
+     * A save in another document reached the page through
+     * `externallyUpdatedRelationship` — an admin-drawer edit. Fires once per
+     * such save, not once per message: the panel repeats its last document
+     * event in every later message, including its own saves of the previewed
+     * document, and neither of those is news. That update re-renders every
+     * bound field even under `skipUnchanged`, because a drawer edit changes
+     * populated values while the form values stay put.
+     */
     readonly relationshipUpdate: {
         readonly detail: PayloadDocumentEventDetail;
         readonly timestamp: number;
@@ -472,6 +568,12 @@ declare class EventEmitter<TMap extends object = LivePreviewEventMap> {
     eventNames(): (keyof TMap)[];
 }
 
+/**
+ * `'strict'` (default) strips `id`, `name` and `data-payload-*` and passes
+ * other `data-*` only via `allowedDataAttributes`; `'compat'` keeps them.
+ */
+type SanitizerPolicyMode = 'compat' | 'strict';
+
 /** Types shared by the runtime primitives. */
 
 /** Payload's field set plus the DOM-binding categories `html`, `url`, `image` and `structural-array`. */
@@ -508,7 +610,7 @@ interface CachedElement {
     /** Nearest enclosing `data-payload-fragment` boundary. Resolved by the cache. */
     readonly fragmentBoundary?: Element;
     /** `data-payload-boundary`: an anchor that hides itself while its field is empty. */
-    readonly boundary?: boolean;
+    readonly hidesWhenEmpty?: boolean;
     /** Write the value into this attribute instead of the content; policed writes. */
     readonly targetAttribute?: string;
     /** Optional sibling-field path bound to the element's `href` attribute. */
@@ -523,8 +625,16 @@ interface CachedElement {
     readonly arraySeparator?: string;
     /** Optional locale code locked onto this element (overrides the global locale). */
     readonly locale?: string;
+    /** Raw `data-payload-format`; the date and number renderers read the vocabulary. */
+    readonly format?: string;
     /** The document this binding belongs to, from the nearest `data-payload-owner`. */
     readonly owner?: string;
+    /**
+     * The value an auto-binding matched on (`data-payload-guessed`), for a
+     * binding the runtime found by value rather than one the template declared.
+     * Absent for a declared binding.
+     */
+    readonly guessed?: string;
 }
 /** What a renderer is given; `allFields` lets it resolve a sibling field. */
 interface RenderContext {
@@ -536,6 +646,20 @@ interface RenderContext {
     readonly schema: PayloadFieldSchema | undefined;
     /** The project's rich-text renderer, when the client was configured with one. */
     readonly renderRichText?: RichTextRenderer;
+    /**
+     * 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
@@ -612,6 +736,10 @@ interface LivePreviewPlugin {
  * one side — the adapter's request decision or the browser runtime — and a
  * test asserts the profile assigns every readiness row that has an option, so
  * a row added later cannot be forgotten. See ADR 0007.
+ *
+ * It lives in the leaf `types` domain, like `merge-depth.ts`, because the
+ * inline generator resolves the profile too, and the generator is server-side
+ * code that may not reach the browser runtime in `core`.
  */
 /** `'v2'` is the 2.0 default; `'v1'` is the 1.x table. */
 type DefaultsProfile = 'v1' | 'v2';
@@ -648,6 +776,13 @@ interface LivePreviewClientConfig {
     readonly skipUnchanged?: boolean;
     /** Scroll the preview to the field being edited when its value changes. Default `false`. */
     readonly revealEditedField?: boolean;
+    /**
+     * Find bindings by value on the connection's first message: a scalar whose
+     * value is the whole content of exactly one element is bound to it as if
+     * `data-payload-field` stood there; every guess is stamped `data-payload-guessed`
+     * and listed in `inspect().bindings.guessed`. Default `'off'`.
+     */
+    readonly autoBind?: 'off' | 'unique';
     /** 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. */
@@ -672,7 +807,11 @@ interface LivePreviewClientConfig {
     readonly disableLocalhostMatching?: boolean;
     /** Which windows may post updates. Default `'parent-or-opener'`; `defaults: 'v1'` sets `'any'`. */
     readonly eventSourcePolicy?: EventSourcePolicy;
-    /** Sanitizer policy for rich text and HTML writes. Default `'strict'`; `defaults: 'v1'` sets `'compat'`. */
+    /**
+     * Sanitizer policy for this client's rich text and HTML writes. Default
+     * `'strict'`; `defaults: 'v1'` sets `'compat'`. Per instance: it leaves the
+     * process default that `setSanitizerPolicy()` sets for direct `sanitizeHtml()` calls alone.
+     */
     readonly sanitizerPolicy?: 'compat' | 'strict';
     /** `'v2'` (default) is the 2.0 table; `'v1'` restores every 1.x row at once. Explicit options win. */
     readonly defaults?: DefaultsProfile;
@@ -735,6 +874,7 @@ declare function initLivePreview(config?: LivePreviewClientConfig): LivePreviewC
 interface FocusReportTarget {
     postMessage: (message: unknown, targetOrigin: string) => void;
 }
+/** @internal */
 interface PreviewFocusMessage {
     readonly type: 'payload-live-preview-focus';
     readonly field: string;
@@ -744,4 +884,37 @@ declare function reportPreviewFocus(target: FocusReportTarget, field: string, ta
 /** A reporter bound to a preview window and origin; `resolveTarget` runs per report, so a re-created iframe is addressed freshly. */
 declare function createPreviewFocusReporter(resolveTarget: () => FocusReportTarget | null | undefined, targetOrigin: string): (field: string) => void;
 
-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 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 RouteStrategy, type StrategyHandlers, type Unsubscribe, type UpdateSource, createPreviewFocusReporter, initLivePreview, reportPreviewFocus };
+/**
+ * The seam between a host framework's own router and the route strategy.
+ *
+ * The route strategy answers a revision by fetching the route and morphing it
+ * into the living page. On a page whose DOM belongs to a reconciler that is
+ * working against the framework, and it was seen to break once: `removeChild`
+ * on `null` inside React's commit phase, over markup this package had patched.
+ * A host that re-renders the route itself does the same job without the morph
+ * and without the second HTML request, so it is given the chance to.
+ *
+ * Why a named slot on `window` and not a reference: the runtime is an inline
+ * script that builds its strategy before any application code has hydrated, so
+ * there is nothing to hand a component; `window.__livePreview`, the only other
+ * public surface, is created later and not at all outside a preview; and the
+ * two richer extension points — plugins and events — are reachable only through
+ * the programmatic client, which a page using an adapter does not have. One
+ * slot, written by whoever mounts and read at the moment of a refresh, is the
+ * smallest thing that survives both orders of arrival.
+ */
+/**
+ * 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.
+ */
+type RouteRefresh = () => void | Promise<void>;
+/**
+ * Lend the runtime the host's route refresh; the return value undoes it, for a
+ * component's cleanup. A later registration wins, and undoing one that has
+ * already been replaced does nothing — two components on one page would
+ * otherwise take the slot from each other on unmount.
+ */
+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 };