payload-live-preview 2.2.1 → 2.3.0

package/dist/core.d.cts

@@ -37,6 +37,8 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly UnattributableUpdate: "LP0202";
     /** An update carried a value for a field the page binds nowhere; editing it changes nothing on this page. */
     readonly UnboundField: "LP0203";
+    /** In development: a bound path covers its group under the `descendant` default, which 3.0 changes. */
+    readonly CoverageDefaultChanges: "LP0204";
     /** The visibility gate held offscreen writes back until they scroll into view. */
     readonly VisibilityGateDeferred: "LP0301";
     /** A value was refused because the attribute or the value itself is unsafe. */
@@ -61,7 +63,7 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly UnrenderedBlockKept: "LP0410";
     /** A patch cannot reach what the server would have drawn; `onUnfaithfulPatch` decided what happens next. */
     readonly UnfaithfulPatch: "LP0411";
-    /** The first write to a date, number or checkbox binding replaced a different reading of the same value. */
+    /** The first write to a date, number, checkbox, select or radio binding replaced a different reading of the same value. */
     readonly ServerFormatReplaced: "LP0412";
     /** A Lexical block has no renderer, and the write could not keep the markup the server rendered for it; it is gone. */
     readonly UnrenderedBlockLost: "LP0413";
@@ -81,7 +83,7 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly StartupFailed: "LP0605";
     /** Sending the ready handshake failed. */
     readonly ReadyFailed: "LP0606";
-    /** The page declared hydration, but no React commit, Vue mount or SvelteKit mount came within the cap; the runtime started without waiting. */
+    /** The page declared hydration, but no React commit, Vue mount, SvelteKit mount or `markHydrated()` call came within the cap; the runtime started without waiting. */
     readonly HydrationWaitTimedOut: "LP0607";
     /** The audit found no runtime in a response that carried preview intent. */
     readonly AuditRuntimeMissing: "LP0701";
@@ -123,6 +125,8 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly V2ReadinessGap: "LP0709";
     /** The preview runtime is served to anonymous visitors, not only inside the admin frame. */
     readonly RuntimeOnPublicPage: "LP0710";
+    /** An element carries attributes that only mean something beside `data-payload-field`, and has none. */
+    readonly AuditModifierWithoutField: "LP0711";
 }>;
 /** A diagnostic code, as it appears in log output and on the `error` event. */
 type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[keyof typeof DIAGNOSTIC_CODES];
@@ -209,8 +213,8 @@ interface SanitizeOptions {
     /** Extra tags to allow. Lower-case, untrimmed. */
     readonly additionalAllowedTags?: readonly string[];
     /**
-     * Extra per-tag attributes, lower-case. Cannot re-admit handlers, `style`,
-     * or — under `'strict'` — `id`, `name` and `data-payload-*`.
+     * Extra per-tag attributes, lower-case. Cannot re-admit handlers, `style`, or —
+     * under `'strict'` — `id`, `name` and `data-payload-*`; their URLs are checked.
      */
     readonly additionalAllowedAttributes?: Readonly<Record<string, readonly string[]>>;
     /**
@@ -345,6 +349,8 @@ interface RenderContext {
      * completes the sentence 'field "x" …' in LP0411.
      */
     readonly reportUnfaithful?: (target: CachedElement, reason: string) => void;
+    /** The route of a Lexical internal link, as `internalLinkPattern` gives it. */
+    readonly internalLinkPattern?: string;
 }
 /**
  * A renderer writes one value into its element. It must not throw: one bad
@@ -851,7 +857,7 @@ interface LivePreviewInspection {
      * SvelteKit page is not connected yet; `timed-out` is LP0607.
      */
     readonly hydration: {
-        readonly mode: 'off' | 'react' | 'vue' | 'sveltekit';
+        readonly mode: 'off' | 'react' | 'vue' | 'sveltekit' | 'manual';
         readonly state: 'idle' | 'waiting' | 'committed' | 'timed-out';
     };
 }
