payload-live-preview 1.0.2 → 1.0.4

package/dist/index.d.ts

@@ -1,6 +1,645 @@
-import { l as LivePreviewPlugin, e as FieldRenderer } from './bind-BSgxoQhN.js';
-export { B as BindOptions, C as CachedElement, a as CspDirectiveMerge, E as EventEmitter, b as EventHandler, F as FieldBindingAttributes, c as FieldName, d as FieldPath, f as FieldTransform, g as FieldType, h as FrameAncestorsOptions, L as LIBRARY_PROTOCOL_VERSION, i as LivePreviewClient, j as LivePreviewClientConfig, k as LivePreviewEventMap, O as OriginDetector, P as PayloadFieldSchema, m as PayloadFieldType, n as PayloadLivePreviewData, o as PayloadLivePreviewMessage, p as PluginContext, q as ProtocolCapability, r as ProtocolNegotiation, R as RenderContext, S as SanitizerDocument, U as Unsubscribe, V as VERSION, s as ValueAt, t as bind, u as bindByPath, v as buildFrameAncestors, w as buildScriptSrcWithNonce, x as detectInitialLocale, y as escapeHtml, z as escapeHtmlAttribute, A as generateCspNonce, D as hasCapability, G as initLivePreview, H as isDevMode, I as isExternalHttpUrl, J as isInIframe, K as isInPopup, M as isInPreviewContext, N as isSafeUrl, Q as mergeCspHeader, T as negotiateProtocol, W as sanitizeHtml, X as setCspCrypto, Y as setSanitizerDocument } from './bind-BSgxoQhN.js';
-export { P as PreviewRequestLike, a as PreviewRequestOptions, i as isPreviewRequest } from './preview-request-DAvxm18T.js';
+/**
+ * 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 per startup attempt after observers, cache, and message listening
+     * are active. A later startup failure may roll that attempt back; retrying then
+     * emits a new `init` event.
+     */
+    readonly init: {
+        readonly timestamp: number;
+    };
+    /** Fired for the first accepted data-bearing update from a trusted origin. */
+    readonly connect: {
+        readonly origin: string;
+        readonly timestamp: number;
+    };
+    /**
+     * Fired when the heartbeat times out or the runtime is destroyed. The
+     * `'unload'` reason remains in the public union for 1.x producer compatibility;
+     * the built-in runtime does not currently emit it.
+     */
+    readonly disconnect: {
+        readonly reason: 'timeout' | 'destroy' | 'unload';
+        readonly timestamp: number;
+    };
+    /**
+     * Fired before the DOM is mutated for an incoming update.
+     *
+     * Handlers may call `cancel()` before their synchronous or asynchronous
+     * work settles to skip exactly this revision.
+     */
+    readonly beforeUpdate: {
+        readonly data: PayloadLivePreviewData;
+        /** Runtime-populated ordering metadata; optional for 1.x producer compatibility. */
+        readonly revision?: number;
+        readonly cancel: () => void;
+    };
+    /**
+     * Fired after each actual, current DOM application batch. Visibility replay
+     * may produce another event for the same revision; cancelled, obsolete, and
+     * deferred-only batches produce none.
+     */
+    readonly afterUpdate: {
+        readonly data: PayloadLivePreviewData;
+        readonly updatedCount: number;
+        readonly durationMs: number;
+        /** Runtime-populated ordering metadata; optional for 1.x producer compatibility. */
+        readonly revision?: number;
+    };
+    /** Fired for each successful, still-current element write. */
+    readonly elementUpdate: {
+        readonly element: Element;
+        readonly fieldName: string;
+        readonly previousValue: unknown;
+        readonly nextValue: unknown;
+        /** Runtime-populated ordering metadata; optional for 1.x producer compatibility. */
+        readonly revision?: number;
+    };
+    /** 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 browser observers and the message listener are
+     * removed. Event/plugin listeners remain available for this notification and
+     * are released by the owning client afterwards.
+     */
+    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
+ *     snapshot for an event is claimed immediately before its dispatch,
+ *     and remains consumed 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>;
+    /**
+     * Lifecycle-only guarded dispatch. The predicate is checked before and after
+     * every handler so an async boundary cannot let an obsolete transaction run
+     * later callbacks. `emit()` intentionally keeps its established behaviour.
+     *
+     * Once-handlers are claimed only when dispatch reaches the once phase. Once
+     * claimed, the whole snapshot remains consumed even if the predicate changes
+     * while one of its handlers is awaiting, matching normal once semantics.
+     *
+     * @internal
+     * @returns `true` when the complete handler sequence ran while eligible.
+     */
+    emitWhile<E extends keyof TMap>(event: E, payload: TMap[E], shouldContinue: () => boolean): Promise<boolean>;
+    /**
+     * 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. The public renderer result remains
+ * `void` for 1.x compatibility. Built-in renderers may use an internal exact
+ * `false` sentinel when they deliberately perform no DOM write; callers must
+ * not rely on that implementation detail.
+ */
+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
+ */
+
+/** Idempotent handle that releases one plugin-owned resource. */
+type PluginDisposer = () => void;
+/**
+ * Event subscriptions scoped to one plugin registration.
+ *
+ * This remains nominally compatible with the pre-1.0.4 `EventEmitter` context
+ * type. Its methods are registration-scoped: even bulk removal affects only
+ * this plugin's subscriptions, never a consumer's or another plugin's
+ * listeners.
+ */
+interface PluginEvents extends EventEmitter {
+    readonly on: <E extends keyof LivePreviewEventMap>(event: E, handler: EventHandler<LivePreviewEventMap[E]>) => Unsubscribe;
+    readonly once: <E extends keyof LivePreviewEventMap>(event: E, handler: EventHandler<LivePreviewEventMap[E]>) => Unsubscribe;
+    readonly off: <E extends keyof LivePreviewEventMap>(event: E, handler: EventHandler<LivePreviewEventMap[E]>) => void;
+    /** Emit through the owning client's event channel. */
+    readonly emit: <E extends keyof LivePreviewEventMap>(event: E, payload: LivePreviewEventMap[E]) => Promise<void>;
+    /**
+     * Guarded emit through the owning client channel. Dispatch stops when the
+     * caller predicate becomes false or this plugin registration is removed.
+     */
+    readonly emitWhile: <E extends keyof LivePreviewEventMap>(event: E, payload: LivePreviewEventMap[E], shouldContinue: () => boolean) => Promise<boolean>;
+    /** Number of listeners owned by this plugin registration. */
+    readonly listenerCount: (event: keyof LivePreviewEventMap) => number;
+    /** Remove only listeners owned by this plugin registration. */
+    readonly removeAllListeners: (event?: keyof LivePreviewEventMap) => void;
+    /** Event names for which this plugin registration owns listeners. */
+    readonly eventNames: () => (keyof LivePreviewEventMap)[];
+}
+/**
+ * Synchronous function that transforms a merged field value while a revision's
+ * per-binding scheduler entry is prepared. Transforms run in registration
+ * order and each receives the preceding transform's result. The final value is
+ * frozen into that entry before later renderer or attribute dispatch;
+ * `allFields` remains the merged, untransformed update snapshot.
+ *
+ * Returning a different shape than the input is allowed, but returning a
+ * Promise or other thenable is a contract error. If a transform throws or
+ * returns a thenable, the chain stops, the runtime emits an `error` event, and
+ * dispatch falls back to the original merged value. That fallback still passes
+ * through the normal renderer and attribute security controls.
+ */
+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: PluginEvents;
+    /** Register a renderer owned by this plugin registration. */
+    readonly registerFieldRenderer: (renderer: FieldRenderer) => void;
+    /** Register an ordered transform owned by this plugin registration. */
+    readonly registerTransform: (fieldName: string, transform: FieldTransform) => void;
+    /**
+     * Register any additional synchronous cleanup owned by this registration.
+     * The manager invokes it during rollback, `unuse()`, or client destruction.
+     * Optional so pre-1.0.4 structural context mocks remain assignable.
+     */
+    readonly registerCleanup?: (cleanup: PluginDisposer) => 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 for connections, applied updates, and mounted
+     * heartbeat-timeout disconnects. Destroy releases it synchronously. 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 frozen into revision-bound scheduler entries before
+ *     their later attribute or 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 this client is eligible and runtime
+     * startup is active or scheduled for DOM readiness. Repeated calls on an
+     * active client also return `true`; `false` means the client was destroyed or
+     * the page is outside a preview context. A deferred startup can still fail,
+     * roll back, and be retried by a later call.
+     */
+    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 and release all resources owned by that registration. */
+    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;
 
 interface RuntimeBuildInfo {
     readonly generatedAt: string;
@@ -83,9 +722,11 @@ interface InlineScriptConfig {
      */
     readonly disableLocalhostMatching?: boolean;
     /**
-     * Optional CSP nonce for the generated `<script>` tag. When provided
-     * via `wrapWithScriptTag()` the nonce is set on the tag. Useful for
-     * strict CSP policies that disallow `unsafe-inline`.
+     * Retained for 1.x source compatibility, but has no effect here:
+     * `generateInlineScript()` returns a script body and creates no tag.
+     * Pass the nonce separately to `wrapWithScriptTag(body, { nonce })`.
+     *
+     * @deprecated Use the second argument of `wrapWithScriptTag()`.
      */
     readonly nonce?: string;
 }
@@ -110,33 +751,354 @@ declare function wrapWithScriptTag(body: string, options?: {
  */
 declare function runtimeBuildInfo(): RuntimeBuildInfo;
 
+/**
+ * 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. Existing policy parsing
+ * follows CSP3's ASCII-whitespace and first-duplicate-wins rules.
+ *
+ * This is the single CSP-merge implementation shared by every adapter.
+ */
+declare function mergeCspHeader(existing: string, additions: Readonly<Record<string, string | CspDirectiveMerge>>): string;
+
+/**
+ * Server-side preview-intent detection.
+ *
+ * The live-preview runtime only ever activates inside the Payload
+ * admin's iframe, but the *server* still has to decide whether a
+ * request expresses preview intent before doing optional preview
+ * work. Adapters use this predicate as a delivery optimisation, and
+ * consumers with hand-rolled middleware can import it directly.
+ *
+ * IMPORTANT: every signal inspected here is controlled or triggerable
+ * by the client. A positive result is never proof of identity,
+ * authentication, or permission to read drafts. Before forwarding
+ * credentials, fetching draft data, bypassing caches, changing CSP,
+ * or injecting the runtime, verify the request with an application-
+ * owned server session or a short-lived signed authorization. Use the
+ * same verified decision for all of those effects.
+ *
+ * Preview intent is present when any of these hold:
+ *
+ *   1. A preview query parameter is present (`?preview=true`,
+ *      `?draft=true`, `?livePreview=true` — configurable).
+ *   2. `Sec-Fetch-Dest: iframe` — the document is being loaded as an
+ *      iframe, which is exactly how the Payload admin embeds it.
+ *      (Sent by all evergreen browsers; absence never *excludes* a
+ *      request, presence includes it.)
+ *   3. The `Referer` points at one of the given admin origins.
+ *
+ * @module @adapters/shared/preview-request
+ */
+/** The individual signals the predicate can consider. */
+type PreviewSignal = 'query' | 'fetch-dest' | 'referer';
+interface PreviewRequestOptions {
+    /**
+     * Which signals count as preview intent. Default: all three.
+     * Restricting this to `['query']` reduces accidental activation, but
+     * an explicit `?preview=true` is still client-controlled and must not
+     * authorize response changes or privileged data access by itself.
+     */
+    readonly signals?: readonly PreviewSignal[];
+    /**
+     * Query parameters (with values `true` or `1`) that signal preview
+     * intent. Default: `['preview', 'draft', 'livePreview']`.
+     */
+    readonly queryParams?: readonly string[];
+    /**
+     * Treat `Sec-Fetch-Dest: iframe` as a preview-intent signal. Default `true`.
+     * Legacy alias for excluding `'fetch-dest'` from `signals`.
+     */
+    readonly checkFetchDest?: boolean;
+    /**
+     * Admin origins whose `Referer` signals preview intent, e.g.
+     * `['https://cms.example.com']`. Referer matching is not HTTP-request
+     * authentication.
+     */
+    readonly adminOrigins?: readonly string[];
+}
+/**
+ * The minimal request surface the predicate needs. The standard
+ * `Request` satisfies it structurally, and server frameworks without
+ * fetch-style requests (e.g. Nitro/H3) can supply a tiny shim.
+ */
+interface PreviewRequestLike {
+    readonly url: string;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+}
+/**
+ * Detect whether `request` carries live-preview intent. See the module
+ * docblock for the exact signals and the required authorization
+ * boundary. This compatibility name does not imply authentication.
+ */
+declare function isPreviewRequest(request: PreviewRequestLike, options?: PreviewRequestOptions): boolean;
+
 /**
  * Draft-aware document fetching for the initial preview render.
  *
  * The live-preview runtime patches the DOM *after* the page loads —
  * the initial server render is the consumer's job. With Payload
- * drafts enabled, a preview must render the **draft** version on
- * first load, otherwise editors see stale published content until
- * their first keystroke.
+ * drafts enabled, an **authorized** preview should render the draft
+ * version on first load, otherwise editors see stale published
+ * content until their first keystroke.
  *
- * These helpers wrap the two REST queries every preview loader needs,
- * with the right flags (`draft=true`, `depth`) and an explicit nudge
- * to keep `depth` in sync with the runtime's `mergeDepth` — a
- * mismatch makes populated relationships degrade to IDs after the
- * first edit.
+ * These helpers wrap the corresponding REST queries with `draft` and
+ * `depth` options and an explicit nudge to keep `depth` in sync with
+ * the runtime's `mergeDepth` — a mismatch makes populated
+ * relationships degrade to IDs after the first edit.
+ *
+ * These helpers do not authenticate or authorize requests.
+ * `isPreviewRequest()` detects client-controlled preview intent only.
+ * Verify an application-owned server session or short-lived signed
+ * authorization first, and use that one decision to gate `draft`, any
+ * privileged headers, cache bypass, CSP changes, and runtime injection.
+ * Never attach a long-lived service/API key merely because
+ * `isPreviewRequest()` returned `true`.
  *
  * Isomorphic and dependency-free: works in Astro frontmatter,
  * SvelteKit `load`, Next.js server components, or any Node/edge
  * runtime with `fetch`.
  *
  * ```ts
- * // Astro frontmatter
+ * // Astro frontmatter. `verifyAppPreviewSession` is application-owned,
+ * // server-only code; it validates the request and returns only the
+ * // minimal Payload session headers needed for this request.
+ * const hasPreviewIntent = isPreviewRequest(Astro.request);
+ * const authorization = hasPreviewIntent
+ *   ? await verifyAppPreviewSession(Astro.request)
+ *   : null;
  * const page = await fetchPreviewDocument<Page>({
  *   serverURL: import.meta.env.PAYLOAD_URL,
  *   collection: 'pages',
  *   where: { slug: { equals: Astro.params.slug } },
- *   draft: isPreviewRequest(Astro.request),
- *   headers: { Authorization: `users API-Key ${import.meta.env.PAYLOAD_PREVIEW_KEY}` },
+ *   draft: authorization !== null,
+ *   ...(authorization === null ? {} : { headers: authorization.payloadHeaders }),
  * });
  * ```
  *
@@ -155,16 +1117,18 @@ interface PreviewFetchBaseOptions {
      */
     readonly depth?: number;
     /**
-     * Fetch the draft version. Defaults to `true` (this is a *preview*
-     * fetch). Pass the result of `isPreviewRequest(request)` to make
-     * the same loader serve published content to normal traffic.
+     * Fetch the draft version. Defaults to `true` for 1.x compatibility.
+     * Set this from a verified authorization decision, not directly
+     * from `isPreviewRequest()`, whose result only expresses intent.
      */
     readonly draft?: boolean;
     /** Locale to fetch. */
     readonly locale?: string;
     /**
-     * Extra request headers — typically auth, since draft reads require
-     * an authenticated user (e.g. `Authorization: users API-Key …`).
+     * Extra request headers. Supply only credentials derived from the
+     * current request's verified server-side session (or another
+     * short-lived, scoped authorization). Do not attach a long-lived
+     * service/API key based on a preview-intent signal.
      */
     readonly headers?: Readonly<Record<string, string>>;
     /** Injectable fetch implementation (tests, custom agents). */
@@ -188,13 +1152,15 @@ interface FetchPreviewGlobalOptions extends PreviewFetchBaseOptions {
     readonly global: string;
 }
 /**
- * Fetch a single collection document (draft-first by default).
+ * Fetch a single collection document (draft-first by default for 1.x
+ * compatibility; callers must authorize draft access).
  * Returns `null` when nothing matches or the request fails —
  * loaders should fall back to their regular data path or a 404.
  */
 declare function fetchPreviewDocument<T = Record<string, unknown>>(options: FetchPreviewDocumentOptions): Promise<T | null>;
 /**
- * Fetch a global (draft-first by default). Returns `null` on failure.
+ * Fetch a global (draft-first by default for 1.x compatibility;
+ * callers must authorize draft access). Returns `null` on failure.
  */
 declare function fetchPreviewGlobal<T = Record<string, unknown>>(options: FetchPreviewGlobalOptions): Promise<T | null>;
 
@@ -360,6 +1326,15 @@ declare function createAnalyticsPlugin(): LivePreviewPlugin & {
  */
 
 type DocumentSaveStrategy = 'silent' | 'reload' | 'revalidate' | 'fetch';
+/**
+ * A fetch strategy handler. The optional parameter preserves calls through
+ * pre-1.0.4 option objects (`options.handler?.()`), while method bivariance
+ * also accepts explicitly signal-aware handlers. The built-in plugin always
+ * supplies a live `AbortSignal`.
+ */
+type DocumentSaveHandler = {
+    bivarianceHack(signal?: AbortSignal): void | Promise<void>;
+}['bivarianceHack'];
 interface DocumentSavePluginOptions {
     /** Strategy to invoke on each `documentSave` event. Default `'silent'`. */
     readonly strategy?: DocumentSaveStrategy;
@@ -375,9 +1350,11 @@ interface DocumentSavePluginOptions {
     readonly revalidateHeaders?: Readonly<Record<string, string>>;
     /**
      * For `'fetch'`: async handler called on each event. The plugin
-     * awaits it; rejections are logged but don't crash the runtime.
+     * awaits it; rejections are logged but don't crash the runtime. The signal
+     * aborts when the plugin is removed. Existing zero-argument handlers remain
+     * compatible because they may ignore the argument.
      */
-    readonly handler?: () => void | Promise<void>;
+    readonly handler?: DocumentSaveHandler;
     /**
      * Optional fallback strategy when `'revalidate'` POST fails (network
      * error or non-2xx). Set to `'reload'` to hard-refresh the page when
@@ -390,6 +1367,192 @@ interface DocumentSavePluginOptions {
  */
 declare function documentSavePlugin(options?: DocumentSavePluginOptions): LivePreviewPlugin;
 
+/**
+ * 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 by an accepted data-bearing
+ * update, callers can call `lockOrigin()` to drop every other candidate,
+ * making subsequent matches exact. A data-less `ready` handshake does
+ * not lock the detector.
+ *
+ * @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 the
+ * lifecycle calls `lockOrigin()` for its first accepted data-bearing
+ * update.
+ */
+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 an accepted
+     * data-bearing update. 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 accepted data-bearing update. 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;
+
 /**
  * Field-renderer registry.
  *
@@ -401,18 +1564,15 @@ declare function documentSavePlugin(options?: DocumentSavePluginOptions): LivePr
  *   - Plugins can register custom renderers via the high-level client.
  *   - New field types ship without touching `lifecycle.ts`.
  *
- * The built-in renderers are collected through `registerBuiltinRenderer`
- * from each renderer module. To avoid tree-shaking, the explicit
- * aggregator `buildBuiltinRenderers` accepts an *additional* renderer
- * array — `@field-types/index` invokes it with every concrete renderer
- * so the references stay reachable.
+ * The explicit aggregator in `@field-types/index` supplies the default
+ * renderers as values, so it remains tree-shaking-safe without module import
+ * side effects. This registry stores only explicit consumer overrides.
  *
  * @module @field-types/registry
  */
 
 /**
- * Register a built-in renderer. Called from each individual renderer
- * module's side-effecting registration.
+ * Register or replace an explicit renderer override for future snapshots.
  */
 declare function registerBuiltinRenderer(renderer: FieldRenderer): void;
 
@@ -470,4 +1630,169 @@ interface PayloadRelationship<TSlug extends string = string> {
  */
 declare function buildBuiltinRenderers(): Readonly<Record<string, FieldRenderer>>;
 
-export { type AnalyticsSnapshot, type BlockRenderContext, type BlockRenderer, type DocumentSavePluginOptions, type DocumentSaveStrategy, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, FieldRenderer, type InlineScriptConfig, type LexicalNode, type LexicalRoot, LivePreviewPlugin, type PayloadMedia, type PayloadRelationship, type PreviewFetchBaseOptions, type PreviewWhere, buildBuiltinRenderers, createAnalyticsPlugin, debugPlugin, documentSavePlugin, fetchPreviewDocument, fetchPreviewGlobal, generateInlineScript, highlightPlugin, isLexicalContent, lexicalToHtml, lexicalToPlainText, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, wrapWithScriptTag };
+/**
+ * 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 { type AnalyticsSnapshot, type BindOptions, type BlockRenderContext, type BlockRenderer, type CachedElement, type CspDirectiveMerge, type DocumentSaveHandler, type DocumentSavePluginOptions, type DocumentSaveStrategy, EventEmitter, type EventHandler, type FetchPreviewDocumentOptions, type FetchPreviewGlobalOptions, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldTransform, type FieldType, type FrameAncestorsOptions, type InlineScriptConfig, LIBRARY_PROTOCOL_VERSION, type LexicalNode, type LexicalRoot, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewPlugin, OriginDetector, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PayloadMedia, type PayloadRelationship, type PluginContext, type PluginDisposer, type PluginEvents, type PreviewFetchBaseOptions, type PreviewRequestLike, type PreviewRequestOptions, type PreviewWhere, type ProtocolCapability, type ProtocolNegotiation, type RenderContext, type SanitizerDocument, type Unsubscribe, VERSION, type ValueAt, bind, bindByPath, buildBuiltinRenderers, buildFrameAncestors, buildScriptSrcWithNonce, createAnalyticsPlugin, debugPlugin, detectInitialLocale, documentSavePlugin, escapeHtml, escapeHtmlAttribute, fetchPreviewDocument, fetchPreviewGlobal, generateCspNonce, generateInlineScript, hasCapability, highlightPlugin, initLivePreview, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isLexicalContent, isPreviewRequest, isSafeUrl, lexicalToHtml, lexicalToPlainText, mergeCspHeader, negotiateProtocol, registerBlockRenderer, registerBuiltinRenderer, runtimeBuildInfo, sanitizeHtml, setCspCrypto, setSanitizerDocument, wrapWithScriptTag };