payload-live-preview 2.1.2 → 2.2.1

package/dist/index.d.ts

@@ -91,11 +91,11 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly AuditFrameOptionsBlocks: "LP0703";
     /** Binding attributes are served to anonymous visitors. */
     readonly AuditBindingsExposed: "LP0704";
-    /** More bindings than the default visibility gate will write eagerly. */
+    /** More bindings than the visibility gate will write eagerly. */
     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";
@@ -113,7 +113,7 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly FragmentStrategyUnavailable: "LP0806";
     /** A revision changed a field with no binding; `onUnfaithfulPatch` refreshed the route. */
     readonly UnboundChangeRefresh: "LP0807";
-    /** `onUnfaithfulPatch: 'escalate'` found no route or fragment strategy to hand an unfaithful patch to; the page keeps it. */
+    /** `onUnfaithfulPatch: 'escalate'` found no route or fragment strategy, or no boundary, 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";
@@ -190,6 +190,177 @@ 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';
+interface SanitizeOptions {
+    /** Overrides the module default set by `setSanitizerPolicy()`. */
+    readonly policy?: SanitizerPolicyMode;
+    /** `data-*` attributes (full names) that pass under `'strict'`; `data-payload-*` never does. */
+    readonly allowedDataAttributes?: readonly string[];
+    /**
+     * Keep `input`, `button`, `textarea`, `select`, `option` and `label` — only
+     * for markup the page author wrote, never for CMS content. `form`,
+     * handlers, `style` and unsafe URLs stay dropped.
+     */
+    readonly allowFormControls?: boolean;
+    /** Extra tags to allow. Lower-case, untrimmed. */
+    readonly additionalAllowedTags?: readonly string[];
+    /**
+     * Extra per-tag attributes, lower-case. Cannot re-admit handlers, `style`,
+     * or — under `'strict'` — `id`, `name` and `data-payload-*`.
+     */
+    readonly additionalAllowedAttributes?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * The input is a page-author item template, so `'strict'` keeps the
+     * applier's reconciliation attributes (`TEMPLATE_ATTRIBUTES`) and nothing
+     * else — every other `data-payload-*` is still stripped, so a template can
+     * never add a binding.
+     */
+    readonly templateMode?: boolean;
+    /**
+     * 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
+ * runtime carries its own `sanitizerPolicy` and never writes here (ADR 0002).
+ */
+declare function setSanitizerPolicy(mode: SanitizerPolicyMode): void;
+/** The `Document` surface the sanitizer needs; jsdom, linkedom and happy-dom all provide it. */
+interface SanitizerDocument {
+    createElement: (tagName: string) => {
+        innerHTML: string;
+        readonly content: ParentNode;
+    };
+}
+/**
+ * Supply a `Document` for SSR, e.g. linkedom's `parseHTML(...).document`;
+ * `null` clears it, 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. The
+ * result is a fixed point: sanitising it again changes nothing.
+ *
+ * @throws {SanitizerEnvironmentError} when no DOM is available.
+ */
+declare function sanitizeHtml(html: string, options?: SanitizeOptions): string;
+
+/** 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
@@ -416,177 +587,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';
-interface SanitizeOptions {
-    /** Overrides the module default set by `setSanitizerPolicy()`. */
-    readonly policy?: SanitizerPolicyMode;
-    /** `data-*` attributes (full names) that pass under `'strict'`; `data-payload-*` never does. */
-    readonly allowedDataAttributes?: readonly string[];
-    /**
-     * Keep `input`, `button`, `textarea`, `select`, `option` and `label` — only
-     * for markup the page author wrote, never for CMS content. `form`,
-     * handlers, `style` and unsafe URLs stay dropped.
-     */
-    readonly allowFormControls?: boolean;
-    /** Extra tags to allow. Lower-case, untrimmed. */
-    readonly additionalAllowedTags?: readonly string[];
-    /**
-     * Extra per-tag attributes, lower-case. Cannot re-admit handlers, `style`,
-     * or — under `'strict'` — `id`, `name` and `data-payload-*`.
-     */
-    readonly additionalAllowedAttributes?: Readonly<Record<string, readonly string[]>>;
-    /**
-     * The input is a page-author item template, so `'strict'` keeps the
-     * applier's reconciliation attributes (`TEMPLATE_ATTRIBUTES`) and nothing
-     * else — every other `data-payload-*` is still stripped, so a template can
-     * never add a binding.
-     */
-    readonly templateMode?: boolean;
-    /**
-     * 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
- * runtime carries its own `sanitizerPolicy` and never writes here (ADR 0002).
- */
-declare function setSanitizerPolicy(mode: SanitizerPolicyMode): void;
-/** The `Document` surface the sanitizer needs; jsdom, linkedom and happy-dom all provide it. */
-interface SanitizerDocument {
-    createElement: (tagName: string) => {
-        innerHTML: string;
-        readonly content: ParentNode;
-    };
-}
-/**
- * Supply a `Document` for SSR, e.g. linkedom's `parseHTML(...).document`;
- * `null` clears it, 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. The
- * result is a fixed point: sanitising it again changes nothing.
- *
- * @throws {SanitizerEnvironmentError} when no DOM is available.
- */
-declare function sanitizeHtml(html: string, options?: SanitizeOptions): string;
-
-/** 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;
-}
-
 /**
  * Protocol negotiation. A capability is granted either by the version a peer
  * announces or by observation, since the stock Payload admin announces none:
@@ -874,7 +874,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[];
@@ -1890,7 +1890,8 @@ declare function isDevMode(): boolean;
 /**
  * Which admin origins the runtime trusts: explicit ones always, the
  * `document.referrer` origin only when none is configured, any localhost port
- * in development. See docs/security.md §1.
+ * in development. See docs/security.md §1. The handshake goes to the trusted
+ * origins, and to guessed localhost ports only while the browser names no parent.
  */
 interface OriginDetectorOptions {
     /** Explicit origins to trust. Always allowed. */
@@ -1915,7 +1916,12 @@ declare class OriginDetector {
     /** Release the lock (heartbeat timeout) so another allow-listed origin may reconnect. Returns the previous lock. */
     unlockOrigin(): string | undefined;
     get lockedOrigin(): string | undefined;
-    /** Every origin the `ready` handshake is broadcast to; the localhost pattern expands to the common dev ports. */
+    /**
+     * Every origin the `ready` handshake is broadcast to. The localhost pattern
+     * expands to the common dev ports, a guess that costs a console error per
+     * wrong port, so a parent the browser names replaces it: that origin when the
+     * pattern trusts it, none when it is not on localhost.
+     */
     enumerate(): string[];
     /** Whether `document.referrer` contributed an origin (absent under `Referrer-Policy: no-referrer`). */
     get referrerWasAvailable(): boolean;