payload-live-preview 2.2.0 → 2.2.1

package/dist/client.d.cts

@@ -91,7 +91,7 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly AuditGateThresholdExceeded: "LP0705";
     /** Owner markers exist, but some bindings are outside all of them. */
     readonly AuditUnownedBindings: "LP0706";
-    /** The preview response carries no bindings at all. */
+    /** The preview response carries no bindings and no fragment boundary. */
     readonly AuditNoBindings: "LP0707";
     /** The URL did not return an HTML page, so nothing else can be judged. */
     readonly AuditNotAPage: "LP0708";
@@ -165,6 +165,116 @@ type PayloadFieldType = 'text' | 'textarea' | 'richText' | 'email' | 'number' |
 /** `admin.condition` is a function in source and cannot cross `postMessage`; modelled, not consumed. */
 type PayloadFieldCondition = (data: unknown, siblingData: unknown) => boolean;
 
+/**
+ * `'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`. */
+type FieldType = PayloadFieldType | 'html' | 'url' | 'image' | 'structural-array';
+/** A namespaced project renderer key, so a typo of a built-in type can never become one. */
+type CustomRendererKey = `${string}:${string}`;
+/** What a renderer may be registered under and an element may ask for. */
+type RendererKey = FieldType | CustomRendererKey;
+/**
+ * A project rich-text renderer, shared by SSR and preview. Its output goes
+ * through the sanitizer; call the same `sanitizeHtml()` server-side for byte equality.
+ */
+type RichTextRenderer = (value: unknown, context: {
+    readonly fieldName: string;
+    readonly element: Element;
+    readonly locale: string | undefined;
+}) => string;
+/** One registered binding. Several may share a field name when it renders in several places. */
+interface CachedElement {
+    /** The bound DOM element. */
+    readonly element: Element;
+    /** Payload field path, e.g., `title` or `hero.subtitle`. */
+    readonly fieldName: string;
+    /** Resolved from attributes and tag heuristics; the schema may override it unless explicit. */
+    readonly fieldType: RendererKey;
+    /** Whether `data-payload-type` set the type, in which case the schema must not override it. */
+    readonly explicitFieldType?: boolean;
+    /** Fields this binding depends on (`data-payload-depends`); a change in any re-applies it under `skipUnchanged`. */
+    readonly dependsOn?: readonly string[];
+    /** Raw `data-payload-strategy` value. */
+    readonly strategy?: string;
+    /** How the runtime brings this binding up to date; `'unknown'` for an unrecognised strategy. Resolved by the cache. */
+    readonly strategyKind?: UpdateSource | 'unknown';
+    /** Nearest enclosing `data-payload-fragment` boundary. Resolved by the cache. */
+    readonly fragmentBoundary?: Element;
+    /** `data-payload-boundary`: an anchor that hides itself while its field is empty. */
+    readonly 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. */
+    readonly hrefField?: string;
+    /** Optional sibling-field path bound to the element's `src` attribute. */
+    readonly srcField?: string;
+    /** Optional sibling-field path bound to the element's `alt` attribute. */
+    readonly altField?: string;
+    /** Optional inline template for array/blocks rendering. */
+    readonly arrayTemplate?: string;
+    /** Optional separator for primitive-array stringification. */
+    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 {
+    /** 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;
+}
+
 /**
  * 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
@@ -391,116 +501,6 @@ 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`. */
-type FieldType = PayloadFieldType | 'html' | 'url' | 'image' | 'structural-array';
-/** A namespaced project renderer key, so a typo of a built-in type can never become one. */
-type CustomRendererKey = `${string}:${string}`;
-/** What a renderer may be registered under and an element may ask for. */
-type RendererKey = FieldType | CustomRendererKey;
-/**
- * A project rich-text renderer, shared by SSR and preview. Its output goes
- * through the sanitizer; call the same `sanitizeHtml()` server-side for byte equality.
- */
-type RichTextRenderer = (value: unknown, context: {
-    readonly fieldName: string;
-    readonly element: Element;
-    readonly locale: string | undefined;
-}) => string;
-/** One registered binding. Several may share a field name when it renders in several places. */
-interface CachedElement {
-    /** The bound DOM element. */
-    readonly element: Element;
-    /** Payload field path, e.g., `title` or `hero.subtitle`. */
-    readonly fieldName: string;
-    /** Resolved from attributes and tag heuristics; the schema may override it unless explicit. */
-    readonly fieldType: RendererKey;
-    /** Whether `data-payload-type` set the type, in which case the schema must not override it. */
-    readonly explicitFieldType?: boolean;
-    /** Fields this binding depends on (`data-payload-depends`); a change in any re-applies it under `skipUnchanged`. */
-    readonly dependsOn?: readonly string[];
-    /** Raw `data-payload-strategy` value. */
-    readonly strategy?: string;
-    /** How the runtime brings this binding up to date; `'unknown'` for an unrecognised strategy. Resolved by the cache. */
-    readonly strategyKind?: UpdateSource | 'unknown';
-    /** Nearest enclosing `data-payload-fragment` boundary. Resolved by the cache. */
-    readonly fragmentBoundary?: Element;
-    /** `data-payload-boundary`: an anchor that hides itself while its field is empty. */
-    readonly 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. */
-    readonly hrefField?: string;
-    /** Optional sibling-field path bound to the element's `src` attribute. */
-    readonly srcField?: string;
-    /** Optional sibling-field path bound to the element's `alt` attribute. */
-    readonly altField?: string;
-    /** Optional inline template for array/blocks rendering. */
-    readonly arrayTemplate?: string;
-    /** Optional separator for primitive-array stringification. */
-    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 {
-    /** 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;
-}
-
 /** Connection status and the heartbeat that decides a disconnect. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected';
 
@@ -720,7 +720,7 @@ interface InspectionFidelity {
     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. */
+    /** How many times one of those was handed to the fragment or route strategy; a later edit hands it again. */
     readonly escalated: number;
     /** The field names behind `unfaithful`, sorted. Cumulative. */
     readonly fields: readonly string[];

package/dist/client.d.ts

@@ -91,7 +91,7 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly AuditGateThresholdExceeded: "LP0705";
     /** Owner markers exist, but some bindings are outside all of them. */
     readonly AuditUnownedBindings: "LP0706";
-    /** The preview response carries no bindings at all. */
+    /** The preview response carries no bindings and no fragment boundary. */
     readonly AuditNoBindings: "LP0707";
     /** The URL did not return an HTML page, so nothing else can be judged. */
     readonly AuditNotAPage: "LP0708";
@@ -165,6 +165,116 @@ type PayloadFieldType = 'text' | 'textarea' | 'richText' | 'email' | 'number' |
 /** `admin.condition` is a function in source and cannot cross `postMessage`; modelled, not consumed. */
 type PayloadFieldCondition = (data: unknown, siblingData: unknown) => boolean;
 
+/**
+ * `'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`. */
+type FieldType = PayloadFieldType | 'html' | 'url' | 'image' | 'structural-array';
+/** A namespaced project renderer key, so a typo of a built-in type can never become one. */
+type CustomRendererKey = `${string}:${string}`;
+/** What a renderer may be registered under and an element may ask for. */
+type RendererKey = FieldType | CustomRendererKey;
+/**
+ * A project rich-text renderer, shared by SSR and preview. Its output goes
+ * through the sanitizer; call the same `sanitizeHtml()` server-side for byte equality.
+ */
+type RichTextRenderer = (value: unknown, context: {
+    readonly fieldName: string;
+    readonly element: Element;
+    readonly locale: string | undefined;
+}) => string;
+/** One registered binding. Several may share a field name when it renders in several places. */
+interface CachedElement {
+    /** The bound DOM element. */
+    readonly element: Element;
+    /** Payload field path, e.g., `title` or `hero.subtitle`. */
+    readonly fieldName: string;
+    /** Resolved from attributes and tag heuristics; the schema may override it unless explicit. */
+    readonly fieldType: RendererKey;
+    /** Whether `data-payload-type` set the type, in which case the schema must not override it. */
+    readonly explicitFieldType?: boolean;
+    /** Fields this binding depends on (`data-payload-depends`); a change in any re-applies it under `skipUnchanged`. */
+    readonly dependsOn?: readonly string[];
+    /** Raw `data-payload-strategy` value. */
+    readonly strategy?: string;
+    /** How the runtime brings this binding up to date; `'unknown'` for an unrecognised strategy. Resolved by the cache. */
+    readonly strategyKind?: UpdateSource | 'unknown';
+    /** Nearest enclosing `data-payload-fragment` boundary. Resolved by the cache. */
+    readonly fragmentBoundary?: Element;
+    /** `data-payload-boundary`: an anchor that hides itself while its field is empty. */
+    readonly 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. */
+    readonly hrefField?: string;
+    /** Optional sibling-field path bound to the element's `src` attribute. */
+    readonly srcField?: string;
+    /** Optional sibling-field path bound to the element's `alt` attribute. */
+    readonly altField?: string;
+    /** Optional inline template for array/blocks rendering. */
+    readonly arrayTemplate?: string;
+    /** Optional separator for primitive-array stringification. */
+    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 {
+    /** 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;
+}
+
 /**
  * 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
@@ -391,116 +501,6 @@ 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`. */
-type FieldType = PayloadFieldType | 'html' | 'url' | 'image' | 'structural-array';
-/** A namespaced project renderer key, so a typo of a built-in type can never become one. */
-type CustomRendererKey = `${string}:${string}`;
-/** What a renderer may be registered under and an element may ask for. */
-type RendererKey = FieldType | CustomRendererKey;
-/**
- * A project rich-text renderer, shared by SSR and preview. Its output goes
- * through the sanitizer; call the same `sanitizeHtml()` server-side for byte equality.
- */
-type RichTextRenderer = (value: unknown, context: {
-    readonly fieldName: string;
-    readonly element: Element;
-    readonly locale: string | undefined;
-}) => string;
-/** One registered binding. Several may share a field name when it renders in several places. */
-interface CachedElement {
-    /** The bound DOM element. */
-    readonly element: Element;
-    /** Payload field path, e.g., `title` or `hero.subtitle`. */
-    readonly fieldName: string;
-    /** Resolved from attributes and tag heuristics; the schema may override it unless explicit. */
-    readonly fieldType: RendererKey;
-    /** Whether `data-payload-type` set the type, in which case the schema must not override it. */
-    readonly explicitFieldType?: boolean;
-    /** Fields this binding depends on (`data-payload-depends`); a change in any re-applies it under `skipUnchanged`. */
-    readonly dependsOn?: readonly string[];
-    /** Raw `data-payload-strategy` value. */
-    readonly strategy?: string;
-    /** How the runtime brings this binding up to date; `'unknown'` for an unrecognised strategy. Resolved by the cache. */
-    readonly strategyKind?: UpdateSource | 'unknown';
-    /** Nearest enclosing `data-payload-fragment` boundary. Resolved by the cache. */
-    readonly fragmentBoundary?: Element;
-    /** `data-payload-boundary`: an anchor that hides itself while its field is empty. */
-    readonly 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. */
-    readonly hrefField?: string;
-    /** Optional sibling-field path bound to the element's `src` attribute. */
-    readonly srcField?: string;
-    /** Optional sibling-field path bound to the element's `alt` attribute. */
-    readonly altField?: string;
-    /** Optional inline template for array/blocks rendering. */
-    readonly arrayTemplate?: string;
-    /** Optional separator for primitive-array stringification. */
-    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 {
-    /** 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;
-}
-
 /** Connection status and the heartbeat that decides a disconnect. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected';
 
@@ -720,7 +720,7 @@ interface InspectionFidelity {
     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. */
+    /** How many times one of those was handed to the fragment or route strategy; a later edit hands it again. */
     readonly escalated: number;
     /** The field names behind `unfaithful`, sorted. Cumulative. */
     readonly fields: readonly string[];