@@ -1004,6 +1010,12 @@ interface LivePreviewClientConfig {
     readonly apiRoute?: string;
     /** Population depth used with `serverURL`. Required with it; `defaults: 'v1'` falls back to `1`. */
     readonly mergeDepth?: number;
+    /** Milliseconds the `serverURL` merge may wait before the update shows its raw values. Off by default. */
+    readonly mergeTimeoutMs?: number;
+    /** The route of a Lexical internal link with no `url` of its own, as `/{locale}/{slug}/`. */
+    readonly internalLinkPattern?: string;
+    /** Hold a route render until Payload reports the save: the route shows what is saved. */
+    readonly routeAfterSave?: boolean;
     /** Custom fetch for the `serverURL` merge request: attach auth headers or route through a proxy. */
     readonly mergeFetch?: typeof fetch;
     /** Verbose console output. Defaults to dev-mode detection. */
@@ -1411,6 +1423,11 @@ interface FieldBindingAttributes {
     readonly 'data-payload-alt'?: string;
     readonly 'data-payload-href'?: string;
     readonly 'data-payload-array-template'?: string;
+    readonly 'data-payload-format'?: string;
+    readonly 'data-payload-text'?: string;
+    readonly 'data-payload-strategy'?: string;
+    readonly 'data-payload-depends'?: string;
+    readonly 'data-payload-boundary'?: string;
 }
 interface BindOptions {
     /** Attribute to write instead of the text content, e.g. `'src'` for `<img>`. */
@@ -1429,6 +1446,19 @@ interface BindOptions {
     readonly href?: string;
     /** Markup per array item with `{{value}}` placeholders. */
     readonly arrayTemplate?: string;
+    /** How a date or number is written, from `data-payload-format`'s vocabulary. */
+    readonly format?: string;
+    /** Let a text write replace the element's children. */
+    readonly text?: boolean;
+    /** Who shows this field: the patch (default), a server-rendered fragment, or the route. */
+    readonly strategy?: 'patch' | 'fragment' | 'route';
+    /** Fields whose change re-applies this binding under `skipUnchanged`. */
+    readonly dependsOn?: readonly string[];
+    /**
+     * An anchor for a field that may be empty, so an edit that fills it has somewhere to
+     * land. Set `hidden` yourself while the value is empty; the runtime keeps it right after that.
+     */
+    readonly anchor?: boolean;
 }
 /** `bind<Homepage>('heroTitle')`; without `T` any string is accepted. */
 declare function bind<T = Record<string, unknown>>(field: FieldName<T>, options?: BindOptions): FieldBindingAttributes;
@@ -1514,6 +1544,111 @@ interface IslandUpdateDetail {
 /** Whether `element` (or an ancestor) is an island that did not opt into patching. @internal */
 declare function isInsideIsland(element: Element): boolean;
 
+/**
+ * The document a framework hook exposes, kept outside any framework: the
+ * message bus decides which windows may speak, `DataMerger` turns the admin's
+ * raw form values back into a populated document, and this class holds the one
+ * snapshot a `useSyncExternalStore`-shaped API reads.
+ *
+ * It touches no DOM. A hook that re-renders a component tree needs the data,
+ * not the bindings — everything about elements lives in the runtime instead.
+ *
+ * The session is per instance (ADR 0002): two hooks on one page have two
+ * mergers, two revisions and two snapshots, so a request or an error in one
+ * never reaches the other. A session given a `document` merges only the
+ * messages for that document; without one it follows the document the admin
+ * sends, whichever document it started from.
+ */
+/**
+ * `idle` — connected, nothing received yet. `live` — the newest update was
+ * merged and is in `data`. `unavailable` — it could not be, and `data` is the
+ * last good document rather than a half-merged one.
+ */
+type DocumentStatus = 'idle' | 'live' | 'unavailable';
+interface DocumentSnapshot<T> {
+    /** The newest document that merged; never a partially applied one. */
+    readonly data: T;
+    /** No update has settled yet, or a merge is in flight. */
+    readonly isLoading: boolean;
+    readonly status: DocumentStatus;
+    /** Why the last update did not merge; `undefined` while `status` is not `unavailable`. */
+    readonly error: Error | undefined;
+    /**
+     * Which of this session's messages `data` came from: `0` for the initial
+     * data, and unchanged when a merge fails. The framework paints `data` in its
+     * own commit; a component that must know it was painted compares this in an
+     * effect (ADR 0023).
+     */
+    readonly revision: number;
+}
+/**
+ * The document a session previews: a collection document by its id, or a global by its slug.
+ * `locale` narrows it to the updates the admin sends for that locale.
+ */
+type PreviewDocument = {
+    readonly collection: string;
+    readonly id: string | number;
+    readonly locale?: string;
+} | {
+    readonly global: string;
+    readonly locale?: string;
+};
+interface DocumentSessionOptions {
+    /** Payload server origin the update is re-fetched from. */
+    readonly serverURL: string;
+    /** REST route prefix. Default `/api`. */
+    readonly apiRoute?: string;
+    /** Population depth for the merge. Default `1`, as Payload's own hook. */
+    readonly depth?: number;
+    /**
+     * Milliseconds a merge may wait for the server; after that the update is `unavailable`
+     * and `data` stays the last good document. Off by default: a merge waits as long as the
+     * server takes.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Admin origins allowed to post updates. Without one the session falls back
+     * to the localhost matcher in development and trusts nothing in production.
+     */
+    readonly allowedOrigins?: readonly string[];
+    /** `'parent-or-opener'` (default) refuses every window but the framing or opening one. */
+    readonly eventSourcePolicy?: 'any' | 'parent-or-opener';
+    /** Trust `document.referrer` as an origin source. Default `false`. */
+    readonly enableReferrerDetection?: boolean;
+    /** Match `localhost` origins in development. Default `true`. */
+    readonly enableLocalhostMatching?: boolean;
+    /**
+     * The document this session previews. An update for another document is ignored, and so is
+     * one that does not say which document it is for: Payload 2 sends no collection or global
+     * slug, and a create screen has no id yet. Without it the session merges every update.
+     */
+    readonly document?: PreviewDocument;
+    /** Injected for tests. */
+    readonly fetchFn?: typeof fetch;
+    /** Window to listen on. Default the global one. */
+    readonly target?: Window;
+}
+type Listener = () => void;
+declare class DocumentSession<T> {
+    #private;
+    constructor(initialData: T, options: DocumentSessionOptions);
+    /**
+     * Attach on the first subscriber and detach with the last, so a component
+     * that mounts twice (React's strict mode) listens once and a page that
+     * unmounts the hook stops listening at all.
+     */
+    subscribe: (listener: Listener) => (() => void);
+    getSnapshot: () => DocumentSnapshot<T>;
+    /** Server rendering has no window and no messages: the initial snapshot a client render starts from. */
+    getServerSnapshot: () => DocumentSnapshot<T>;
+}
+/**
+ * One preview document, with no framework around it: `subscribe` and `getSnapshot`
+ * fit a `useSyncExternalStore` or a Svelte store.
+ * @beta
+ */
+declare function createDocumentSession<T extends Record<string, unknown>>(initialData: T, options: DocumentSessionOptions): DocumentSession<T>;
+
 /**
  * Narrow public entry — the minimum API for sites that only need to
  * receive postMessage updates and apply them to the DOM.
@@ -1536,4 +1671,4 @@ declare function isInsideIsland(element: Element): boolean;
 /** @internal */
 declare const CORE_ENTRY = true;
 
-export { AUTHORIZED_PREVIEW_BRAND_KEY, type AuthorizedPreviewContext, type AuthorizedPreviewDocument, type AuthorizedPreviewPayloadScope, type AuthorizedPreviewScope, type BindOptions, CAPABILITY_DECLARATIONS, CAPABILITY_DOCUMENTATION, CORE_ENTRY, type CachedElement, type CapabilityDeclaration, type CapabilityDocumentation, type CapabilitySource, type ConnectionStatus, type CustomRendererKey, DIAGNOSTIC_CODES, type DefaultsProfile, type DiagnosticCode, EventEmitter, type EventHandler, type EventSourcePolicy, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FragmentBoundaryAttributes, type FragmentBoundaryOptions, type FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InspectionBindings, type InspectionFidelity, type InspectionFragments, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionRoute, type InspectionScheduler, type IslandUpdateDetail, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, OriginDetector, type OwnerBindingAttributes, PROTOCOL_CAPABILITIES, type PayloadDocumentEventDetail, type PayloadFieldCondition, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PluginCompatibility, type PluginInspection, type PreviewAuthorizationStrategyName, type PreviewBindings, type PreviewBindingsOptions, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RevisionDisplay, type RevisionDisplayState, type RevisionShortfall, type RichTextRenderer, type RouteContext, type RouteOutcome, type RoutePlanContext, type RouteRefresh, type RouteStrategy, type SanitizerDocument, type SanitizerPolicyMode, type StrategyHandlers, type SuppressedBinding, type Unsubscribe, type UpdateSource, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createPreviewBindings, detectInitialLocale, detectProtocolProfile, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isAuthorizedPreviewContext, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isInsideIsland, isSafeUrl, negotiateProtocol, registerRouteRefresh, sanitizeHtml, setCspCrypto, setSanitizerDocument };
+export { AUTHORIZED_PREVIEW_BRAND_KEY, type AuthorizedPreviewContext, type AuthorizedPreviewDocument, type AuthorizedPreviewPayloadScope, type AuthorizedPreviewScope, type BindOptions, CAPABILITY_DECLARATIONS, CAPABILITY_DOCUMENTATION, CORE_ENTRY, type CachedElement, type CapabilityDeclaration, type CapabilityDocumentation, type CapabilitySource, type ConnectionStatus, type CustomRendererKey, DIAGNOSTIC_CODES, type DefaultsProfile, type DiagnosticCode, DocumentSession, type DocumentSessionOptions, type DocumentSnapshot, type DocumentStatus, EventEmitter, type EventHandler, type EventSourcePolicy, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FragmentBoundaryAttributes, type FragmentBoundaryOptions, type FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InspectionBindings, type InspectionFidelity, type InspectionFragments, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionRoute, type InspectionScheduler, type IslandUpdateDetail, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, OriginDetector, type OwnerBindingAttributes, PROTOCOL_CAPABILITIES, type PayloadDocumentEventDetail, type PayloadFieldCondition, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PluginCompatibility, type PluginInspection, type PreviewAuthorizationStrategyName, type PreviewBindings, type PreviewBindingsOptions, type PreviewDocument, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RevisionDisplay, type RevisionDisplayState, type RevisionShortfall, type RichTextRenderer, type RouteContext, type RouteOutcome, type RoutePlanContext, type RouteRefresh, type RouteStrategy, type SanitizerDocument, type SanitizerPolicyMode, type StrategyHandlers, type SuppressedBinding, type Unsubscribe, type UpdateSource, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createDocumentSession, createPreviewBindings, detectInitialLocale, detectProtocolProfile, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isAuthorizedPreviewContext, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isInsideIsland, isSafeUrl, negotiateProtocol, registerRouteRefresh, sanitizeHtml, setCspCrypto, setSanitizerDocument };

package/dist/core.d.ts

@@ -37,6 +37,8 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly UnattributableUpdate: "LP0202";
     /** An update carried a value for a field the page binds nowhere; editing it changes nothing on this page. */
     readonly UnboundField: "LP0203";
+    /** In development: a bound path covers its group under the `descendant` default, which 3.0 changes. */
+    readonly CoverageDefaultChanges: "LP0204";
     /** The visibility gate held offscreen writes back until they scroll into view. */
     readonly VisibilityGateDeferred: "LP0301";
     /** A value was refused because the attribute or the value itself is unsafe. */
@@ -61,7 +63,7 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly UnrenderedBlockKept: "LP0410";
     /** A patch cannot reach what the server would have drawn; `onUnfaithfulPatch` decided what happens next. */
     readonly UnfaithfulPatch: "LP0411";
-    /** The first write to a date, number or checkbox binding replaced a different reading of the same value. */
+    /** The first write to a date, number, checkbox, select or radio binding replaced a different reading of the same value. */
     readonly ServerFormatReplaced: "LP0412";
     /** A Lexical block has no renderer, and the write could not keep the markup the server rendered for it; it is gone. */
     readonly UnrenderedBlockLost: "LP0413";
@@ -81,7 +83,7 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly StartupFailed: "LP0605";
     /** Sending the ready handshake failed. */
     readonly ReadyFailed: "LP0606";
-    /** The page declared hydration, but no React commit, Vue mount or SvelteKit mount came within the cap; the runtime started without waiting. */
+    /** The page declared hydration, but no React commit, Vue mount, SvelteKit mount or `markHydrated()` call came within the cap; the runtime started without waiting. */
     readonly HydrationWaitTimedOut: "LP0607";
     /** The audit found no runtime in a response that carried preview intent. */
     readonly AuditRuntimeMissing: "LP0701";
@@ -123,6 +125,8 @@ declare const DIAGNOSTIC_CODES: Readonly<{
     readonly V2ReadinessGap: "LP0709";
     /** The preview runtime is served to anonymous visitors, not only inside the admin frame. */
     readonly RuntimeOnPublicPage: "LP0710";
+    /** An element carries attributes that only mean something beside `data-payload-field`, and has none. */
+    readonly AuditModifierWithoutField: "LP0711";
 }>;
 /** A diagnostic code, as it appears in log output and on the `error` event. */
 type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[keyof typeof DIAGNOSTIC_CODES];
@@ -209,8 +213,8 @@ interface SanitizeOptions {
     /** Extra tags to allow. Lower-case, untrimmed. */
     readonly additionalAllowedTags?: readonly string[];
     /**
-     * Extra per-tag attributes, lower-case. Cannot re-admit handlers, `style`,
-     * or — under `'strict'` — `id`, `name` and `data-payload-*`.
+     * Extra per-tag attributes, lower-case. Cannot re-admit handlers, `style`, or —
+     * under `'strict'` — `id`, `name` and `data-payload-*`; their URLs are checked.
      */
     readonly additionalAllowedAttributes?: Readonly<Record<string, readonly string[]>>;
     /**
@@ -345,6 +349,8 @@ interface RenderContext {
      * completes the sentence 'field "x" …' in LP0411.
      */
     readonly reportUnfaithful?: (target: CachedElement, reason: string) => void;
+    /** The route of a Lexical internal link, as `internalLinkPattern` gives it. */
+    readonly internalLinkPattern?: string;
 }
 /**
  * A renderer writes one value into its element. It must not throw: one bad
@@ -851,7 +857,7 @@ interface LivePreviewInspection {
      * SvelteKit page is not connected yet; `timed-out` is LP0607.
      */
     readonly hydration: {
-        readonly mode: 'off' | 'react' | 'vue' | 'sveltekit';
+        readonly mode: 'off' | 'react' | 'vue' | 'sveltekit' | 'manual';
         readonly state: 'idle' | 'waiting' | 'committed' | 'timed-out';
     };
 }
@@ -1004,6 +1010,12 @@ interface LivePreviewClientConfig {
     readonly apiRoute?: string;
     /** Population depth used with `serverURL`. Required with it; `defaults: 'v1'` falls back to `1`. */
     readonly mergeDepth?: number;
+    /** Milliseconds the `serverURL` merge may wait before the update shows its raw values. Off by default. */
+    readonly mergeTimeoutMs?: number;
+    /** The route of a Lexical internal link with no `url` of its own, as `/{locale}/{slug}/`. */
+    readonly internalLinkPattern?: string;
+    /** Hold a route render until Payload reports the save: the route shows what is saved. */
+    readonly routeAfterSave?: boolean;
     /** Custom fetch for the `serverURL` merge request: attach auth headers or route through a proxy. */
     readonly mergeFetch?: typeof fetch;
     /** Verbose console output. Defaults to dev-mode detection. */
@@ -1411,6 +1423,11 @@ interface FieldBindingAttributes {
     readonly 'data-payload-alt'?: string;
     readonly 'data-payload-href'?: string;
     readonly 'data-payload-array-template'?: string;
+    readonly 'data-payload-format'?: string;
+    readonly 'data-payload-text'?: string;
+    readonly 'data-payload-strategy'?: string;
+    readonly 'data-payload-depends'?: string;
+    readonly 'data-payload-boundary'?: string;
 }
 interface BindOptions {
     /** Attribute to write instead of the text content, e.g. `'src'` for `<img>`. */
@@ -1429,6 +1446,19 @@ interface BindOptions {
     readonly href?: string;
     /** Markup per array item with `{{value}}` placeholders. */
     readonly arrayTemplate?: string;
+    /** How a date or number is written, from `data-payload-format`'s vocabulary. */
+    readonly format?: string;
+    /** Let a text write replace the element's children. */
+    readonly text?: boolean;
+    /** Who shows this field: the patch (default), a server-rendered fragment, or the route. */
+    readonly strategy?: 'patch' | 'fragment' | 'route';
+    /** Fields whose change re-applies this binding under `skipUnchanged`. */
+    readonly dependsOn?: readonly string[];
+    /**
+     * An anchor for a field that may be empty, so an edit that fills it has somewhere to
+     * land. Set `hidden` yourself while the value is empty; the runtime keeps it right after that.
+     */
+    readonly anchor?: boolean;
 }
 /** `bind<Homepage>('heroTitle')`; without `T` any string is accepted. */
 declare function bind<T = Record<string, unknown>>(field: FieldName<T>, options?: BindOptions): FieldBindingAttributes;
@@ -1514,6 +1544,111 @@ interface IslandUpdateDetail {
 /** Whether `element` (or an ancestor) is an island that did not opt into patching. @internal */
 declare function isInsideIsland(element: Element): boolean;
 
+/**
+ * The document a framework hook exposes, kept outside any framework: the
+ * message bus decides which windows may speak, `DataMerger` turns the admin's
+ * raw form values back into a populated document, and this class holds the one
+ * snapshot a `useSyncExternalStore`-shaped API reads.
+ *
+ * It touches no DOM. A hook that re-renders a component tree needs the data,
+ * not the bindings — everything about elements lives in the runtime instead.
+ *
+ * The session is per instance (ADR 0002): two hooks on one page have two
+ * mergers, two revisions and two snapshots, so a request or an error in one
+ * never reaches the other. A session given a `document` merges only the
+ * messages for that document; without one it follows the document the admin
+ * sends, whichever document it started from.
+ */
+/**
+ * `idle` — connected, nothing received yet. `live` — the newest update was
+ * merged and is in `data`. `unavailable` — it could not be, and `data` is the
+ * last good document rather than a half-merged one.
+ */
+type DocumentStatus = 'idle' | 'live' | 'unavailable';
+interface DocumentSnapshot<T> {
+    /** The newest document that merged; never a partially applied one. */
+    readonly data: T;
+    /** No update has settled yet, or a merge is in flight. */
+    readonly isLoading: boolean;
+    readonly status: DocumentStatus;
+    /** Why the last update did not merge; `undefined` while `status` is not `unavailable`. */
+    readonly error: Error | undefined;
+    /**
+     * Which of this session's messages `data` came from: `0` for the initial
+     * data, and unchanged when a merge fails. The framework paints `data` in its
+     * own commit; a component that must know it was painted compares this in an
+     * effect (ADR 0023).
+     */
+    readonly revision: number;
+}
+/**
+ * The document a session previews: a collection document by its id, or a global by its slug.
+ * `locale` narrows it to the updates the admin sends for that locale.
+ */
+type PreviewDocument = {
+    readonly collection: string;
+    readonly id: string | number;
+    readonly locale?: string;
+} | {
+    readonly global: string;
+    readonly locale?: string;
+};
+interface DocumentSessionOptions {
+    /** Payload server origin the update is re-fetched from. */
+    readonly serverURL: string;
+    /** REST route prefix. Default `/api`. */
+    readonly apiRoute?: string;
+    /** Population depth for the merge. Default `1`, as Payload's own hook. */
+    readonly depth?: number;
+    /**
+     * Milliseconds a merge may wait for the server; after that the update is `unavailable`
+     * and `data` stays the last good document. Off by default: a merge waits as long as the
+     * server takes.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Admin origins allowed to post updates. Without one the session falls back
+     * to the localhost matcher in development and trusts nothing in production.
+     */
+    readonly allowedOrigins?: readonly string[];
+    /** `'parent-or-opener'` (default) refuses every window but the framing or opening one. */
+    readonly eventSourcePolicy?: 'any' | 'parent-or-opener';
+    /** Trust `document.referrer` as an origin source. Default `false`. */
+    readonly enableReferrerDetection?: boolean;
+    /** Match `localhost` origins in development. Default `true`. */
+    readonly enableLocalhostMatching?: boolean;
+    /**
+     * The document this session previews. An update for another document is ignored, and so is
+     * one that does not say which document it is for: Payload 2 sends no collection or global
+     * slug, and a create screen has no id yet. Without it the session merges every update.
+     */
+    readonly document?: PreviewDocument;
+    /** Injected for tests. */
+    readonly fetchFn?: typeof fetch;
+    /** Window to listen on. Default the global one. */
+    readonly target?: Window;
+}
+type Listener = () => void;
+declare class DocumentSession<T> {
+    #private;
+    constructor(initialData: T, options: DocumentSessionOptions);
+    /**
+     * Attach on the first subscriber and detach with the last, so a component
+     * that mounts twice (React's strict mode) listens once and a page that
+     * unmounts the hook stops listening at all.
+     */
+    subscribe: (listener: Listener) => (() => void);
+    getSnapshot: () => DocumentSnapshot<T>;
+    /** Server rendering has no window and no messages: the initial snapshot a client render starts from. */
+    getServerSnapshot: () => DocumentSnapshot<T>;
+}
+/**
+ * One preview document, with no framework around it: `subscribe` and `getSnapshot`
+ * fit a `useSyncExternalStore` or a Svelte store.
+ * @beta
+ */
+declare function createDocumentSession<T extends Record<string, unknown>>(initialData: T, options: DocumentSessionOptions): DocumentSession<T>;
+
 /**
  * Narrow public entry — the minimum API for sites that only need to
  * receive postMessage updates and apply them to the DOM.
@@ -1536,4 +1671,4 @@ declare function isInsideIsland(element: Element): boolean;
 /** @internal */
 declare const CORE_ENTRY = true;
 
-export { AUTHORIZED_PREVIEW_BRAND_KEY, type AuthorizedPreviewContext, type AuthorizedPreviewDocument, type AuthorizedPreviewPayloadScope, type AuthorizedPreviewScope, type BindOptions, CAPABILITY_DECLARATIONS, CAPABILITY_DOCUMENTATION, CORE_ENTRY, type CachedElement, type CapabilityDeclaration, type CapabilityDocumentation, type CapabilitySource, type ConnectionStatus, type CustomRendererKey, DIAGNOSTIC_CODES, type DefaultsProfile, type DiagnosticCode, EventEmitter, type EventHandler, type EventSourcePolicy, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FragmentBoundaryAttributes, type FragmentBoundaryOptions, type FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InspectionBindings, type InspectionFidelity, type InspectionFragments, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionRoute, type InspectionScheduler, type IslandUpdateDetail, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, OriginDetector, type OwnerBindingAttributes, PROTOCOL_CAPABILITIES, type PayloadDocumentEventDetail, type PayloadFieldCondition, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PluginCompatibility, type PluginInspection, type PreviewAuthorizationStrategyName, type PreviewBindings, type PreviewBindingsOptions, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RevisionDisplay, type RevisionDisplayState, type RevisionShortfall, type RichTextRenderer, type RouteContext, type RouteOutcome, type RoutePlanContext, type RouteRefresh, type RouteStrategy, type SanitizerDocument, type SanitizerPolicyMode, type StrategyHandlers, type SuppressedBinding, type Unsubscribe, type UpdateSource, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createPreviewBindings, detectInitialLocale, detectProtocolProfile, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isAuthorizedPreviewContext, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isInsideIsland, isSafeUrl, negotiateProtocol, registerRouteRefresh, sanitizeHtml, setCspCrypto, setSanitizerDocument };
+export { AUTHORIZED_PREVIEW_BRAND_KEY, type AuthorizedPreviewContext, type AuthorizedPreviewDocument, type AuthorizedPreviewPayloadScope, type AuthorizedPreviewScope, type BindOptions, CAPABILITY_DECLARATIONS, CAPABILITY_DOCUMENTATION, CORE_ENTRY, type CachedElement, type CapabilityDeclaration, type CapabilityDocumentation, type CapabilitySource, type ConnectionStatus, type CustomRendererKey, DIAGNOSTIC_CODES, type DefaultsProfile, type DiagnosticCode, DocumentSession, type DocumentSessionOptions, type DocumentSnapshot, type DocumentStatus, EventEmitter, type EventHandler, type EventSourcePolicy, type FieldBindingAttributes, type FieldName, type FieldPath, type FieldRenderer, type FieldType, type FragmentBoundaryAttributes, type FragmentBoundaryOptions, type FragmentContext, type FragmentReport, type FragmentStrategy, type FrameAncestorsOptions, ISLAND_EVENT, type InspectionBindings, type InspectionFidelity, type InspectionFragments, type InspectionOrigins, type InspectionProtocol, type InspectionRevisions, type InspectionRoute, type InspectionScheduler, type IslandUpdateDetail, LIBRARY_PROTOCOL_VERSION, LivePreviewClient, type LivePreviewClientConfig, type LivePreviewEventMap, type LivePreviewInspection, OriginDetector, type OwnerBindingAttributes, PROTOCOL_CAPABILITIES, type PayloadDocumentEventDetail, type PayloadFieldCondition, type PayloadFieldSchema, type PayloadFieldType, type PayloadLivePreviewData, type PayloadLivePreviewMessage, type PluginCompatibility, type PluginInspection, type PreviewAuthorizationStrategyName, type PreviewBindings, type PreviewBindingsOptions, type PreviewDocument, type ProtocolCapability, type ProtocolNegotiation, type ProtocolProfile, type ProtocolProfileName, type RenderContext, type RendererKey, type RevisionDisplay, type RevisionDisplayState, type RevisionShortfall, type RichTextRenderer, type RouteContext, type RouteOutcome, type RoutePlanContext, type RouteRefresh, type RouteStrategy, type SanitizerDocument, type SanitizerPolicyMode, type StrategyHandlers, type SuppressedBinding, type Unsubscribe, type UpdateSource, VERSION, type ValueAt, bind, bindByPath, buildFrameAncestors, buildScriptSrcWithNonce, createDocumentSession, createPreviewBindings, detectInitialLocale, detectProtocolProfile, escapeHtml, escapeHtmlAttribute, generateCspNonce, hasCapability, initLivePreview, isAuthorizedPreviewContext, isDevMode, isExternalHttpUrl, isInIframe, isInPopup, isInPreviewContext, isInsideIsland, isSafeUrl, negotiateProtocol, registerRouteRefresh, sanitizeHtml, setCspCrypto, setSanitizerDocument };