payload-live-preview 1.0.0

package/dist/bind-BSgxoQhN.d.ts

@@ -0,0 +1,1137 @@
+/**
+ * Single source of truth for the library version.
+ *
+ * Both the npm package surface (`src/index.ts`, `src/core-entry.ts`)
+ * and the inline runtime (`src/core/runtime.ts`, which gets bundled by
+ * esbuild and embedded into `runtime.generated.ts`) read the version
+ * from here so they never drift.
+ *
+ * Imports `package.json` directly — tsc, tsup, and esbuild all inline
+ * the value at build time when `resolveJsonModule` is enabled.
+ *
+ * @module @/version
+ */
+declare const VERSION: string;
+
+/**
+ * Payload Live Preview message protocol.
+ *
+ * Mirrors the messages emitted by Payload CMS through
+ * `window.postMessage`, verified against the shipped admin code
+ * (`@payloadcms/ui` → `elements/LivePreview/Window`):
+ *
+ *   - Payload **3.x** sends `{ type, collectionSlug, globalSlug, data,
+ *     locale, externallyUpdatedRelationship }` on every form edit —
+ *     `data` holds **raw form values** (relationships as bare IDs) and
+ *     there is **no** `fieldSchemaJSON`.
+ *   - Payload **2.x** additionally sent `fieldSchemaJSON` with the
+ *     first update (client-side merge era).
+ *   - `previewToken` and `protocolVersion` are extensions of THIS
+ *     library for custom admin senders; stock Payload never sends
+ *     them and ignores them in our `ready` handshake.
+ *
+ * @module @/types/payload-protocol
+ */
+/**
+ * A `payload-live-preview` data update.
+ *
+ * `data` is the serialized document state. `fieldSchemaJSON`, when
+ * present (Payload 2.x or custom senders), allows the schema-driven
+ * engine to resolve field types without any DOM annotations.
+ */
+interface PayloadLivePreviewMessage {
+    readonly type: 'payload-live-preview';
+    readonly data?: Record<string, unknown>;
+    readonly fieldSchemaJSON?: readonly PayloadFieldSchema[];
+    readonly globalSlug?: string;
+    readonly collectionSlug?: string;
+    readonly locale?: string;
+    readonly ready?: boolean;
+    /**
+     * Payload 3.x: most recent relationship-document event (create/update
+     * in a drawer), or `null`. The official client ignores it too — it is
+     * modeled here for completeness and consumer event access.
+     */
+    readonly externallyUpdatedRelationship?: PayloadDocumentEventDetail | null;
+    /**
+     * Optional preview JWT. ⚠️ Library extension — stock Payload never
+     * sends one. When `RuntimeOptions.validateToken` is set, the runtime
+     * requires every data update to carry a token that passes the
+     * validator; messages without a valid token are dropped.
+     */
+    readonly previewToken?: string;
+    /**
+     * Highest protocol version the sender supports. ⚠️ Library extension
+     * for custom senders — stock Payload sends no version. When absent,
+     * the receiver assumes v1.
+     */
+    readonly protocolVersion?: number;
+}
+/**
+ * Payload's `DocumentEvent` shape (admin `providers/DocumentEvents`).
+ */
+interface PayloadDocumentEventDetail {
+    readonly entitySlug: string;
+    readonly operation?: 'create' | 'update';
+    readonly id?: string | number;
+    readonly updatedAt?: string;
+    readonly [extra: string]: unknown;
+}
+/**
+ * Parsed, validated message payload exposed to consumers via events.
+ */
+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 description we rely on.
+ *
+ * Payload emits the entire field configuration tree but we only need
+ * the discriminator `type` and the nesting via `fields`/`blocks`.
+ * Extra properties are preserved 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;
+}
+/**
+ * The Payload core field types this library recognises (20 as of
+ * Payload 3.x). `tabs` is treated as a structural container; `group`
+ * flattens nested fields.
+ */
+type PayloadFieldType = 'text' | 'textarea' | 'richText' | 'email' | 'number' | 'checkbox' | 'date' | 'select' | 'radio' | 'array' | 'blocks' | 'group' | 'tabs' | 'row' | 'collapsible' | 'relationship' | 'upload' | 'point' | 'json' | 'code' | 'ui';
+/**
+ * Payload's `admin.condition` is a function in source, but it cannot
+ * be transferred over postMessage. The schema arrives with this slot
+ * either absent or, in future Payload versions, replaced by a
+ * serialized expression. We model the slot but do not consume it yet.
+ */
+type PayloadFieldCondition = (data: unknown, siblingData: unknown) => boolean;
+
+/**
+ * Public event payload shapes for the live preview lifecycle.
+ *
+ * The map keys form the union of valid event names. Adding a new event
+ * is a two-line change: add the entry here and dispatch from the
+ * relevant module. Consumers get autocompletion and exhaustive checks
+ * for free because the `EventEmitter` is generic over this map.
+ *
+ * @module @events/types
+ */
+
+interface LivePreviewEventMap {
+    /** Fired once when a client instance finishes its synchronous init. */
+    readonly init: {
+        readonly timestamp: number;
+    };
+    /** Fired the first time a valid update message is received from a trusted origin. */
+    readonly connect: {
+        readonly origin: string;
+        readonly timestamp: number;
+    };
+    /** Fired when the heartbeat times out or the iframe is unloaded. */
+    readonly disconnect: {
+        readonly reason: 'timeout' | 'destroy' | 'unload';
+        readonly timestamp: number;
+    };
+    /**
+     * Fired before the DOM is mutated for an incoming update.
+     *
+     * Handlers may call `cancel()` synchronously to skip the update —
+     * useful for read-only previews or A/B testing.
+     */
+    readonly beforeUpdate: {
+        readonly data: PayloadLivePreviewData;
+        readonly cancel: () => void;
+    };
+    /** Fired after all DOM mutations for an incoming update have completed. */
+    readonly afterUpdate: {
+        readonly data: PayloadLivePreviewData;
+        readonly updatedCount: number;
+        readonly durationMs: number;
+    };
+    /** Fired for each individual element write performed during an update. */
+    readonly elementUpdate: {
+        readonly element: Element;
+        readonly fieldName: string;
+        readonly previousValue: unknown;
+        readonly nextValue: unknown;
+    };
+    /** Fired whenever the element cache is rebuilt (initial scan or MutationObserver-triggered). */
+    readonly cacheRefresh: {
+        readonly elementCount: number;
+        readonly fieldCount: number;
+        readonly durationMs: number;
+    };
+    /** Fired when a `payload-document-event` message arrives (document save). */
+    readonly documentSave: {
+        readonly timestamp: number;
+    };
+    /**
+     * Fired on errors that the runtime caught but cannot fully recover from.
+     *
+     * The `context` string identifies where the error originated.
+     */
+    readonly error: {
+        readonly error: Error;
+        readonly context: string;
+    };
+    /** Fired during destroy after observers and listeners are removed. */
+    readonly destroy: {
+        readonly timestamp: number;
+    };
+}
+/**
+ * Handler signature: receives the payload and may return a Promise.
+ *
+ * Promise-returning handlers are awaited in registration order — this
+ * is important for `beforeUpdate.cancel()` semantics.
+ */
+type EventHandler<TPayload> = (payload: TPayload) => void | Promise<void>;
+/** Subscription removal function returned by `on()`/`once()`. */
+type Unsubscribe = () => void;
+
+/**
+ * Per-instance, type-safe event emitter.
+ *
+ * Replaces the legacy module-level singleton. Each `LivePreviewClient`
+ * instantiates its own emitter so that calling `destroy()` on one
+ * instance cannot clobber listeners attached to another.
+ *
+ * Design notes:
+ *
+ *   - Generic over an event map type. The default `LivePreviewEventMap`
+ *     captures every event this library emits, but the implementation
+ *     is reusable for any map.
+ *   - Handlers may be `async`. They are awaited sequentially in
+ *     registration order. This is intentional: `beforeUpdate.cancel()`
+ *     and similar synchronization rely on stable ordering.
+ *   - Errors thrown by one handler are logged via `console.error` and
+ *     do not prevent later handlers from running.
+ *   - `once()` semantics: registered into a separate map; the entire
+ *     set for an event is cleared after dispatch, even if individual
+ *     handlers throw.
+ *
+ * @module @events/emitter
+ */
+
+declare class EventEmitter<TMap extends object = LivePreviewEventMap> {
+    #private;
+    /**
+     * Subscribe `handler` to `event`. Returns an unsubscribe function;
+     * call it to remove the handler. The handler is invoked for every
+     * subsequent emit until unsubscribed.
+     */
+    on<E extends keyof TMap>(event: E, handler: EventHandler<TMap[E]>): Unsubscribe;
+    /**
+     * Subscribe `handler` for a single emit. After the first dispatch,
+     * the handler is removed automatically.
+     */
+    once<E extends keyof TMap>(event: E, handler: EventHandler<TMap[E]>): Unsubscribe;
+    /**
+     * Remove `handler` from `event`. Works for both `on`- and
+     * `once`-registered handlers. No-op when the handler isn't registered.
+     */
+    off<E extends keyof TMap>(event: E, handler: EventHandler<TMap[E]>): void;
+    /**
+     * Dispatch `payload` to every handler registered for `event`.
+     *
+     * Handlers run sequentially in registration order — regular ones
+     * first, then `once` handlers. Async handlers are awaited. Synchronous
+     * exceptions are caught, logged, and isolated to the offending handler.
+     */
+    emit<E extends keyof TMap>(event: E, payload: TMap[E]): Promise<void>;
+    /**
+     * Number of handlers currently registered for `event`.
+     * Sum of `on` and `once` registrations.
+     */
+    listenerCount(event: keyof TMap): number;
+    /**
+     * Remove every handler. Pass an event name to limit the removal to
+     * one event; omit it to clear every event on this emitter.
+     *
+     * Crucially this only affects the current instance — there is no
+     * shared global state.
+     */
+    removeAllListeners(event?: keyof TMap): void;
+    /**
+     * Snapshot of all event names that currently have at least one
+     * registered handler. Useful for debugging.
+     */
+    eventNames(): (keyof TMap)[];
+}
+
+/**
+ * Core type definitions shared across all runtime primitives.
+ *
+ * @module @core/types
+ */
+
+/**
+ * Field types recognized by the live preview renderer.
+ *
+ * Extends Payload's field set with `html` and `url` which are not
+ * Payload field types per se but useful DOM-binding categories.
+ */
+type FieldType = PayloadFieldType | 'html' | 'url' | 'image' | 'structural-array';
+/**
+ * A DOM element that has been registered as a live preview binding.
+ *
+ * Stored in the element cache indexed by `fieldName`. Multiple cached
+ * entries can share a field name when the same field is rendered in
+ * several places (e.g., a title shown in both the header and the
+ * page body).
+ */
+interface CachedElement {
+    /** The bound DOM element. */
+    readonly element: Element;
+    /** Payload field path, e.g., `title` or `hero.subtitle`. */
+    readonly fieldName: string;
+    /**
+     * Resolved field type, used to dispatch to the right renderer.
+     *
+     * The cache resolves this from DOM attributes (`data-payload-type`,
+     * tag-based heuristics) at build time. When `explicitFieldType` is
+     * `false` the lifecycle is allowed to override this with the type
+     * learned from the schema once `fieldSchemaJSON` arrives.
+     */
+    readonly fieldType: FieldType;
+    /**
+     * `true` when the field type was set by an explicit
+     * `data-payload-type` attribute (consumer trumps schema), `false`
+     * when it was inferred via tag-based heuristics (schema may
+     * override later). Optional so synthetic bindings (tests / programmatic
+     * `cache.add()` callers) need not supply it; the cache always
+     * populates it for DOM-derived bindings.
+     */
+    readonly explicitFieldType?: boolean;
+    /**
+     * Optional target attribute: the value is written to this attribute
+     * instead of the element's content (from `data-payload-attribute`,
+     * or `bind(field, { attribute })`). Writes are policed — event
+     * handlers, `style`, and unsafe URLs are refused.
+     */
+    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;
+}
+/**
+ * Context passed to every field renderer. Provides access to the
+ * entire field tree so renderers can resolve sibling fields (e.g.,
+ * an `<a>` that pulls `href` from a different 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;
+}
+/**
+ * Contract that every field renderer implements.
+ *
+ * Renderers are pure DOM-write functions: they receive the cached
+ * binding plus the new value and apply it to the element. They must
+ * not throw — failures should be silenced and logged so that one bad
+ * field cannot stop an entire update.
+ */
+interface FieldRenderer {
+    readonly name: FieldType;
+    render(target: CachedElement, value: unknown, context: RenderContext): void;
+}
+
+/**
+ * Plugin system types.
+ *
+ * Each plugin participates in the live-preview lifecycle through a
+ * scoped, per-instance context. Plugins can register custom field
+ * renderers, transform incoming values, and subscribe to events —
+ * the same primitives the built-in renderers use.
+ *
+ * The system is intentionally minimal. Anything that can be expressed
+ * with an event subscription belongs in `events`, not `plugins`.
+ *
+ * @module @plugins/types
+ */
+
+/**
+ * Function that mutates a value before the renderer receives it.
+ * Returning a different shape than the input is allowed.
+ */
+type FieldTransform = (value: unknown, context: {
+    readonly fieldName: string;
+    readonly element: Element;
+    readonly allFields: Record<string, unknown>;
+}) => unknown;
+/**
+ * Per-instance plugin context. Replaces the legacy singleton context.
+ *
+ * Plugins receive a context that is bound to the parent
+ * `LivePreviewClient`. They can:
+ *
+ *   - subscribe via `events.on/once`,
+ *   - register field renderers,
+ *   - register value transforms,
+ *   - read the client's (frozen) configuration,
+ *   - log through the client's debug channel.
+ */
+interface PluginContext {
+    readonly events: EventEmitter;
+    readonly registerFieldRenderer: (renderer: FieldRenderer) => void;
+    readonly registerTransform: (fieldName: string, transform: FieldTransform) => void;
+    readonly getConfig: () => Readonly<Record<string, unknown>>;
+    readonly log: (...args: unknown[]) => void;
+}
+/**
+ * Plugin definition. `init` runs once per registration; `destroy`
+ * runs when the plugin is unregistered or the client is destroyed.
+ *
+ * Both hooks may return a promise; the manager awaits them.
+ */
+interface LivePreviewPlugin {
+    readonly name: string;
+    readonly version?: string;
+    readonly init: (context: PluginContext) => void | Promise<void>;
+    readonly destroy?: () => void | Promise<void>;
+}
+
+/**
+ * `LivePreviewClient` configuration shape.
+ *
+ * @module @client/config
+ */
+interface LivePreviewClientConfig {
+    /** Explicit additional trusted origins. */
+    readonly allowedOrigins?: readonly string[];
+    /**
+     * Payload server origin, e.g. `https://cms.example.com`. When set,
+     * every incoming update is re-fetched through the Payload REST API
+     * so relationship/upload fields render populated instead of as bare
+     * IDs (same strategy as the official client). Recommended for
+     * Payload 3.x.
+     */
+    readonly serverURL?: string;
+    /** REST API route prefix used with `serverURL`. Defaults to `/api`. */
+    readonly apiRoute?: string;
+    /** Population depth used with `serverURL`. Defaults to `1`. */
+    readonly mergeDepth?: number;
+    /**
+     * Custom fetch implementation for the `serverURL` merge request —
+     * the equivalent of the official client's `requestHandler`. Use it
+     * to attach auth headers or route through your own proxy. Only
+     * available on the programmatic client (functions cannot be
+     * serialised into the inline script).
+     */
+    readonly mergeFetch?: typeof fetch;
+    /** Enable verbose console debug output. Defaults to dev-mode detection. */
+    readonly debug?: boolean;
+    /** Debounce window for incoming updates. Defaults to 50 ms. */
+    readonly debounceMs?: number;
+    /**
+     * Heartbeat timeout in ms. Defaults to `0` (disabled) because the
+     * Payload admin sends messages only on form edits — there is no
+     * protocol keepalive, so an idle timeout would produce false
+     * disconnects.
+     */
+    readonly heartbeatMs?: number;
+    /** IntersectionObserver rootMargin. Defaults to `200px`. */
+    readonly intersectionRootMargin?: string;
+    /** Bypass the visibility gate (apply every update). Defaults to `false`. */
+    readonly disableVisibilityGate?: boolean;
+    /** Cache-size threshold above which off-screen updates are queued for replay. Defaults to 50. */
+    readonly visibilityGateThreshold?: number;
+    /** Mount an `aria-live` region and announce lifecycle to screen readers. Default `true`. */
+    readonly enableA11y?: boolean;
+    /** Locale used to pick A11y announcement strings. Defaults to detected locale. */
+    readonly a11yLocale?: string;
+    /** Document root, defaults to `document`. */
+    readonly root?: Document | Element;
+    /** Disable `document.referrer` detection. */
+    readonly disableReferrerDetection?: boolean;
+    /** Disable the localhost dev-mode pattern matcher. */
+    readonly disableLocalhostMatching?: boolean;
+    /** Auto-start the runtime in the constructor. Defaults to `true`. */
+    readonly autoStart?: boolean;
+    /**
+     * Optional preview-token validator. When set, every data update
+     * must carry a `previewToken` field that this function approves.
+     *
+     * ⚠️ `previewToken` is an extension of THIS library, not part of the
+     * stock Payload postMessage protocol — the Payload admin never sends
+     * one. Only enable this when a custom admin component adds the token
+     * to outgoing messages; against an unmodified Payload admin it would
+     * drop every update.
+     */
+    readonly validateToken?: (token: string | undefined, origin: string) => boolean | Promise<boolean>;
+}
+
+/**
+ * Public, high-level `LivePreviewClient`.
+ *
+ * The client wraps a `LivePreviewRuntime` with:
+ *
+ *   - Per-instance event emitter (no singleton).
+ *   - Per-instance plugin manager.
+ *   - Custom-renderer registration.
+ *   - Field-name transforms applied before renderer dispatch.
+ *
+ * Consumers who want full programmatic control instantiate
+ * `LivePreviewClient` directly. Consumers who just want a working
+ * inline preview should use `generateInlineScript()` instead.
+ *
+ * @module @client
+ */
+
+declare class LivePreviewClient {
+    #private;
+    constructor(config?: LivePreviewClientConfig);
+    /**
+     * Start the runtime. Returns `true` when the runtime actually
+     * started (it may refuse to start outside a preview context).
+     */
+    start(): boolean;
+    /**
+     * Stop the runtime and tear down every plugin. Idempotent.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Register a plugin.
+     */
+    use(plugin: LivePreviewPlugin): Promise<void>;
+    /**
+     * Unregister a plugin by name.
+     */
+    unuse(name: string): Promise<void>;
+    /** Rebuild the element cache manually. */
+    refreshCache(): void;
+    /** Read-only access to the event emitter for `on`/`once`/`off`. */
+    get events(): EventEmitter;
+    /** Names of currently registered plugins. */
+    get plugins(): readonly string[];
+    /** Current connection status. */
+    get status(): 'disconnected' | 'connecting' | 'connected';
+    /** Number of valid updates received so far. */
+    get updateCount(): number;
+    /** `true` once `destroy()` has been called. */
+    get destroyed(): boolean;
+}
+/**
+ * Convenience factory: instantiate the client, returning `null` when
+ * the page is not currently a preview context (top-level navigation).
+ * Useful for SSR-style integrations that import this from any context.
+ */
+declare function initLivePreview(config?: LivePreviewClientConfig): LivePreviewClient | null;
+
+/**
+ * HTML-escape primitives.
+ *
+ * Implementations follow the OWASP XSS Prevention Cheat Sheet: each
+ * special character is replaced with its decimal or hex entity. The
+ * functions are isomorphic — they have no dependency on the DOM and
+ * can run in any JavaScript environment (browser, Node, Deno, Bun).
+ *
+ * @module @security/escape
+ */
+/**
+ * Escape every HTML-significant character in `text` so the result is
+ * safe to interpolate into any HTML context (element body or attribute).
+ *
+ * - Coerces non-strings via `String(value)`; pass `null`/`undefined`
+ *   intentionally — they become `"null"`/`"undefined"`.
+ * - Cannot fail; returns `""` for the empty input.
+ */
+declare function escapeHtml(text: string): string;
+/**
+ * Escape characters that would break out of a double-quoted HTML
+ * attribute value. Stricter than `escapeHtml` for body content but
+ * preserves URL characters (`/`, `=`, etc.) that are common in
+ * `href` and `src` values.
+ *
+ * Only call this for values that have already been validated as safe
+ * URLs or trusted strings; it does NOT block dangerous protocols.
+ */
+declare function escapeHtmlAttribute(value: string): string;
+
+/**
+ * URL safety validation.
+ *
+ * Single source of truth for URL-protocol decisions used by both the
+ * inline runtime and the high-level client. The previous version of
+ * this library had two implementations that subtly disagreed; this
+ * module replaces both.
+ *
+ * Policy:
+ *   - Allow only the protocols in `SAFE_PROTOCOLS`.
+ *   - Reject every other protocol explicitly, including `javascript:`,
+ *     `data:`, `vbscript:`, `file:`, `blob:`, and any custom scheme.
+ *   - Empty strings are NOT considered safe (this is a tightening from
+ *     the legacy behaviour and avoids producing `<a href="">` markup).
+ *
+ * @module @security/url-validator
+ */
+/**
+ * Returns `true` only when `url` is one of the explicitly allowed forms:
+ *
+ *   - Absolute URL with `http:`, `https:`, `mailto:`, or `tel:` protocol
+ *   - Protocol-relative URL (`//example.com/...`)
+ *   - Same-origin absolute path (`/foo`)
+ *   - Hash or query fragment (`#section`, `?q=1`)
+ *   - Plain relative path (`foo/bar`, `./foo`, `../foo`)
+ */
+declare function isSafeUrl(url: unknown): boolean;
+/**
+ * Returns `true` when the URL points to an external HTTP(S) origin.
+ * Protocol-relative URLs (`//example.com/...`) count as external —
+ * they resolve to another origin and need the same `noopener`
+ * hardening as absolute ones.
+ *
+ * Used by renderers to decide whether to add `target="_blank"` and the
+ * `noopener noreferrer` rel attributes to anchors. Inputs that fail
+ * `isSafeUrl()` always return `false`.
+ */
+declare function isExternalHttpUrl(url: string): boolean;
+
+interface SanitizeOptions {
+    /** Extra tags to allow beyond the built-in list. Lower-case, untrimmed. */
+    readonly additionalAllowedTags?: readonly string[];
+    /** Extra per-tag attributes to allow. Tag and attribute names must be lower-case. */
+    readonly additionalAllowedAttributes?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Minimal `Document`-shaped surface the sanitizer needs. Any DOM
+ * implementation (browser, jsdom, linkedom, happy-dom, parse5 + a
+ * thin adapter) that produces `<template>`-style elements works.
+ */
+interface SanitizerDocument {
+    createElement: (tagName: string) => {
+        innerHTML: string;
+        readonly content: ParentNode;
+    };
+}
+/**
+ * Inject a `Document` implementation for the sanitizer to use when
+ * `globalThis.document` is unavailable.
+ *
+ * Server-side renderers (Node, Bun, Deno without DOM globals) can wire
+ * this up once at startup with any of the popular pure-JS DOM
+ * libraries:
+ *
+ *   ```ts
+ *   // linkedom — recommended (smallest, fastest)
+ *   import { parseHTML } from 'linkedom';
+ *   import { setSanitizerDocument } from 'payload-live-preview';
+ *   const { document } = parseHTML('<!doctype html><html><body></body></html>');
+ *   setSanitizerDocument(document);
+ *   ```
+ *
+ *   ```ts
+ *   // jsdom — heavier, but already in many SSR pipelines
+ *   import { JSDOM } from 'jsdom';
+ *   setSanitizerDocument(new JSDOM().window.document);
+ *   ```
+ *
+ * Pass `null` to clear a previous override (mostly useful for tests).
+ */
+declare function setSanitizerDocument(doc: SanitizerDocument | null): void;
+/**
+ * Sanitize `html` and return safe HTML.
+ *
+ * The function never returns `undefined`/`null`. On malformed input the
+ * browser parser silently recovers and the sanitizer continues from
+ * the recovered tree.
+ *
+ * @throws {SanitizerEnvironmentError} when no DOM is available.
+ */
+declare function sanitizeHtml(html: string, options?: SanitizeOptions): string;
+
+/**
+ * Content-Security-Policy helpers.
+ *
+ * Two responsibilities:
+ *
+ *   1. Generate cryptographic nonces so consumers can opt into a strict
+ *      `script-src 'nonce-...'` policy and avoid `'unsafe-inline'`.
+ *   2. Build the `frame-ancestors` directive value, restricting which
+ *      origins may embed the preview page in an iframe.
+ *
+ * Both functions are isomorphic — they work in browsers, Node, and
+ * edge runtimes that expose Web Crypto via `globalThis.crypto`.
+ *
+ * @module @security/csp
+ */
+/**
+ * Minimal Web-Crypto surface area we actually call. The full `Crypto`
+ * type drags in browser-only declarations that don't typecheck cleanly
+ * against Node's `webcrypto` shape — this narrower interface accepts
+ * both without an unsafe cast.
+ */
+interface WebCryptoLike {
+    getRandomValues: <T extends ArrayBufferView | null>(array: T) => T;
+}
+/**
+ * Inject a Web Crypto implementation to use when `globalThis.crypto`
+ * is unavailable.
+ *
+ * Node.js exposed `globalThis.crypto` globally starting with v19. On
+ * Node 18 (still LTS at time of writing) consumers can flip the
+ * `--experimental-global-webcrypto` flag *or* call this function once
+ * at startup:
+ *
+ *   ```ts
+ *   import { webcrypto } from 'node:crypto';
+ *   import { setCspCrypto } from 'payload-live-preview';
+ *   setCspCrypto(webcrypto as { getRandomValues: typeof webcrypto.getRandomValues });
+ *   ```
+ *
+ * Browser bundles never need to call this — `globalThis.crypto` is
+ * always present there, and the override only matters when the global
+ * is missing.
+ *
+ * Pass `null` to clear a previous override (mostly useful for tests).
+ */
+declare function setCspCrypto(crypto: WebCryptoLike | null): void;
+/**
+ * Generate a base64url-encoded cryptographic nonce.
+ *
+ * Uses `crypto.getRandomValues` everywhere — falls back to throwing
+ * if no Web Crypto implementation is available, because a predictable
+ * nonce would silently defeat the entire CSP.
+ *
+ * @param bytes Number of random bytes (defaults to 16 → 128-bit entropy).
+ */
+declare function generateCspNonce(bytes?: number): string;
+interface FrameAncestorsOptions {
+    readonly self?: boolean;
+    readonly origins?: readonly string[];
+    readonly allowNone?: boolean;
+}
+/**
+ * Build the value for `frame-ancestors` in a `Content-Security-Policy`
+ * header.
+ *
+ * Returns `'none'` if `allowNone: true` and no other sources are
+ * provided. Otherwise concatenates `'self'` (if requested) with the
+ * given origins, deduplicating and trimming entries.
+ *
+ * @example
+ *   `frame-ancestors ${buildFrameAncestors({ self: true, origins: [adminUrl] })}`
+ */
+declare function buildFrameAncestors(options?: FrameAncestorsOptions): string;
+/**
+ * Build a `script-src` value that permits a single nonce plus optional
+ * extra sources.
+ *
+ * `'strict-dynamic'` is **opt-in**: under CSP 3 it makes browsers
+ * ignore `'self'` and every host source in the directive, so any
+ * parser-inserted script without a nonce (framework hydration scripts,
+ * consumer `<script>` tags) would be blocked. Only enable it when every
+ * script on the page carries the nonce.
+ */
+declare function buildScriptSrcWithNonce(nonce: string, options?: {
+    readonly self?: boolean;
+    readonly extra?: readonly string[];
+    readonly strictDynamic?: boolean;
+}): string;
+/**
+ * How a directive is merged into an existing CSP header value.
+ *
+ *   - `union` (default) — the new sources are added to the existing
+ *     directive's sources (deduplicated). An existing `'none'` is
+ *     dropped when real sources are added, since `'none'` may not be
+ *     combined with other sources.
+ *   - `replace` — the new value overwrites the existing directive.
+ */
+interface CspDirectiveMerge {
+    readonly value: string;
+    readonly mode?: 'union' | 'replace';
+}
+/**
+ * Merge directives into an existing `Content-Security-Policy` header
+ * value without clobbering what a consumer (or another middleware)
+ * already configured. Directives not mentioned in `additions` pass
+ * through untouched; new directives are appended.
+ *
+ * This is the single CSP-merge implementation shared by every adapter.
+ */
+declare function mergeCspHeader(existing: string, additions: Readonly<Record<string, string | CspDirectiveMerge>>): string;
+
+/**
+ * Environment introspection helpers.
+ *
+ * The detection layer needs to know whether the runtime is currently
+ * running inside an iframe, in a popup, in development mode, and
+ * whether environment variables are accessible. None of these checks
+ * is dramatic on its own, but having a single, tested module avoids
+ * the duplicated, subtly-different `typeof process` snippets that
+ * accumulated in the legacy implementation.
+ *
+ * @module @detection/environment
+ */
+/**
+ * Returns `true` when the current window is inside an iframe.
+ *
+ * Uses a try/catch around `window.self !== window.top` because the
+ * comparison throws in cross-origin iframes — and that very throw is
+ * itself a definitive "yes, I am in an iframe" signal.
+ */
+declare function isInIframe(): boolean;
+/**
+ * Returns `true` when the current window was opened via `window.open()`
+ * and the opener reference is still accessible.
+ */
+declare function isInPopup(): boolean;
+/**
+ * Returns `true` when running in a preview-capable context: iframe or
+ * popup. Anything else (top-level navigation) should skip live preview
+ * initialisation entirely.
+ */
+declare function isInPreviewContext(): boolean;
+/**
+ * Returns `true` when the runtime appears to be in development mode.
+ *
+ * Detection order:
+ *   1. `process.env.NODE_ENV !== 'production'`
+ *   2. `import.meta.env.DEV === true` (Vite / Astro / SvelteKit)
+ *   3. `window.location.hostname` is `localhost`/`127.0.0.1`
+ *
+ * Returns `false` when none of those are available.
+ */
+declare function isDevMode(): boolean;
+
+/**
+ * Origin detection and matching.
+ *
+ * Builds the set of trusted Payload admin origins and exposes a fast
+ * matcher used by the message bus. Three sources, in precedence order:
+ *
+ *   1. Explicit origins passed via configuration. Always trusted.
+ *   2. `document.referrer` — **only when no explicit origins are
+ *      configured**. The browser writes the embedder's origin here
+ *      when the iframe loads; using it as a fallback gives a
+ *      zero-config path, but it must never widen an explicit
+ *      allow-list (the referrer is whoever framed the page, which in
+ *      an attack is the attacker).
+ *   3. Localhost pattern (any port on `localhost` / `127.0.0.1`),
+ *      enabled when development mode is detected. Replaces the
+ *      legacy hand-rolled port list.
+ *
+ * Once the parent's origin is *confirmed* through a successful message
+ * handshake, callers can call `lockOrigin()` to drop every other
+ * candidate, making subsequent matches exact.
+ *
+ * @module @detection/origin
+ */
+interface OriginDetectorOptions {
+    /** Explicit additional origins to trust. Always allowed. */
+    readonly additionalOrigins?: readonly string[];
+    /** Set to `false` to opt out of `document.referrer` detection. */
+    readonly enableReferrerDetection?: boolean;
+    /** Set to `false` to opt out of localhost-pattern matching. */
+    readonly enableLocalhostMatching?: boolean;
+    /**
+     * Override the dev-mode detection. When `undefined`, dev mode is
+     * inferred from the runtime (see `isDevMode`).
+     */
+    readonly forceDevMode?: boolean;
+    /** Override `document.referrer` for tests. */
+    readonly referrer?: string;
+}
+/**
+ * Holds the resolved origin policy and exposes a matcher.
+ *
+ * The detector is stateful: it starts with the union of all candidate
+ * sources, then narrows down to a single, verified origin once
+ * `lockOrigin()` is called by the message bus on first valid handshake.
+ */
+declare class OriginDetector {
+    #private;
+    constructor(options?: OriginDetectorOptions);
+    /**
+     * Returns `true` when `origin` is trusted under the current policy.
+     *
+     * If an origin has been locked, only that exact value matches.
+     * Otherwise explicit origins and (in dev mode) localhost-pattern
+     * matches are accepted. The referrer-derived origin is a **fallback,
+     * not a union member**: it only counts when NO explicit origins are
+     * configured. `document.referrer` always names whoever actually
+     * framed the page — if it were unioned with the explicit list, any
+     * site embedding the page in an iframe would become a trusted
+     * postMessage sender despite the consumer having pinned the admin
+     * origin explicitly.
+     */
+    matches(origin: string): boolean;
+    /**
+     * Narrow the trusted set to a single origin after a successful
+     * handshake. Subsequent calls to `matches()` only allow `origin`.
+     *
+     * Returns `true` if locking succeeded; `false` if the candidate is
+     * not currently considered trusted (which would defeat the purpose
+     * of locking).
+     */
+    lockOrigin(origin: string): boolean;
+    /**
+     * Release the origin lock so any allow-listed origin is trusted
+     * again until the next successful handshake. The lifecycle calls
+     * this on heartbeat timeout — after the trusted parent disappears,
+     * a different (still-allowed) origin should be free to reconnect.
+     *
+     * Returns the previously-locked origin, or `undefined` when nothing
+     * was locked.
+     */
+    unlockOrigin(): string | undefined;
+    /** The currently locked origin, or `undefined`. */
+    get lockedOrigin(): string | undefined;
+    /**
+     * Snapshot of every origin currently allowed by the policy. Used by
+     * the message bus to broadcast `ready` messages.
+     *
+     * Localhost pattern matches are expanded into the common dev ports
+     * so the handshake can find a Payload running on its usual port.
+     */
+    enumerate(): string[];
+    /**
+     * Reports whether `document.referrer` contributed at least one
+     * origin. Useful for surfacing a console warning when running in
+     * production without an explicit origin and the referrer is absent
+     * (because of a `Referrer-Policy: no-referrer` header).
+     */
+    get referrerWasAvailable(): boolean;
+    /**
+     * Indicates whether the detector is operating in a "production-without-
+     * explicit-origin" configuration. When `true`, the host should log a
+     * loud warning — silent connection failure is the worst outcome.
+     */
+    get isProductionUnconfigured(): boolean;
+    /**
+     * `true` when the referrer is the ONLY trust source (no explicit
+     * origins, no localhost matching). In that mode any site that frames
+     * the page becomes a trusted postMessage sender — `document.referrer`
+     * always names the actual embedder. Content is still sanitized, but
+     * the origin allow-list no longer restricts who may drive it. Hosts
+     * should surface a warning suggesting explicit `allowedOrigins` and
+     * a `frame-ancestors` policy in production.
+     */
+    get isReferrerOnlyTrust(): boolean;
+}
+
+/**
+ * Locale detection.
+ *
+ * The runtime needs a sensible default locale for date/number renders
+ * before Payload tells us the active locale. Order of precedence:
+ *
+ *   1. The `lang` attribute on `<html>`.
+ *   2. `navigator.language`.
+ *   3. The hard-coded fallback `'en'`.
+ *
+ * The previous version of this library defaulted to `'de'` — a German
+ * default that surprised consumers in other locales. We now use the
+ * browser hint and fall back to English.
+ *
+ * @module @detection/locale
+ */
+/**
+ * Returns a BCP-47 locale string suitable for `Intl.*` constructors.
+ *
+ * Always returns a non-empty string. When no signal is available the
+ * fallback (`'en'`) is returned.
+ */
+declare function detectInitialLocale(): string;
+
+/**
+ * Protocol-version negotiation.
+ *
+ * ⚠️ Reality check: **stock Payload does not version its live-preview
+ * postMessage protocol.** The admin never sends a `protocolVersion`
+ * field and ignores extra fields in our `ready` handshake. Observed
+ * wire behaviour:
+ *
+ *   - Payload **2.x** sent `fieldSchemaJSON` with the first update
+ *     (client-side merge era).
+ *   - Payload **3.x** removed `fieldSchemaJSON` entirely; the official
+ *     client re-fetches merged documents through the REST API instead.
+ *   - No Payload version sends `previewToken` or any keepalive.
+ *
+ * This module therefore only matters for NON-stock admin panels — a
+ * custom `window.postMessage` sender can advertise a version and this
+ * library will negotiate `min(ours, theirs)` and expose capability
+ * flags. Against stock Payload, `theirs` stays `undefined`, negotiation
+ * collapses to v1, and nothing is gated on it: schema handling
+ * activates whenever `fieldSchemaJSON` is actually present, and token
+ * validation only runs when the consumer opts in.
+ *
+ * Version ladder (this library's own numbering, not Payload's):
+ *
+ *   - **v1** — data + slug + locale (matches stock Payload of any era).
+ *   - **v2** — remote sends `fieldSchemaJSON` (Payload 2.x behaviour).
+ *   - **v3** — remote sends `previewToken` (custom senders only).
+ *   - **v4** — nested-array recursion / richer document events
+ *     (custom senders only).
+ *
+ * @module @core/protocol-version
+ */
+declare const LIBRARY_PROTOCOL_VERSION = 4;
+/** Capability flag → minimum protocol version it requires. */
+declare const CAPABILITY_REQUIREMENTS: Readonly<Record<string, number>>;
+type ProtocolCapability = keyof typeof CAPABILITY_REQUIREMENTS;
+interface ProtocolNegotiation {
+    /** This library's protocol version. */
+    readonly ours: number;
+    /** The remote party's version, when known. */
+    readonly theirs: number | undefined;
+    /** `min(ours, theirs ?? 1)` — the version both sides actually share. */
+    readonly negotiated: number;
+    /** Capability flags enabled at the negotiated version. */
+    readonly capabilities: ReadonlySet<string>;
+}
+/**
+ * Compute the negotiated view of the protocol.
+ *
+ * `theirs === undefined` collapses to v1 — assume the remote party is
+ * an older Payload that does not advertise a version.
+ *
+ * Non-finite or non-positive `theirs` values fall back to v1 as well —
+ * we never trust an obviously-corrupted negotiation byte.
+ */
+declare function negotiateProtocol(theirs: number | undefined): ProtocolNegotiation;
+declare function hasCapability(negotiation: ProtocolNegotiation, capability: ProtocolCapability): boolean;
+
+/**
+ * Type-level path utilities — used by the typed binding DSL to give
+ * callers compile-time autocomplete on field names.
+ *
+ * The same path strings the runtime reads from `data-payload-field`
+ * are typed here, so a typo like `'heroTitlee'` is rejected at compile
+ * time *and* the runtime side does not need to change.
+ *
+ * @module @dsl/paths
+ */
+/**
+ * All string-typed top-level keys of `T`. Non-string keys (numeric
+ * indices on arrays) are filtered out.
+ */
+type FieldName<T> = Extract<keyof T, string>;
+/**
+ * Dotted paths into nested object structures, capped at three levels
+ * deep — sufficient for Payload's `group`/`tab`/`array` nesting
+ * without ballooning the IDE's IntelliSense list past the point of
+ * usefulness.
+ */
+type FieldPath<T, Depth extends 0 | 1 | 2 | 3 = 3> = Depth extends 0 ? never : T extends readonly (infer U)[] ? FieldPath<U, Prev<Depth>> : T extends object ? {
+    [K in Extract<keyof T, string>]: K | (T[K] extends object ? `${K}.${FieldPath<T[K], Prev<Depth>>}` : never);
+}[Extract<keyof T, string>] : never;
+/** Decrement helper for depth-bounded recursion. */
+type Prev<N extends 0 | 1 | 2 | 3> = N extends 3 ? 2 : N extends 2 ? 1 : N extends 1 ? 0 : 0;
+/**
+ * Resolve the value type at a dotted path. Returns `unknown` when the
+ * path does not exist on `T`, so consumers can opt into stricter
+ * `keyof`-based DSLs when they want absolute type safety.
+ */
+type ValueAt<T, P extends string> = P extends `${infer Head}.${infer Rest}` ? Head extends keyof T ? T[Head] extends readonly (infer U)[] ? ValueAt<U, Rest> : T[Head] extends object ? ValueAt<T[Head], Rest> : unknown : unknown : P extends keyof T ? T[P] : unknown;
+
+/**
+ * Typed binding helpers — emit the `data-payload-field` attribute pair
+ * that the live-preview runtime reads, with compile-time validation
+ * of the field name.
+ *
+ * Two forms are exposed:
+ *
+ *   - **`bind<Schema>('heroTitle')`** — string-literal form. Lightest
+ *     possible runtime (no Proxy), but a rename in the IDE does NOT
+ *     follow into the string.
+ *   - **`bindByPath<Schema>(s => s.heroTitle)`** — proxy form. The
+ *     callback walks a Proxy that records the access path, returning
+ *     the same shape as `bind` so the two are interchangeable. Slightly
+ *     heavier runtime, but rename-safe and discourages typos.
+ *
+ * Both helpers also accept a richer return — `bind('image', 'src')` —
+ * to bind an attribute other than the default `data-payload-field`,
+ * matching the cache resolver's `data-payload-attribute` flow.
+ *
+ * @module @dsl/bind
+ */
+
+/**
+ * Shape returned by every binding helper — a spreadable HTML attribute
+ * record. Astro / JSX / Svelte all accept this style directly:
+ *
+ *   ```astro
+ *   <h1 {...bind<Homepage>('heroTitle')}>{data.heroTitle}</h1>
+ *   ```
+ */
+interface FieldBindingAttributes {
+    readonly 'data-payload-field': string;
+    readonly 'data-payload-attribute'?: string;
+    readonly 'data-payload-type'?: string;
+}
+interface BindOptions {
+    /** Override the bound attribute (e.g., `'src'` for `<img>`). Default: textContent. */
+    readonly attribute?: string;
+    /** Explicit field-type override — bypasses schema detection. */
+    readonly type?: string;
+}
+/**
+ * String-literal binding helper.
+ *
+ *   ```ts
+ *   import { bind } from 'payload-live-preview';
+ *   import type { Homepage } from './payload-types';
+ *
+ *   <h1 {...bind<Homepage>('heroTitle')}>{data.heroTitle}</h1>
+ *   <img {...bind<Homepage>('heroImage', { attribute: 'src' })} />
+ *   ```
+ *
+ * The generic `T` is the schema interface emitted by `pll-codegen`.
+ * `field` is constrained to `keyof T` so misspellings fail at compile
+ * time. When `T` is omitted, the helper accepts any string — useful
+ * for incremental adoption.
+ */
+declare function bind<T = Record<string, unknown>>(field: FieldName<T>, options?: BindOptions): FieldBindingAttributes;
+/**
+ * Proxy-path binding helper.
+ *
+ *   ```ts
+ *   <h1 {...bindByPath<Homepage>(d => d.heroTitle)}>{data.heroTitle}</h1>
+ *   ```
+ *
+ * The picker is invoked once with a recording Proxy; the recorded path
+ * is joined with `.` and emitted as the binding name. Property access
+ * on nested objects and arrays both work — `d => d.slides[0].title`
+ * becomes `slides.title` (array indices are normalised away because the
+ * runtime resolves bindings against schema, not against positional
+ * indices).
+ */
+declare function bindByPath<T = Record<string, unknown>>(picker: (data: T) => unknown, options?: BindOptions): FieldBindingAttributes;
+
+export { generateCspNonce as A, type BindOptions as B, type CachedElement as C, hasCapability as D, EventEmitter as E, type FieldBindingAttributes as F, initLivePreview as G, isDevMode as H, isExternalHttpUrl as I, isInIframe as J, isInPopup as K, LIBRARY_PROTOCOL_VERSION as L, isInPreviewContext as M, isSafeUrl as N, OriginDetector as O, type PayloadFieldSchema as P, mergeCspHeader as Q, type RenderContext as R, type SanitizerDocument as S, negotiateProtocol as T, type Unsubscribe as U, VERSION as V, sanitizeHtml as W, setCspCrypto as X, setSanitizerDocument as Y, type CspDirectiveMerge as a, type EventHandler as b, type FieldName as c, type FieldPath as d, type FieldRenderer as e, type FieldTransform as f, type FieldType as g, type FrameAncestorsOptions as h, LivePreviewClient as i, type LivePreviewClientConfig as j, type LivePreviewEventMap as k, type LivePreviewPlugin as l, type PayloadFieldType as m, type PayloadLivePreviewData as n, type PayloadLivePreviewMessage as o, type PluginContext as p, type ProtocolCapability as q, type ProtocolNegotiation as r, type ValueAt as s, bind as t, bindByPath as u, buildFrameAncestors as v, buildScriptSrcWithNonce as w, detectInitialLocale as x, escapeHtml as y, escapeHtmlAttribute as z };